insomni-plot 0.1.0-alpha.0

package/src/grammar/attach-brush.d.ts

@@ -0,0 +1,44 @@
+import type { BrushRect, Frame, InteractionManager, Invalidator, Layer } from "insomni";
+import type { CompiledHitTest, HoveredHit } from "./geoms/types.ts";
+import type { Theme } from "./theme.ts";
+import { type GrammarBrush, type GrammarBrushConfig } from "./interactions/brush.ts";
+export interface AttachBrushOptions extends GrammarBrushConfig {
+    /**
+     * Fires whenever the brushed set changes — including the empty `[]` after
+     * `clear()` / background tap. Receives one `HoveredHit` per data row whose
+     * hit-test position falls within the brush rect.
+     */
+    onSelect?(hits: readonly HoveredHit[]): void;
+}
+export interface AttachedBrush {
+    /** Read-only snapshot of the current brushed hits. */
+    peek(): readonly HoveredHit[];
+    /** Current brush rect in element-local CSS px, or `null` while idle. */
+    rect(): BrushRect | null;
+    /** Subscribe to changes. Fires immediately with the current set. */
+    subscribe(fn: (hits: readonly HoveredHit[]) => void): () => void;
+    /** Imperatively clear the brush. */
+    clear(): void;
+    /** Tear down the brush + interaction nodes. */
+    dispose(): void;
+}
+export interface AttachBrushDeps {
+    manager: InteractionManager;
+    /** Plot-frame bounds in element-local CSS px. */
+    bounds: () => Frame;
+    hudLayer: () => Layer;
+    theme: () => Theme;
+    invalidator: Invalidator;
+}
+/**
+ * Internal handle exposed to the mount so it can drive `sync` + `draw` from
+ * its rAF loop and dispose alongside teardown. Public consumers receive the
+ * narrower `AttachedBrush` view returned by `MountedPlot.attachBrush`.
+ */
+export interface AttachedBrushInternal extends AttachedBrush {
+    syncHits<T>(hits: readonly CompiledHitTest<T>[]): void;
+    draw(): void;
+    /** Underlying grammar brush — exposed for tests; not part of the public API. */
+    readonly brush: GrammarBrush;
+}
+export declare function createAttachedBrush(deps: AttachBrushDeps, opts: AttachBrushOptions): AttachedBrushInternal;

package/src/grammar/attach-brush.test.ts

