insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/text.ts

@@ -0,0 +1,234 @@
+// ---------------------------------------------------------------------------
+// text geom — value labels at (x, y)
+// ---------------------------------------------------------------------------
+// Optional `collisionMode` runs a post-layout pass before the labels are
+// handed to `valueLabelMark`:
+//
+// - `"none"` (default): emit every label as-is.
+// - `"hide"`: greedy first-fit. Labels are processed in data order; a
+//   label whose padded bounding rect overlaps any previously kept label
+//   is dropped. Stable for stable inputs, but the visible set shifts
+//   under pan/zoom — no hysteresis (the proposal calls this out; we ship
+//   the simple algorithm and document the trade-off).
+// - `"stagger"`: alternate odd-indexed labels by `fontSize + 2` pixels in
+//   y. Doesn't drop labels — gives roughly twice the horizontal density
+//   in exchange for vertical real estate.
+
+import type { Color } from "insomni";
+import { valueLabelMark, type LabelBoxStyle, type ValueLabelAlign } from "../../annotations.ts";
+import type { Aes } from "../aes.ts";
+import { resolveAes } from "../aes.ts";
+import type { CompileContext, CompiledHitTest, Geom, ResolvedChannelMap } from "./types.ts";
+import { resolveCoord, wrapMark } from "./_mark.ts";
+
+export type TextCollisionMode = "none" | "hide" | "stagger";
+
+export interface TextChannels<T> {
+  x: Aes<T, number | Date | string>;
+  y: Aes<T, number | Date | string>;
+  text: Aes<T, string>;
+}
+
+export interface TextOptions {
+  fontSize?: number;
+  color?: Color;
+  align?: ValueLabelAlign;
+  offsetX?: number;
+  offsetY?: number;
+  /** Optional rounded-rect background. Requires the chart's glyph atlas. */
+  box?: LabelBoxStyle;
+  label?: string;
+  /**
+   * Post-layout collision handling. Default `"none"`. `"hide"` drops
+   * overlapping labels via a greedy first-fit pass; `"stagger"` adds an
+   * alternating y offset so adjacent labels sit on two rows.
+   */
+  collisionMode?: TextCollisionMode;
+  /** Pixel padding around each label's measured rect when checking overlap. Default `2`. */
+  collisionPadding?: number;
+}
+
+interface LabelRect {
+  index: number;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+function rectsOverlap(a: LabelRect, b: LabelRect, pad: number): boolean {
+  return (
+    a.x - pad < b.x + b.w + pad &&
+    a.x + a.w + pad > b.x - pad &&
+    a.y - pad < b.y + b.h + pad &&
+    a.y + a.h + pad > b.y - pad
+  );
+}
+
+function originForAlign(
+  align: ValueLabelAlign,
+  x: number,
+  y: number,
+  w: number,
+  h: number,
+): { x: number; y: number } {
+  if (align === "left") return { x, y: y - h / 2 };
+  if (align === "right") return { x: x - w, y: y - h / 2 };
+  return { x: x - w / 2, y: y - h / 2 };
+}
+
+export function text<T>(channels: TextChannels<T>, options: TextOptions = {}): Geom<T> {
+  return {
+    kind: "text",
+    channels: { x: channels.x, y: channels.y },
+    label: options.label,
+    compile(ctx: CompileContext<T>) {
+      const { data, scales, plot, theme, atlas } = ctx;
+      if (!atlas) return [];
+      const coord = resolveCoord(ctx);
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const tAes = resolveAes<T, string>(channels.text);
+      const xFn = scales.x.fn;
+      const yFn = scales.y.fn;
+      const fontSize = options.fontSize ?? theme.marks.labelFontSize;
+      const align = options.align ?? "center";
+      const offsetX = options.offsetX ?? 0;
+      const offsetY = options.offsetY ?? 0;
+      const mode: TextCollisionMode = options.collisionMode ?? "none";
+      const pad = options.collisionPadding ?? 2;
+      const staggerDy = fontSize + 2;
+
+      // Indices into `data` we'll actually render. For "hide" mode we trim
+      // via greedy first-fit; for everything else we keep every row.
+      let keptIndices: readonly number[] = data.map((_, i) => i);
+      const staggerOffsets = new Map<number, number>();
+
+      if (mode === "hide" || mode === "stagger") {
+        // Measure all labels once. Stagger doesn't strictly need the rects,
+        // but unifying the path keeps the code legible.
+        const rects: LabelRect[] = [];
+        for (let i = 0; i < data.length; i++) {
+          const datum = data[i]!;
+          const rawX = xFn(xAes.fn(datum, i) as never);
+          const rawY = yFn(yAes.fn(datum, i) as never);
+          if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+          const projected = coord.project({ x: rawX, y: rawY });
+          const px = projected.x + offsetX;
+          const py = projected.y + offsetY;
+          const text = tAes.fn(datum, i);
+          const m = atlas.measureText(text, { fontSize, simple: true });
+          const origin = originForAlign(align, px, py, m.width, fontSize);
+          rects.push({ index: i, x: origin.x, y: origin.y, w: m.width, h: fontSize });
+        }
+
+        if (mode === "hide") {
+          const kept: LabelRect[] = [];
+          for (const r of rects) {
+            let collides = false;
+            for (const k of kept) {
+              if (rectsOverlap(r, k, pad)) {
+                collides = true;
+                break;
+              }
+            }
+            if (!collides) kept.push(r);
+          }
+          keptIndices = kept.map((r) => r.index);
+        } else {
+          // stagger: keep all, alternate odd rows by staggerDy. Tracked by
+          // original index so the y accessor below can branch cheaply.
+          for (let i = 0; i < rects.length; i++) {
+            if (i % 2 === 1) staggerOffsets.set(rects[i]!.index, staggerDy);
+          }
+        }
+      }
+
+      const renderData = mode === "hide" ? keptIndices.map((i) => data[i]!) : data;
+      const renderIndices = mode === "hide" ? keptIndices : null;
+      // Per-datum coord projection — under Cartesian, identity. Stagger
+      // offsets are post-projection layer-pixel deltas (additive in the
+      // current frame), so we apply them after projecting.
+      const projectLabel = (d: T, originalIndex: number): { x: number; y: number } => {
+        const rawX = xFn(xAes.fn(d, originalIndex) as never);
+        const rawY = yFn(yAes.fn(d, originalIndex) as never);
+        return coord.project({ x: rawX, y: rawY });
+      };
+      const mark = valueLabelMark(renderData, {
+        x: (d, i) => {
+          const originalIndex = renderIndices ? renderIndices[i]! : i;
+          return projectLabel(d, originalIndex).x;
+        },
+        y: (d, i) => {
+          const originalIndex = renderIndices ? renderIndices[i]! : i;
+          const base = projectLabel(d, originalIndex).y;
+          const stagger = mode === "stagger" ? (staggerOffsets.get(originalIndex) ?? 0) : 0;
+          return base + stagger;
+        },
+        text: (d, i) => {
+          const originalIndex = renderIndices ? renderIndices[i]! : i;
+          return tAes.fn(d, originalIndex);
+        },
+        fontSize,
+        color: options.color ?? theme.text.color,
+        align,
+        offset: { x: offsetX, y: offsetY },
+        box: options.box,
+      });
+      return [wrapMark(mark, plot.topLeft, renderData.length)];
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot, theme } = ctx;
+      if (data.length === 0) return null;
+      const coord = resolveCoord(ctx);
+      const xAes = resolveAes<T, unknown>(channels.x as Aes<T, unknown>);
+      const yAes = resolveAes<T, unknown>(channels.y as Aes<T, unknown>);
+      const tAes = resolveAes<T, string>(channels.text);
+      const xFn = scales.x.fn;
+      const yFn = scales.y.fn;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      const positions = new Float32Array(data.length * 2);
+      const dataIndex = new Int32Array(data.length);
+      let n = 0;
+      for (let i = 0; i < data.length; i++) {
+        const datum = data[i]!;
+        const rawX = xFn(xAes.fn(datum, i) as never);
+        const rawY = yFn(yAes.fn(datum, i) as never);
+        if (!Number.isFinite(rawX) || !Number.isFinite(rawY)) continue;
+        const projected = coord.project({ x: rawX, y: rawY });
+        positions[n * 2] = ox + projected.x;
+        positions[n * 2 + 1] = oy + projected.y;
+        dataIndex[n] = i;
+        n++;
+      }
+      if (n === 0) return null;
+      // Pick within a glyph-sized halo. Errors on the side of forgiving so
+      // labels remain easy to hover (they're typically sparse vs. point clouds).
+      const fontSize = options.fontSize ?? theme.marks.labelFontSize;
+      // Surface the text string in the tooltip via a synthetic accessor under
+      // the `shape` slot — `text` isn't a standard channel, and `shape` is
+      // otherwise unused by `text()`. The displayed label resolves from
+      // `aes.column` (set to "text"), so the slot choice is invisible to users.
+      const textAes = {
+        kind: "accessor" as const,
+        column: "text" as keyof T & string,
+        fn: tAes.fn,
+      };
+      const channelsMap: ResolvedChannelMap<T> = {
+        x: xAes,
+        y: yAes,
+        shape: textAes as never,
+      };
+      return {
+        geomKind: "text",
+        label: options.label,
+        positions: positions.subarray(0, n * 2),
+        dataIndex: dataIndex.subarray(0, n),
+        pickRadius: Math.max(8, fontSize),
+        channels: channelsMap,
+        data,
+      };
+    },
+  };
+}

