insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,161 @@
+// Tests for P1-A: touch-tap (onPress) wiring in tooltip and series-readout.
+//
+// These are unit tests — no GPU, no canvas. They verify:
+//   1. onPress calls commit() immediately (no settle delay)
+//   2. onHoverEnter still goes through the settle debounce unchanged
+//   3. onPress fires the onHover callback (so hoverSignal in mount gets the hit)
+//   4. series-readout's onPress updates cursorX
+
+import { createInvalidator, 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 } from "../theme.ts";
+import { createGrammarTooltip } from "./tooltip.ts";
+import type { GrammarHitLayer, HitEventContext, HitLayerSubscriber } from "./hit-layer.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface Row {
+  name: string;
+  v: number;
+}
+
+function makeHit(data: readonly Row[], indices: number[]): CompiledHitTest<Row> {
+  return {
+    geomKind: "point",
+    positions: Float32Array.from(indices.flatMap((_, i) => [i * 10, 50])),
+    dataIndex: Int32Array.from(indices),
+    pickRadius: 5,
+    channels: {},
+    data,
+  };
+}
+
+function makePointer(x: number, y: number): HitEventContext["pointer"] {
+  return { x, y } as HitEventContext["pointer"];
+}
+
+/**
+ * Harness that exposes both onHoverEnter and onPress so tests can fire them
+ * directly, plus an optional settleDelay for debounce verification.
+ */
+function harness(opts?: { settleDelay?: number }) {
+  const data: Row[] = [
+    { name: "A", v: 1 },
+    { name: "B", v: 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]) as CompiledHitTest<unknown>,
+    hitIndex: 0,
+    pointer: makePointer(idx * 10, 50),
+  });
+
+  const onHover = vi.fn();
+  const tip = createGrammarTooltip(
+    {
+      hitLayer,
+      hudLayer: () => ({}) as never,
+      atlas: () => undefined as GlyphAtlas | undefined,
+      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)),
+    press: (idx: number) => sub!.onPress!(ctxFor(idx)),
+    leave: () => sub!.onHoverLeave!(ctxFor(0)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// onPress bypasses settle
+// ---------------------------------------------------------------------------
+
+describe("createGrammarTooltip — onPress touch-tap path", () => {
+  test("onPress commits immediately even with a non-zero settleDelay", () => {
+    // With settleDelay=200ms, onHoverEnter would need step() to elapse before
+    // committing. onPress must commit synchronously.
+    const h = harness({ settleDelay: 200 });
+    h.press(0);
+    // onHover should have been fired immediately — no step() needed.
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+  });
+
+  test("onPress fires onHover with the hit object", () => {
+    const h = harness({ settleDelay: 100 });
+    h.press(1);
+    const hit = h.onHover.mock.calls[0]![0] as HoveredHit;
+    expect(hit.dataIndex).toBe(1);
+    expect(hit.x).toBe(10); // idx=1 → x=10
+    expect(hit.y).toBe(50);
+  });
+
+  test("onHoverEnter fires onHover immediately (crosshair) but defers tooltip show until settle", () => {
+    const h = harness({ settleDelay: 100 });
+    h.enter(0);
+    // onHover fires immediately for crosshair/hoverSignal.
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+    // Mid-window: tooltip show still deferred; no extra onHover.
+    h.tip.step(0.05);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Past the window: settle commits tooltip show without re-firing onHover.
+    h.tip.step(0.06);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+  });
+
+  test("onPress while a hover settle is pending clears pending and commits immediately — no stale settle fires", () => {
+    const h = harness({ settleDelay: 100 });
+    // Start a hover but don't let it settle.
+    h.enter(0);
+    // onHover fires immediately for crosshair (call 1, dataIndex 0).
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    expect(h.onHover.mock.calls[0]![0]).toMatchObject({ dataIndex: 0 });
+    h.tip.step(0.05);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    // Touch tap arrives before hover settles — should commit index 1 right away.
+    h.press(1);
+    // onPress fires commit which calls onHover (call 2, dataIndex 1).
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+    expect(h.onHover.mock.calls[1]![0]).toMatchObject({ dataIndex: 1 });
+    // Step well past the settle window — the old pending was cleared by
+    // onPress, so no stale settle should fire.
+    h.tip.step(1.0);
+    expect(h.onHover).toHaveBeenCalledTimes(2);
+  });
+
+  test("onPress with settleDelay=0 also commits immediately", () => {
+    const h = harness({ settleDelay: 0 });
+    h.press(0);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+  });
+
+  test("onPress clears stale pending even when no previous enter was settling", () => {
+    // Verify the fix is idempotent — clearing null pending is safe.
+    const h = harness({ settleDelay: 100 });
+    h.press(0);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+    h.tip.step(1.0);
+    expect(h.onHover).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,140 @@
+import { type GlyphAtlas, type Invalidator, type Layer, type TooltipBounds, type TooltipContent } from "insomni";
+import type { AxisTooltipContentResolver, TooltipContentResolver, TooltipContentResult } from "../chart.ts";
+import type { CompiledHitTest, HoveredHit, ScaleBundle } from "../geoms/types.ts";
+import { type SnapGroup, type SnapResult } from "./series-snap.ts";
+import type { Theme } from "../theme.ts";
+import type { GrammarHitLayer } from "./hit-layer.ts";
+export interface GrammarTooltipOptions {
+    /** Hover-intent delay before showing (ms). Default from theme.motion.tooltip.showDelay. */
+    showDelay?: number;
+    /** Linger before hiding (ms). Default from theme.motion.tooltip.hideDelay. */
+    hideDelay?: number;
+    /** Fade duration (ms). 0 disables. Default from theme.motion.tooltip.fadeMs. */
+    fadeMs?: number;
+    /**
+     * Hover-intent settle (ms). Coalesces rapid enter/leave/switch events so the
+     * tooltip only commits a show/hide once the cursor holds a target this long —
+     * sweeping across a dense mark grid or through gaps no longer fires an overlay
+     * re-render per cell. 0 disables (commit immediately).
+     * Default from theme.motion.tooltip.settleDelay.
+     */
+    settleDelay?: number;
+    /** Override placement. Default "top". */
+    placement?: "top" | "bottom" | "left" | "right" | "auto";
+    /**
+     * Consumer-supplied content resolver. Returning a string / shorthand
+     * overrides the auto-built channel rows; returning null / undefined falls
+     * back to the default builder.
+     */
+    content?: TooltipContentResolver;
+    /**
+     * Optional secondary observer fired alongside the tooltip's own show/hide.
+     * Receives the active `HoveredHit` (geom kind, data array reference, data
+     * index, snapped position) on enter, and `null` on leave. Used by the
+     * grammar crosshair to track hit positions, and by the mount to publish
+     * `hovered` as a public signal.
+     *
+     * Also fires on touch-tap (`onPress`) since that path calls `commit` which
+     * calls this callback, bypassing the settle debounce.
+     */
+    onHover?(info: HoveredHit | null): void;
+    /**
+     * Trigger model. Default `"item"` (one box per hovered mark — unchanged).
+     * `"axis"` = floating unified readout snapping to the nearest data column.
+     */
+    trigger?: "item" | "axis";
+    /** Snap axis for `trigger:"axis"`. Default `"x"`. */
+    axis?: "x" | "y";
+    /** Axis-mode content hook (replaces the auto rows when it returns a shorthand). */
+    axisContent?: AxisTooltipContentResolver;
+    /** Format the snapped column value (title) in axis mode. */
+    axisTitleFormat?: (v: unknown) => string;
+    /** Format each auto-built row's value in axis mode. */
+    axisValueFormat?: (v: unknown) => string;
+}
+export interface GrammarTooltipDeps {
+    hitLayer: GrammarHitLayer;
+    hudLayer: () => Layer;
+    atlas: () => GlyphAtlas | undefined;
+    theme: () => Theme;
+    bounds: () => TooltipBounds;
+    invalidator: Invalidator;
+    /**
+     * Optional: current cursor position in element-local CSS px. When provided,
+     * the tooltip anchor follows the cursor every frame while visible — no need
+     * to wait for a cell-transition enter event.
+     */
+    pointerPos?: () => {
+        x: number;
+        y: number;
+    } | null;
+    /** Latest resolved scales (axis-mode swatch resolution). Optional. */
+    scales?: () => ScaleBundle | null;
+    /**
+     * Axis-mode pointer source: a full-frame interaction node registered by the
+     * mount. The tooltip subscribes for cursor tracking when `trigger:"axis"`.
+     * Returns an unregister fn.
+     */
+    onAxisPointer?: (handlers: {
+        move(p: {
+            x: number;
+            y: number;
+        }): void;
+        leave(): void;
+    }) => () => void;
+}
+export interface GrammarTooltip {
+    /** Tick opacity + delay timers. */
+    step(dt: number): void;
+    /** Draw into the hud layer. */
+    draw(): void;
+    dispose(): void;
+    /** Push fresh compiled hit-tests (axis mode only; item mode ignores). */
+    syncHits?<T>(hits: readonly CompiledHitTest<T>[]): void;
+}
+/**
+ * Best-effort default formatter. Numbers go through `Intl.NumberFormat` with
+ * adaptive precision; Dates through ISO; booleans/strings stringify.
+ */
+export declare function defaultFormat(value: unknown): string;
+/**
+ * Normalize a consumer-supplied resolver result into the canvas tooltip's
+ * `TooltipContent` shape. Returns null if the result is null/undefined so the
+ * caller can fall through to the default builder.
+ *
+ * - `string` → single value-only row.
+ * - `{ title, rows }` shorthand → rows mapped through the default formatter
+ *   (strings pass through) with accent → row color via theme.
+ *
+ * Exported for tests and for reuse by alternative tooltip hosts.
+ */
+export declare function normalizeTooltipContent(result: TooltipContentResult | null | undefined, theme: Theme): TooltipContent | null;
+/**
+ * Resolve final tooltip content for a hit: run the consumer resolver if any,
+ * normalize the result, and fall back to the default channel-driven content
+ * when the resolver returns null/undefined.
+ */
+export declare function resolveTooltipContent<T>(hit: CompiledHitTest<T>, hitIndex: number, theme: Theme, resolver?: TooltipContentResolver): TooltipContent;
+/**
+ * Build the axis-mode tooltip content from a snap result. Pure (no GPU / no
+ * closure state) so it is unit-testable. For `axis:"x"` each auto row's value
+ * is the series Y; for `axis:"y"` it is the series X. When `axisContent`
+ * returns a shorthand it REPLACES the auto rows (normalized through the theme).
+ */
+export declare function buildAxisTooltipContent(args: {
+    result: SnapResult;
+    axis: "x" | "y";
+    scales: ScaleBundle | null;
+    theme: Theme;
+    titleFormat: (v: unknown) => string;
+    valueFormat: (v: unknown) => string;
+    axisContent?: AxisTooltipContentResolver;
+}): TooltipContent;
+/** Project a snap group's picked hit to a `HoveredHit` (for crosshair snap). */
+export declare function hoveredHitFromGroup(g: SnapGroup): HoveredHit;
+export declare function createGrammarTooltip(deps: GrammarTooltipDeps, opts?: GrammarTooltipOptions): GrammarTooltip;
+/** @internal — exposed for unit tests only. */
+export declare const __test__: {
+    buildAxisTooltipContent: typeof buildAxisTooltipContent;
+    hoveredHitFromGroup: typeof hoveredHitFromGroup;
+};