@@ -0,0 +1,214 @@
+import {
+  createFrame,
+  type DragPointerInfo,
+  type InteractionManager,
+  type InteractionNode,
+  type InteractionNodeSpec,
+  type PointerInfo,
+} from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { createAttachedBrush } from "./attach-brush.ts";
+import type { CompiledHitTest, HoveredHit } from "./geoms/types.ts";
+import { themeDefault } from "./theme.ts";
+
+interface CapturedNode {
+  spec: InteractionNodeSpec;
+  destroyed: boolean;
+}
+
+function fakeManager(): {
+  manager: InteractionManager;
+  nodes: CapturedNode[];
+  fireBackgroundTap: () => void;
+} {
+  const nodes: CapturedNode[] = [];
+  let bgHandler: (() => void) | null = null;
+  const manager = {
+    element: {} as HTMLElement,
+    add(spec: InteractionNodeSpec): InteractionNode {
+      const captured: CapturedNode = { spec, destroyed: false };
+      nodes.push(captured);
+      return {
+        id: Symbol("node"),
+        update(patch) {
+          captured.spec = { ...captured.spec, ...patch };
+        },
+        destroy() {
+          captured.destroyed = true;
+        },
+      };
+    },
+    addPointCloud() {
+      throw new Error("not used");
+    },
+    onBackgroundTap(handler: () => void) {
+      bgHandler = handler;
+      return () => {
+        if (bgHandler === handler) bgHandler = null;
+      };
+    },
+    onChange() {
+      return () => {};
+    },
+    destroy() {},
+  } as unknown as InteractionManager;
+  return {
+    manager,
+    nodes,
+    fireBackgroundTap: () => bgHandler?.(),
+  };
+}
+
+const noMods = { shift: false, ctrl: false, meta: false, alt: false };
+function pointer(x: number, y: number): PointerInfo {
+  return {
+    pointerId: 1,
+    type: "mouse",
+    x,
+    y,
+    localX: x,
+    localY: y,
+    buttons: 1,
+    mods: noMods,
+    stopPropagation: () => {},
+  };
+}
+function dragInfo(x: number, y: number, dx = 0, dy = 0): DragPointerInfo {
+  return { ...pointer(x, y), dx, dy };
+}
+
+interface Row {
+  x: number;
+  y: number;
+}
+function hitFor(
+  positions: number[],
+  indices: number[],
+  data: readonly Row[],
+): CompiledHitTest<Row> {
+  return {
+    geomKind: "point",
+    positions: Float32Array.from(positions),
+    dataIndex: Int32Array.from(indices),
+    pickRadius: 5,
+    channels: {},
+    data,
+  };
+}
+
+const fullBounds = () => createFrame({ x: 0, y: 0, width: 100, height: 200 });
+
+function setup(opts: { onSelect?: (hits: readonly HoveredHit[]) => void } = {}) {
+  const { manager, nodes, fireBackgroundTap } = fakeManager();
+  const hudLayer = { pushRect: () => hudLayer };
+  const inv = { invalidate: () => {}, dirty: false } as never;
+  const attached = createAttachedBrush(
+    {
+      manager,
+      bounds: fullBounds,
+      hudLayer: () => hudLayer as never,
+      theme: () => themeDefault,
+      invalidator: inv,
+    },
+    {
+      onSelect: opts.onSelect,
+    },
+  );
+  return { attached, nodes, fireBackgroundTap };
+}
+
+describe("attachBrush (createAttachedBrush)", () => {
+  test("returns an empty peek + null rect before any drag", () => {
+    const { attached } = setup();
+    expect(attached.peek()).toEqual([]);
+    expect(attached.rect()).toBeNull();
+  });
+
+  test("subscribe fires immediately with current state", () => {
+    const { attached } = setup();
+    const seen: (readonly HoveredHit[])[] = [];
+    attached.subscribe((hits) => seen.push(hits));
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toEqual([]);
+  });
+
+  test("drag populates peek + rect and notifies subscribers and onSelect", () => {
+    const onSelect: (readonly HoveredHit[])[] = [];
+    const { attached, nodes } = setup({ onSelect: (h) => onSelect.push(h) });
+    const data: Row[] = [
+      { x: 10, y: 20 },
+      { x: 50, y: 60 },
+      { x: 80, y: 90 },
+    ];
+    attached.syncHits([hitFor([10, 20, 50, 60, 80, 90], [0, 1, 2], data)]);
+
+    const subseen: (readonly HoveredHit[])[] = [];
+    attached.subscribe((hits) => subseen.push(hits));
+
+    nodes[0]!.spec.onDragStart!(pointer(5, 15));
+    nodes[0]!.spec.onDragMove!(dragInfo(60, 70));
+    nodes[0]!.spec.onDragEnd!(pointer(60, 70));
+
+    expect(attached.peek().map((h) => h.dataIndex)).toEqual([0, 1]);
+    expect(attached.rect()).toEqual({ x: 5, y: 15, width: 55, height: 55 });
+    // onSelect fires at least once with the final set.
+    expect(onSelect.at(-1)!.map((h) => h.dataIndex)).toEqual([0, 1]);
+    // Subscriber fires once with [] (initial) plus updates during the drag.
+    expect(subseen[0]).toEqual([]);
+    expect(subseen.at(-1)!.map((h) => h.dataIndex)).toEqual([0, 1]);
+  });
+
+  test("clear empties state + fires onSelect with []", () => {
+    const fired: (readonly HoveredHit[])[] = [];
+    const { attached, nodes } = setup({ onSelect: (h) => fired.push(h) });
+    const data: Row[] = [{ x: 10, y: 20 }];
+    attached.syncHits([hitFor([10, 20], [0], data)]);
+
+    nodes[0]!.spec.onDragStart!(pointer(0, 0));
+    nodes[0]!.spec.onDragMove!(dragInfo(40, 40));
+    nodes[0]!.spec.onDragEnd!(pointer(40, 40));
+    expect(attached.peek()).toHaveLength(1);
+
+    attached.clear();
+    expect(attached.peek()).toEqual([]);
+    expect(attached.rect()).toBeNull();
+    expect(fired.at(-1)).toEqual([]);
+  });
+
+  test("background tap routes through onSelect as a clear", () => {
+    const fired: (readonly HoveredHit[])[] = [];
+    const { attached, nodes, fireBackgroundTap } = setup({ onSelect: (h) => fired.push(h) });
+    const data: Row[] = [{ x: 10, y: 20 }];
+    attached.syncHits([hitFor([10, 20], [0], data)]);
+    nodes[0]!.spec.onDragStart!(pointer(0, 0));
+    nodes[0]!.spec.onDragMove!(dragInfo(40, 40));
+    nodes[0]!.spec.onDragEnd!(pointer(40, 40));
+    expect(attached.peek()).toHaveLength(1);
+
+    fireBackgroundTap();
+    expect(attached.peek()).toEqual([]);
+    expect(attached.rect()).toBeNull();
+    expect(fired.at(-1)).toEqual([]);
+  });
+
+  test("dispose tears down nodes and stops subscriber fan-out", () => {
+    const { attached, nodes } = setup();
+    const seen: (readonly HoveredHit[])[] = [];
+    attached.subscribe((hits) => seen.push(hits));
+    expect(seen).toHaveLength(1);
+
+    attached.dispose();
+    for (const n of nodes) expect(n.destroyed).toBe(true);
+    // A subscribe after dispose is a no-op — nothing else should append.
+    attached.subscribe((hits) => seen.push(hits));
+    expect(seen).toHaveLength(1);
+    expect(attached.peek()).toEqual([]);
+  });
+
+  test("dispose is idempotent", () => {
+    const { attached } = setup();
+    attached.dispose();
+    expect(() => attached.dispose()).not.toThrow();
+  });
+});

