feat(#189): searchable multiselect for query-backed Dashboard filters with Apply

[BorisTyshkevich]

What & why

Closes #189 — searchable multiselect UX for query-backed Dashboard filters whose consumers use a ClickHouse Array(T) parameter, with local draft state and an explicit Apply.

Schema & core. DashboardFilterDefinitionV1 gains an optional selection.mode ("single" | "multiple") override (closed sub-object, regenerated types/validators). The new pure core/filter-selection.ts resolves each source-backed filter's helper contract from its executable consumers — defined once in gatherExecutableConsumers: the resolved executable target tiles (explicit targets else declaring tiles; Filter sources are never consumers, since under #360's single-layer rule a source depending on a source-backed parameter can never execute) — and derives the effective mode per the issue's table (omitted mode: scalar T → single, Array(T) → multiselect; explicit multiple on scalar is diagnosed, never silently downgraded). Any unresolved contract (mixed arity, type/element conflicts, nested arrays, undeclared/non-executable targets, target-less configs, unknown modes) falls back to the ordinary string input with persistent, path-precise filter-selection-* diagnostics; a source left with zero consumers never executes; declarations outside the resolved consumer set (a presentation-error tile, a cascading-invalid source, a non-targeted tile) can never suppress a valid helper — the per-wave merge consumes controls derived from the same resolved contracts. The same resolver runs at authoring/import time in validateDashboardSemantics, mapping each diagnostic to its exact document path (filters[i].selection.mode, filters[i].targets[j], filters[i].parameter), so an invalid dashboard is caught at whole-workspace validation, not first in the viewer. Inference is runtime-only — nothing is ever written back into the dashboard document.

Runtime value model. Committed multiselect values are real string[] end to end: viewer state, the typed pipeline (the existing Array(T) serializer — new element coverage for Unicode, empty strings, commas, Decimal, Enum labels, DateTime), structural equality (sameSelection), and localStorage persistence (DashboardFilterEntry.value: string | string[]). Empty-string elements are valid; duplicates are removed; an inactive filter retains its dormant array; every array — including [] — passes through untouched (an active empty array serializes as a real []), with activation decided exclusively by the active flag and array-aware default-activation inference (defaultValue: [] starts inactive).

Execution planning. Filter commits now plan the affected-panel wave from each parameter's resolved targets instead of rerunning every tile that merely declares the name (one shared resolver with the #235 wave-deferral gate, which is now computed post-fallback). One commit → at most one wave; a no-op Apply issues nothing.

Option-refresh reconciliation (array-aware, by bound value): surviving selections stay active in canonical option order; label/order-only refreshes rerun nothing; removals join the single reconciled wave; an empty intersection deactivates keeping the dormant value; new options are never auto-selected. A refresh landing while the popover is open cancels it as a draft-discard and announces "Filter options were refreshed" via a persistent live region.

UI. New dedicated ui/multi-select-field.ts (per the issue: not the single-select combobox forced into multiselect ARIA): closed trigger (All / Not set / selected label / N selected / loading / waiting), role="dialog" popover with labeled search, tri-state Select visible scoped to the filtered subset, checkbox options, Clear / Cancel / Apply, a Tab focus trap, focus return to the trigger on every dismissal, and an announced noninteractive busy body while options load mid-open. Error statuses swap in an enabled free-text input (raw values still flow through the typed pipeline via the serializer's scalar passthrough). selection.mode: "single" on an Array(T) contract keeps the strict single-select and commits [value] / clears to [], false.

Merge-gate review round (2026-07-22)

All four maintainer findings fixed as commits on this PR:

1. a7dc5ff — selection contracts are now validated in validateDashboardSemantics with exact JSON paths (was runtime-only), and "executable consumer" is defined once (gatherExecutableConsumers; resolveFilterSelection dropped its dependentSources input — a Filter source can never be an executable consumer).
2. 9d552b5 — the over-broad dashboard-wide conflict gate is removed; the per-wave merge consumes resolved-consumer-derived controls, so non-executable/non-targeted declarations can't suppress a valid helper. Regression: a valid Array(String) helper survives a conflicting declaration in a presentation-error tile and in a cascading-invalid source.
3. 9d552b5 — toParamValue preserves every array including [] (active [] serializes as '[]'); default activation is array-aware; activation comes exclusively from the active map.
4. b37feb2 — Apply closes the popover before onApply, and the "Filter options were refreshed" announcement fires only when the open parameter's optionsRev actually changed; focus lands on the fresh trigger after an Apply-triggered rebuild.

Review notes / deliberate decisions

• Strict single-select keeps Allow Filter-role source queries to use root Dashboard parameters (single-layer dependencies) #360's disabled-on-error affordance. Dashboard query-backed filters: searchable multiselect with Apply #189's failure section says "render the ordinary string input" on helper-query failure; the multiselect control implements exactly that (its error mode has a real free-text path). The strict single-select (filter-option-field, Dashboard: multi-filter option bundles, shared preview, and role-aware result selector #160) has no free-text commit path — enabling it on error produced a field that looked editable but reverted everything typed, so the review reverted to disabled-on-error. If the strict single-select should also gain a free-text failure fallback, that's a small follow-up decision on Dashboard: multi-filter option bundles, shared preview, and role-aware result selector #160's strictness contract.
• Zero-consumer / undeclared-target filters now fall back (string input + diagnostic) instead of silently curating — this is the issue's explicit rule and slightly tightens Refactor Dashboard Filter sources: execute once per source, preserve diagnostics, and reconcile option state #359/Allow Filter-role source queries to use root Dashboard parameters (single-layer dependencies) #360-era behavior; the affected older tests were re-fixtured with real consumers. With the semantic validator now running the same resolver, such dashboards are also flagged at import/authoring time — a few unit-test fixtures elsewhere (import-planner, saved-query-mutation, state) were re-fixtured or switched to plain filters accordingly.
• Completion for selection / selection.mode / single / multiple comes for free from the schema-driven engine; there is no dashboard-JSON editor surface yet, so a schema-service conformance test pins the suggestions for the day one binds dashboardV1Schema.
• A reviewer noted (unverified, session-layer, reproducible at the pre-Dashboard query-backed filters: searchable multiselect with Apply #189 HEAD) that a full refresh() may not re-execute a tile whose committed value is deactivated by newly-arrived options within the same wave in some fixture shape — flagged here rather than filed, since we could not reduce it to a confirmed product bug.

Process: coordinator + sequential file-scoped sonnet workers; three independent read-only review passes (issue conformance, session correctness, UI/a11y) with all majors fixed in 3840d57.

Checklist

• npm test passes (159 files / 4648 tests; per-file coverage gate green)
• Tests added/updated in the same change as the code (+153 tests)
• npm run build succeeds (single-file dist/sql.html)
• Layers kept honest: pure logic in src/core/ (filter-selection.ts 100%), DOM in src/ui/ behind the app controller; no network changes
• No new runtime dependency
• CHANGELOG.md ([Unreleased]) updated
• Reconciled affected tracked work (roadmap Roadmap to 1.0.0 #68 checked off)
• e2e: chromium + webkit fully green on the final code (incl. the merge-gate fixes). Firefox was fully green (231/231 all engines) on 3840d57 earlier the same day, but is currently environmentally degraded on this build host — every failure is a page.goto/context-teardown timeout in beforeEach under load (loadavg 5–7.5, shared box), never an assertion or app code. Known host-specific Firefox instability; chromium+webkit are the real signal here.

🤖 Generated with Claude Code