feat(interactions): declarative interaction_spec for specifying chart interactions with presets

[xavier (xavier-shaw)]

Summary

Charts can now ask for behaviour in the same JSON document that asks for the chart. A new top-level field, interaction_spec, lists interaction presets by name with their options, plus the surface policies. Retained state stays a host signal (applyUpdate, setUpdates, dispatch), not part of the spec. A registry maps each name to the factory code already calls, so a spec entry and a factory call are two spellings of one definition. The mount decides what the chart can honour: a spec entry it cannot honour is dropped with a warning, and the chart still renders.

"interaction_spec": {
  "interactions": [
    { "type": "legend-toggle" },
    { "type": "click-highlight", "options": { "dimOpacity": 0.2 } },
    { "type": "navigate", "options": { "axes": "x", "pan": false, "reset": ["double-click", "escape"] } }
  ]
}

Design notes and the decision record: docs/design-interaction-spec.md.

Commits

1. spec — core/interaction-spec.ts: the InteractionSpec contract, interaction_spec on ChartAssemblyInput. The four surface-policy interfaces move to core; flint-chart/interactive re-exports them under their old names.
2. registry — INTERACTION_PRESETS (name → factory, capability, gesture) and resolveInteractionSpec(). Entries are { type, id?, options }; the resolver rejects an unknown type, a flat option outside options, a missing required option, and a duplicate id, naming the entry each time.
3. admission — admitInteractions() extracted from the inline checks in addVegaLiteInteractions(). Code definitions still throw with the same messages. Spec entries are dropped with a ChartWarning (unsupported_interaction, conflicting_interactions); in a pan-versus-drag conflict the later entry yields. The plan carries the admitted list and the Vega mount runs it.
4. compose — composeInteractiveOptions(): spec first, then code; an id shared by both is an error; code wins on dismiss, assistedTargeting, keyboardTargeting; a non-Vega-Lite backend ignores the spec with one info warning. The surface exposes surface.warnings and logs the list once.
5. refactor — updates removed from the spec after review: retained state arrives from outside the chart, so it stays on options.updates and the surface methods.
6. reset, step 1 — every preset that retains state accepts reset, a list of click-none, double-click, escape; the registry records each preset's supported and default lists; the resolver rejects an unknown or unsupported gesture by name; navigate renames click-background to click-none.
7. reset, step 2 — one reset dispatcher in the Vega runtime replaces the global dismiss policy: a gesture resets only the interactions whose list holds it, each by its own id; legend-toggle drops closure state through onReset(); a chart with an escape reset becomes focusable and takes focus on a pointer press; double-activate next to a double-click reset is an admission conflict.
8. reset, step 3 — dismiss is removed from the spec and from the code options; the resolver rejects the key with a hint.
9. site — a Spec test cases tab in the Interactions lab (playground/spec-test-cases). It renders the same cases as Test cases, but every chart mounts from interaction_spec; modeSpec() mirrors modeInteractions() entry for entry. Each card shows the JSON it used in a foldable, token-coloured panel with a copy button, dropped entries appear in a callout, and the page tallies ready and dropped cards.

Behaviour guarantees

• Breaking: options.dismiss is removed. Write reset on the interaction, for example clickHighlight({ reset: ['escape'] }) or { "type": "click-highlight", "options": { "reset": ["escape"] } }. Every other caller of buildInteractiveChart() and the factories is unchanged, and the code path keeps every exception it had.
• Vega-Lite only, as for all interactions today.
• The core bundle gains the preset names and the JSON types and none of the runtime.

Verification

• 70 test files, 1603 tests pass; 42 new tests across interaction-spec, interaction-admission, and interaction-compose.
• Each commit was checked out alone in a worktree and type-checked and tested on its own.
• Parity check between the two lab tabs: a headless browser clicked every mode on Test cases and on Spec test cases and read each card's status. 23 modes, 837 cards per tab, 0 differences.
• Browser check of the reset dispatcher on the Spec test cases tab: a click on empty space clears a highlight; Escape resets only the focused chart of two; a hidden legend series survives a click on nothing; a double-click flies a zoom home; Escape clears a brush.
• Browser check on the site dev server: a bar chart mounted from a spec with brush-angle, navigate on x, click-highlight, and a seeded annotation rendered with the annotation in place, reported the two dropped entries on surface.warnings and once on the console, and a click emphasised a bar with the flint-interaction event carrying click-highlight.

Upcoming work (not in this PR)

• Admission per chart type. Each template declares which presets it supports, next to navigation and reorder; admitInteractions() reads that first. Today's checks infer support from navigation axes, region gestures, and element semantics only.
• Phase 2: validation and discovery. validateChart() reports the same warnings; the MCP schema gains interaction_spec; list_chart_types gains interactions per chart type; the chart-author skill, docs/api-reference.md, a new docs/interaction-spec.md, and the generated chart reference gain sections.
• Spec API lab page. A coverage matrix of chart type by preset, a spec editor with a warnings panel, a two-spellings comparison, and merge-rule toggles.
• Phase 3: hosts and extensions. The MCP chart view and the site editor mount interactive charts from a spec; a declarative text template for click-annotate; an external-select binding; guide colours grounded from theme_spec.

🤖 Generated with Claude Code

[Chenglong Wang (Chenglong-MS)]

Let's move update / dismiss out of the interaction API?

[xavier (xavier-shaw)]

The update and dismiss are out of the API spec now.

updates left the spec in a8747bc. State arrives from the host through applyUpdate, setUpdates, dispatch, or options.updates. The spec describes behavior only.

dismiss left the spec and the code options in 1d5927c. Each interaction now owns a reset list (click-none, double-click, escape), so a gesture clears only the interactions that list it. The resolver rejects a spec that still carries either field.