package/src/grammar/attach-brush.ts

@@ -0,0 +1,111 @@
+// ---------------------------------------------------------------------------
+// attachBrush — high-level helper on top of createGrammarBrush
+// ---------------------------------------------------------------------------
+// Mirrors `attachRangePresets` / `attachSeriesReadout`: returns a controller
+// with `peek` / `rect` / `subscribe` / `clear` / `dispose` so a consumer can
+// wire a drag-to-rect brush onto a `MountedPlot` without going through the
+// declarative `interactions: { brush: ... }` config path. Internally this is
+// just `createGrammarBrush` wrapped so the mount can track sync/draw + cleanup.
+
+import type { BrushRect, Frame, InteractionManager, Invalidator, Layer } from "insomni";
+import type { CompiledHitTest, HoveredHit } from "./geoms/types.ts";
+import type { Theme } from "./theme.ts";
+import {
+  createGrammarBrush,
+  type GrammarBrush,
+  type GrammarBrushConfig,
+} from "./interactions/brush.ts";
+
+export interface AttachBrushOptions extends GrammarBrushConfig {
+  /**
+   * Fires whenever the brushed set changes — including the empty `[]` after
+   * `clear()` / background tap. Receives one `HoveredHit` per data row whose
+   * hit-test position falls within the brush rect.
+   */
+  onSelect?(hits: readonly HoveredHit[]): void;
+}
+
+export interface AttachedBrush {
+  /** Read-only snapshot of the current brushed hits. */
+  peek(): readonly HoveredHit[];
+  /** Current brush rect in element-local CSS px, or `null` while idle. */
+  rect(): BrushRect | null;
+  /** Subscribe to changes. Fires immediately with the current set. */
+  subscribe(fn: (hits: readonly HoveredHit[]) => void): () => void;
+  /** Imperatively clear the brush. */
+  clear(): void;
+  /** Tear down the brush + interaction nodes. */
+  dispose(): void;
+}
+
+export interface AttachBrushDeps {
+  manager: InteractionManager;
+  /** Plot-frame bounds in element-local CSS px. */
+  bounds: () => Frame;
+  hudLayer: () => Layer;
+  theme: () => Theme;
+  invalidator: Invalidator;
+}
+
+/**
+ * Internal handle exposed to the mount so it can drive `sync` + `draw` from
+ * its rAF loop and dispose alongside teardown. Public consumers receive the
+ * narrower `AttachedBrush` view returned by `MountedPlot.attachBrush`.
+ */
+export interface AttachedBrushInternal extends AttachedBrush {
+  syncHits<T>(hits: readonly CompiledHitTest<T>[]): void;
+  draw(): void;
+  /** Underlying grammar brush — exposed for tests; not part of the public API. */
+  readonly brush: GrammarBrush;
+}
+
+export function createAttachedBrush(
+  deps: AttachBrushDeps,
+  opts: AttachBrushOptions,
+): AttachedBrushInternal {
+  const subscribers = new Set<(hits: readonly HoveredHit[]) => void>();
+  let current: readonly HoveredHit[] = [];
+  let disposed = false;
+
+  const brush = createGrammarBrush(deps, {
+    ...opts,
+    onChange: (hits) => {
+      current = hits;
+      opts.onSelect?.(hits);
+      for (const fn of subscribers) fn(hits);
+    },
+  });
+
+  return {
+    peek: () => current,
+    rect: () => brush.rect(),
+    subscribe(fn) {
+      if (disposed) return () => {};
+      subscribers.add(fn);
+      fn(current);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    clear: () => brush.clear(),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      brush.dispose();
+      // Notify the documented empty `[]` on teardown so consumers mirroring the
+      // selection into external UI don't keep a stale non-empty value. Fire
+      // before removing subscribers.
+      if (current.length > 0) {
+        const empty: readonly HoveredHit[] = [];
+        current = empty;
+        opts.onSelect?.(empty);
+        for (const fn of subscribers) fn(empty);
+      }
+      subscribers.clear();
+      current = [];
+    },
+    syncHits: (hits) => brush.sync(hits),
+    draw: () => brush.draw(),
+    brush,
+  };
+}