package/src/grammar/geoms/tile.d.ts

@@ -0,0 +1,61 @@
+import type { Color } from "insomni";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export interface TileChannels<T> {
+    x: Aes<T, string | number | Date>;
+    y: Aes<T, string | number | Date>;
+    /**
+     * Continuous fill — typically a numeric column. Drives the chart's color
+     * scale (legend renders as a continuous color bar). For a per-cell constant
+     * color, pass `options.fill` instead and omit this channel.
+     */
+    fill?: Aes<T, unknown>;
+}
+export interface TileNAOptions {
+    /** Fill for missing/non-finite values. When unset, NA cells are skipped. */
+    fill?: Color;
+}
+export interface TileOptions<T = unknown> {
+    /**
+     * Constant cell color when no `fill` channel is mapped. Ignored when
+     * `channels.fill` is present (in which case the color scale supplies the
+     * fill).
+     */
+    fill?: Color;
+    /** Horizontal/vertical inset between cells. Default `0`. */
+    padding?: number;
+    /** Per-axis padding override (multi-key form). Wins over `padding`. */
+    paddingX?: number;
+    paddingY?: number;
+    /** Optional border outline per cell. */
+    stroke?: Color;
+    strokeWidth?: number;
+    cornerRadius?: number;
+    /**
+     * Per-cell text label. Receives the (numeric) fill value when the `fill`
+     * channel is mapped; receives `NaN` otherwise (in which case you'll
+     * typically derive the label from the datum directly).
+     */
+    showValues?: (value: number, datum: T, index: number) => string;
+    labelColor?: Color;
+    labelFontSize?: number;
+    /**
+     * Skip per-cell labels when the projected cell is below this pixel size on
+     * either axis. Labels at small cell sizes are unreadable smudges and the
+     * shaping cost dominates frame time at high cell counts. Default: unset
+     * (every cell labeled). A value around `1.5 * labelFontSize` is a sensible
+     * floor for legibility.
+     */
+    minLabelCellPx?: number;
+    /**
+     * For numeric/time x or y axes only — the implicit cell width/height in
+     * domain units. When omitted, the cell extent is inferred from the
+     * smallest gap between sorted unique values in the data.
+     */
+    cellWidth?: number;
+    cellHeight?: number;
+    /** Missing-value handling. */
+    na?: TileNAOptions;
+    label?: string;
+}
+export declare function tile<T>(channels: TileChannels<T>, options?: TileOptions<T>): Geom<T>;

