@ggts-sh/svelte 0.43.0

package/dist/legend/filter-state.svelte.js

@@ -0,0 +1,284 @@
+import { encodeKey } from "@ggts-sh/core";
+import { isLegendValueKeyVisible, isLegendValueVisible, legendFilterValueKeys, nextLegendFilterValues, reconcileLegendFilterValues, } from "./filter.js";
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+const FILTERABLE_LEGEND_SCALES = [
+    "color",
+    "fill",
+    "size",
+    "linewidth",
+    "alpha",
+    "shape",
+    "linetype",
+];
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the legend-filter controller. Construction registers capability-reset,
+ * mode-reset, and catalog-reconcile effects (#627).
+ */
+export function createLegendFilterState(deps) {
+    const legendFilterOptions = $derived.by(() => {
+        const legendFilter = deps.legendFilterProp();
+        if (legendFilter === false)
+            return null;
+        return {
+            mode: typeof legendFilter === "object" ? (legendFilter.mode ?? "exclude") : "exclude",
+            multiple: typeof legendFilter === "object" ? (legendFilter.multiple ?? true) : true,
+        };
+    });
+    let localLegendFilters = $state([]);
+    let appliedLegendFilterMode = $state(null);
+    const legendCatalogFingerprints = new Map();
+    const activeLegendFilterBindings = $derived.by(() => {
+        const bindings = new Set();
+        const effectiveSpec = deps.effectiveSpec();
+        if (effectiveSpec === null)
+            return bindings;
+        for (const layer of effectiveSpec.layers) {
+            for (const scale of FILTERABLE_LEGEND_SCALES) {
+                const own = layer.aes?.[scale];
+                // Explicit null is an unset (normalize's null-unset semantics): the
+                // layer deliberately removed the plot-level binding — never inherit.
+                if (own === null)
+                    continue;
+                const channel = own ?? effectiveSpec.aes?.[scale];
+                if (channel !== null && channel !== undefined && "field" in channel)
+                    bindings.add(`${scale}:${channel.field}`);
+            }
+        }
+        return bindings;
+    });
+    const effectiveLegendFilters = $derived(legendFilterOptions === null
+        ? []
+        : localLegendFilters.filter((clause) => activeLegendFilterBindings.has(`${clause.scale}:${clause.field}`)));
+    let legendFilterPointerType = null;
+    function emitLegendFilter(event) {
+        deps.onlegendfilter()?.(event);
+        deps.oninteraction()?.(event);
+    }
+    // A disabled capability or a remapped spec must never leave an invisible
+    // filter active. Reset the chart-local filter set atomically so the public
+    // `clear` event always describes the actual resulting state.
+    $effect(() => {
+        if (effectiveLegendFilters.length === localLegendFilters.length)
+            return;
+        localLegendFilters = [];
+        emitLegendFilter({
+            type: "legend-filter",
+            phase: "clear",
+            source: "programmatic",
+            clause: null,
+        });
+        deps.announce("Legend filters reset after the filter capability changed.");
+    });
+    // Mode changes are controlled API changes, not reinterpretations of old
+    // state. Reset active clauses so an exclude set can never become a stale
+    // include set (or vice versa).
+    $effect(() => {
+        const mode = legendFilterOptions?.mode ?? null;
+        if (appliedLegendFilterMode === null) {
+            appliedLegendFilterMode = mode;
+            return;
+        }
+        if (mode === appliedLegendFilterMode)
+            return;
+        appliedLegendFilterMode = mode;
+        if (localLegendFilters.length === 0)
+            return;
+        localLegendFilters = [];
+        emitLegendFilter({
+            type: "legend-filter",
+            phase: "clear",
+            source: "programmatic",
+            clause: null,
+        });
+        deps.announce("Legend filters reset after the filter mode changed.");
+    });
+    function computeEntries(model) {
+        if (model === null || legendFilterOptions === null)
+            return [];
+        return model.scene.legends.flatMap((sceneLegend) => {
+            if (sceneLegend.type !== "discrete" || sceneLegend.interactive === false)
+                return [];
+            if (!FILTERABLE_LEGEND_SCALES.some((scale) => scale === sceneLegend.scale))
+                return [];
+            const fields = new Set(model.layerFields
+                .flat()
+                .filter((mapped) => mapped.channel === sceneLegend.scale && mapped.source !== "stat")
+                .map((mapped) => mapped.field));
+            const field = fields.values().next().value;
+            // One combined scale fed by unlike fields has no honest one-toggle
+            // filtering semantics. Keep the static legend rather than filtering
+            // only whichever field happened to be encountered first.
+            if (field === undefined || fields.size !== 1)
+                return [];
+            // A scaled constant (aes { value, scale: true }) feeds this legend
+            // without a field: toggling its entry would filter an unrelated field
+            // while the constant-colored layer stays rendered. Keep it static —
+            // but only when that constant is actually a *visible* legend entry.
+            // Rowless annotation constants train the scale and appear on
+            // layerScaledConstants for focus/index, yet are excluded from the
+            // interactive legend domain (#598); those must not disable filters.
+            const scaledConstantKeys = new Set(model.layerScaledConstants
+                .map((constants) => constants[sceneLegend.scale])
+                .filter((value) => value !== undefined)
+                .map((value) => encodeKey(value)));
+            if (scaledConstantKeys.size > 0 &&
+                sceneLegend.entries.some((entry) => scaledConstantKeys.has(encodeKey(entry.value))))
+                return [];
+            const current = localLegendFilters.find((clause) => clause.scale === sceneLegend.scale && clause.field === field);
+            if (current === undefined) {
+                return sceneLegend.entries.map((entry) => ({
+                    legend: sceneLegend,
+                    entry,
+                    field,
+                    visible: true,
+                }));
+            }
+            // One Set per clause, then O(1) membership per entry (O(E+V) not O(E×V)).
+            const valueKeys = legendFilterValueKeys(current.values);
+            const mode = current.mode;
+            return sceneLegend.entries.map((entry) => ({
+                legend: sceneLegend,
+                entry,
+                field,
+                visible: isLegendValueKeyVisible(valueKeys, entry.value, mode),
+            }));
+        });
+    }
+    function legendFilterSource(event) {
+        if (event.detail === 0)
+            return "keyboard";
+        return legendFilterPointerType === "touch" ? "touch" : "pointer";
+    }
+    function toggle(target, event) {
+        if (legendFilterOptions === null)
+            return target.visible;
+        // Controlled checkbox: cancel the UA toggle when this still runs inside
+        // the click event. Delegated/async handlers can miss that window — the
+        // host forces input.checked from the returned visibility.
+        event.preventDefault();
+        const catalog = target.legend.entries.map((entry) => entry.value);
+        const index = localLegendFilters.findIndex((clause) => clause.scale === target.legend.scale && clause.field === target.field);
+        const current = localLegendFilters[index];
+        const baseline = current?.values ?? (legendFilterOptions.mode === "include" ? catalog : []);
+        const values = nextLegendFilterValues(baseline, target.entry.value, catalog, legendFilterOptions.mode, legendFilterOptions.multiple);
+        const clause = Object.freeze({
+            scale: target.legend.scale,
+            field: target.field,
+            values,
+            mode: legendFilterOptions.mode,
+        });
+        localLegendFilters =
+            index < 0
+                ? [...localLegendFilters, clause]
+                : localLegendFilters.map((candidate, candidateIndex) => candidateIndex === index ? clause : candidate);
+        const source = legendFilterSource(event);
+        legendFilterPointerType = null;
+        const visible = isLegendValueVisible(values, target.entry.value, legendFilterOptions.mode);
+        const filterEvent = Object.freeze({
+            type: "legend-filter",
+            phase: "change",
+            source,
+            clause,
+        });
+        emitLegendFilter(filterEvent);
+        deps.announce(`${target.entry.label} ${visible ? "shown" : "hidden"}.`);
+        return visible;
+    }
+    function reset(event) {
+        if (localLegendFilters.length === 0)
+            return;
+        // Focus restoration is owned by the child component (zero DOM here).
+        const source = legendFilterSource(event);
+        localLegendFilters = [];
+        legendFilterPointerType = null;
+        emitLegendFilter(Object.freeze({
+            type: "legend-filter",
+            phase: "clear",
+            source,
+            clause: null,
+        }));
+    }
+    function setPointerType(type) {
+        legendFilterPointerType = type;
+    }
+    // Catalog changes prune values that no longer exist. An emptied clause is
+    // removed, so a category that disappears and later returns is visible by
+    // default. resetScales() deliberately does not alter this filter state.
+    $effect(() => {
+        const catalogs = new Map();
+        for (const target of deps.catalogEntries()) {
+            const key = `${target.legend.scale}:${target.field}`;
+            const catalog = catalogs.get(key) ?? [];
+            catalog.push(target.entry.value);
+            catalogs.set(key, catalog);
+        }
+        let next = localLegendFilters;
+        const reconciled = [];
+        // A clause whose field is still mapped but whose legend stopped being
+        // filterable (second unlike field on the scale, a scaled constant, a
+        // non-discrete legend) has no checkbox or reset control left — remove it
+        // rather than filtering rows invisibly. Unmapped fields are handled by
+        // the capability reset above.
+        if (deps.model() !== null && legendFilterOptions !== null) {
+            for (const clause of next.filter((candidate) => activeLegendFilterBindings.has(`${candidate.scale}:${candidate.field}`) &&
+                !catalogs.has(`${candidate.scale}:${candidate.field}`))) {
+                next = next.filter((candidate) => candidate !== clause);
+                reconciled.push({ clause, removed: true });
+            }
+        }
+        for (const [key, catalog] of catalogs) {
+            const fingerprint = JSON.stringify(catalog.map((value) => encodeKey(value)));
+            const priorFingerprint = legendCatalogFingerprints.get(key);
+            legendCatalogFingerprints.set(key, fingerprint);
+            if (priorFingerprint === undefined || priorFingerprint === fingerprint)
+                continue;
+            const index = next.findIndex((clause) => `${clause.scale}:${clause.field}` === key);
+            if (index < 0)
+                continue;
+            const clause = next[index];
+            const values = reconcileLegendFilterValues(clause.values, catalog);
+            reconciled.push({
+                clause: Object.freeze({ ...clause, values }),
+                removed: values.length === 0,
+            });
+            next =
+                values.length === 0
+                    ? next.filter((_, candidateIndex) => candidateIndex !== index)
+                    : next.map((candidate, candidateIndex) => candidateIndex === index ? Object.freeze({ ...candidate, values }) : candidate);
+        }
+        for (const key of legendCatalogFingerprints.keys())
+            if (!catalogs.has(key))
+                legendCatalogFingerprints.delete(key);
+        if (next === localLegendFilters)
+            return;
+        localLegendFilters = [...next];
+        for (const { clause, removed } of reconciled)
+            emitLegendFilter({
+                type: "legend-filter",
+                phase: removed ? "remove" : "change",
+                source: "programmatic",
+                clause,
+            });
+        deps.announce("Legend filters reconciled with the available groups.");
+    });
+    return {
+        get options() {
+            return legendFilterOptions;
+        },
+        get filters() {
+            return effectiveLegendFilters;
+        },
+        get hasActiveFilters() {
+            return localLegendFilters.length > 0;
+        },
+        computeEntries,
+        toggle,
+        reset,
+        setPointerType,
+    };
+}

package/dist/legend/filter.d.ts

@@ -0,0 +1 @@
+export { type LegendFilterClause, type LegendFilterOptions, type LegendFilterInput, type LegendFilterEvent, legendFilterValueKeys, isLegendValueKeyVisible, isLegendValueVisible, reconcileLegendFilterValues, nextLegendFilterValues, } from "@ggts-sh/core/interaction";

package/dist/legend/filter.js

@@ -0,0 +1,2 @@
+// Shared pure behavior used by React and Svelte.
+export { legendFilterValueKeys, isLegendValueKeyVisible, isLegendValueVisible, reconcileLegendFilterValues, nextLegendFilterValues, } from "@ggts-sh/core/interaction";

package/dist/legend/focus-emphasis.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure legend emphasis helpers: pressed-identity, preview decisions, and
+ * effective emphasis key precedence (preview / controller / local).
+ *
+ * Identity/roving: `focus.ts`. Host `$effect` plans: `focus-plans.ts`.
+ */
+import type { InteractionSource } from "../interaction/interaction.js";
+import { type InteractiveLegendEntry, type LegendEntryIdentity, type LegendInteractionSource } from "./focus.js";
+export type FindLegendPressedIdentityInput = {
+    readonly keys: readonly PropertyKey[];
+    readonly entries: readonly InteractiveLegendEntry[];
+    readonly keyIndex: ReadonlyMap<string, readonly PropertyKey[]>;
+    readonly committed: {
+        readonly identity: LegendEntryIdentity;
+        readonly keys: readonly PropertyKey[];
+    } | null;
+};
+/**
+ * Resolve which legend entry should appear pressed.
+ * Committed identity wins when its key set still matches (even if multiple
+ * entries share the same keys). Otherwise require exactly one matching entry.
+ *
+ * Complexity: O(K + E) — one Set for the emphasis keys, then per-entry size
+ * short-circuit + membership (no Set rebuild per entry). Multi-match returns
+ * null as soon as a second hit is found. Empty keys, or empty entries with no
+ * committed identity, return before allocating the Set.
+ */
+export declare function findLegendPressedIdentity(input: FindLegendPressedIdentityInput): LegendEntryIdentity | null;
+/**
+ * Decide what a legend preview attempt should do with resolved keys.
+ * Empty key sets clear any active preview (empty domain entry / stale target)
+ * rather than leaving the previous entry highlighted.
+ *
+ * Non-empty `set` carries mapped InteractionSource via `legendInteractionSource`
+ * so the host does not re-map `action.source` after the pure decision.
+ */
+export declare function resolveLegendPreviewKeysDecision(input: {
+    readonly keys: readonly PropertyKey[];
+    /** Host: `action.source` (legend entry interaction source). */
+    readonly entrySource: LegendInteractionSource;
+}): {
+    readonly type: "clear";
+} | {
+    readonly type: "set";
+    readonly keys: readonly PropertyKey[];
+    readonly source: InteractionSource;
+};
+/**
+ * Emphasis keys shown while legend focus is enabled vs disabled.
+ * When disabled, chart-local preview and local commits must not mute the plot
+ * (controls are gone). Controller emphasis still flows through when present.
+ */
+export declare function resolveLegendEmphasisKeys(input: {
+    readonly legendFocusEnabled: boolean;
+    readonly previewKeys: readonly PropertyKey[] | null;
+    readonly controllerKeys: readonly PropertyKey[] | null;
+    readonly localKeys: readonly PropertyKey[];
+}): readonly PropertyKey[];
+export type LegendPreviewState = {
+    readonly identity: LegendEntryIdentity;
+    readonly keys: readonly PropertyKey[];
+};
+/**
+ * Reconcile a transient preview against the current entry list / key index.
+ * Clears when the identity disappears or its keys empty; refreshes keys when
+ * membership changes for the same identity.
+ */
+export declare function reconcileLegendPreview(input: {
+    readonly preview: LegendPreviewState | null;
+    readonly entries: readonly InteractiveLegendEntry[];
+    readonly keyIndex: ReadonlyMap<string, readonly PropertyKey[]>;
+}): LegendPreviewState | null;

package/dist/legend/focus-emphasis.js

@@ -0,0 +1,91 @@
+import { keysForLegendEntry, legendInteractionSource, samePropertyKeySet, } from "./focus.js";
+/**
+ * Whether a first-seen-unique key array matches a Set's membership.
+ * Used by pressed-identity resolution so entry compares stay O(K) without
+ * allocating a Set per legend entry. Entry-key index values and committed
+ * keys are frozen unique arrays from `buildLegendEntryKeyIndex`.
+ */
+function uniqueKeysMatchSet(keys, keySet) {
+    if (keys.length !== keySet.size)
+        return false;
+    for (const key of keys)
+        if (!keySet.has(key))
+            return false;
+    return true;
+}
+/**
+ * Resolve which legend entry should appear pressed.
+ * Committed identity wins when its key set still matches (even if multiple
+ * entries share the same keys). Otherwise require exactly one matching entry.
+ *
+ * Complexity: O(K + E) — one Set for the emphasis keys, then per-entry size
+ * short-circuit + membership (no Set rebuild per entry). Multi-match returns
+ * null as soon as a second hit is found. Empty keys, or empty entries with no
+ * committed identity, return before allocating the Set.
+ */
+export function findLegendPressedIdentity(input) {
+    if (input.keys.length === 0)
+        return null;
+    // Ramp-only / no discrete legends and no commit: nothing to match (issue #209).
+    if (input.entries.length === 0 && input.committed === null)
+        return null;
+    const inputSet = new Set(input.keys);
+    if (input.committed !== null && uniqueKeysMatchSet(input.committed.keys, inputSet))
+        return input.committed.identity;
+    let match = null;
+    for (const entry of input.entries) {
+        const entryKeys = keysForLegendEntry(input.keyIndex, entry.identity);
+        if (!uniqueKeysMatchSet(entryKeys, inputSet))
+            continue;
+        if (match !== null)
+            return null;
+        match = entry.identity;
+    }
+    return match;
+}
+/**
+ * Decide what a legend preview attempt should do with resolved keys.
+ * Empty key sets clear any active preview (empty domain entry / stale target)
+ * rather than leaving the previous entry highlighted.
+ *
+ * Non-empty `set` carries mapped InteractionSource via `legendInteractionSource`
+ * so the host does not re-map `action.source` after the pure decision.
+ */
+export function resolveLegendPreviewKeysDecision(input) {
+    if (input.keys.length === 0)
+        return { type: "clear" };
+    return {
+        type: "set",
+        keys: input.keys,
+        source: legendInteractionSource(input.entrySource),
+    };
+}
+/**
+ * Emphasis keys shown while legend focus is enabled vs disabled.
+ * When disabled, chart-local preview and local commits must not mute the plot
+ * (controls are gone). Controller emphasis still flows through when present.
+ */
+export function resolveLegendEmphasisKeys(input) {
+    if (!input.legendFocusEnabled)
+        return input.controllerKeys ?? [];
+    return input.previewKeys ?? input.controllerKeys ?? input.localKeys;
+}
+/**
+ * Reconcile a transient preview against the current entry list / key index.
+ * Clears when the identity disappears or its keys empty; refreshes keys when
+ * membership changes for the same identity.
+ */
+export function reconcileLegendPreview(input) {
+    if (input.preview === null)
+        return null;
+    const current = input.entries.find(({ identity }) => identity.scale === input.preview.identity.scale &&
+        identity.entryIndex === input.preview.identity.entryIndex);
+    if (current === undefined)
+        return null;
+    const keys = keysForLegendEntry(input.keyIndex, current.identity);
+    if (keys.length === 0)
+        return null;
+    if (samePropertyKeySet(keys, input.preview.keys))
+        return input.preview;
+    return { identity: current.identity, keys };
+}

package/dist/legend/focus-plans.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure host `$effect` plans for legend focus (committed reconcile, disable
+ * clear, roving focus sync). Controllers own DOM / emission side effects.
+ *
+ * Identity/roving: `focus.ts`. Emphasis/preview: `focus-emphasis.ts`.
+ */
+import { type InteractiveLegendEntry, type LegendEntryIdentity } from "./focus.js";
+export type LegendCommittedState = {
+    readonly identity: LegendEntryIdentity;
+    readonly keys: readonly PropertyKey[];
+};
+export type LegendCommittedReconcilePlan = {
+    readonly type: "noop";
+} | {
+    readonly type: "clear-committed";
+} | {
+    readonly type: "clear-committed-local-emit";
+};
+/**
+ * Pure plan for the committed-legend reconcile effect after data reshuffle.
+ *
+ * Owns entry lookup + key compare (same shape as `reconcileLegendPreview`).
+ * Host on non-noop: always nulls `legendCommitted`. On local-emit also clears
+ * chart-local emphasis keys and emits legend-focus clear.
+ *
+ *   1. no commit → noop
+ *   2. live keys still match → noop
+ *   3. mismatch + local emphasis active → clear-committed-local-emit
+ *   4. mismatch otherwise → clear-committed
+ */
+export declare function planLegendCommittedReconcile(input: {
+    readonly committed: LegendCommittedState | null;
+    readonly entries: readonly InteractiveLegendEntry[];
+    readonly keyIndex: ReadonlyMap<string, readonly PropertyKey[]>;
+    /** Host: `interaction === undefined`. */
+    readonly usesLocalEmphasis: boolean;
+    readonly localEmphasisCount: number;
+}): LegendCommittedReconcilePlan;
+export type LegendFocusDisabledClearPlan = {
+    readonly type: "noop";
+} | {
+    readonly type: "clear-host";
+} | {
+    readonly type: "clear-host-local";
+};
+/**
+ * Pure plan when legend focus is turned off at runtime.
+ *
+ *   1. still enabled → noop
+ *   2. host legend state already empty → noop
+ *   3. chart-local mode → clear preview+committed+localEmphasisKeys
+ *   4. controller mode → clear preview+committed only (controller emphasis stays)
+ */
+export declare function planLegendFocusDisabledClear(input: {
+    readonly legendFocusEnabled: boolean;
+    readonly hasPreview: boolean;
+    readonly hasCommitted: boolean;
+    readonly hasLocalEmphasis: boolean;
+    /** Host: `interaction === undefined`. */
+    readonly usesLocalEmphasis: boolean;
+}): LegendFocusDisabledClearPlan;
+export type LegendRovingFocusSyncPlan = {
+    readonly type: "noop";
+    readonly nextIndex: number;
+} | {
+    readonly type: "clamp-roving";
+    readonly nextIndex: number;
+} | {
+    readonly type: "refocus";
+    readonly nextIndex: number;
+    readonly returnIndex: number;
+};
+/**
+ * Pure plan for the legend roving-index `$effect.pre`.
+ *
+ * Host owns `document.activeElement` / dataset parse for `focusedIndex`.
+ * `Number(dataset.index)` yields NaN when missing — pass that through so
+ * `clampLegendRovingIndex` maps non-finite → 0 (refocus first entry).
+ *
+ *   - focusedIndex === null OR entryCount === 0 → no DOM refocus
+ *     (clamp-roving when nextIndex differs from current, else noop)
+ *   - otherwise → refocus with returnIndex = clamp(focusedIndex, count)
+ */
+export declare function planLegendRovingFocusSync(input: {
+    readonly currentRoving: number;
+    readonly entryCount: number;
+    /** null = focus not on a legend target inside root; may be NaN. */
+    readonly focusedIndex: number | null;
+}): LegendRovingFocusSyncPlan;

package/dist/legend/focus-plans.js

@@ -0,0 +1,72 @@
+/**
+ * Pure host `$effect` plans for legend focus (committed reconcile, disable
+ * clear, roving focus sync). Controllers own DOM / emission side effects.
+ *
+ * Identity/roving: `focus.ts`. Emphasis/preview: `focus-emphasis.ts`.
+ */
+import { clampLegendRovingIndex, keysForLegendEntry, samePropertyKeySet, } from "./focus.js";
+/**
+ * Pure plan for the committed-legend reconcile effect after data reshuffle.
+ *
+ * Owns entry lookup + key compare (same shape as `reconcileLegendPreview`).
+ * Host on non-noop: always nulls `legendCommitted`. On local-emit also clears
+ * chart-local emphasis keys and emits legend-focus clear.
+ *
+ *   1. no commit → noop
+ *   2. live keys still match → noop
+ *   3. mismatch + local emphasis active → clear-committed-local-emit
+ *   4. mismatch otherwise → clear-committed
+ */
+export function planLegendCommittedReconcile(input) {
+    if (input.committed === null)
+        return { type: "noop" };
+    const current = input.entries.find(({ identity }) => identity.scale === input.committed.identity.scale &&
+        identity.entryIndex === input.committed.identity.entryIndex);
+    const currentKeys = current === undefined ? [] : keysForLegendEntry(input.keyIndex, current.identity);
+    if (samePropertyKeySet(currentKeys, input.committed.keys))
+        return { type: "noop" };
+    if (input.usesLocalEmphasis && input.localEmphasisCount > 0) {
+        return { type: "clear-committed-local-emit" };
+    }
+    return { type: "clear-committed" };
+}
+/**
+ * Pure plan when legend focus is turned off at runtime.
+ *
+ *   1. still enabled → noop
+ *   2. host legend state already empty → noop
+ *   3. chart-local mode → clear preview+committed+localEmphasisKeys
+ *   4. controller mode → clear preview+committed only (controller emphasis stays)
+ */
+export function planLegendFocusDisabledClear(input) {
+    if (input.legendFocusEnabled)
+        return { type: "noop" };
+    if (!input.hasPreview && !input.hasCommitted && !input.hasLocalEmphasis) {
+        return { type: "noop" };
+    }
+    return input.usesLocalEmphasis ? { type: "clear-host-local" } : { type: "clear-host" };
+}
+/**
+ * Pure plan for the legend roving-index `$effect.pre`.
+ *
+ * Host owns `document.activeElement` / dataset parse for `focusedIndex`.
+ * `Number(dataset.index)` yields NaN when missing — pass that through so
+ * `clampLegendRovingIndex` maps non-finite → 0 (refocus first entry).
+ *
+ *   - focusedIndex === null OR entryCount === 0 → no DOM refocus
+ *     (clamp-roving when nextIndex differs from current, else noop)
+ *   - otherwise → refocus with returnIndex = clamp(focusedIndex, count)
+ */
+export function planLegendRovingFocusSync(input) {
+    const nextIndex = clampLegendRovingIndex(input.currentRoving, input.entryCount);
+    if (input.focusedIndex === null || input.entryCount === 0) {
+        return nextIndex === input.currentRoving
+            ? { type: "noop", nextIndex }
+            : { type: "clamp-roving", nextIndex };
+    }
+    return {
+        type: "refocus",
+        nextIndex,
+        returnIndex: clampLegendRovingIndex(input.focusedIndex, input.entryCount),
+    };
+}

package/dist/legend/focus-reconcile.svelte.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Host-derived reconcile effects for the legend-focus controller (S5).
+ *
+ * Hosts the four reconcile effects previously registered inside
+ * focus-state.installHostDerivedEffects: roving-index sync ($effect.pre),
+ * committed reconcile, preview reconcile, and focus-disabled clear.
+ *
+ * Registration happens synchronously inside installHostDerivedEffects — the
+ * late-hook ordering is intentional: these effects must not register before
+ * the host declares the entry/pressed deriveds that the controller's compute*
+ * methods feed (#627).
+ *
+ * Ports are LIVE getters/setters over the controller's rune state — never
+ * snapshots. Shared controller emphasis survives disable while local emphasis
+ * clears (planLegendFocusDisabledClear "clear-host" vs "clear-host-local").
+ */
+import type { PlotInteractionController } from "../interaction/controller.svelte.js";
+import type { LegendFocusEvent } from "../interaction/interaction.js";
+import type { ScopedStore } from "../interaction/scoped-store.svelte.js";
+import { type InteractiveLegendEntry, type LegendEntryAction, type LegendEntryIdentity } from "./focus.js";
+import type { LegendEntryKeyAccess } from "./entry-key-index.svelte.js";
+export type LegendFocusPreviewState = {
+    action: LegendEntryAction;
+    keys: readonly PropertyKey[];
+} | null;
+export type LegendFocusCommittedState = {
+    identity: LegendEntryIdentity;
+    keys: readonly PropertyKey[];
+} | null;
+export type LegendFocusReconcilePorts = {
+    readonly entries: () => readonly InteractiveLegendEntry[];
+    readonly entryKeys: () => LegendEntryKeyAccess;
+    readonly root: () => HTMLElement | null;
+    readonly interaction: () => PlotInteractionController | undefined;
+    readonly legendFocusEnabled: () => boolean;
+    /** Emphasis store — local shadow when controller-driven, source of truth local. */
+    readonly emphasisKeys: ScopedStore<readonly PropertyKey[]>;
+    /** Live accessors over the controller's rune state (never snapshotted). */
+    readonly rovingIndex: () => number;
+    readonly setRovingIndex: (next: number) => void;
+    readonly committed: () => LegendFocusCommittedState;
+    readonly setCommitted: (next: LegendFocusCommittedState) => void;
+    readonly preview: () => LegendFocusPreviewState;
+    readonly setPreview: (next: LegendFocusPreviewState) => void;
+    readonly emitLegendFocus: (event: LegendFocusEvent) => void;
+    readonly previewLegend: (action: LegendEntryAction | null) => void;
+};
+/**
+ * Register the four reconcile effects. Called synchronously from
+ * `installHostDerivedEffects` while the component initializes — never from a
+ * callback or after init.
+ */
+export declare function installLegendFocusReconcileEffects(ports: LegendFocusReconcilePorts): void;