package/src/grammar/attach-presets.d.ts

@@ -0,0 +1,33 @@
+import type { Theme } from "./theme.ts";
+import { type RangePreset, type RangePresetDataDomain, type RangePresetsSubscriber, type TimePresetKey } from "../range-presets.ts";
+import type { DataViewport } from "../viewport.ts";
+/** Where the chip strip sits inside its mount element. */
+export type AttachRangePresetsPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+export interface AttachRangePresetsUi {
+    /** Element to append the chip strip into (typically the chart's stage). */
+    mount: HTMLElement;
+    /** Corner placement inside `mount`. Defaults to `"top-left"`. */
+    position?: AttachRangePresetsPosition;
+    /** Inset (px) from the chosen corner. Defaults to `12`. */
+    inset?: number;
+}
+export interface AttachRangePresetsOptions {
+    axis: "x" | "y";
+    /**
+     * Presets to expose. A `TimePresetKey` string is expanded to `timePreset(key)`;
+     * pass a full `RangePreset` for custom presets (label override, linear/log
+     * presets, etc.).
+     */
+    presets: readonly (TimePresetKey | RangePreset)[];
+    dataDomain?: RangePresetDataDomain;
+    now?: () => number;
+    /** Omit to skip DOM construction — returns the same controller, headless. */
+    ui?: AttachRangePresetsUi;
+}
+export interface AttachedRangePresets {
+    setActive(key: string | null): void;
+    getActive(): string | null;
+    subscribe(fn: RangePresetsSubscriber): () => void;
+    dispose(): void;
+}
+export declare function attachRangePresets(viewport: DataViewport<any, any>, theme: Theme, opts: AttachRangePresetsOptions): AttachedRangePresets;