package/src/grammar/geoms/tile.test.ts

@@ -0,0 +1,157 @@
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { tile } from "./tile.ts";
+import { emphasisKeyFor, geomEmphasisBase } from "./emphasis.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: string;
+  y: string;
+  v: number;
+}
+
+const data: Row[] = [
+  { x: "a", y: "p", v: 1 },
+  { x: "b", y: "p", v: 2 },
+  { x: "a", y: "q", v: 3 },
+  { x: "b", y: "q", v: 4 },
+];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("y");
+  const xScale = buildPositionScale(xAes, rows, [0, 100], { type: "band", padding: 0 });
+  const yScale = buildPositionScale(yAes, rows, [0, 200], { type: "band", padding: 0 });
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: 50, y: 30, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+    emphasisBase: geomEmphasisBase(0),
+  };
+}
+
+function captureRects(builders: ReturnType<ReturnType<typeof tile<Row>>["compile"]>) {
+  const rects: Array<{ fill?: unknown; emphasisKey?: number }> = [];
+  const layer = { pushRect: (s: { fill?: unknown; emphasisKey?: number }) => rects.push(s) };
+  for (const b of builders) b.addTo(layer as never);
+  return rects;
+}
+
+describe("tile geom — emphasis-key tagging (P5-T3)", () => {
+  test("tags each cell with a per-row key (ordinal = dataIndex); no hover dim/halo", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const base = geomEmphasisBase(0);
+    const plain = captureRects(geom.compile(makeCtx(data)));
+    expect(plain.length).toBe(4);
+    expect(plain.map((r) => r.emphasisKey)).toEqual([
+      emphasisKeyFor(base, 0),
+      emphasisKeyFor(base, 1),
+      emphasisKeyFor(base, 2),
+      emphasisKeyFor(base, 3),
+    ]);
+    // Fills are stable across hover (compile no longer reads ctx.hovered).
+    const hovered = captureRects(
+      geom.compile({
+        ...makeCtx(data),
+        hovered: { geomKind: "tile", dataIndex: 1, data, x: 0, y: 0 },
+      }),
+    );
+    expect(hovered.map((r) => r.fill)).toEqual(plain.map((r) => r.fill));
+  });
+
+  test("resolver maps a hit's dataIndex to the tagged key", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const res = geom.emphasisResolution!(makeCtx(data))!;
+    expect(res.resolve({ geomKind: "tile", dataIndex: 3, data, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(geomEmphasisBase(0), 3),
+    );
+    // A hit from another geom is not ours.
+    expect(res.resolve({ geomKind: "bar", dataIndex: 0, data, x: 0, y: 0 })).toBeNull();
+  });
+
+  test("no emphasisBase (SSR/SVG) → cells untagged", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const ctx = { ...makeCtx(data), emphasisBase: undefined };
+    const rects = captureRects(geom.compile(ctx));
+    expect(rects.every((r) => r.emphasisKey === undefined)).toBe(true);
+  });
+});
+
+describe("tile geom — compileHitTest", () => {
+  test("emits one hit per cell at center", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.geomKind).toBe("tile");
+    expect(hits.dataIndex.length).toBe(4);
+    // Band x range = [0,100], two bands "a","b" → bandwidth 50, centers at 25, 75.
+    // First row x="a" → center x = 25; +plot.x(50) = 75.
+    expect(hits.positions[0]).toBeCloseTo(75, 3);
+    // Band y range = [0,200], two bands "p","q" → bandwidth 100, centers at 50, 150.
+    // First row y="p" → center y = 50; +plot.y(30) = 80.
+    expect(hits.positions[1]).toBeCloseTo(80, 3);
+  });
+
+  test("pickRadius is half the smallest cell extent", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    // min(bandwidth_x=50, bandwidth_y=100) / 2 = 25.
+    expect(hits.pickRadius).toBeCloseTo(25, 3);
+  });
+
+  test("returns null for empty data", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    expect(geom.compileHitTest!(makeCtx([]))).toBeNull();
+  });
+
+  test("exposes x/y/color (fill) channels", () => {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.channels.x?.column).toBe("x");
+    expect(hits.channels.y?.column).toBe("y");
+    expect(hits.channels.color?.column).toBe("v");
+  });
+});
+
+describe("tile geom — focus halo decorator (Gap 2)", () => {
+  function decorate(dataIndex: number, hitData: readonly unknown[] = data) {
+    const geom = tile<Row>({ x: "x", y: "y", fill: "v" });
+    const deco = geom.hoverDecoration!(makeCtx(data))!;
+    const rects: Array<{
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+      fill?: unknown;
+      stroke?: unknown;
+      strokeWidth?: number;
+      emphasisKey?: number;
+    }> = [];
+    const layer = { pushRect: (s: never) => rects.push(s) };
+    deco.decorate({ geomKind: "tile", dataIndex, data: hitData, x: 0, y: 0 }, layer as never);
+    return { deco, rects };
+  }
+
+  test("emits a stroke-only halo rect at the hovered cell, exempt from dim", () => {
+    const { deco, rects } = decorate(2);
+    expect(deco.geomKind).toBe("tile");
+    expect(rects.length).toBe(1);
+    expect(rects[0]!.fill).toBeUndefined();
+    expect(rects[0]!.stroke).toBeDefined();
+    expect(rects[0]!.strokeWidth).toBe(themeDefault.interactions.hover.haloStrokeWidth);
+    expect(rects[0]!.emphasisKey).toBeUndefined();
+    // The halo covers row 2's cell (x="a", y="q") — top-left at plot origin.
+    expect(rects[0]!.width).toBeGreaterThan(0);
+    expect(rects[0]!.height).toBeGreaterThan(0);
+  });
+
+  test("hover on a foreign data array emits nothing", () => {
+    expect(decorate(0, []).rects.length).toBe(0);
+  });
+});