@ggts-sh/svelte 0.43.0

package/dist/plot-props.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Internal props contract for <GGPlot> + the plot engine (#1040).
+ * Not part of the public package surface — never export from the package root.
+ *
+ * Runtime helpers here own:
+ * - capability defaults (`resolveCapabilities`)
+ * - PublicKey → PropertyKey widening for engine controllers (`widenPlotProps`)
+ */
+import type { Snippet } from "svelte";
+import type { A11yMode, AesInput, DataInput, LayerInput, PortableSpec, SpecInput } from "@ggts-sh/spec";
+import type { CellValue, RenderModel } from "@ggts-sh/core";
+import type { PlotDiagnostic } from "./diagnostics/deprecation.js";
+import type { InspectInput, InteractionTool, LegendFocusEvent, LegendFocusInput, PlotInspection, PlotInteractionEvent, PlotInteractionScope, PlotSelection, SelectInput, ZoomEvent, ZoomInput } from "./interaction/interaction.js";
+import type { PlotInteractionController } from "./interaction/controller.svelte.js";
+import type { LegendFilterEvent, LegendFilterInput } from "./legend/filter.js";
+type PublicKey<Row extends Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey)> = Identity extends keyof Row ? Extract<Row[Identity], PropertyKey> : Identity extends (row: Row, index: number) => infer Key ? Extract<Key, PropertyKey> : never;
+/**
+ * Props for `<GGPlot>`. Grammar pieces (theme, scales, coord, facet, labs,
+ * guides, legend) are declaration-only children — not props (#704 / #659).
+ * Removed from the prop surface in 0.13.0 (deprecated since 0.11.0).
+ */
+export interface GGPlotProps<Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row> {
+    /** A complete spec (bare-string channel shorthand allowed). Wins over the other props. */
+    spec?: SpecInput;
+    /** Data rows, columns, or a DataRef ({values}/{columns}/{name}). */
+    data?: DataInput | readonly Row[];
+    /** Plot-level aesthetic mapping (inherited by every layer). */
+    aes?: AesInput;
+    /** Layers (props-first canonical form). Wins over declaration-only children. */
+    layers?: LayerInput[];
+    /** Accessibility mode ("force-svg" keeps every layer as SVG marks). */
+    a11y?: A11yMode;
+    /** Plot width in px. Omitted is container-responsive. */
+    width?: number | "container";
+    /** Plot height in px (falls back to spec.height, then 400). */
+    height?: number;
+    /**
+     * @deprecated since 0.21.0 — use `identity` on `<Inspect>`, object-form
+     * `select={{ type, identity }}`, or `createPlotInteraction({ identity })`.
+     * Still honoured (dual-read) until 0.22.0; emits DEPRECATED_PLOT_PROP.
+     * Default when no surface sets identity: `id` column when present, else
+     * row index. Ordinary charts should omit identity entirely.
+     * Migration: https://ggts.sh/guide/upgrading#row-identity-on-interaction
+     */
+    key?: Identity;
+    /** Opt into inspection, its semantic crosshair, tooltip, and pinning. */
+    inspect?: InspectInput;
+    /** Opt into point or interval selection. */
+    select?: SelectInput;
+    /** Opt into brush zoom. */
+    zoom?: ZoomInput;
+    /**
+     * @deprecated since 0.19.0 — use `<GuideLegend channel="…" focus />` instead.
+     * Still honoured (plot-wide enablement) until 0.20.0; emits DEPRECATED_PLOT_PROP.
+     * Migration: https://ggts.sh/guide/upgrading#legend-focus-on-guidelegend
+     */
+    legendFocus?: LegendFocusInput;
+    /**
+     * @deprecated since 0.19.0 — use `<GuideLegend channel="…" filter />` instead.
+     * Still honoured (plot-wide enablement) until 0.20.0; emits DEPRECATED_PLOT_PROP.
+     * Migration: https://ggts.sh/guide/upgrading#legend-filter-on-guidelegend
+     */
+    legendFilter?: LegendFilterInput;
+    /** Controlled initial/active tool. */
+    tool?: InteractionTool;
+    /** Optional durable semantic state shared with other plots and Svelte UI. */
+    interaction?: PlotInteractionController<PublicKey<Row, Identity>>;
+    /** Semantic identity for linked keys and positional domains. */
+    interactionScope?: PlotInteractionScope;
+    /** Accessible chart name; falls back to the plot title/generated label. */
+    ariaLabel?: string;
+    oninspect?: (event: PlotInspection<Row, PublicKey<Row, Identity>>) => void;
+    onselect?: (event: PlotSelection<PublicKey<Row, Identity>>) => void;
+    onzoom?: (event: ZoomEvent) => void;
+    onlegendfocus?: (event: LegendFocusEvent<PublicKey<Row, Identity>>) => void;
+    onlegendfilter?: (event: LegendFilterEvent) => void;
+    oninteraction?: (event: PlotInteractionEvent<Row, PublicKey<Row, Identity>>) => void;
+    ondiagnostic?: (diagnostic: PlotDiagnostic) => void;
+    ontoolchange?: (tool: InteractionTool) => void;
+    /** Called after each committed render with the model (warnings,
+     *  advisories, scales) and the normalized PortableSpec. */
+    onrender?: (model: RenderModel, spec: PortableSpec) => void;
+    children?: Snippet;
+}
+/** Capability defaults after optional props resolve (engine-facing). */
+export type ResolvedPlotCapabilities = {
+    inspect: InspectInput;
+    select: SelectInput;
+    zoom: ZoomInput;
+    legendFocus: LegendFocusInput;
+    legendFilter: LegendFilterInput;
+};
+/**
+ * Defaults the five interaction capability props to `false` when omitted.
+ * Pure — does not clone object-form configs (identity preserved for epoch
+ * and reference-equality consumers).
+ *
+ * Input is a plain bag (not `Pick<GGPlotProps, …>`) so dual-read of the
+ * deprecated `legendFocus` / `legendFilter` props does not trip
+ * `typescript/no-deprecated` at every resolveCapabilities call site during
+ * the 0.19→0.20 window.
+ */
+export declare function resolveCapabilities(props: {
+    readonly inspect?: InspectInput;
+    readonly select?: SelectInput;
+    readonly zoom?: ZoomInput;
+    readonly legendFocus?: LegendFocusInput;
+    readonly legendFilter?: LegendFilterInput;
+}): ResolvedPlotCapabilities;
+/**
+ * Read the deprecated plot-level `key` prop during the dual-read window.
+ * Prefer Inspect / Select / createPlotInteraction `identity` instead.
+ */
+export declare function readLegacyPlotKey(props: EnginePlotProps | GGPlotProps): EnginePlotProps["key"] | undefined;
+/**
+ * Read the deprecated plot-level `legendFocus` prop during the dual-read
+ * window. Isolate the deprecation access so call sites stay clean.
+ */
+export declare function readLegacyPlotLegendFocus(props: EnginePlotProps | GGPlotProps): LegendFocusInput | undefined;
+/**
+ * Read the deprecated plot-level `legendFilter` prop during the dual-read
+ * window. Isolate the deprecation access so call sites stay clean.
+ */
+export declare function readLegacyPlotLegendFilter(props: EnginePlotProps | GGPlotProps): LegendFilterInput | undefined;
+/**
+ * Engine-facing props: same surface as `GGPlotProps` with the six
+ * PublicKey-generic fields widened to PropertyKey (controller deps).
+ * Derived via `Omit` — not a hand-restated 30-field mirror (#1040).
+ */
+export type EnginePlotProps = Omit<GGPlotProps, "key" | "interaction" | "oninspect" | "onselect" | "onlegendfocus" | "oninteraction"> & {
+    key?: PropertyKey | ((row: Record<string, CellValue>, index: number) => PropertyKey);
+    interaction?: PlotInteractionController;
+    oninspect?: (event: PlotInspection<Record<string, CellValue>>) => void;
+    onselect?: (event: PlotSelection) => void;
+    onlegendfocus?: (event: LegendFocusEvent) => void;
+    oninteraction?: (event: PlotInteractionEvent<Record<string, CellValue>>) => void;
+};
+/**
+ * Stable lazy view of plot props for the engine. Non-widened fields forward
+ * through the source proxy (per-field reactive deps). The six PublicKey
+ * fields cast once here instead of at the GGPlot call site.
+ */
+export declare function widenPlotProps<Row extends Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey)>(props: GGPlotProps<Row, Identity>): EnginePlotProps;
+export {};