package/src/grammar/attach-presets.test.ts

@@ -0,0 +1,106 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from "vite-plus/test";
+
+import { viewportFrame } from "insomni";
+import { createDataViewport } from "../viewport.ts";
+import { themeDefault } from "./theme.ts";
+import { attachRangePresets } from "./attach-presets.ts";
+
+const FROZEN_NOW = new Date("2026-05-20T12:00:00Z").getTime();
+const now = () => FROZEN_NOW;
+const DATA_DOMAIN: [Date, Date] = [new Date("2024-01-01T00:00:00Z"), new Date(FROZEN_NOW)];
+
+const makeViewport = () =>
+  createDataViewport({
+    frame: viewportFrame(400, 300),
+    x: { type: "time", domain: DATA_DOMAIN },
+    y: { type: "linear", domain: [0, 100] },
+  });
+
+describe("attachRangePresets — headless (no ui)", () => {
+  test("expands TimePresetKey strings into timePreset() entries", () => {
+    const vp = makeViewport();
+    const a = attachRangePresets(vp, themeDefault, {
+      axis: "x",
+      presets: ["1M", "MAX"],
+      dataDomain: DATA_DOMAIN,
+      now,
+    });
+    a.setActive("1M");
+    const [s, e] = vp.visibleXDomain as readonly [Date, Date];
+    expect(e.getTime()).toBe(FROZEN_NOW);
+    expect(s.getTime()).toBe(FROZEN_NOW - 30 * 24 * 3600_000);
+    a.dispose();
+  });
+
+  test("subscribe fires on setActive", () => {
+    const vp = makeViewport();
+    const a = attachRangePresets(vp, themeDefault, {
+      axis: "x",
+      presets: ["1M"],
+      dataDomain: DATA_DOMAIN,
+      now,
+    });
+    const log: (string | null)[] = [];
+    a.subscribe((k) => log.push(k));
+    a.setActive("1M");
+    a.setActive(null);
+    expect(log).toEqual(["1M", null]);
+    a.dispose();
+  });
+});
+
+describe("attachRangePresets — with ui", () => {
+  test("renders a chip per preset and toggles active styling on click", () => {
+    const vp = makeViewport();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const a = attachRangePresets(vp, themeDefault, {
+      axis: "x",
+      presets: ["1M", "3M", "MAX"],
+      dataDomain: DATA_DOMAIN,
+      now,
+      ui: { mount: host, position: "top-left" },
+    });
+
+    const buttons = Array.from(host.querySelectorAll("button"));
+    expect(buttons.map((b) => b.textContent)).toEqual(["1M", "3M", "MAX"]);
+
+    const oneM = buttons[0]!;
+    const inactiveBg = oneM.style.background;
+    oneM.click();
+    expect(oneM.style.background).not.toBe(inactiveBg);
+    expect(a.getActive()).toBe("1M");
+
+    // A controller-side setActive update must propagate back to chip styling.
+    a.setActive("MAX");
+    const max = buttons[2]!;
+    expect(max.style.background).not.toBe(inactiveBg);
+    // 1M chip should have reverted to its inactive look.
+    expect(oneM.style.background).toBe(inactiveBg);
+
+    a.dispose();
+    expect(host.querySelector("button")).toBeNull();
+    host.remove();
+  });
+
+  test("position option flips the chip strip's CSS anchor", () => {
+    const vp = makeViewport();
+    const host = document.createElement("div");
+    document.body.appendChild(host);
+    const a = attachRangePresets(vp, themeDefault, {
+      axis: "x",
+      presets: ["1M"],
+      dataDomain: DATA_DOMAIN,
+      now,
+      ui: { mount: host, position: "bottom-right", inset: 8 },
+    });
+    const strip = host.querySelector("div") as HTMLDivElement;
+    expect(strip.style.bottom).toBe("8px");
+    expect(strip.style.right).toBe("8px");
+    expect(strip.style.top).toBe("");
+    expect(strip.style.left).toBe("");
+    a.dispose();
+    host.remove();
+  });
+});