@ggts-sh/svelte 0.43.0

package/dist/GGPlot.svelte.d.ts

@@ -0,0 +1,67 @@
+/**
+   * <GGPlot> — the props-first Svelte adapter (plan: "Svelte adapter").
+   *
+   * Guaranteed API: `spec={...}` or `data`/`aes`/`layers` props. Declaration-
+   * only children (<GeomPoint>/<GeomLine>) are OPTIONAL sugar; explicit
+   * `layers` props win over children when both are present.
+   *
+   * Reactivity: spec assembly is $derived; model production runs in the plot
+   * runtime with run-id gating; the committed scale
+   * state lives in a NON-reactive box (never read-modify-write shared reactive
+   * state across init/teardown — decision 0001, finding 3). That box is what
+   * makes discrete colors value-stable across data changes AND across
+   * brush-to-zoom respecs.
+   *
+   * M2 compositing (decision 0006): when any layer resolves to the canvas
+   * backend, the plot root becomes an ordered list of full-size sibling
+   * strata (SVG chrome-bottom, mark strata in svg/canvas, SVG chrome-top) —
+   * document order = paint order, no z-index anywhere. Every stratum is
+   * pointer-events: none; ONE transparent capture layer (last child) owns
+   * all pointer events and resolves them through the semantic viewport, so
+   * hover/tooltip/brush never care which stratum painted a mark. Hover,
+   * tooltip, and the transient brush are pure overlays — the pipeline NEVER
+   * re-runs for them. Brush-to-zoom is an intentional respec (explicit
+   * continuous domains via scale inversion) with prevScales flowing, so
+   * color assignments never shift. Double-click resets the zoom;
+   * resetScales() (component export) also clears grow-mode scale state.
+   *
+   * Memory (plan: "Memory ownership"): the previous RenderModel is disposed
+   * on commit ($effect cleanup — runs after the DOM has moved to the new
+   * model) and the last one on unmount.
+   *
+   * Controller wiring lives in `plot-engine.svelte.ts` (construction /
+   * effect-order contract documented there).
+   */
+import type { CellValue } from "@ggts-sh/core";
+import type { ZoomDomains } from "./interaction/interaction.js";
+import type { GGPlotProps } from "./plot-props.js";
+declare function $$render<Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row>(): {
+    props: GGPlotProps<Row, Identity>;
+    exports: {
+        resetScales: () => void;
+        setZoom: (domains: Partial<ZoomDomains>) => void;
+    };
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row> {
+    props(): ReturnType<typeof $$render<Row, Identity>>['props'];
+    events(): ReturnType<typeof $$render<Row, Identity>>['events'];
+    slots(): ReturnType<typeof $$render<Row, Identity>>['slots'];
+    bindings(): "";
+    exports(): {
+        resetScales: () => void;
+        setZoom: (domains: Partial<ZoomDomains>) => void;
+    };
+}
+interface $$IsomorphicComponent {
+    new <Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<Row, Identity>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<Row, Identity>['props']>, ReturnType<__sveltets_Render<Row, Identity>['events']>, ReturnType<__sveltets_Render<Row, Identity>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<Row, Identity>['bindings']>;
+    } & ReturnType<__sveltets_Render<Row, Identity>['exports']>;
+    <Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row>(internal: unknown, props: ReturnType<__sveltets_Render<Row, Identity>['props']> & {}): ReturnType<__sveltets_Render<Row, Identity>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+declare const GGPlot: $$IsomorphicComponent;
+type GGPlot<Row extends Record<string, CellValue> = Record<string, CellValue>, Identity extends keyof Row | ((row: Row, index: number) => PropertyKey) = keyof Row> = InstanceType<typeof GGPlot<Row, Identity>>;
+export default GGPlot;

package/dist/a11y/CanvasA11y.svelte

@@ -0,0 +1,115 @@
+<script lang="ts">
+  /**
+   * Canvas-stratum accessibility surface for GGPlot.
+   * Host owns shared open state (plot-scoped across canvas strata).
+   */
+  import type { GeometryBatch, RenderModel } from "@ggts-sh/core";
+
+  import { a11yMarkCount, a11yRows } from "./canvas-a11y.js";
+
+  const {
+    model,
+    batches,
+    sceneLabelText,
+    open,
+    onToggle,
+  }: {
+    model: RenderModel;
+    batches: GeometryBatch[];
+    sceneLabelText: string;
+    open: boolean;
+    onToggle: () => void;
+  } = $props();
+
+  // Closed: O(P) distinct-index count only (aria-label). Open: one full table
+  // build — reuse `table.total` so the primitive scan is not paid twice (#1329).
+  const table = $derived(open ? a11yRows(model, batches) : null);
+  const total = $derived(table === null ? a11yMarkCount(batches) : table.total);
+  const ariaLabel = $derived(
+    `${sceneLabelText} — ${String(total)} canvas-rendered marks. Canvas marks are not individually focusable; use the data table.`,
+  );
+</script>
+
+<div class="gg-canvas-a11y" role="img" aria-label={ariaLabel}></div>
+<button
+  type="button"
+  class="gg-a11y-toggle"
+  aria-expanded={open}
+  onclick={() => onToggle()}
+  >{open ? "Hide data table" : "Show data table"}</button
+>
+{#if open && table !== null}
+  <div class="gg-a11y-table">
+    <table>
+      <thead>
+        <tr>
+          {#each table.fields as field (field)}<th>{field}</th>{/each}
+        </tr>
+      </thead>
+      <tbody>
+        {#each table.rows as row, ri (ri)}
+          <tr>
+            {#each row as cell, ci (ci)}<td>{cell}</td>{/each}
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+    {#if table.total > table.rows.length}
+      <p>First {table.rows.length} of {table.total} rows.</p>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  /* Full-size inert layer base; sr-only clip below keeps it in the a11y tree. */
+  .gg-canvas-a11y {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  /* sr-only pattern (NOT display:none — must stay in the a11y tree). */
+  .gg-canvas-a11y,
+  .gg-a11y-toggle:not(:focus) {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .gg-a11y-toggle {
+    pointer-events: auto;
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    font-size: 11px;
+    line-height: 1.2;
+  }
+
+  .gg-a11y-table {
+    position: absolute;
+    inset: 0;
+    overflow: auto;
+    background: var(--gg-paper, #fff);
+    color: var(--gg-ink, #1f2328);
+    font-size: 11px;
+    line-height: 1.4;
+    pointer-events: auto;
+  }
+
+  .gg-a11y-table table {
+    border-collapse: collapse;
+  }
+
+  .gg-a11y-table th,
+  .gg-a11y-table td {
+    border: 1px solid var(--gg-grid, rgba(128, 128, 128, 0.4));
+    padding: 2px 6px;
+    text-align: left;
+  }
+</style>

package/dist/a11y/CanvasA11y.svelte.d.ts

@@ -0,0 +1,15 @@
+/**
+   * Canvas-stratum accessibility surface for GGPlot.
+   * Host owns shared open state (plot-scoped across canvas strata).
+   */
+import type { GeometryBatch, RenderModel } from "@ggts-sh/core";
+type $$ComponentProps = {
+    model: RenderModel;
+    batches: GeometryBatch[];
+    sceneLabelText: string;
+    open: boolean;
+    onToggle: () => void;
+};
+declare const CanvasA11y: import("svelte").Component<$$ComponentProps, {}, "">;
+type CanvasA11y = ReturnType<typeof CanvasA11y>;
+export default CanvasA11y;

package/dist/a11y/canvas-a11y.d.ts

@@ -0,0 +1 @@
+export { A11Y_TABLE_CAP, collectCanvasRowIndexes, a11yMarkCount, a11yRows, } from "@ggts-sh/core/interaction";

package/dist/a11y/canvas-a11y.js

@@ -0,0 +1,2 @@
+// Shared pure behavior used by React and Svelte.
+export { A11Y_TABLE_CAP, collectCanvasRowIndexes, a11yMarkCount, a11yRows, } from "@ggts-sh/core/interaction";

package/dist/assembly/assemble.d.ts

@@ -0,0 +1 @@
+export { assemblePortableSpec, isFacetedPlotIntent, mappedChannelField, resolveInteractionScope, toLayerInput, } from "@ggts-sh/compose";

package/dist/assembly/assemble.js

@@ -0,0 +1 @@
+export { assemblePortableSpec, isFacetedPlotIntent, mappedChannelField, resolveInteractionScope, toLayerInput, } from "@ggts-sh/compose";

package/dist/assembly/labels.d.ts

@@ -0,0 +1,43 @@
+import type { CellValue, RenderModel } from "@ggts-sh/core";
+import type { LegendFocusEvent, PlotInspectionChange, PlotSelection, ReadonlyZoomDomains } from "../interaction/interaction.js";
+/** Shared a11y count phrase: "1 datum" / "N data". */
+export declare function countLabel(count: number): string;
+/** Live message when the brush needs a second corner (pointer or keyboard). */
+export declare const BRUSH_SECOND_CORNER_ANNOUNCEMENT: "Choose opposite corner.";
+/**
+ * Live message for selection emission, or null when the phase does not announce
+ * (interval start/change).
+ */
+export declare function selectionAnnouncement(event: PlotSelection): string | null;
+/** Live message for legend-focus change/clear events. */
+export declare function legendFocusAnnouncement(event: LegendFocusEvent): string;
+/** Live message after a zoom commit or reset (`null` domains → reset). */
+export declare function zoomAnnouncement(domains: ReadonlyZoomDomains | null): string;
+/**
+ * Unique mapped field names across layers (first-seen order).
+ * Hosts that label many marks should call once per model and close over the
+ * result — `markLabel` / `datumLabel` recompute it per call (#1329).
+ */
+export declare function uniqueMappedFields(model: RenderModel): readonly string[];
+/** Label parts from a precomputed unique field list and a row record. */
+export declare function labelFromFields(fields: readonly string[], values: Record<string, CellValue>, emptyFallback: string): string;
+/** Accessible per-mark label from the layer's mapped fields. */
+export declare function markLabel(model: RenderModel | null, row: number): string;
+export declare function datumLabel(model: RenderModel | null, values: Record<string, CellValue> | null): string;
+export declare function inspectionLiveText(model: RenderModel | null, value: PlotInspectionChange<Record<string, CellValue>, PropertyKey>): string;
+/**
+ * Capture live-region text for the interaction ARIA live region.
+ *
+ * Priority (matches host `announcement || fallback`):
+ *   1. non-empty sticky `announcement` (including after microtask fill)
+ *   2. keyboard/touch inspection → `inspectionLiveText` (short-circuited)
+ *   3. otherwise empty string
+ *
+ * Empty-string announcement is falsy and falls through — host
+ * `announceInteraction` briefly sets `""` before the microtask message.
+ */
+export declare function resolveInteractionLiveText(input: {
+    readonly announcement: string;
+    readonly model: RenderModel | null;
+    readonly inspection: PlotInspectionChange<Record<string, CellValue>, PropertyKey> | null;
+}): string;

package/dist/assembly/labels.js

@@ -0,0 +1,126 @@
+import { collapseIdenticalDisplayMembers, formatTooltipCell, } from "../inspection/display-members.js";
+/** Shared a11y count phrase: "1 datum" / "N data". */
+export function countLabel(count) {
+    return `${String(count)} ${count === 1 ? "datum" : "data"}`;
+}
+/** Live message when the brush needs a second corner (pointer or keyboard). */
+export const BRUSH_SECOND_CORNER_ANNOUNCEMENT = "Choose opposite corner.";
+/**
+ * Live message for selection emission, or null when the phase does not announce
+ * (interval start/change).
+ */
+export function selectionAnnouncement(event) {
+    if (event.phase === "end") {
+        const count = event.mode === "point" ? event.keys.length : event.lineageCount;
+        return `Selection complete, ${countLabel(count)}.`;
+    }
+    if (event.phase === "clear")
+        return "Selection cleared.";
+    return null;
+}
+/** Live message for legend-focus change/clear events. */
+export function legendFocusAnnouncement(event) {
+    if (event.phase === "change") {
+        const verb = event.state === "committed" ? "focused" : "previewed";
+        return `${event.label} ${verb}, ${countLabel(event.keys.length)}.`;
+    }
+    return "Legend focus cleared.";
+}
+/** Live message after a zoom commit or reset (`null` domains → reset). */
+export function zoomAnnouncement(domains) {
+    return domains === null ? "Zoom reset." : "Zoom complete.";
+}
+/**
+ * Unique mapped field names across layers (first-seen order).
+ * Hosts that label many marks should call once per model and close over the
+ * result — `markLabel` / `datumLabel` recompute it per call (#1329).
+ */
+export function uniqueMappedFields(model) {
+    const seen = new Set();
+    const fields = [];
+    for (const layer of model.layerFields) {
+        if (layer === undefined)
+            continue;
+        for (const mapped of layer) {
+            if (seen.has(mapped.field))
+                continue;
+            seen.add(mapped.field);
+            fields.push(mapped.field);
+        }
+    }
+    return fields;
+}
+/** Label parts from a precomputed unique field list and a row record. */
+export function labelFromFields(fields, values, emptyFallback) {
+    if (fields.length === 0)
+        return emptyFallback;
+    const parts = [];
+    for (const field of fields)
+        parts.push(`${field} ${String(values[field] ?? "")}`);
+    return parts.join(", ");
+}
+/** Accessible per-mark label from the layer's mapped fields. */
+export function markLabel(model, row) {
+    if (model === null)
+        return `data point ${row + 1}`;
+    const values = model.row(row);
+    if (values === null)
+        return `data point ${row + 1}`;
+    return labelFromFields(uniqueMappedFields(model), values, `data point ${row + 1}`);
+}
+export function datumLabel(model, values) {
+    if (values === null)
+        return "No active datum";
+    if (model === null)
+        return labelFromFields([], values, "Active datum");
+    return labelFromFields(uniqueMappedFields(model), values, "Active datum");
+}
+export function inspectionLiveText(model, value) {
+    // Count distinct default-tooltip payloads so line+point same-data does not
+    // announce "2 data" for one observation (#385).
+    const axisFormatters = model?.axisFormatters ?? null;
+    const count = collapseIdenticalDisplayMembers(value.members, value.focus, axisFormatters, value.mode).length;
+    const state = value.state === "pinned" ? ", pinned" : "";
+    if (value.mode !== "x" && value.mode !== "y")
+        return `${datumLabel(model, value.focus.row)}; ${countLabel(count)}${state}`;
+    // Stat focus (no source row) formats x/y with axis formatters; identity keeps
+    // precise cell values (#1113).
+    const focusFormatters = value.focus.row === null ? axisFormatters : null;
+    const seen = new Set();
+    const focused = value.focus.fields
+        .filter((field) => {
+        if (field.channel === value.mode || seen.has(field.field))
+            return false;
+        seen.add(field.field);
+        return true;
+    })
+        .map((field) => {
+        const display = formatTooltipCell(field.value, {
+            channel: field.channel,
+            axisFormatters: focusFormatters,
+        });
+        return `${field.field} ${display}`;
+    })
+        .join(", ");
+    return `${value.mode} ${value.axisLabel}; ${countLabel(count)}${focused ? `; focused ${focused}` : ""}${state}`;
+}
+/**
+ * Capture live-region text for the interaction ARIA live region.
+ *
+ * Priority (matches host `announcement || fallback`):
+ *   1. non-empty sticky `announcement` (including after microtask fill)
+ *   2. keyboard/touch inspection → `inspectionLiveText` (short-circuited)
+ *   3. otherwise empty string
+ *
+ * Empty-string announcement is falsy and falls through — host
+ * `announceInteraction` briefly sets `""` before the microtask message.
+ */
+export function resolveInteractionLiveText(input) {
+    if (input.announcement)
+        return input.announcement;
+    if (input.inspection === null)
+        return "";
+    if (input.inspection.source === "keyboard" || input.inspection.source === "touch")
+        return inspectionLiveText(input.model, input.inspection);
+    return "";
+}

package/dist/assembly/layout.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Pure plot-root layout chrome: inline size/theme style, responsive
+ * breakpoint helpers, tooltip viewport clamp, and legend clear-control
+ * anchor lookup. Hosts own class bindings and tool-rail visibility.
+ */
+export type ResolvePlotSizeInput = {
+    /** Host width prop: fixed px, `"container"`, or omitted (container mode). */
+    readonly width: number | "container" | undefined;
+    readonly height: number | undefined;
+    /** ResizeObserver content width when in container mode; null before first measure. */
+    readonly containerWidth: number | null;
+    /** Assembled spec width fallback. */
+    readonly assembledWidth: number | undefined;
+    /** Assembled spec height fallback. */
+    readonly assembledHeight: number | undefined;
+};
+/**
+ * True when the width prop is omitted or `"container"` (responsive layout).
+ * Shared by resolvePlotSize, paint readiness widthMode, root class, ResizeObserver
+ * install, and plotRootInlineStyle containerWidth flag.
+ * Type predicate so fixed-mode branches narrow to `number`.
+ */
+export declare function isContainerWidthProp(width: number | "container" | undefined): width is "container" | undefined;
+/**
+ * Resolved plot pixel size for the pipeline and root style.
+ * Container mode: measured container width, then assembled, then
+ * DEFAULT_PLOT_WIDTH_PX (832). Fixed mode: the numeric width prop (assembled
+ * fallback is unused once fixed). Height: height prop, then assembled, then 400.
+ */
+export declare function resolvePlotSize(input: ResolvePlotSizeInput): {
+    readonly width: number;
+    readonly height: number;
+};
+/** True when the tool rail should use the narrow layout (width < 560). */
+export declare function isNarrowToolsWidth(widthPx: number): boolean;
+/**
+ * True when a pinned tooltip should dock (width < 480).
+ * Prefer `isTooltipDocked` at call sites that also gate on pin state.
+ */
+export declare function isDockedTooltipWidth(widthPx: number): boolean;
+/**
+ * Whether the inspection tooltip (and root docked chrome class) should dock.
+ * Unifies root class and Tooltip `docked` prop (both used pinned + width).
+ */
+export declare function isTooltipDocked(input: {
+    readonly inspectionState: "transient" | "pinned" | "none" | null | undefined;
+    readonly widthPx: number;
+}): boolean;
+/** Stable DOM id for the plot's inspection tooltip element. */
+export declare function plotTooltipDomId(plotId: string): string;
+/**
+ * Capture-surface `aria-controls` when a pinned interactive tooltip is up.
+ * Undefined otherwise (attribute omitted).
+ *
+ * Takes domain state (not pre-derived booleans) so hosts pass `inspection?.state`
+ * and inspect `contentMode` directly — same shape as `isTooltipDocked`.
+ */
+export declare function resolveCaptureAriaControls(input: {
+    readonly inspectionState: "transient" | "pinned" | "none" | null | undefined;
+    readonly contentMode: "interactive" | "informational" | undefined;
+    readonly plotId: string;
+}): string | undefined;
+export type TooltipViewportSizeInput = {
+    readonly sceneWidth: number;
+    readonly sceneHeight: number;
+    /** Host: `root?.clientWidth` — nullish falls back to scene; 0 is kept. */
+    readonly clientWidth: number | null | undefined;
+    /** Host: `root?.clientHeight` — nullish falls back to scene; 0 is kept. */
+    readonly clientHeight: number | null | undefined;
+};
+/**
+ * Tooltip layout box: min(scene, client) per axis.
+ * Uses nullish coalesce so a laid-out zero client size does not fall back
+ * to the scene (matches historical `root?.clientWidth ?? sceneWidth`).
+ */
+export declare function tooltipViewportSize(input: TooltipViewportSizeInput): {
+    readonly width: number;
+    readonly height: number;
+};
+export type PlotRootStyleInput = {
+    /**
+     * When true, emit width/height CSS before theme tokens.
+     * Host: hasCanvas || interactive || emphasis || selection.
+     */
+    readonly needsSizedBox: boolean;
+    /** True when the width prop is undefined or `"container"`. */
+    readonly containerWidth: boolean;
+    /** Fixed-width CSS uses scene dimensions (model scene with resolved fallback). */
+    readonly sceneWidth: number;
+    readonly sceneHeight: number;
+    readonly themeStyle: string;
+};
+/**
+ * Root `style` attribute value.
+ * Sized box: `width:…;height:…;` then raw `themeStyle` (no extra separator).
+ * Empty concatenation → `undefined` (matches host `… || undefined`).
+ */
+export declare function plotRootInlineStyle(input: PlotRootStyleInput): string | undefined;
+/** Edge/gap pad between a pressed legend box and the Clear recovery control. */
+export declare const CLEAR_CONTROL_GAP_PX = 4;
+/**
+ * Compact control height — matches discrete legend row targets (min 24px AA
+ * target size) rather than the old 44×44 AAA square that dwarfed swatches.
+ */
+export declare const CLEAR_CONTROL_HEIGHT_PX = 24;
+/** Grace period after pointer leaves legend chrome before Clear fades for screenshots. */
+export declare const CLEAR_HIDE_DELAY_MS = 2500;
+export type ClearControlLayoutInput = {
+    /**
+     * Host: `interactionConfig.legendFocus !== null`.
+     * Must stay even when `pressedScale` is non-null: controller emphasis can
+     * briefly leave a pressed scale after legend focus is disabled; Clear is
+     * intentionally suppressed then.
+     */
+    readonly legendFocusEnabled: boolean;
+    /** Host: `effectiveLegendPressed?.scale ?? null`. */
+    readonly pressedScale: string | null;
+    /** Scene legends — full box + position so Clear anchors off the pressed guide. */
+    readonly legends: readonly {
+        readonly scale: string;
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+        readonly position?: "right" | "bottom";
+        readonly direction?: "vertical" | "horizontal";
+    }[];
+    readonly sceneWidth: number;
+    readonly sceneHeight: number;
+};
+export type ClearControlLayout = {
+    readonly left: number;
+    readonly top: number;
+};
+/**
+ * Scene-local position for the legend Clear recovery control, or null to hide.
+ *
+ * Placement (collision-safe relative to the pressed legend):
+ * - **right / vertical** — prefer **below** the stack; if that would clamp into
+ *   the legend box (tall low guide), try **above**, then **left** of the box
+ * - **bottom / horizontal** — prefer **right** of the strip; else under, then above
+ *
+ * Candidates are clamped into the scene, then the first that does not intersect
+ * the pressed legend box wins. null when focus is off / nothing pressed / no match.
+ */
+export declare function resolveClearControlLayout(input: ClearControlLayoutInput): ClearControlLayout | null;
+/**
+ * Whether the Clear control should paint (opacity / pointer-events) while a
+ * series remains pressed. Host owns the hide timer; this pure gate only
+ * combines pressed + chrome hover/focus + elapsed hide.
+ */
+export declare function shouldRevealClearControl(input: {
+    readonly pressed: boolean;
+    /** Pointer over legend targets/clear, or focus within that chrome. */
+    readonly chromeActive: boolean;
+    /** True once the post-leave hide delay has elapsed without re-entry. */
+    readonly hideElapsed: boolean;
+}): boolean;