insomni-plot 0.1.0-alpha.0

package/src/grammar/interactions/hit-layer.d.ts

@@ -0,0 +1,64 @@
+import { type InteractionManager, type PointerInfo } from "insomni";
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+export interface HitEventContext {
+    /** Resolved hit projected to the public `HoveredHit` shape. */
+    hit: HoveredHit;
+    /** The CompiledHitTest the hit belongs to (for channel introspection). */
+    compiled: CompiledHitTest<unknown>;
+    /** Index into `compiled.positions` / `compiled.dataIndex`. */
+    hitIndex: number;
+    /** Raw pointer event from the manager. */
+    pointer: PointerInfo;
+}
+export interface HitLayerSubscriber {
+    /** Stable key for debugging. e.g. "tooltip", "selection". */
+    key: string;
+    onHoverEnter?(ctx: HitEventContext): void;
+    onHoverLeave?(ctx: HitEventContext): void;
+    onPress?(ctx: HitEventContext): void;
+}
+export interface GrammarHitLayerDeps {
+    manager: InteractionManager;
+    element: HTMLElement;
+}
+export interface PickAtOptions {
+    /**
+     * Which slot kinds participate in the lookup.
+     * - `"point"`: only point clouds (uses `pickRadius`).
+     * - `"region"`: only region clouds (rect containment).
+     * - `"any"`: both, with region containment winning ties.
+     * Default `"any"`.
+     */
+    mode?: "point" | "region" | "any";
+}
+export interface HitLayerActive {
+    layerIdx: number;
+    hitIndex: number;
+    compiled: CompiledHitTest<unknown>;
+    hit: HoveredHit;
+}
+export interface HitLayerState {
+    active: HitLayerActive | null;
+}
+export interface PickResult {
+    hit: HoveredHit;
+    compiled: CompiledHitTest<unknown>;
+    hitIndex: number;
+}
+export interface GrammarHitLayer {
+    /** Replace the active hit-test set after each pipeline run. */
+    sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+    /** Register a fan-out target. Returns an unsubscribe fn. */
+    subscribe(sub: HitLayerSubscriber): () => void;
+    /** Live view of the currently-dispatched hit (or null). */
+    state(): HitLayerState;
+    /** Subscribe to changes in `state()`. Fires after each transition. */
+    subscribeState(fn: (state: HitLayerState) => void): () => void;
+    /**
+     * One-shot lookup at element-local CSS coordinates. Highest-z slot wins
+     * (matches the pointer-event dispatch z-order).
+     */
+    pickAt(x: number, y: number, opts?: PickAtOptions): PickResult | null;
+    dispose(): void;
+}
+export declare function createGrammarHitLayer(deps: GrammarHitLayerDeps): GrammarHitLayer;

package/src/grammar/interactions/hit-layer.ts