package/dist/plot-props.js

@@ -0,0 +1,81 @@
+/**
+ * Defaults the five interaction capability props to `false` when omitted.
+ * Pure — does not clone object-form configs (identity preserved for epoch
+ * and reference-equality consumers).
+ *
+ * Input is a plain bag (not `Pick<GGPlotProps, …>`) so dual-read of the
+ * deprecated `legendFocus` / `legendFilter` props does not trip
+ * `typescript/no-deprecated` at every resolveCapabilities call site during
+ * the 0.19→0.20 window.
+ */
+export function resolveCapabilities(props) {
+    return {
+        inspect: props.inspect ?? false,
+        select: props.select ?? false,
+        zoom: props.zoom ?? false,
+        legendFocus: props.legendFocus ?? false,
+        legendFilter: props.legendFilter ?? false,
+    };
+}
+/**
+ * Read the deprecated plot-level `key` prop during the dual-read window.
+ * Prefer Inspect / Select / createPlotInteraction `identity` instead.
+ */
+export function readLegacyPlotKey(props) {
+    // Dual-read until 0.22.0 — prefer interaction-surface identity.
+    // oxlint-disable-next-line typescript/no-deprecated -- intentional dual-read
+    return props.key;
+}
+/**
+ * Read the deprecated plot-level `legendFocus` prop during the dual-read
+ * window. Isolate the deprecation access so call sites stay clean.
+ */
+export function readLegacyPlotLegendFocus(props) {
+    // Dual-read until 0.20.0 — prefer <GuideLegend focus>.
+    // oxlint-disable-next-line typescript/no-deprecated -- intentional dual-read
+    return props.legendFocus;
+}
+/**
+ * Read the deprecated plot-level `legendFilter` prop during the dual-read
+ * window. Isolate the deprecation access so call sites stay clean.
+ */
+export function readLegacyPlotLegendFilter(props) {
+    // Dual-read until 0.20.0 — prefer <GuideLegend filter>.
+    // oxlint-disable-next-line typescript/no-deprecated -- intentional dual-read
+    return props.legendFilter;
+}
+/**
+ * Stable lazy view of plot props for the engine. Non-widened fields forward
+ * through the source proxy (per-field reactive deps). The six PublicKey
+ * fields cast once here instead of at the GGPlot call site.
+ */
+export function widenPlotProps(props) {
+    const handler = {
+        get(target, prop, receiver) {
+            // Six precise casts — only these fields change assignability.
+            if (prop === "key") {
+                // Dual-read until 0.22.0 — prefer interaction-surface identity.
+                // oxlint-disable-next-line typescript/no-deprecated -- intentional dual-read
+                return target.key;
+            }
+            if (prop === "interaction") {
+                return target.interaction;
+            }
+            if (prop === "oninspect") {
+                return target.oninspect;
+            }
+            if (prop === "onselect") {
+                return target.onselect;
+            }
+            if (prop === "onlegendfocus") {
+                return target.onlegendfocus;
+            }
+            if (prop === "oninteraction") {
+                return target.oninteraction;
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    };
+    // Proxy of GGPlotProps is the EnginePlotProps view; bridge via unknown once.
+    return new Proxy(props, handler);
+}

package/dist/runtime/announcer.svelte.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Plot live-region announcer extracted from GGPlot shared services.
+ *
+ * Pure refactor host: move body verbatim; no behavior change.
+ */
+export type PlotAnnouncer = {
+    readonly text: string;
+    announce(message: string): void;
+    clear(): void;
+};
+/**
+ * Owns the interaction live-region string: clear then set after a microtask
+ * so re-announcements of the same message still fire for assistive tech.
+ * `clear` is synchronous and queues nothing — a queued blank would run after
+ * (and swallow) a message announced earlier in the same tick.
+ */
+export declare function createPlotAnnouncer(): PlotAnnouncer;

package/dist/runtime/announcer.svelte.js

@@ -0,0 +1,28 @@
+/**
+ * Plot live-region announcer extracted from GGPlot shared services.
+ *
+ * Pure refactor host: move body verbatim; no behavior change.
+ */
+/**
+ * Owns the interaction live-region string: clear then set after a microtask
+ * so re-announcements of the same message still fire for assistive tech.
+ * `clear` is synchronous and queues nothing — a queued blank would run after
+ * (and swallow) a message announced earlier in the same tick.
+ */
+export function createPlotAnnouncer() {
+    let interactionAnnouncement = $state("");
+    return {
+        get text() {
+            return interactionAnnouncement;
+        },
+        announce(message) {
+            interactionAnnouncement = "";
+            queueMicrotask(() => {
+                interactionAnnouncement = message;
+            });
+        },
+        clear() {
+            interactionAnnouncement = "";
+        },
+    };
+}

package/dist/runtime/paint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Canvas first-paint readiness for GGPlot compositing.
+ *
+ * Readiness waits until every canvas stratum of the current model run has
+ * painted at least once. Tracking is by distinct stratum key (not raw
+ * notification count) so a re-attached canvas cannot mark the plot ready
+ * before sibling strata paint.
+ */
+export type PlotReadyInput = {
+    readonly hasModel: boolean;
+    readonly widthMode: "fixed" | "container";
+    readonly containerHasPositiveWidth: boolean;
+    readonly hasCanvas: boolean;
+    /** True when every canvas stratum of the current model run has painted. */
+    readonly paintComplete: boolean;
+};
+/**
+ * VR / screenshot readiness predicate for `[data-gg-ready]`.
+ * Container width must be positive only when width is container-responsive.
+ * Canvas plots additionally require paintComplete.
+ */
+export declare function isPlotReady(input: PlotReadyInput): boolean;
+export type PaintLedger = {
+    /** Record that a canvas stratum painted for `runId`. */
+    notify(runId: number, stratumKey: string): void;
+    /** Distinct strata painted for the current run. */
+    readonly paintedCount: number;
+    /** Run id of the current paint set, or -1 before any notify. */
+    readonly paintedRunId: number;
+    /**
+     * True when `runId` matches the ledger run and at least `canvasCount`
+     * distinct stratum keys have notified. `canvasCount === 0` is complete
+     * only when the ledger run already matches (including the initial -1 run).
+     */
+    isComplete(runId: number, canvasCount: number): boolean;
+};
+/** Mutable paint ledger owned by one GGPlot instance. */
+export declare function createPaintLedger(): PaintLedger;

package/dist/runtime/paint.js

@@ -0,0 +1,45 @@
+/**
+ * Canvas first-paint readiness for GGPlot compositing.
+ *
+ * Readiness waits until every canvas stratum of the current model run has
+ * painted at least once. Tracking is by distinct stratum key (not raw
+ * notification count) so a re-attached canvas cannot mark the plot ready
+ * before sibling strata paint.
+ */
+/**
+ * VR / screenshot readiness predicate for `[data-gg-ready]`.
+ * Container width must be positive only when width is container-responsive.
+ * Canvas plots additionally require paintComplete.
+ */
+export function isPlotReady(input) {
+    if (!input.hasModel)
+        return false;
+    if (input.widthMode === "container" && !input.containerHasPositiveWidth)
+        return false;
+    if (input.hasCanvas && !input.paintComplete)
+        return false;
+    return true;
+}
+/** Mutable paint ledger owned by one GGPlot instance. */
+export function createPaintLedger() {
+    let paintedRunId = -1;
+    const paintedKeys = new Set();
+    return {
+        notify(runId, stratumKey) {
+            if (paintedRunId !== runId) {
+                paintedRunId = runId;
+                paintedKeys.clear();
+            }
+            paintedKeys.add(stratumKey);
+        },
+        get paintedCount() {
+            return paintedKeys.size;
+        },
+        get paintedRunId() {
+            return paintedRunId;
+        },
+        isComplete(runId, canvasCount) {
+            return paintedRunId === runId && paintedKeys.size >= canvasCount;
+        },
+    };
+}

package/dist/runtime/resolve-datum-key.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resolve durable row identity for interaction (selection, legend focus, pin
+ * rebind, linked controllers).
+ *
+ * Plot authors should not need a custom identity for ordinary charts:
+ * 1. Interaction-surface identity (Inspect / Select / controller) when set.
+ * 2. Deprecated GGPlot `key` dual-read (until removal).
+ * 3. Else if plot data exposes a PropertyKey-valued `id` column → use `"id"`.
+ * 4. Else use the row index (order-stable only — not reorder-safe).
+ *
+ * Index identity is enough for single-plot legend focus / inspect / local
+ * selection. Custom durable identity across reorders or non-`id` natural keys
+ * belongs on Inspect / Select / createPlotInteraction — not plot grammar.
+ */
+import type { CellValue } from "@ggts-sh/core";
+export type DatumKey = PropertyKey | ((row: Record<string, CellValue>, index: number) => PropertyKey);
+/**
+ * Explicit identity sources. Prefer interaction surfaces over the deprecated
+ * plot-level `key` prop. First defined wins in this order.
+ */
+export type ExplicitDatumKeySources = {
+    /** `<Inspect identity=…>` or `inspect={{ identity: … }}`. */
+    readonly inspect?: DatumKey;
+    /** `select={{ type, identity: … }}`. */
+    readonly select?: DatumKey;
+    /** `createPlotInteraction({ identity })` when bound via `interaction=`. */
+    readonly controller?: DatumKey;
+    /** Deprecated GGPlot `key` dual-read (prefer interaction-surface identity). */
+    readonly legacy?: DatumKey;
+};
+export type ResolveDatumKeyInput = {
+    /**
+     * Already-picked explicit identity (from {@link pickExplicitDatumKey} or a
+     * single override). Wins over auto `id` / row-index defaults.
+     */
+    readonly explicit?: DatumKey;
+    /** Plot data input (row array, DataRef, or bare columns map). */
+    readonly data?: unknown;
+};
+/**
+ * Pick the first defined identity from interaction surfaces, then legacy
+ * GGPlot `key`. Returns `undefined` when no surface supplies an override.
+ */
+export declare function pickExplicitDatumKey(sources: ExplicitDatumKeySources): DatumKey | undefined;
+/** Read `identity` from object-form `select` (string shorthand has none). */
+export declare function identityFromSelectInput(input: false | string | {
+    readonly identity?: DatumKey;
+} | undefined): DatumKey | undefined;
+/**
+ * Resolve the datum-key used by the plot engine.
+ * Always returns a key strategy — never `undefined`.
+ */
+export declare function resolveDatumKey(input: ResolveDatumKeyInput): DatumKey;

package/dist/runtime/resolve-datum-key.js

@@ -0,0 +1,73 @@
+/**
+ * Pick the first defined identity from interaction surfaces, then legacy
+ * GGPlot `key`. Returns `undefined` when no surface supplies an override.
+ */
+export function pickExplicitDatumKey(sources) {
+    if (sources.inspect !== undefined)
+        return sources.inspect;
+    if (sources.select !== undefined)
+        return sources.select;
+    if (sources.controller !== undefined)
+        return sources.controller;
+    if (sources.legacy !== undefined)
+        return sources.legacy;
+    return undefined;
+}
+/** Read `identity` from object-form `select` (string shorthand has none). */
+export function identityFromSelectInput(input) {
+    if (input === undefined || input === false || typeof input === "string")
+        return undefined;
+    return input.identity;
+}
+/** Row-index identity — default when no `id` column and no explicit key. */
+function rowIndexDatumKey(_row, index) {
+    return index;
+}
+/** True when `value` is a legal PropertyKey for semantic row identity. */
+function isPropertyKeyIdentity(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "symbol";
+}
+/**
+ * Detect a usable `id` column on plot data (first cell must be PropertyKey).
+ * Does not scan every row for uniqueness — invalid/duplicate keys still emit
+ * INTERACTION_* key diagnostics at resolve time.
+ */
+function dataHasIdIdentityColumn(data) {
+    if (data === null || data === undefined)
+        return false;
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return false;
+        const row = data[0];
+        if (row === null || typeof row !== "object" || Array.isArray(row))
+            return false;
+        return isPropertyKeyIdentity(row["id"]);
+    }
+    if (typeof data !== "object")
+        return false;
+    const record = data;
+    // DataRef { values: Row[] }
+    if (Array.isArray(record["values"]))
+        return dataHasIdIdentityColumn(record["values"]);
+    // DataRef { columns: { id: [...] } } or bare column map with id array
+    const columns = record["columns"] !== null &&
+        typeof record["columns"] === "object" &&
+        !Array.isArray(record["columns"])
+        ? record["columns"]
+        : record;
+    const idColumn = columns["id"];
+    if (!Array.isArray(idColumn) || idColumn.length === 0)
+        return false;
+    return isPropertyKeyIdentity(idColumn[0]);
+}
+/**
+ * Resolve the datum-key used by the plot engine.
+ * Always returns a key strategy — never `undefined`.
+ */
+export function resolveDatumKey(input) {
+    if (input.explicit !== undefined)
+        return input.explicit;
+    if (dataHasIdIdentityColumn(input.data))
+        return "id";
+    return rowIndexDatumKey;
+}

package/dist/runtime/runtime.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { RenderModel, Stratum } from "@ggts-sh/core";
+import type { PortableSpec } from "@ggts-sh/spec";
+import type { LegendFilterClause } from "../legend/filter.js";
+import type { ReadonlyZoomDomains } from "../interaction/interaction.js";
+export type PlotRuntimeDeps = {
+    widthProp: () => number | "container" | undefined;
+    heightProp: () => number | undefined;
+    assembled: () => PortableSpec | null;
+    effectiveSpec: () => PortableSpec | null;
+    effectiveZoomDomains: () => ReadonlyZoomDomains | null;
+    effectiveLegendFilters: () => readonly LegendFilterClause[];
+    root: () => HTMLDivElement | null;
+    /** Silent zoom clear owned by the S4 zoom controller (`resetForScales`). */
+    resetZoom: () => void;
+    /**
+     * Getter for the onrender callback. The dispose/onrender effects wrap the
+     * getter invocation in `untrack` so callback identity is not a dependency
+     * (matches GGPlot.svelte:677-680).
+     */
+    onrender: () => ((model: RenderModel, spec: PortableSpec) => void) | undefined;
+};
+export type PlotRuntime = {
+    readonly model: RenderModel | null;
+    readonly resolvedWidth: number;
+    readonly resolvedHeight: number;
+    readonly strata: readonly Stratum[];
+    readonly hasCanvas: boolean;
+    readonly ready: boolean;
+    notifyPainted(runId: number, stratumKey: string): void;
+    resetScales(): void;
+};
+/**
+ * Create the plot runtime. Construction registers ResizeObserver, model
+ * dispose/onrender, and clientFlush effects (#627). Dep getters must not be
+ * invoked during construction for construction-time deriveds.
+ */
+export declare function createPlotRuntime(deps: PlotRuntimeDeps): PlotRuntime;