insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,422 @@
+// ---------------------------------------------------------------------------
+// Grammar-level series-readout — dygraph-style pinned legend
+// ---------------------------------------------------------------------------
+// Renders a side panel that updates as the cursor moves across the plot
+// frame, showing each series' value at the snapped x (one row per series,
+// grouped by `color` channel for multi-series layers). Reuses the compiled
+// hit-tests for snapping; coordinates flow through a low-zIndex pointer node
+// that overlays the plot frame so hover events on individual marks still win.
+//
+// Comes in two flavors:
+//   - DOM-attached:  `opts.ui = { mount, position, inset }` builds and tracks
+//                    a small absolute-positioned panel.
+//   - Headless:      omit `opts.ui`; subscribe to `snapshot` changes and roll
+//                    your own UI (Svelte / React / Solid / whatever).
+//
+// Mirrors the `attach-presets` shape — controller-first, optional DOM layer.
+
+import {
+  type Color,
+  type Frame,
+  type InteractionManager,
+  type InteractionNode,
+  type Invalidator,
+} from "insomni";
+import type { CompiledHitTest, ScaleBundle } from "../geoms/types.ts";
+import type { Theme } from "../theme.ts";
+import { createDisposable } from "./_disposable.ts";
+import type { GrammarHitLayer } from "./hit-layer.ts";
+import { defaultFormat } from "./tooltip.ts";
+import {
+  collectLayerGroups,
+  computeSnap,
+  overrideGroupPick,
+  resolveGroupColor,
+  resolveGroupKey,
+} from "./series-snap.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Internal: dependencies + factory
+// ---------------------------------------------------------------------------
+
+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 function createSeriesReadout(
+  deps: SeriesReadoutDeps,
+  opts: AttachSeriesReadoutOptions,
+): SeriesReadoutInternal {
+  const snap = opts.snap ?? "nearest-x";
+  const hideOnLeave = opts.hideOnLeave !== false;
+  const formatX = opts.format?.x ?? defaultFormat;
+  const formatY = opts.format?.y ?? defaultFormat;
+  const subscribers = new Set<(snapshot: SeriesReadoutSnapshot | null) => void>();
+  if (opts.onChange) {
+    subscribers.add((snapshot) => opts.onChange!(snapshot));
+  }
+
+  let activeHits: readonly CompiledHitTest<unknown>[] = [];
+  let cursorX: number | null = null;
+  let snapshot: SeriesReadoutSnapshot | null = null;
+
+  function emit(next: SeriesReadoutSnapshot | null): void {
+    if (snapshotEqual(snapshot, next)) return;
+    snapshot = next;
+    panel?.render(snapshot);
+    for (const fn of subscribers) fn(snapshot);
+  }
+
+  function recompute(): void {
+    if (d.isDisposed) return;
+    if (cursorX === null || activeHits.length === 0) {
+      emit(null);
+      return;
+    }
+    // The hit-layer owns "which hit is active" — read its live state rather
+    // than caching dispatch events, so the active row stays anchored across a
+    // chart re-render (state() re-dereferences from the slot).
+    const active = deps.hitLayer?.state().active ?? null;
+    const scales = deps.scales();
+    const result = computeSnap({
+      hits: activeHits,
+      cursor: cursorX,
+      axis: "x",
+      snap,
+      active,
+    });
+    if (result === null) {
+      emit(null);
+      return;
+    }
+    const rows: SeriesReadoutRow[] = result.groups.map((g) => ({
+      label: g.label,
+      value: formatY(g.yValue),
+      color: g.color ?? resolveGroupColor(g, scales),
+      active: snap === "hover" ? true : g.id === result.activeId,
+    }));
+    emit({
+      x: formatX(result.columnValue),
+      xValue: result.columnValue,
+      rows,
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Pointer tracking — low-zIndex node over the plot frame. Hit-cloud nodes
+  // sit at Z_HIT_CLOUD_BASE (1000+) so any tooltip / selection cloud still
+  // claims hover ahead of us. When the cursor crosses an actual mark we
+  // never get a hover event, but the `recompute` we already triggered on
+  // entering the frame keeps the panel populated — `nearest-x` doesn't
+  // care whether the cursor sits ON a hit, only what x it's at.
+  // -----------------------------------------------------------------------
+
+  // When the cursor sits over a hit (high-z point cloud claims the hover),
+  // our own low-z plot-frame node never fires — track `cursorX` off the
+  // shared hit-layer's enter events instead.
+  //
+  // The hit-layer is the source of truth for "which hit is active". Our
+  // `recompute` reads it via `state()`; here we just subscribe to enter
+  // events for cursor tracking and to `subscribeState` for invalidation so
+  // the panel re-renders the moment the dispatched hit changes (or its
+  // underlying compiled is swapped by a sync).
+  const unsubscribeHit = deps.hitLayer?.subscribe({
+    key: "series-readout",
+    onHoverEnter: (ctx) => {
+      cursorX = ctx.pointer.x;
+      // recompute fires from the state subscription below.
+    },
+    onPress: (ctx) => {
+      // Touch tap: update cursor position so the panel populates immediately.
+      cursorX = ctx.pointer.x;
+    },
+  });
+  const unsubscribeState = deps.hitLayer?.subscribeState(() => {
+    recompute();
+  });
+
+  const node: InteractionNode = deps.manager.add({
+    space: "ui",
+    bounds: deps.bounds,
+    // Negative so this never wins hover claims against engine/user nodes.
+    zIndex: -2,
+    onHoverEnter: (info) => {
+      cursorX = info.x;
+      recompute();
+    },
+    onHoverMove: (info) => {
+      cursorX = info.x;
+      recompute();
+    },
+    onHoverLeave: () => {
+      if (!hideOnLeave) return;
+      cursorX = null;
+      emit(null);
+    },
+  });
+
+  // -----------------------------------------------------------------------
+  // DOM panel — optional. Re-renders on each snapshot change.
+  // -----------------------------------------------------------------------
+
+  const panel = opts.ui ? buildPanel(opts.ui, deps.theme()) : null;
+
+  const d = createDisposable(() => {
+    unsubscribeHit?.();
+    unsubscribeState?.();
+    node.destroy();
+    panel?.dispose();
+    subscribers.clear();
+  });
+
+  return {
+    peek() {
+      return snapshot;
+    },
+    subscribe(fn) {
+      if (d.isDisposed) return () => {};
+      subscribers.add(fn);
+      // Fire current state so consumers don't need a separate `peek()` call.
+      fn(snapshot);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    syncHits(hits) {
+      activeHits = hits as readonly CompiledHitTest<unknown>[];
+      // Recompute against the new hit set; the cursor x is unchanged so the
+      // panel tracks data changes without waiting for the next pointer move.
+      recompute();
+    },
+    dispose: () => d.dispose(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot equality — avoids redundant DOM writes / subscriber fan-outs.
+// ---------------------------------------------------------------------------
+
+function snapshotEqual(a: SeriesReadoutSnapshot | null, b: SeriesReadoutSnapshot | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.x !== b.x) return false;
+  if (a.rows.length !== b.rows.length) return false;
+  for (let i = 0; i < a.rows.length; i++) {
+    const ra = a.rows[i]!;
+    const rb = b.rows[i]!;
+    if (ra.label !== rb.label) return false;
+    if (ra.value !== rb.value) return false;
+    if (ra.active !== rb.active) return false;
+    if (!colorEqual(ra.color, rb.color)) return false;
+  }
+  return true;
+}
+
+function colorEqual(a: Color | undefined, b: Color | undefined): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.r === b.r && a.g === b.g && a.b === b.b && a.a === b.a;
+}
+
+// ---------------------------------------------------------------------------
+// DOM panel
+// ---------------------------------------------------------------------------
+
+interface PanelHandle {
+  render(snapshot: SeriesReadoutSnapshot | null): void;
+  dispose(): void;
+}
+
+const POSITION_STYLES: Record<SeriesReadoutPosition, (inset: number) => string> = {
+  "top-left": (i) => `top:${i}px;left:${i}px`,
+  "top-right": (i) => `top:${i}px;right:${i}px`,
+  "bottom-left": (i) => `bottom:${i}px;left:${i}px`,
+  "bottom-right": (i) => `bottom:${i}px;right:${i}px`,
+};
+
+function buildPanel(ui: SeriesReadoutUi, theme: Theme): PanelHandle {
+  const doc = ui.mount.ownerDocument;
+  const inset = ui.inset ?? 12;
+  const position = ui.position ?? "top-right";
+
+  const root = doc.createElement("div");
+  root.style.cssText = [
+    "position:absolute",
+    POSITION_STYLES[position](inset),
+    "min-width:120px",
+    "padding:6px 9px",
+    "border-radius:5px",
+    `background:${cssColor(withAlphaC(theme.background, 0.92))}`,
+    `border:1px solid ${cssColor(withAlphaC(theme.legend.labelColor, 0.18))}`,
+    `color:${cssColor(theme.legend.labelColor)}`,
+    `font:${theme.legend.fontSize - 1}px/1.5 ${cssFontStack(theme.text.fontFamily)}`,
+    "z-index:55",
+    "pointer-events:none",
+    "display:none",
+  ].join(";");
+
+  const title = doc.createElement("div");
+  title.style.cssText = [
+    "font-weight:600",
+    "margin-bottom:4px",
+    `color:${cssColor(withAlphaC(theme.legend.labelColor, 0.85))}`,
+  ].join(";");
+  root.appendChild(title);
+
+  const list = doc.createElement("div");
+  list.style.cssText = "display:flex;flex-direction:column;gap:2px";
+  root.appendChild(list);
+  ui.mount.appendChild(root);
+
+  return {
+    render(snapshot) {
+      if (!snapshot) {
+        root.style.display = "none";
+        return;
+      }
+      root.style.display = "block";
+      title.textContent = snapshot.x;
+      // Rebuild the rows in place — small N (one per series) keeps this cheap.
+      while (list.firstChild) list.removeChild(list.firstChild);
+      for (const row of snapshot.rows) {
+        const rowEl = doc.createElement("div");
+        rowEl.style.cssText = [
+          "display:flex",
+          "align-items:center",
+          "gap:6px",
+          row.active ? "opacity:1" : "opacity:0.72",
+        ].join(";");
+        if (row.color) {
+          const sw = doc.createElement("span");
+          sw.style.cssText = [
+            "display:inline-block",
+            "width:9px",
+            "height:9px",
+            "border-radius:2px",
+            `background:${cssColor(row.color)}`,
+            "flex-shrink:0",
+          ].join(";");
+          rowEl.appendChild(sw);
+        }
+        const label = doc.createElement("span");
+        label.textContent = row.label;
+        label.style.cssText = "flex:1;white-space:nowrap;overflow:hidden;text-overflow:ellipsis";
+        const value = doc.createElement("span");
+        value.textContent = row.value;
+        value.style.cssText = [
+          "font-variant-numeric:tabular-nums",
+          row.active ? "font-weight:600" : "font-weight:400",
+        ].join(";");
+        rowEl.appendChild(label);
+        rowEl.appendChild(value);
+        list.appendChild(rowEl);
+      }
+    },
+    dispose() {
+      root.remove();
+    },
+  };
+}
+
+function cssColor(c: Color): string {
+  const r = Math.round(c.r * 255);
+  const g = Math.round(c.g * 255);
+  const b = Math.round(c.b * 255);
+  return `rgba(${r},${g},${b},${c.a})`;
+}
+
+function withAlphaC(c: Color, alpha: number): Color {
+  return { r: c.r, g: c.g, b: c.b, a: c.a * alpha };
+}
+
+function cssFontStack(family: string | undefined): string {
+  return family && family.length > 0 ? family : "ui-sans-serif,system-ui,sans-serif";
+}
+
+/** @internal — exposed for unit tests only. */
+export const __test__ = { collectLayerGroups, resolveGroupKey, overrideGroupPick, snapshotEqual };

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

@@ -0,0 +1,70 @@
+import type { Color } from "insomni";
+import type { CompiledHitTest, ScaleBundle } from "../geoms/types.ts";
+import type { HitLayerActive } from "./hit-layer.ts";
+/** One per-series group snapped to the cursor's column. */
+export interface SnapGroup {
+    /** Stable id `${layerIdx}::${seriesKey ?? "default"}`. */
+    id: string;
+    label: string;
+    /** Picked hit index inside the compiled hit. */
+    index: number;
+    /** |cursor − positions[index*2 (+1 for y)]|. */
+    dist: number;
+    xValue: unknown;
+    yValue: unknown;
+    /** Raw color-channel value, for scale lookup when no constant. */
+    colorRaw?: unknown;
+    /** Constant color when the layer's color channel is a constant aes. */
+    color?: Color;
+    /** seriesKey of the picked hit (stacked / dodged segments). */
+    seriesKey?: string;
+    /** Reference back to the compiled hit (used for swatch resolution). */
+    hit: CompiledHitTest<unknown>;
+}
+export interface SnapResult {
+    /** Snapped column value: the X for `axis:"x"`, the Y for `axis:"y"`. */
+    columnValue: unknown;
+    /** Ordered groups, one per series across all layers. */
+    groups: SnapGroup[];
+    /** Resolved active group id (closest to cursor / dispatched hit). */
+    activeId: string | null;
+}
+/**
+ * Resolve the group identity for a given hit index. Group key priority:
+ *   1. `seriesKey[i]` from the compiled hit (stacked / dodged geoms).
+ *   2. `colorAes(datum, i)` when color is an accessor / column.
+ *   3. Otherwise the whole layer is one group keyed by the layer label.
+ * Returns null when no x/y channels are bound. (axis-independent.)
+ */
+export declare function resolveGroupKey<T>(hit: CompiledHitTest<T>, hitIndex: number): {
+    key: string;
+    label: string;
+    raw: unknown;
+} | null;
+/**
+ * Collect per-series groups for one layer, picking the nearest hit on `axis`
+ * within each group. `axis` is the LAST param and defaults to `"x"` so the
+ * existing 5-arg callers / `__test__` signature are unaffected.
+ */
+export declare function collectLayerGroups<T>(hit: CompiledHitTest<T>, layerIdx: number, cursor: number, snap: "nearest-x" | "hover", out: SnapGroup[], axis?: "x" | "y"): void;
+/**
+ * Replace a group's pick with the exact dispatched hit. No-op if the group
+ * isn't in the collected set. (moved verbatim, axis-independent.)
+ */
+export declare function overrideGroupPick<T>(groups: SnapGroup[], groupId: string, hit: CompiledHitTest<T>, hitIndex: number): void;
+/** Resolve a group's swatch color, falling back to the color scale. (moved.) */
+export declare function resolveGroupColor(group: SnapGroup, scales: ScaleBundle | null): Color | undefined;
+/**
+ * Encapsulates the body of series-readout's `recompute()` MINUS emit/DOM: snaps
+ * the cursor to the active hit's column (when one is dispatched), collects all
+ * groups across layers, resolves the active group, and returns the title column
+ * value. Pure — the caller maps `groups` → rows and resolves swatch colors via
+ * `resolveGroupColor`. Returns null when no layer produced a group.
+ */
+export declare function computeSnap(args: {
+    hits: readonly CompiledHitTest<unknown>[];
+    cursor: number;
+    axis: "x" | "y";
+    snap: "nearest-x" | "hover";
+    active: HitLayerActive | null;
+}): SnapResult | null;