@@ -0,0 +1,246 @@
+// ---------------------------------------------------------------------------
+// Grammar-level hit-test projection
+// ---------------------------------------------------------------------------
+// Thin adapter on top of insomni's generic `HitFanOut`. Takes the grammar's
+// `CompiledHitTest[]` (which carries data/channels/seriesKey/geomKind), turns
+// each into an opaque `HitSlot` the fan-out can index, and projects events
+// back into grammar shapes (`HoveredHit`, `HitEventContext`).
+//
+// Everything load-bearing — slot lifecycle, multi-subscriber dispatch,
+// primary-state survival across in-place re-syncs, synthesized leaves,
+// `pickAt` — lives in insomni. This file only adds:
+//   1. CompiledHitTest → HitSlot construction
+//   2. Generic event → HoveredHit projection
+//
+// Brush still consumes the raw `CompiledHitTest[]` directly via
+// point-in-rect tests on the positions buffer; that path doesn't need the
+// fan-out and so it isn't routed through here.
+
+import {
+  createHitFanOut,
+  type HitFanOut,
+  type HitFanOutEventContext,
+  type HitSlot,
+  type InteractionManager,
+  type PointerInfo,
+} from "insomni";
+
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import { Z_HIT_CLOUD_BASE } from "./_z.ts";
+
+export interface HitEventContext {
+  /** Resolved hit projected to the public `HoveredHit` shape. */
+  hit: HoveredHit;
+  /** The CompiledHitTest the hit belongs to (for channel introspection). */
+  compiled: CompiledHitTest<unknown>;
+  /** Index into `compiled.positions` / `compiled.dataIndex`. */
+  hitIndex: number;
+  /** Raw pointer event from the manager. */
+  pointer: PointerInfo;
+}
+
+export interface HitLayerSubscriber {
+  /** Stable key for debugging. e.g. "tooltip", "selection". */
+  key: string;
+  onHoverEnter?(ctx: HitEventContext): void;
+  onHoverLeave?(ctx: HitEventContext): void;
+  onPress?(ctx: HitEventContext): void;
+}
+
+export interface GrammarHitLayerDeps {
+  manager: InteractionManager;
+  element: HTMLElement;
+}
+
+export interface PickAtOptions {
+  /**
+   * Which slot kinds participate in the lookup.
+   * - `"point"`: only point clouds (uses `pickRadius`).
+   * - `"region"`: only region clouds (rect containment).
+   * - `"any"`: both, with region containment winning ties.
+   * Default `"any"`.
+   */
+  mode?: "point" | "region" | "any";
+}
+
+export interface HitLayerActive {
+  layerIdx: number;
+  hitIndex: number;
+  compiled: CompiledHitTest<unknown>;
+  hit: HoveredHit;
+}
+
+export interface HitLayerState {
+  active: HitLayerActive | null;
+}
+
+export interface PickResult {
+  hit: HoveredHit;
+  compiled: CompiledHitTest<unknown>;
+  hitIndex: number;
+}
+
+export interface GrammarHitLayer {
+  /** Replace the active hit-test set after each pipeline run. */
+  sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+  /** Register a fan-out target. Returns an unsubscribe fn. */
+  subscribe(sub: HitLayerSubscriber): () => void;
+  /** Live view of the currently-dispatched hit (or null). */
+  state(): HitLayerState;
+  /** Subscribe to changes in `state()`. Fires after each transition. */
+  subscribeState(fn: (state: HitLayerState) => void): () => void;
+  /**
+   * One-shot lookup at element-local CSS coordinates. Highest-z slot wins
+   * (matches the pointer-event dispatch z-order).
+   */
+  pickAt(x: number, y: number, opts?: PickAtOptions): PickResult | null;
+  dispose(): void;
+}
+
+// ---------------------------------------------------------------------------
+// CompiledHitTest → HitSlot
+// ---------------------------------------------------------------------------
+
+function buildSlot(hit: CompiledHitTest<unknown>, layerIdx: number): HitSlot {
+  const useRegions = hit.rects !== undefined && hit.rects.length > 0;
+  return useRegions
+    ? {
+        id: layerIdx,
+        rects: hit.rects!,
+        pickRadius: hit.pickRadius,
+      }
+    : {
+        id: layerIdx,
+        positions: hit.positions,
+        pickRadius: hit.pickRadius,
+        pickAxis: hit.pickAxis,
+      };
+}
+
+function projectHit(
+  compiled: CompiledHitTest<unknown>,
+  hitIndex: number,
+  position: { x: number; y: number },
+): HoveredHit {
+  return {
+    geomKind: compiled.geomKind,
+    dataIndex: compiled.dataIndex[hitIndex] ?? hitIndex,
+    seriesKey: compiled.seriesKey?.[hitIndex],
+    data: compiled.data as readonly unknown[],
+    x: position.x,
+    y: position.y,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createGrammarHitLayer(deps: GrammarHitLayerDeps): GrammarHitLayer {
+  // The fan-out is the engine. We keep a parallel `compiledList` so we can
+  // recover the CompiledHitTest for each event/state — the fan-out's HitSlot
+  // is intentionally opaque (no `data`, no `channels`).
+  let compiledList: readonly CompiledHitTest<unknown>[] = [];
+
+  const fanOut: HitFanOut = createHitFanOut({
+    manager: deps.manager,
+    element: deps.element,
+    baseZIndex: Z_HIT_CLOUD_BASE,
+  });
+
+  function projectCtx(ctx: HitFanOutEventContext): HitEventContext | null {
+    const compiled = compiledList[ctx.slotIdx];
+    if (!compiled) return null;
+    return {
+      hit: projectHit(compiled, ctx.hitIndex, ctx.position),
+      compiled,
+      hitIndex: ctx.hitIndex,
+      pointer: ctx.pointer,
+    };
+  }
+
+  return {
+    sync<T>(hits: readonly CompiledHitTest<T>[]) {
+      const next = hits as readonly CompiledHitTest<unknown>[];
+      const slots: HitSlot[] = next.map((hit, i) => buildSlot(hit, i));
+      // Sync the fan-out FIRST so any synthetic leave events for removed
+      // slots still reference the OLD compiledList (their slotIdx values
+      // are from the previous sync). Only then replace compiledList.
+      fanOut.sync(slots);
+      compiledList = next;
+    },
+    subscribe(sub) {
+      return fanOut.subscribe({
+        key: sub.key,
+        onHoverEnter: sub.onHoverEnter
+          ? (ctx) => {
+              const projected = projectCtx(ctx);
+              if (projected) sub.onHoverEnter!(projected);
+            }
+          : undefined,
+        onHoverLeave: sub.onHoverLeave
+          ? (ctx) => {
+              const projected = projectCtx(ctx);
+              if (projected) sub.onHoverLeave!(projected);
+            }
+          : undefined,
+        onPress: sub.onPress
+          ? (ctx) => {
+              const projected = projectCtx(ctx);
+              if (projected) sub.onPress!(projected);
+            }
+          : undefined,
+      });
+    },
+    state() {
+      const s = fanOut.state();
+      if (s.active === null) return { active: null };
+      const compiled = compiledList[s.active.slotIdx];
+      if (!compiled) return { active: null };
+      return {
+        active: {
+          layerIdx: s.active.slotIdx,
+          hitIndex: s.active.hitIndex,
+          compiled,
+          hit: projectHit(compiled, s.active.hitIndex, s.active.position),
+        },
+      };
+    },
+    subscribeState(fn) {
+      return fanOut.subscribeState((s) => {
+        if (s.active === null) {
+          fn({ active: null });
+          return;
+        }
+        const compiled = compiledList[s.active.slotIdx];
+        if (!compiled) {
+          fn({ active: null });
+          return;
+        }
+        fn({
+          active: {
+            layerIdx: s.active.slotIdx,
+            hitIndex: s.active.hitIndex,
+            compiled,
+            hit: projectHit(compiled, s.active.hitIndex, s.active.position),
+          },
+        });
+      });
+    },
+    pickAt(x, y, opts) {
+      const r = fanOut.pickAt(x, y, opts);
+      if (r === null) return null;
+      const compiled = compiledList[r.slotIdx];
+      if (!compiled) return null;
+      return {
+        hit: projectHit(compiled, r.hitIndex, r.position),
+        compiled,
+        hitIndex: r.hitIndex,
+      };
+    },
+    dispose() {
+      fanOut.dispose();
+      compiledList = [];
+    },
+  };
+}

package/src/grammar/interactions/legend.d.ts

@@ -0,0 +1,19 @@
+import type { InteractionManager, Invalidator } from "insomni";
+import type { PipelineOutput } from "../pipeline.ts";
+import type { Signal } from "insomni/reactivity";
+export interface GrammarLegendDeps {
+    manager: InteractionManager;
+    hidden: Signal<ReadonlySet<string>>;
+    invalidator: Invalidator;
+}
+export interface GrammarLegend {
+    /** Sync interaction nodes with the latest pipeline output. */
+    sync<T>(out: PipelineOutput<T>): void;
+    dispose(): void;
+}
+/**
+ * Legend interactivity — owns press-only InteractionNodes over each legend
+ * entry's bounding box. Toggled keys are written to the `hidden` signal,
+ * which the pipeline respects to filter marks and dim legend entries.
+ */
+export declare function createGrammarLegend(deps: GrammarLegendDeps): GrammarLegend;

package/src/grammar/interactions/legend.ts

@@ -0,0 +1,101 @@
+import type { InteractionManager, InteractionNode, Invalidator } from "insomni";
+import type { PipelineOutput } from "../pipeline.ts";
+import type { Signal } from "insomni/reactivity";
+import { createDisposable } from "./_disposable.ts";
+
+export interface GrammarLegendDeps {
+  manager: InteractionManager;
+  hidden: Signal<ReadonlySet<string>>;
+  invalidator: Invalidator;
+}
+
+export interface GrammarLegend {
+  /** Sync interaction nodes with the latest pipeline output. */
+  sync<T>(out: PipelineOutput<T>): void;
+  dispose(): void;
+}
+
+/**
+ * Legend interactivity — owns press-only InteractionNodes over each legend
+ * entry's bounding box. Toggled keys are written to the `hidden` signal,
+ * which the pipeline respects to filter marks and dim legend entries.
+ */
+export function createGrammarLegend(deps: GrammarLegendDeps): GrammarLegend {
+  let nodes: InteractionNode[] = [];
+  // Latest legend ref so node `bounds()` closures pick up new origins/bboxes
+  // each frame without rebuilding the InteractionNodes.
+  let latest: {
+    origin: { x: number; y: number };
+    bboxes: ReturnType<NonNullable<PipelineOutput["legend"]>["builder"]["getEntryBboxes"]>;
+  } | null = null;
+  let labelsKey = "";
+
+  const rebuild = () => {
+    for (const n of nodes) n.destroy();
+    if (!latest) {
+      nodes = [];
+      return;
+    }
+    nodes = latest.bboxes.map((_b, idx) => {
+      return deps.manager.add({
+        space: "ui",
+        bounds: () => {
+          const cur = latest;
+          if (!cur) return { x: 0, y: 0, width: 0, height: 0 };
+          const bb = cur.bboxes[idx];
+          if (!bb) return { x: 0, y: 0, width: 0, height: 0 };
+          return {
+            x: cur.origin.x + bb.x,
+            y: cur.origin.y + bb.y,
+            width: bb.width,
+            height: bb.height,
+          };
+        },
+        onPress: () => {
+          const cur = latest;
+          if (!cur) return;
+          const bb = cur.bboxes[idx];
+          if (!bb) return;
+          const next = new Set(deps.hidden.peek());
+          if (next.has(bb.label)) next.delete(bb.label);
+          else next.add(bb.label);
+          deps.hidden.set(next);
+          deps.invalidator.invalidate();
+        },
+        cursor: "pointer",
+      });
+    });
+  };
+
+  const d = createDisposable(() => {
+    for (const n of nodes) n.destroy();
+    nodes = [];
+    latest = null;
+  });
+
+  return {
+    sync(out) {
+      if (d.isDisposed) return;
+      if (!out.legend) {
+        if (nodes.length > 0) {
+          for (const n of nodes) n.destroy();
+          nodes = [];
+        }
+        latest = null;
+        labelsKey = "";
+        return;
+      }
+      const bboxes = out.legend.builder.getEntryBboxes();
+      latest = { origin: out.legend.origin, bboxes };
+      // Only rebuild InteractionNodes when the legend's structural shape
+      // (label list) changes — origin/position changes are picked up by the
+      // `bounds()` closure reading `latest`.
+      const nextKey = bboxes.map((b) => b.label).join("\0");
+      if (nextKey !== labelsKey) {
+        labelsKey = nextKey;
+        rebuild();
+      }
+    },
+    dispose: () => d.dispose(),
+  };
+}

package/src/grammar/interactions/menu.d.ts

@@ -0,0 +1,93 @@
+import { type ContextMenuOpts, type GlyphAtlas, type InteractionManager, type Invalidator, type Layer, type MenuPlacement, type MenuStyle, type Mods } from "insomni";
+import type { ContextMenuItem, ContextMenuTriggerPayload } from "../chart.ts";
+import type { GeomKind, HoveredHit } from "../geoms/types.ts";
+import type { Theme } from "../theme.ts";
+import type { GrammarHitLayer } from "./hit-layer.ts";
+export type ContextMenuHitMode = "nearest-point" | "any-mark" | "background";
+export interface ContextMenuTriggerInfo {
+    /**
+     * Resolved hit at the trigger point, or `null` for a background trigger.
+     * `nearest-point` resolution uses each compiled hit-test's `pickRadius`;
+     * `any-mark` additionally includes region-based geoms (bars, tiles).
+     * `background` mode always returns `null`.
+     */
+    hit: HoveredHit | null;
+    /** Convenience: the resolved data row, or `null` for background. */
+    datum: unknown | null;
+    /** Convenience: the geom kind that produced the hit (e.g. "point", "bar"). */
+    mark: GeomKind | null;
+    /** Element-local CSS px where the menu should anchor. */
+    screenX: number;
+    screenY: number;
+    source: "mouse" | "touch" | "pen" | "keyboard";
+    mods: Mods;
+    originalEvent: Event | null;
+}
+export interface GrammarContextMenuOptions {
+    /**
+     * Resolution policy for the trigger point. Default `"nearest-point"`.
+     *
+     * - `"nearest-point"`: walks point-based geoms (scatter, line vertices, ...)
+     *   only. Honors each compiled hit-test's `pickRadius`. **Suppresses the
+     *   trigger entirely when no mark is hit.**
+     * - `"any-mark"`: includes region-based geoms (bars, histograms, tiles).
+     *   Same suppression behavior as `"nearest-point"`.
+     * - `"background"`: never resolves to a mark; `hit` / `datum` / `mark` are
+     *   always null. Fires unconditionally — useful for empty-space menus.
+     */
+    hitMode?: ContextMenuHitMode;
+    /**
+     * Optional gate: when this returns true (e.g. an active pan/zoom drag), the
+     * context-menu trigger is suppressed. The InteractionManager already cancels
+     * touch long-press on drag promotion, but a right-click during a left-button
+     * drag still arrives as a native `contextmenu` event — this hook lets the
+     * mount tie suppression to its own panning state.
+     */
+    isSuppressed?(): boolean;
+    /** Override default ContextMenuOpts (holdMs, slopPx) for touch long-press. */
+    managerOpts?: ContextMenuOpts;
+    /** Low-level trigger emitter (fires alongside the rendered menu, if any). */
+    onTrigger?(info: ContextMenuTriggerInfo): void;
+    /**
+     * Menu items (static or per-trigger). When set, the library renders a
+     * canvas menu and routes clicks through `onAction`. When omitted, only
+     * `onTrigger` fires.
+     */
+    items?: readonly ContextMenuItem[] | ((info: ContextMenuTriggerInfo) => readonly ContextMenuItem[]);
+    onAction?(itemId: string, info: ContextMenuTriggerInfo): void;
+    placement?: MenuPlacement;
+    style?: MenuStyle;
+}
+export interface GrammarContextMenuDeps {
+    manager: InteractionManager;
+    hitLayer: GrammarHitLayer;
+    /** Required only when `items` is configured. Where the menu draws. */
+    hudLayer?: () => Layer;
+    /** Required only when `items` is configured. For text measurement. */
+    atlas?: () => GlyphAtlas | undefined;
+    /** Required only when `items` is configured. For default styling tokens. */
+    theme?: () => Theme;
+    /** Required only when `items` is configured. Bounds for menu clamp/flip. */
+    bounds?: () => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Required only when `items` is configured. Wakes the loop on fade ticks. */
+    invalidator?: Invalidator;
+    /**
+     * Subscribe to pan/zoom changes (so the menu closes when the chart moves
+     * under it). Returns an unsubscribe, or null when pan/zoom is disabled.
+     */
+    onViewportChange?(cb: () => void): (() => void) | null;
+}
+export interface GrammarContextMenu {
+    /** Tick fade timers. */
+    step(dt: number): void;
+    /** Draw the menu into the hud layer. */
+    draw(): void;
+    dispose(): void;
+}
+export declare function createGrammarContextMenu(deps: GrammarContextMenuDeps, opts: GrammarContextMenuOptions): GrammarContextMenu;
+export type { ContextMenuTriggerPayload };