insomni-plot 0.1.0-alpha.0

package/src/grammar/interactions/selection.ts

@@ -0,0 +1,142 @@
+// ---------------------------------------------------------------------------
+// Grammar-level click-selection wiring
+// ---------------------------------------------------------------------------
+// Subscribes to the shared `GrammarHitLayer` for press events. Each press is
+// routed through the generic `Selection<string>` primitive — plain click
+// replaces, shift toggles, meta/ctrl removes — and a background tap clears.
+// Selection state is exposed through `onChange(HoveredHit[])`; the mount
+// projects this onto `MountedPlot.selected` and `CompileContext.selected`.
+//
+// Selection IDs are `${geomKind}:${dataIndex}:${seriesKey?}`, stable across
+// re-renders as long as the row stays in `data` at the same index (and the
+// same segment key for multi-series hits). When data reshuffles the stale ids
+// drop on the next sync (their position lookup misses).
+
+import { createSelection, type InteractionManager, type Selection } from "insomni";
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import type { GrammarHitLayer, HitEventContext } from "./hit-layer.ts";
+import { createDisposable } from "./_disposable.ts";
+
+export interface GrammarSelectionOptions {
+  /**
+   * Fired whenever the selection set changes. Receives a fresh array of
+   * `HoveredHit`s (one per currently-selected row) so callers can mirror it
+   * onto a public signal or run side-effects.
+   */
+  onChange?(selected: HoveredHit[]): void;
+}
+
+export interface GrammarSelectionDeps {
+  manager: InteractionManager;
+  hitLayer: GrammarHitLayer;
+}
+
+export interface GrammarSelection {
+  /** Refresh id→position registry after each pipeline run. */
+  sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+  /** Read-only snapshot of the current selection. */
+  current(): HoveredHit[];
+  /** Imperatively clear the selection (e.g., from outside on Escape). */
+  clear(): void;
+  dispose(): void;
+}
+
+function idFor(geomKind: string, dataIndex: number, seriesKey?: string): string {
+  return `${geomKind}:${dataIndex}:${seriesKey ?? ""}`;
+}
+
+export function createGrammarSelection(
+  deps: GrammarSelectionDeps,
+  opts: GrammarSelectionOptions = {},
+): GrammarSelection {
+  const selection: Selection<string> = createSelection<string>();
+  // Map<id, HoveredHit> — used to project Selection<string> back to the
+  // public HoveredHit[] payload. Updated on every sync so positions stay
+  // current as the chart redraws.
+  const idToHit = new Map<string, HoveredHit>();
+
+  const emit = () => {
+    const out: HoveredHit[] = [];
+    for (const id of selection.values()) {
+      const hit = idToHit.get(id);
+      if (hit) out.push(hit);
+    }
+    opts.onChange?.(out);
+  };
+
+  selection.onChange(emit);
+
+  const unsubscribeBgTap = deps.manager.onBackgroundTap(() => {
+    selection.clear();
+  });
+
+  const unsubscribeHits = deps.hitLayer.subscribe({
+    key: "selection",
+    onPress(ctx: HitEventContext) {
+      const id = idFor(ctx.hit.geomKind, ctx.hit.dataIndex, ctx.hit.seriesKey);
+      // Refresh hit registry for this id so the projected HoveredHit has
+      // the freshest position; sync() will overwrite again next frame.
+      idToHit.set(id, ctx.hit);
+      selection.pressFromEvent(id, ctx.pointer.mods);
+    },
+  });
+
+  const refreshIdMap = <T>(hits: readonly CompiledHitTest<T>[]) => {
+    idToHit.clear();
+    for (const hit of hits) {
+      const positions = hit.positions;
+      const indices = hit.dataIndex;
+      const n = indices.length;
+      for (let i = 0; i < n; i++) {
+        const dataIdx = indices[i]!;
+        const seriesKey = hit.seriesKey?.[i];
+        const id = idFor(hit.geomKind, dataIdx, seriesKey);
+        idToHit.set(id, {
+          geomKind: hit.geomKind,
+          dataIndex: dataIdx,
+          seriesKey,
+          data: hit.data as readonly unknown[],
+          x: positions[i * 2]!,
+          y: positions[i * 2 + 1]!,
+        });
+      }
+    }
+  };
+
+  const d = createDisposable(() => {
+    unsubscribeBgTap();
+    unsubscribeHits();
+    idToHit.clear();
+  });
+
+  return {
+    sync(hits) {
+      if (d.isDisposed) return;
+      const before = selection.size;
+      refreshIdMap(hits);
+      // Drop selection ids whose row is no longer present (data array changed
+      // or index filtered out). Emit only when something actually drops.
+      const stale: string[] = [];
+      for (const id of selection.values()) {
+        if (!idToHit.has(id)) stale.push(id);
+      }
+      for (const id of stale) selection.delete(id);
+      // Emit when there was a prior selection: covers both rows dropping
+      // out (selection shrunk) and positions on still-selected rows shifting
+      // after a re-layout, so consumers always see fresh coords.
+      if (before > 0) emit();
+    },
+    current() {
+      const out: HoveredHit[] = [];
+      for (const id of selection.values()) {
+        const hit = idToHit.get(id);
+        if (hit) out.push(hit);
+      }
+      return out;
+    },
+    clear() {
+      selection.clear();
+    },
+    dispose: () => d.dispose(),
+  };
+}

