insomni-plot 0.1.0-alpha.0

package/src/grammar/interactions/brush.ts

@@ -0,0 +1,452 @@
+// ---------------------------------------------------------------------------
+// Grammar-level brush wiring
+// ---------------------------------------------------------------------------
+// Owns a single drag-capable InteractionNode covering the plot frame. Drag
+// gestures route through the generic `Brush` primitive; on each change we
+// project the rect against the current hit-test positions and emit the
+// matching `HoveredHit[]` via `onChange`. The grammar mount mirrors that
+// payload onto `MountedPlot.brushed`, parallel to (and independent of) the
+// click `selected` signal.
+//
+// Background tap clears the brush — same dismissal pattern as click selection.
+
+import {
+  type Brush,
+  type BrushAxis,
+  type BrushEdge,
+  type BrushRect,
+  type Color,
+  createBrush,
+  type CrosshairBounds,
+  isCoarsePointer,
+  type InteractionManager,
+  type InteractionNode,
+  type Invalidator,
+  type Layer,
+  withAlpha,
+} from "insomni";
+
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import type { Theme } from "../theme.ts";
+import { createDisposable } from "./_disposable.ts";
+import { Z_BRUSH_DRAG, Z_BRUSH_HANDLE_CORNER, Z_BRUSH_HANDLE_EDGE } from "./_z.ts";
+
+export interface GrammarBrushConfig {
+  /** Which axes the brush spans. Default `"xy"`. */
+  axis?: BrushAxis;
+  /** Translucent fill color. Default theme.axis.color × 0.12 alpha. */
+  fillColor?: Color;
+  /** Outline color. Default theme.axis.color × 0.6 alpha. */
+  strokeColor?: Color;
+  /** Outline width in CSS px. Default 1. */
+  strokeWidth?: number;
+  /**
+   * Enable edge/corner resize handles on the committed rect. Default `true`.
+   * Disable to lock a brush rect to its initial drag.
+   */
+  handles?: boolean;
+  /** Hit-test extent of each handle in CSS px. Default 8. */
+  handleSize?: number;
+  /**
+   * Enable drag-to-move on the committed rect interior. Default `true`. The
+   * rect's size is held constant during the move; off-axis movement is locked
+   * for `axis: "x"` / `"y"` brushes. Disable to lock a brush rect in place.
+   */
+  translate?: boolean;
+  /**
+   * Snap brush rect edges to the nearest hit-test position along the chosen
+   * axis. `true` snaps on the brush's active `axis`; pass `"x"` / `"y"` /
+   * `"xy"` to override. Default `false`. Useful for axis-locked range brushes
+   * over discrete x-ticks. The snap is computed against the live hit-test
+   * positions (refreshed on every `sync()`), so it follows the data.
+   */
+  snap?: boolean | BrushAxis;
+}
+
+export interface GrammarBrushOptions extends GrammarBrushConfig {
+  /**
+   * Fired when the brushed set changes. Receives one `HoveredHit` per data
+   * row whose hit-test position falls within the brush rect.
+   */
+  onChange?(hits: HoveredHit[]): void;
+}
+
+export interface GrammarBrushDeps {
+  manager: InteractionManager;
+  /** Plot-frame bounds in element-local CSS px. The brush only fires inside this rect. */
+  bounds: () => CrosshairBounds;
+  hudLayer: () => Layer;
+  theme: () => Theme;
+  invalidator: Invalidator;
+}
+
+export interface GrammarBrush {
+  /** Replace the active hit-test set after each pipeline run. */
+  sync<T>(hits: readonly CompiledHitTest<T>[]): void;
+  /** Read-only snapshot of the current brushed hits. */
+  current(): HoveredHit[];
+  /** Current brush rect, or null when idle. */
+  rect(): BrushRect | null;
+  /** Imperatively clear the brush. */
+  clear(): void;
+  /** Draw the brush overlay into the hud layer. */
+  draw(): void;
+  dispose(): void;
+}
+
+function pointInRect(px: number, py: number, r: BrushRect): boolean {
+  return px >= r.x && px <= r.x + r.width && py >= r.y && py <= r.y + r.height;
+}
+
+export function createGrammarBrush(
+  deps: GrammarBrushDeps,
+  opts: GrammarBrushOptions = {},
+): GrammarBrush {
+  const themeAxis = deps.theme().axis.color;
+  const defaultFill: Color = withAlpha(themeAxis, themeAxis.a * 0.12);
+  const defaultStroke: Color = withAlpha(themeAxis, themeAxis.a * 0.6);
+
+  // Cached hit-test set; refreshed on every sync.
+  let hits: readonly CompiledHitTest<unknown>[] = [];
+  let brushed: HoveredHit[] = [];
+
+  // Snap config. `true` = snap on the brush's active axis; explicit axis
+  // overrides. Snap reads `hits` so it tracks the latest hit-test positions.
+  const brushAxis: BrushAxis = opts.axis ?? "xy";
+  const snapMode: BrushAxis | false =
+    opts.snap === undefined || opts.snap === false
+      ? false
+      : opts.snap === true
+        ? brushAxis
+        : opts.snap;
+  const snapX = snapMode === "x" || snapMode === "xy";
+  const snapY = snapMode === "y" || snapMode === "xy";
+
+  function nearestHitValue(v: number, axis: "x" | "y"): number {
+    let best = v;
+    let bestDist = Infinity;
+    for (const hit of hits) {
+      const positions = hit.positions;
+      const n = positions.length / 2;
+      const offset = axis === "x" ? 0 : 1;
+      for (let i = 0; i < n; i++) {
+        const p = positions[i * 2 + offset]!;
+        if (!Number.isFinite(p)) continue;
+        const d = Math.abs(p - v);
+        if (d < bestDist) {
+          bestDist = d;
+          best = p;
+        }
+      }
+    }
+    return best;
+  }
+
+  function snapRect(rect: BrushRect): BrushRect {
+    if (!snapX && !snapY) return rect;
+    let { x, y, width, height } = rect;
+    if (snapX) {
+      const x1 = nearestHitValue(x, "x");
+      const x2 = nearestHitValue(x + width, "x");
+      x = Math.min(x1, x2);
+      width = Math.abs(x2 - x1);
+    }
+    if (snapY) {
+      const y1 = nearestHitValue(y, "y");
+      const y2 = nearestHitValue(y + height, "y");
+      y = Math.min(y1, y2);
+      height = Math.abs(y2 - y1);
+    }
+    return { x, y, width, height };
+  }
+
+  const recomputeBrushed = (rect: BrushRect | null): boolean => {
+    const next: HoveredHit[] = [];
+    if (rect && (rect.width > 0 || rect.height > 0)) {
+      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 px = positions[i * 2]!;
+          const py = positions[i * 2 + 1]!;
+          if (!pointInRect(px, py, rect)) continue;
+          next.push({
+            geomKind: hit.geomKind,
+            dataIndex: indices[i]!,
+            seriesKey: hit.seriesKey?.[i],
+            data: hit.data as readonly unknown[],
+            x: px,
+            y: py,
+          });
+        }
+      }
+    }
+    const changed =
+      next.length !== brushed.length ||
+      next.some(
+        (h, i) =>
+          h.dataIndex !== brushed[i]?.dataIndex ||
+          h.geomKind !== brushed[i]?.geomKind ||
+          h.seriesKey !== brushed[i]?.seriesKey,
+      );
+    brushed = next;
+    return changed;
+  };
+
+  const brush: Brush = createBrush({
+    axis: brushAxis,
+    bounds: deps.bounds,
+    style: {
+      fill: opts.fillColor ?? defaultFill,
+      stroke: opts.strokeColor ?? defaultStroke,
+      strokeWidth: opts.strokeWidth ?? 1,
+    },
+    invalidator: deps.invalidator,
+    snap: snapX || snapY ? snapRect : undefined,
+    onChange: (rect) => {
+      if (recomputeBrushed(rect)) opts.onChange?.(brushed.slice());
+    },
+    onEnd: (rect) => {
+      // Final emission so callers see the post-clamp committed rect even when
+      // the rect didn't change since the last onChange.
+      recomputeBrushed(rect);
+      opts.onChange?.(brushed.slice());
+    },
+  });
+
+  // Drag node sits inside the plot frame. We deliberately don't register an
+  // onPress here — clicks fall through to background-tap, which we use to
+  // clear the brush below.
+  const node: InteractionNode = deps.manager.add({
+    space: "ui",
+    bounds: deps.bounds,
+    // Lower than tooltip (1000+) and selection (900+) PointCloud nodes so
+    // those still claim hover/press at the same spot. Drag routes
+    // independently anyway, but a low z keeps insertion-order ties sane.
+    zIndex: Z_BRUSH_DRAG,
+    cursor: "crosshair",
+    onDragStart: (info) => {
+      brush.begin(info.x, info.y);
+    },
+    onDragMove: (info) => {
+      brush.update(info.x, info.y);
+    },
+    onDragEnd: (info) => {
+      brush.update(info.x, info.y);
+      brush.end();
+    },
+  });
+
+  // -----------------------------------------------------------------------
+  // Resize handles — 4 edges + 4 corners overlaid on the committed rect.
+  // Each handle is a fixed-size hit zone tracking its slot on the live rect;
+  // when there's no rect, bounds collapse to zero so the node never hits.
+  // -----------------------------------------------------------------------
+
+  const handlesEnabled = opts.handles !== false;
+  const defaultHandle = isCoarsePointer() ? 24 : 8;
+  const handleSize = Math.max(2, opts.handleSize ?? defaultHandle);
+  const allowVertical = brushAxis === "xy" || brushAxis === "y";
+  const allowHorizontal = brushAxis === "xy" || brushAxis === "x";
+  // Filter to edges that match the brush axis. For axis "x" only east/west
+  // make sense; the off-axis is locked to the bounds so vertical resize is
+  // a no-op and the cursor would be misleading.
+  const ALL_EDGES: BrushEdge[] = ["n", "s", "e", "w", "ne", "nw", "se", "sw"];
+  const handleEdges: BrushEdge[] = ALL_EDGES.filter((e) => {
+    if (!allowVertical && (e === "n" || e === "s")) return false;
+    if (!allowHorizontal && (e === "e" || e === "w")) return false;
+    if (brushAxis === "x" && (e === "ne" || e === "nw" || e === "se" || e === "sw")) return false;
+    if (brushAxis === "y" && (e === "ne" || e === "nw" || e === "se" || e === "sw")) return false;
+    return true;
+  });
+
+  // Per-edge cursor + bbox derivation. Corner bboxes are h×h squares centered
+  // on the corner; edge bboxes hug the side and shrink inward at the corners
+  // so they don't overlap the corner squares.
+  function cursorFor(edge: BrushEdge): string {
+    switch (edge) {
+      case "n":
+      case "s":
+        return "ns-resize";
+      case "e":
+      case "w":
+        return "ew-resize";
+      case "ne":
+      case "sw":
+        return "nesw-resize";
+      case "nw":
+      case "se":
+        return "nwse-resize";
+    }
+  }
+
+  function handleBounds(edge: BrushEdge): BrushRect {
+    const r = brush.rect;
+    if (r === null) return { x: 0, y: 0, width: 0, height: 0 };
+    const h = handleSize;
+    const half = h / 2;
+    const x1 = r.x;
+    const y1 = r.y;
+    const x2 = r.x + r.width;
+    const y2 = r.y + r.height;
+    switch (edge) {
+      case "nw":
+        return { x: x1 - half, y: y1 - half, width: h, height: h };
+      case "ne":
+        return { x: x2 - half, y: y1 - half, width: h, height: h };
+      case "sw":
+        return { x: x1 - half, y: y2 - half, width: h, height: h };
+      case "se":
+        return { x: x2 - half, y: y2 - half, width: h, height: h };
+      case "n":
+        return {
+          x: x1 + half,
+          y: y1 - half,
+          width: Math.max(0, r.width - h),
+          height: h,
+        };
+      case "s":
+        return {
+          x: x1 + half,
+          y: y2 - half,
+          width: Math.max(0, r.width - h),
+          height: h,
+        };
+      case "w":
+        return {
+          x: x1 - half,
+          y: y1 + half,
+          width: h,
+          height: Math.max(0, r.height - h),
+        };
+      case "e":
+        return {
+          x: x2 - half,
+          y: y1 + half,
+          width: h,
+          height: Math.max(0, r.height - h),
+        };
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Translate node — drag the rect interior to move it without changing size.
+  // Sits above the create node (so dragging inside the rect translates rather
+  // than starting a new brush) but below resize handles (so handles win on
+  // edges). Bounds collapse to zero when there's no rect, making it inert.
+  // -----------------------------------------------------------------------
+  const translateEnabled = opts.translate !== false;
+  function moveBounds(): BrushRect {
+    const r = brush.rect;
+    if (r === null || (r.width <= 0 && r.height <= 0)) {
+      return { x: 0, y: 0, width: 0, height: 0 };
+    }
+    // Inset by handleSize/2 on each axis when handles are enabled so the
+    // resize zones get exclusive ownership at the edges and corners.
+    const inset = handlesEnabled ? handleSize / 2 : 0;
+    return {
+      x: r.x + inset,
+      y: r.y + inset,
+      width: Math.max(0, r.width - 2 * inset),
+      height: Math.max(0, r.height - 2 * inset),
+    };
+  }
+  const translateNode: InteractionNode | null = translateEnabled
+    ? deps.manager.add({
+        space: "ui",
+        bounds: moveBounds,
+        zIndex: Z_BRUSH_HANDLE_EDGE,
+        cursor: "move",
+        onPress: () => {},
+        onDragStart: (info) => {
+          brush.beginTranslate(info.x, info.y);
+        },
+        onDragMove: (info) => {
+          brush.update(info.x, info.y);
+        },
+        onDragEnd: (info) => {
+          brush.update(info.x, info.y);
+          brush.end();
+        },
+      })
+    : null;
+
+  const handleNodes: InteractionNode[] = handlesEnabled
+    ? handleEdges.map((edge) =>
+        deps.manager.add({
+          space: "ui",
+          bounds: () => handleBounds(edge),
+          // Above the create drag node so handles claim the gesture inside
+          // the rect; corners get a small extra bump so they win over
+          // overlapping edge zones at small rect sizes.
+          zIndex:
+            edge === "ne" || edge === "nw" || edge === "se" || edge === "sw"
+              ? Z_BRUSH_HANDLE_CORNER
+              : Z_BRUSH_HANDLE_EDGE,
+          cursor: cursorFor(edge),
+          // Empty onPress claims the press so a click without drag doesn't
+          // fall through to background-tap (which would clear the brush).
+          onPress: () => {},
+          onDragStart: (info) => {
+            brush.beginResize(edge, info.x, info.y);
+          },
+          onDragMove: (info) => {
+            brush.update(info.x, info.y);
+          },
+          onDragEnd: (info) => {
+            brush.update(info.x, info.y);
+            brush.end();
+          },
+        }),
+      )
+    : [];
+
+  const unsubscribeBgTap = deps.manager.onBackgroundTap(() => {
+    if (brush.rect !== null) brush.cancel();
+    if (brushed.length > 0) {
+      brushed = [];
+      opts.onChange?.([]);
+    }
+  });
+
+  const d = createDisposable(() => {
+    unsubscribeBgTap();
+    node.destroy();
+    translateNode?.destroy();
+    for (const h of handleNodes) h.destroy();
+    brush.dispose();
+    brushed = [];
+    hits = [];
+  });
+
+  return {
+    sync(next) {
+      if (d.isDisposed) return;
+      hits = next as readonly CompiledHitTest<unknown>[];
+      // Refresh brushed positions/membership against the new hit-test data so
+      // a static rect over a re-rendered chart still reports current rows.
+      if (brush.rect !== null) {
+        if (recomputeBrushed(brush.rect)) opts.onChange?.(brushed.slice());
+      }
+    },
+    current() {
+      return brushed.slice();
+    },
+    rect() {
+      return brush.rect;
+    },
+    clear() {
+      brush.cancel();
+      if (brushed.length > 0) {
+        brushed = [];
+        opts.onChange?.([]);
+      }
+    },
+    draw() {
+      if (d.isDisposed) return;
+      brush.draw(deps.hudLayer());
+    },
+    dispose: () => d.dispose(),
+  };
+}

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

@@ -0,0 +1,19 @@
+import { type CrosshairBounds, type Invalidator, type Layer, type Vec2 } from "insomni";
+import type { CrosshairConfig } from "../chart.ts";
+import type { Theme } from "../theme.ts";
+export interface GrammarCrosshairDeps {
+    hudLayer: () => Layer;
+    theme: () => Theme;
+    bounds: () => CrosshairBounds;
+    invalidator: Invalidator;
+}
+export interface GrammarCrosshair {
+    /** Set the snapped position, or `null` to hide. */
+    setPosition(p: Vec2 | null): void;
+    /** Toggle visibility (e.g., off for band x-scales). Hides immediately. */
+    setEnabled(enabled: boolean): void;
+    /** Draw guide line(s) into the hud layer. */
+    draw(): void;
+    dispose(): void;
+}
+export declare function createGrammarCrosshair(deps: GrammarCrosshairDeps, opts?: CrosshairConfig): GrammarCrosshair;

package/src/grammar/interactions/crosshair.test.ts

@@ -0,0 +1,127 @@
+import { createInvalidator, type Layer } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { themeDefault } from "../theme.ts";
+import { createGrammarCrosshair } from "./crosshair.ts";
+
+interface RecordedSegment {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+function fakeLayer(): { segments: RecordedSegment[]; layer: Layer } {
+  const segments: RecordedSegment[] = [];
+  const layer = {
+    pushSegment(s: { x1: number; y1: number; x2: number; y2: number }) {
+      segments.push({ x1: s.x1, y1: s.y1, x2: s.x2, y2: s.y2 });
+      return layer;
+    },
+  };
+  return { segments, layer: layer as unknown as Layer };
+}
+
+const bounds = () => ({ x: 0, y: 0, width: 100, height: 200 });
+
+describe("grammar crosshair", () => {
+  test("setPosition draws a vertical line by default", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair({
+      hudLayer: () => layer,
+      theme: () => themeDefault,
+      bounds,
+      invalidator: inv,
+    });
+    ch.setPosition({ x: 40, y: 80 });
+    ch.draw();
+    expect(segments).toHaveLength(1);
+    expect(segments[0]!.x1).toBe(40);
+    expect(segments[0]!.x2).toBe(40);
+    expect(segments[0]!.y1).toBe(0);
+    expect(segments[0]!.y2).toBe(200);
+  });
+
+  test("axis: 'xy' draws both vertical and horizontal lines", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair(
+      {
+        hudLayer: () => layer,
+        theme: () => themeDefault,
+        bounds,
+        invalidator: inv,
+      },
+      { axis: "xy" },
+    );
+    ch.setPosition({ x: 40, y: 80 });
+    ch.draw();
+    expect(segments).toHaveLength(2);
+  });
+
+  test("setPosition(null) hides the crosshair", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair({
+      hudLayer: () => layer,
+      theme: () => themeDefault,
+      bounds,
+      invalidator: inv,
+    });
+    ch.setPosition({ x: 40, y: 80 });
+    ch.setPosition(null);
+    ch.draw();
+    expect(segments).toHaveLength(0);
+  });
+
+  test("setEnabled(false) drops position and skips draw", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair({
+      hudLayer: () => layer,
+      theme: () => themeDefault,
+      bounds,
+      invalidator: inv,
+    });
+    ch.setPosition({ x: 40, y: 80 });
+    ch.setEnabled(false);
+    ch.draw();
+    expect(segments).toHaveLength(0);
+    // Re-enabling does not restore the prior position (caller must repush).
+    ch.setEnabled(true);
+    ch.draw();
+    expect(segments).toHaveLength(0);
+  });
+
+  test("setPosition is a no-op while disabled", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair({
+      hudLayer: () => layer,
+      theme: () => themeDefault,
+      bounds,
+      invalidator: inv,
+    });
+    ch.setEnabled(false);
+    ch.setPosition({ x: 40, y: 80 });
+    ch.setEnabled(true);
+    ch.draw();
+    expect(segments).toHaveLength(0);
+  });
+
+  test("dispose stops further draws", () => {
+    const { segments, layer } = fakeLayer();
+    const inv = createInvalidator();
+    const ch = createGrammarCrosshair({
+      hudLayer: () => layer,
+      theme: () => themeDefault,
+      bounds,
+      invalidator: inv,
+    });
+    ch.setPosition({ x: 40, y: 80 });
+    ch.dispose();
+    ch.draw();
+    expect(segments).toHaveLength(0);
+  });
+});

