insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,406 @@
+import { createInvalidator, rgba, type GlyphAtlas, type TooltipBounds } from "insomni";
+import { describe, expect, test, vi } from "vite-plus/test";
+
+import type { CompiledHitTest, HoveredHit } from "../geoms/types.ts";
+import { themeDefault, type Theme } from "../theme.ts";
+import { createGrammarTooltip } from "./tooltip.ts";
+import type { GrammarHitLayer, HitEventContext, HitLayerSubscriber } from "./hit-layer.ts";
+import { defaultFormat, normalizeTooltipContent, resolveTooltipContent } from "./tooltip.ts";
+
+interface Row {
+  name: string;
+  weight: number;
+}
+
+function makeHit(data: readonly Row[], indices: number[], label?: string): CompiledHitTest<Row> {
+  return {
+    geomKind: "point",
+    label,
+    positions: Float32Array.from(indices.flatMap((_, i) => [i * 10, 50])),
+    dataIndex: Int32Array.from(indices),
+    pickRadius: 5,
+    channels: {},
+    data,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// normalizeTooltipContent — shorthand → canvas TooltipContent
+// ---------------------------------------------------------------------------
+
+describe("normalizeTooltipContent", () => {
+  test("null / undefined → null (caller falls back)", () => {
+    expect(normalizeTooltipContent(null, themeDefault)).toBeNull();
+    expect(normalizeTooltipContent(undefined, themeDefault)).toBeNull();
+  });
+
+  test("string → single value-only row", () => {
+    const c = normalizeTooltipContent("hello", themeDefault);
+    expect(c).toEqual({ rows: [{ value: "hello" }] });
+  });
+
+  test("shorthand passes label + string value through verbatim", () => {
+    const c = normalizeTooltipContent(
+      { title: "Patient", rows: [{ label: "name", value: "Alice" }] },
+      themeDefault,
+    );
+    expect(c).toEqual({ title: "Patient", rows: [{ label: "name", value: "Alice" }] });
+  });
+
+  test("numeric / Date / null values go through defaultFormat", () => {
+    const date = new Date("2026-05-20T00:00:00Z");
+    const c = normalizeTooltipContent(
+      {
+        rows: [
+          { label: "n", value: 1234.56 },
+          { label: "d", value: date },
+          { label: "missing", value: null },
+          { label: "u", value: undefined },
+        ],
+      },
+      themeDefault,
+    );
+    expect(c!.rows[0]!.value).toBe(defaultFormat(1234.56));
+    expect(c!.rows[1]!.value).toBe("2026-05-20");
+    expect(c!.rows[2]!.value).toBe("—");
+    expect(c!.rows[3]!.value).toBe("—");
+  });
+
+  test("accent 'positive' / 'negative' resolve to theme tokens", () => {
+    const a = themeDefault.interactions.tooltipAccents;
+    const pos = normalizeTooltipContent(
+      { rows: [{ value: "+1.2", accent: "positive" }] },
+      themeDefault,
+    );
+    const neg = normalizeTooltipContent(
+      { rows: [{ value: "-0.4", accent: "negative" }] },
+      themeDefault,
+    );
+    expect(pos!.rows[0]!.color).toBe(a.positive);
+    expect(neg!.rows[0]!.color).toBe(a.negative);
+  });
+
+  test("accent 'neutral' is a no-op (no color override)", () => {
+    const c = normalizeTooltipContent({ rows: [{ value: "x", accent: "neutral" }] }, themeDefault);
+    expect(c!.rows[0]!.color).toBeUndefined();
+  });
+
+  test("accent as raw Color is used directly (bypasses theme)", () => {
+    const tint = rgba(0.1, 0.2, 0.3, 1);
+    const c = normalizeTooltipContent({ rows: [{ value: "x", accent: tint }] }, themeDefault);
+    expect(c!.rows[0]!.color).toBe(tint);
+  });
+
+  test("swatch passes through to the row", () => {
+    const sw = rgba(1, 0, 0, 1);
+    const c = normalizeTooltipContent(
+      { rows: [{ label: "k", value: "v", swatch: sw }] },
+      themeDefault,
+    );
+    expect(c!.rows[0]!.swatch).toBe(sw);
+  });
+
+  test("multi-line value emitted verbatim — caller controls newlines", () => {
+    const c = normalizeTooltipContent(
+      { rows: [{ label: "notes", value: "first\nsecond" }] },
+      themeDefault,
+    );
+    expect(c!.rows[0]!.value).toBe("first\nsecond");
+  });
+
+  test("omits title when shorthand has none", () => {
+    const c = normalizeTooltipContent({ rows: [{ value: "x" }] }, themeDefault);
+    expect(c).not.toBeNull();
+    expect("title" in c!).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveTooltipContent — resolver + default fallback
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipContent", () => {
+  test("no resolver → default channel-driven content (title from hit.label)", () => {
+    const data: Row[] = [{ name: "Alice", weight: 70 }];
+    const hit = makeHit(data, [0], "weight");
+    const c = resolveTooltipContent(hit, 0, themeDefault);
+    expect(c.title).toBe("weight");
+  });
+
+  test("resolver returning null falls back to default content", () => {
+    const data: Row[] = [{ name: "Alice", weight: 70 }];
+    const hit = makeHit(data, [0], "weight");
+    const c = resolveTooltipContent(hit, 0, themeDefault, () => null);
+    expect(c.title).toBe("weight");
+  });
+
+  test("resolver returning shorthand is normalized + accent-tinted", () => {
+    const data: Row[] = [{ name: "Alice", weight: 70 }];
+    const hit = makeHit(data, [0]);
+    const c = resolveTooltipContent(hit, 0, themeDefault, (info) => {
+      const d = info.datum as Row;
+      return {
+        title: d.name,
+        rows: [{ label: "weight", value: d.weight, accent: "positive" }],
+      };
+    });
+    expect(c.title).toBe("Alice");
+    expect(c.rows[0]!.label).toBe("weight");
+    expect(c.rows[0]!.value).toBe(defaultFormat(70));
+    expect(c.rows[0]!.color).toBe(themeDefault.interactions.tooltipAccents.positive);
+  });
+
+  test("resolver info exposes datum, dataIndex, mark, channels, seriesKey", () => {
+    const data: Row[] = [
+      { name: "A", weight: 1 },
+      { name: "B", weight: 2 },
+    ];
+    const hit: CompiledHitTest<Row> = {
+      ...makeHit(data, [1], "scatter"),
+      seriesKey: ["B"],
+    };
+    const resolver = vi.fn(() => "ok");
+    resolveTooltipContent(hit, 0, themeDefault, resolver);
+    const info = (resolver.mock.calls[0] as unknown[])[0] as {
+      datum: Row;
+      dataIndex: number;
+      mark: string;
+      seriesKey?: string;
+      channels: unknown;
+    };
+    expect(info.datum).toEqual({ name: "B", weight: 2 });
+    expect(info.dataIndex).toBe(1);
+    expect(info.mark).toBe("scatter");
+    expect(info.seriesKey).toBe("B");
+    expect(info.channels).toBe(hit.channels);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createGrammarTooltip — hover-intent settle (debounce)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal harness: a fake hit-layer that captures the tooltip's subscriber so
+ * the test can fire enter/leave events synchronously, plus the bits of
+ * GrammarTooltipDeps the show/step path actually touches (no GPU / atlas).
+ */
+function harness(opts?: { settleDelay?: number; theme?: Theme }) {
+  const data: Row[] = [
+    { name: "A", weight: 1 },
+    { name: "B", weight: 2 },
+  ];
+  let sub: HitLayerSubscriber | null = null;
+  const hitLayer = {
+    subscribe(s: HitLayerSubscriber) {
+      sub = s;
+      return () => {
+        sub = null;
+      };
+    },
+  } as unknown as GrammarHitLayer;
+
+  const ctxFor = (idx: number): HitEventContext => ({
+    hit: { geomKind: "point", dataIndex: idx, data, x: idx * 10, y: 50 } as HoveredHit,
+    compiled: makeHit(data, [idx], "weight") as CompiledHitTest<unknown>,
+    hitIndex: 0,
+    pointer: { x: idx * 10 + 2, y: 52 } as HitEventContext["pointer"],
+  });
+
+  const onHover = vi.fn();
+  const tip = createGrammarTooltip(
+    {
+      hitLayer,
+      hudLayer: () => ({}) as never,
+      atlas: () => undefined as GlyphAtlas | undefined,
+      theme: () => opts?.theme ?? themeDefault,
+      bounds: (): TooltipBounds => ({ x: 0, y: 0, width: 500, height: 500 }),
+      invalidator: createInvalidator(),
+    },
+    { settleDelay: opts?.settleDelay, onHover },
+  );
+
+  return {
+    tip,
+    onHover,
+    enter: (idx: number) => sub!.onHoverEnter!(ctxFor(idx)),
+    leave: () => sub!.onHoverLeave!(ctxFor(0)),
+  };
+}
+
+describe("createGrammarTooltip settle", () => {
+  test("cold-start enter fires onHover immediately (crosshair) but defers tooltip show until settle", () => {
+    const h = harness({ settleDelay: 100 });
+    h.enter(0);
+    // onHover fires immediately in schedule() for crosshair/hoverSignal updates.
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+    // Within the window: tooltip show is deferred; no extra onHover.
+    h.tip.step(0.05);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Past the window: settle commits the tooltip show without re-firing onHover.
+    h.tip.step(0.06);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+  });
+
+  test("rapid cold-start enter→enter switch fires onHover immediately for each target", () => {
+    const h = harness({ settleDelay: 100 });
+    h.enter(0);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+    h.tip.step(0.05); // mid-window
+    h.enter(1); // switch before commit → fires onHover immediately (dataIndex 1)
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls[1]![0]).toMatchObject({ dataIndex: 1 });
+    h.tip.step(0.05); // 0.05s into the NEW window — still pending settle
+    expect(h.onHover).toHaveBeenCalledTimes(2); // no extra fires
+    h.tip.step(0.06); // past settle
+    expect(h.onHover).toHaveBeenCalledTimes(2); // no extra fires (fireHover=false)
+  });
+
+  test("enter then leave inside the window — enter fires onHover immediately, leave commits null after settle", () => {
+    const h = harness({ settleDelay: 100 });
+    h.enter(0);
+    // Immediate onHover for the enter (crosshair).
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+    h.tip.step(0.05);
+    h.leave();
+    // Leave schedules but doesn't fire onHover yet (settle pending for hide).
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    h.tip.step(0.11);
+    // Leave committed — onHover(null) fires (crosshair clears, hoverSignal nulls).
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls[1]![0]).toBeNull();
+  });
+
+  test("settleDelay 0 commits immediately (opt-out)", () => {
+    const h = harness({ settleDelay: 0 });
+    h.enter(0);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+  });
+
+  test("enter skips settle when tooltip is already visible (warm switch)", () => {
+    const h = harness({ settleDelay: 100 });
+    // Cold start: first enter must settle across two steps.
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06); // settle 0.1s expired → commit enter(0), opacity advances > 0
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Warm switch: tooltip is visible; new enter should commit immediately.
+    h.enter(1);
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls[1]![0]).toMatchObject({ dataIndex: 1 });
+    // Step past where the old leave's settle would have expired — warm
+    // switch cleared pending, so nothing extra fires.
+    h.tip.step(1.0);
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+  });
+
+  test("rapid warm switching coalesces via immediate commits (no flicker)", () => {
+    const h = harness({ settleDelay: 100 });
+    // Prime: make the tooltip visible.
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit enter(0)
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Sweep across three points — each commits instantly.
+    h.enter(1);
+    h.enter(2);
+    h.enter(3);
+    // Every enter committed (no settle on warm switches).
+    expect(h.onHover).toHaveBeenCalledTimes(4);
+    expect(h.onHover.mock.calls[1]![0]).toMatchObject({ dataIndex: 1 });
+    expect(h.onHover.mock.calls[2]![0]).toMatchObject({ dataIndex: 2 });
+    expect(h.onHover.mock.calls[3]![0]).toMatchObject({ dataIndex: 3 });
+  });
+
+  test("leave still settles even when tooltip is visible", () => {
+    const h = harness({ settleDelay: 100 });
+    // Make tooltip visible.
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit enter(0)
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Leave should settle — preventing flicker on brief gap crossings.
+    h.leave();
+    h.tip.step(0.05);
+    expect(h.onHover).toHaveBeenCalledTimes(1); // not committed yet
+    h.tip.step(0.06);
+    expect(h.onHover).toHaveBeenCalledTimes(2); // committed null
+    expect(h.onHover.mock.calls[1]![0]).toBeNull();
+  });
+
+  test("enter during leave settle cancels null and commits immediately", () => {
+    const h = harness({ settleDelay: 100 });
+    // Make tooltip visible.
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit enter(0)
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Start a leave settle.
+    h.leave();
+    h.tip.step(0.02); // mid-settle
+    // New enter arrives — should cancel leave and commit immediately (warm switch).
+    h.enter(1);
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls[1]![0]).toMatchObject({ dataIndex: 1 });
+    // Verify null was never committed — even after the full settle window
+    // would have expired, since pending was cleared on warm switch.
+    h.tip.step(1.0);
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls.flat()).not.toContain(null);
+  });
+
+  test("enter after leave commits skips cold-start settle (re-enter grace)", () => {
+    const h = harness({ settleDelay: 100 });
+    // Make tooltip visible, then let leave commit fully.
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit enter(0)
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    h.leave();
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit leave — tooltip now hidden, justHid = true
+    expect(h.onHover).toHaveBeenCalledTimes(2); // null committed
+    // Re-enter after hide: should skip cold-start settle (justHid grace).
+    h.enter(2);
+    expect(h.onHover).toHaveBeenCalledTimes(3); // immediate commit
+    expect(h.onHover.mock.calls[2]![0]).toMatchObject({ dataIndex: 2 });
+    // Step well past JUST_HID_GRACE_S to verify no stale fires.
+    h.tip.step(1.0);
+    expect(h.onHover).toHaveBeenCalledTimes(3);
+  });
+
+  test("justHid grace decays after timeout — cold-start settle re-activates", () => {
+    const h = harness({ settleDelay: 100 });
+    // Prime: visible → leave commits → justHid = true
+    h.enter(0);
+    h.tip.step(0.05);
+    h.tip.step(0.06);
+    h.leave();
+    h.tip.step(0.05);
+    h.tip.step(0.06); // commit leave, justHid = true
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    // Advance past JUST_HID_GRACE_S (0.3s) without an enter — grace expires.
+    h.tip.step(0.35);
+    // Now a cold-start enter should go through settle again.
+    h.enter(1);
+    // onHover fires immediately (crosshair update) — call 3.
+    expect(h.onHover).toHaveBeenCalledTimes(3);
+    expect(h.onHover.mock.calls[2]![0]).toMatchObject({ dataIndex: 1 });
+    // Not committed yet (settle pending).
+    h.tip.step(0.05);
+    expect(h.onHover).toHaveBeenCalledTimes(3);
+    // Past the settle window: committed without re-firing onHover.
+    h.tip.step(0.06);
+    expect(h.onHover).toHaveBeenCalledTimes(3);
+  });
+
+  test("defaultFormat handles invalid Date and Symbol without crashing", () => {
+    expect(defaultFormat(new Date("invalid"))).toBe("—");
+    expect(defaultFormat(Symbol("test"))).toBe("test");
+    expect(defaultFormat(Symbol())).toBe("Symbol()");
+  });
+});