package/src/grammar/interactions/series-readout.d.ts

@@ -0,0 +1,91 @@
+import { type Color, type Frame, type InteractionManager, type Invalidator } from "insomni";
+import type { CompiledHitTest, ScaleBundle } from "../geoms/types.ts";
+import type { Theme } from "../theme.ts";
+import type { GrammarHitLayer } from "./hit-layer.ts";
+import { collectLayerGroups, overrideGroupPick, resolveGroupKey } from "./series-snap.ts";
+export interface SeriesReadoutRow {
+    /** Series name (color-channel value) or layer label. */
+    label: string;
+    /** Formatted display value (raw y at the snapped x). */
+    value: string;
+    /** Series swatch color, when the layer has a color channel. */
+    color?: Color;
+    /** True for the row whose snapped position is closest to the cursor. */
+    active: boolean;
+}
+export interface SeriesReadoutSnapshot {
+    /** Formatted snapped x (from the closest layer). */
+    x: string;
+    /** Raw snapped x value (column-typed). Useful for custom formatting. */
+    xValue: unknown;
+    /** One row per series across all layers, in original layer + series order. */
+    rows: readonly SeriesReadoutRow[];
+}
+export type SeriesReadoutFormat = {
+    /** Format the snapped x for the panel title. Default: `defaultFormat`. */
+    x?: (value: unknown) => string;
+    /** Format each per-series y value. Default: `defaultFormat`. */
+    y?: (value: unknown) => string;
+};
+export type SeriesReadoutPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export interface SeriesReadoutUi {
+    /** Element to append the panel into (typically the chart's stage). */
+    mount: HTMLElement;
+    /** Corner inside `mount`. Default `"top-right"`. */
+    position?: SeriesReadoutPosition;
+    /** Inset (px) from the chosen corner. Default `12`. */
+    inset?: number;
+}
+export interface AttachSeriesReadoutOptions {
+    /** DOM mount info. Omit to run headless and observe via `subscribe`. */
+    ui?: SeriesReadoutUi;
+    /**
+     * How to pick a hit per series.
+     * - `"nearest-x"` (default): the hit with smallest |x − cursorX|. Best for
+     *   time-series readouts; one row per series at the cursor's x.
+     * - `"hover"`: only show rows while the cursor is over a real hit (the
+     *   tooltip-style behavior, but extended to every series in the chart).
+     */
+    snap?: "nearest-x" | "hover";
+    /** Per-channel formatters. */
+    format?: SeriesReadoutFormat;
+    /** Hide when the cursor leaves the plot frame. Default `true`. */
+    hideOnLeave?: boolean;
+    /** Notified whenever the snapshot changes (incl. with `ui` attached). */
+    onChange?(snapshot: SeriesReadoutSnapshot | null): void;
+}
+export interface AttachedSeriesReadout {
+    peek(): SeriesReadoutSnapshot | null;
+    subscribe(fn: (snapshot: SeriesReadoutSnapshot | null) => void): () => void;
+    dispose(): void;
+}
+export interface SeriesReadoutDeps {
+    manager: InteractionManager;
+    /** Plot-frame bounds (absolute element-CSS px). */
+    bounds: () => Frame;
+    /** Latest resolved scales (for color swatches). */
+    scales: () => ScaleBundle | null;
+    theme: () => Theme;
+    invalidator: Invalidator;
+    /**
+     * Optional shared hit-layer. When provided, the readout also subscribes to
+     * its hover events so the panel stays populated while the cursor is over a
+     * real mark (where high-z hit-cloud nodes claim hover and the readout's own
+     * low-z pointer node never fires).
+     */
+    hitLayer?: GrammarHitLayer;
+}
+/** Internal handle used by the mount to push fresh hit-tests in. */
+export interface SeriesReadoutInternal extends AttachedSeriesReadout {
+    syncHits<T>(hits: readonly CompiledHitTest<T>[]): void;
+}
+export declare function createSeriesReadout(deps: SeriesReadoutDeps, opts: AttachSeriesReadoutOptions): SeriesReadoutInternal;
+declare function snapshotEqual(a: SeriesReadoutSnapshot | null, b: SeriesReadoutSnapshot | null): boolean;
+/** @internal — exposed for unit tests only. */
+export declare const __test__: {
+    collectLayerGroups: typeof collectLayerGroups;
+    resolveGroupKey: typeof resolveGroupKey;
+    overrideGroupPick: typeof overrideGroupPick;
+    snapshotEqual: typeof snapshotEqual;
+};
+export {};