package/src/grammar/interactions/crosshair.ts

@@ -0,0 +1,76 @@
+// ---------------------------------------------------------------------------
+// Grammar-level crosshair wiring
+// ---------------------------------------------------------------------------
+// Wraps insomni's generic `createCrosshair` for plot charts. The mount creates
+// this once; the grammar tooltip pushes hover positions in via `setPosition`,
+// and the mount toggles `setEnabled(false)` when the active x-scale is `band`
+// (where a snapping crosshair adds nothing to a categorical layout).
+
+import {
+  type Color,
+  createCrosshair,
+  type Crosshair,
+  type CrosshairBounds,
+  type Invalidator,
+  type Layer,
+  type Vec2,
+  withAlpha,
+} from "insomni";
+import type { CrosshairConfig } from "../chart.ts";
+import type { Theme } from "../theme.ts";
+import { createDisposable } from "./_disposable.ts";
+
+export interface GrammarCrosshairDeps {
+  hudLayer: () => Layer;
+  theme: () => Theme;
+  bounds: () => CrosshairBounds;
+  invalidator: Invalidator;
+}
+
+export interface GrammarCrosshair {
+  /** Set the snapped position, or `null` to hide. */
+  setPosition(p: Vec2 | null): void;
+  /** Toggle visibility (e.g., off for band x-scales). Hides immediately. */
+  setEnabled(enabled: boolean): void;
+  /** Draw guide line(s) into the hud layer. */
+  draw(): void;
+  dispose(): void;
+}
+
+export function createGrammarCrosshair(
+  deps: GrammarCrosshairDeps,
+  opts: CrosshairConfig = {},
+): GrammarCrosshair {
+  const themeAxisColor = deps.theme().axis.color;
+  const defaultColor: Color = withAlpha(themeAxisColor, themeAxisColor.a * 0.6);
+  const crosshair: Crosshair = createCrosshair({
+    axis: opts.axis ?? "x",
+    bounds: deps.bounds,
+    style: {
+      color: opts.color ?? defaultColor,
+      width: opts.width ?? 1,
+    },
+    invalidator: deps.invalidator,
+  });
+
+  let enabled = true;
+  const d = createDisposable(() => crosshair.dispose());
+
+  return {
+    setPosition(p) {
+      if (d.isDisposed || !enabled) return;
+      crosshair.setPosition(p);
+    },
+    setEnabled(next) {
+      if (d.isDisposed) return;
+      if (enabled === next) return;
+      enabled = next;
+      if (!enabled) crosshair.setPosition(null);
+    },
+    draw() {
+      if (d.isDisposed || !enabled) return;
+      crosshair.draw(deps.hudLayer());
+    },
+    dispose: () => d.dispose(),
+  };
+}