insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/band.ts

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// band geom — highlighted x or y range
+// ---------------------------------------------------------------------------
+// `band({ x: [a, b] })`  → vertical band between x=a and x=b
+// `band({ y: [a, b] })`  → horizontal band
+
+import type { Color } from "insomni";
+import { bandMark } from "../../annotations.ts";
+import { isAccentKey, resolveAccent, withAlpha, type ColorOrAccent } from "../color-utils.ts";
+import type { CompileContext, CompiledHitTest, Geom } from "./types.ts";
+import { wrapMark } from "./_mark.ts";
+
+export interface BandChannels {
+  x?: readonly [number | Date, number | Date];
+  y?: readonly [number | Date, number | Date];
+}
+
+export interface BandOptions {
+  /**
+   * Fill color. Accepts a literal {@link Color} or a theme accent key
+   * (`"positive" | "negative" | "warn" | "info"`); accent keys resolve through
+   * `theme.accents` and have `theme.marks.bandFillAlpha` applied unless
+   * {@link BandOptions.alpha} is set.
+   */
+  fill?: ColorOrAccent;
+  stroke?: ColorOrAccent;
+  strokeWidth?: number;
+  /**
+   * Override the fill alpha. Defaults to `theme.marks.bandFillAlpha` when
+   * `fill` is omitted or is an accent key; defaults to no override (use the
+   * color's own alpha) when `fill` is a literal {@link Color}.
+   */
+  alpha?: number;
+  label?: string;
+  labelColor?: Color;
+}
+
+export function band<T>(channels: BandChannels, options: BandOptions = {}): Geom<T> {
+  if (!channels.x && !channels.y) {
+    throw new Error("band(): one of `x` or `y` must be provided");
+  }
+  const vertical = channels.x !== undefined;
+  return {
+    kind: "band",
+    channels: {},
+    label: options.label,
+    compile(ctx: CompileContext<T>) {
+      const { scales, plot, theme, atlas } = ctx;
+      const rawFill = resolveAccent(options.fill, theme) ?? theme.text.color;
+      // Apply alpha when the user supplied one, or when the fill is an accent
+      // key / falls through to the default text color — accents and text are
+      // saturated and need a tint multiplier to read as a band.
+      const needsDefaultAlpha = options.fill === undefined || isAccentKey(options.fill);
+      const fillAlpha =
+        options.alpha ?? (needsDefaultAlpha ? theme.marks.bandFillAlpha : undefined);
+      const fill = fillAlpha !== undefined ? withAlpha(rawFill, fillAlpha) : rawFill;
+      const stroke = resolveAccent(options.stroke, theme);
+      const strokeWidth = options.strokeWidth;
+      const labelColor = options.labelColor ?? theme.subtitle.color;
+      const fontSize = theme.marks.annotationFontSize;
+
+      const sharedStyle = {
+        fill,
+        stroke,
+        strokeWidth,
+        label: options.label,
+        labelColor,
+        atlas,
+        fontSize,
+      };
+      const mark = vertical
+        ? bandMark({
+            x: [scales.x.fn(channels.x![0]), scales.x.fn(channels.x![1])],
+            extent: [0, plot.height],
+            ...sharedStyle,
+          })
+        : bandMark({
+            y: [scales.y.fn(channels.y![0]), scales.y.fn(channels.y![1])],
+            extent: [0, plot.width],
+            ...sharedStyle,
+          });
+      return [wrapMark(mark, plot.topLeft, 1)];
+    },
+    compileHitTest(ctx: CompileContext<T>): CompiledHitTest<T> | null {
+      const { data, scales, plot } = ctx;
+      const ox = plot.topLeft.x;
+      const oy = plot.topLeft.y;
+      // Single synthetic hit at the band's center. Channels stay empty —
+      // tooltip relies on the band's `label` for title text.
+      let cx: number;
+      let cy: number;
+      let halfX: number;
+      let halfY: number;
+      if (vertical) {
+        const a = scales.x.fn(channels.x![0]);
+        const b = scales.x.fn(channels.x![1]);
+        if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
+        cx = ox + (a + b) / 2;
+        cy = oy + plot.height / 2;
+        halfX = Math.abs(b - a) / 2;
+        halfY = plot.height / 2;
+      } else {
+        const a = scales.y.fn(channels.y![0]);
+        const b = scales.y.fn(channels.y![1]);
+        if (!Number.isFinite(a) || !Number.isFinite(b)) return null;
+        cx = ox + plot.width / 2;
+        cy = oy + (a + b) / 2;
+        halfX = plot.width / 2;
+        halfY = Math.abs(b - a) / 2;
+      }
+      const positions = new Float32Array([cx, cy]);
+      const dataIndex = new Int32Array([0]);
+      const rects = new Float32Array([cx - halfX, cy - halfY, halfX * 2, halfY * 2]);
+      return {
+        geomKind: "band",
+        label: options.label,
+        positions,
+        dataIndex,
+        rects,
+        pickRadius: Math.max(halfX, halfY),
+        channels: {},
+        data,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,56 @@
+import { type Color } from "insomni";
+import { type BarBorderStyle, type BarOrientation, type StackOrder } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export type BarPosition = "identity" | "stack" | "dodge" | "fill";
+export interface BarChannels<T> {
+    x: Aes<T, string | number | Date>;
+    /**
+     * Single column → simple bars (one per category). Array of column keys →
+     * multi-series bars (stacked / dodged / 100% stacked).
+     *
+     * For horizontal layouts (`orientation: "x"`) the single-column form carries
+     * the band category, so a string is accepted; the value axis then lives on
+     * `x`.
+     */
+    y: Aes<T, string | number | Date> | readonly (keyof T & string)[];
+    color?: Aes<T, unknown>;
+}
+export interface BarOptions<T = unknown> {
+    orientation?: BarOrientation;
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    cornerRadius?: number;
+    /**
+     * Border treatment shared across every bar (or segment, for stacked/dodged
+     * layouts). See {@link BarBorderStyle}.
+     */
+    borderStyle?: BarBorderStyle;
+    /**
+     * Multi-series layout. Only meaningful when `y` (or `x`) is an array of keys.
+     * - `"stack"` (default for arrays) — segments stacked from 0
+     * - `"dodge"` — bars side-by-side within each category
+     * - `"fill"` — stacked, normalized to [0, 1]
+     * - `"identity"` — each datum drawn at its raw value
+     */
+    position?: BarPosition;
+    order?: StackOrder;
+    label?: string;
+    /** Inner-band padding for `position: 'dodge'`. Default 0.05. */
+    groupPadding?: number;
+    /** If set, render a label above each bar with the per-category total. */
+    showTotals?: (total: number, datum: T, datumIndex: number) => string;
+    /**
+     * If set, render a label per-bar (or per-segment for stacked / fill) with
+     * the segment's value. For `fill`, the supplied `value` is normalized
+     * `[0, 1]`; for other positions it's the raw segment value. `key` is the
+     * column name for multi-series bars, `undefined` for simple bars.
+     */
+    showValues?: (value: number, datum: T, datumIndex: number, key?: string) => string;
+    /** Override label color. */
+    labelColor?: Color;
+    /** Override label font size. */
+    labelFontSize?: number;
+}
+export declare function bar<T>(channels: BarChannels<T>, options?: BarOptions<T>): Geom<T>;

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

@@ -0,0 +1,367 @@
+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 { bar } from "./bar.ts";
+import { emphasisKeyFor, geomEmphasisBase } from "./emphasis.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  cat: string;
+  val: number;
+  group: string;
+  east?: number;
+  west?: number;
+}
+
+const data: Row[] = [
+  { cat: "a", val: 10, group: "x" },
+  { cat: "b", val: 20, group: "y" },
+  { cat: "c", val: 5, group: "x" },
+];
+
+function makeCtx(rows: readonly Row[]): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("cat");
+  const yAes = resolveAes<Row, unknown>("val");
+  // Domain for value axis must include 0 (bar baseline) for tests to be sane.
+  const xScale = buildPositionScale(xAes, rows, [0, 100]);
+  const yScale = buildPositionScale(yAes, rows, [200, 0], { domain: [0, 20] });
+  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,
+    // Geom index 0 → emphasis band base (P5-T3). Enables emphasis-key tagging.
+    emphasisBase: geomEmphasisBase(0),
+  };
+}
+
+function fakeRectLayer(): {
+  rects: Array<{ x: number; y: number; width: number; height: number }>;
+  layer: { pushRect: (shape: { x: number; y: number; width: number; height: number }) => void };
+} {
+  const rects: Array<{ x: number; y: number; width: number; height: number }> = [];
+  return {
+    rects,
+    layer: {
+      pushRect(shape) {
+        rects.push(shape);
+      },
+    },
+  };
+}
+
+describe("bar geom — compileHitTest", () => {
+  test("emits one hit per simple bar at bar bbox center (absolute px)", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits).not.toBeNull();
+    expect(hits.geomKind).toBe("bar");
+    expect(hits.dataIndex.length).toBe(3);
+    // y center for cat "a" (val=10): baseline=200 (val=0), top=100 (val=10)
+    // → mid = 150, absolute = plot.y + 150 = 180
+    expect(hits.positions[1]).toBeCloseTo(180, 3);
+  });
+
+  test("dataIndex preserves order with all-finite data", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(Array.from(hits.dataIndex)).toEqual([0, 1, 2]);
+  });
+
+  test("filters non-finite values", () => {
+    const dirty: Row[] = [
+      { cat: "a", val: 10, group: "x" },
+      { cat: "b", val: NaN, group: "y" },
+      { cat: "c", val: 5, group: "x" },
+    ];
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const hits = geom.compileHitTest!(makeCtx(dirty))!;
+    expect(Array.from(hits.dataIndex)).toEqual([0, 2]);
+  });
+
+  test("captures channel metadata for tooltip labels", () => {
+    const geom = bar<Row>({ x: "cat", y: "val", color: "group" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.channels.x?.column).toBe("cat");
+    expect(hits.channels.y?.column).toBe("val");
+    expect(hits.channels.color?.column).toBe("group");
+  });
+
+  test("returns null for empty data", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    expect(geom.compileHitTest!(makeCtx([]))).toBeNull();
+  });
+
+  test("emits one hit per visible segment for stacked multi-series bars", () => {
+    const rows: Row[] = [
+      { cat: "a", val: 0, group: "g", east: 4, west: 6 },
+      { cat: "b", val: 0, group: "g", east: 3, west: 5 },
+    ];
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const hits = geom.compileHitTest!(makeCtx(rows))!;
+    expect(Array.from(hits.dataIndex)).toEqual([0, 0, 1, 1]);
+    expect(hits.seriesKey).toEqual(["east", "west", "east", "west"]);
+  });
+
+  test("omits hidden segments from multi-series hit-test output", () => {
+    const rows: Row[] = [{ cat: "a", val: 0, group: "g", east: 4, west: 6 }];
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const hits = geom.compileHitTest!({
+      ...makeCtx(rows),
+      hidden: new Set(["west"]),
+    })!;
+    expect(Array.from(hits.dataIndex)).toEqual([0]);
+    expect(hits.seriesKey).toEqual(["east"]);
+  });
+
+  test("captures one frame entry per visible segment for multi-series bars", () => {
+    const rows: Row[] = [{ cat: "a", val: 0, group: "g", east: 4, west: 6 }];
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const frame = geom.captureFrame!(makeCtx(rows))!;
+    expect(frame.count).toBe(2);
+    expect(Array.from(frame.r!)).toEqual([4, 6]);
+  });
+
+  test("stacked multi-series compile lerps segment heights during activeTransition", () => {
+    const fromRows: Row[] = [{ cat: "a", val: 0, group: "g", east: 4, west: 4 }];
+    const toRows: Row[] = [{ cat: "a", val: 0, group: "g", east: 8, west: 8 }];
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const from = geom.captureFrame!(makeCtx(fromRows))!;
+    const builders = geom.compile({
+      ...makeCtx(toRows),
+      activeTransition: {
+        t: 0.5,
+        from,
+        matchIndex: (_key, fallbackIndex) => fallbackIndex,
+      },
+    });
+    const { rects, layer } = fakeRectLayer();
+    for (const builder of builders) builder.addTo(layer as never);
+    expect(rects).toHaveLength(2);
+    expect(rects[0]!.height).toBeCloseTo(60, 3);
+    expect(rects[1]!.height).toBeCloseTo(60, 3);
+  });
+
+  test("pickRadius covers half-bandwidth or half-bar-height", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    // The tallest bar (val=20) spans 0..200 so half-height is 100.
+    expect(hits.pickRadius).toBeGreaterThanOrEqual(100);
+  });
+});
+
+describe("bar geom — multi-series halos & selection rings", () => {
+  const rows: Row[] = [
+    { cat: "a", val: 0, group: "g", east: 4, west: 6 },
+    { cat: "b", val: 0, group: "g", east: 3, west: 5 },
+  ];
+
+  function countStrokedRects(builders: ReturnType<ReturnType<typeof bar<Row>>["compile"]>) {
+    const { rects, layer } = fakeRectLayer();
+    const stroked: Array<{ fill?: unknown; stroke?: unknown }> = [];
+    const allRects: Array<{ fill?: unknown; stroke?: unknown; emphasisKey?: number }> = [];
+    const wrapped = {
+      pushRect: (shape: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        fill?: unknown;
+        stroke?: unknown;
+        emphasisKey?: number;
+      }) => {
+        layer.pushRect(shape);
+        allRects.push(shape);
+        if (shape.stroke !== undefined) stroked.push(shape);
+      },
+    };
+    for (const builder of builders) builder.addTo(wrapped as never);
+    return { rects, stroked, allRects };
+  }
+
+  test("stacked: tags each segment with a per-segment emphasis key (no hover halo)", () => {
+    const ctx = makeCtx(rows);
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const builders = geom.compile({
+      ...ctx,
+      hovered: { geomKind: "bar", dataIndex: 0, seriesKey: "west", data: rows, x: 0, y: 0 },
+    });
+    const { stroked, allRects } = countStrokedRects(builders);
+    // The marks-baked hover halo is gone (GPU dim replaces it) — no stroked ring.
+    expect(stroked.length).toBe(0);
+    // 2 rows × 2 series = 4 tagged segment rects, each with a distinct key.
+    const tagged = allRects.filter((r) => r.emphasisKey !== undefined);
+    expect(tagged.length).toBe(4);
+    // Stable namespacing: ordinal = dataIndex * keys.length + seriesIndex (full
+    // keys ["east","west"]); base = geom 0's band. (row0,east)=ord0, (row0,west)=ord1.
+    const base = geomEmphasisBase(0);
+    const keysSet = new Set(tagged.map((r) => r.emphasisKey));
+    expect(keysSet.has(emphasisKeyFor(base, 0))).toBe(true); // row0,east
+    expect(keysSet.has(emphasisKeyFor(base, 1))).toBe(true); // row0,west
+    expect(keysSet.size).toBe(4); // all distinct
+  });
+
+  test("resolver maps a hit's (dataIndex, seriesKey) to the tagged key", () => {
+    const ctx = makeCtx(rows);
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const res = geom.emphasisResolution!(ctx)!;
+    expect(res).not.toBeNull();
+    const base = geomEmphasisBase(0);
+    // row1,west → ordinal 1*2 + 1 = 3.
+    expect(
+      res.resolve({ geomKind: "bar", dataIndex: 1, seriesKey: "west", data: rows, x: 0, y: 0 }),
+    ).toBe(emphasisKeyFor(base, 3));
+    // A hit with no seriesKey focuses nothing.
+    expect(res.resolve({ geomKind: "bar", dataIndex: 0, data: rows, x: 0, y: 0 })).toBeNull();
+  });
+
+  test("single bars tag per-row keys (ordinal = dataIndex)", () => {
+    const ctx = makeCtx(data);
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const builders = geom.compile(ctx);
+    const { allRects } = countStrokedRects(builders);
+    const tagged = allRects.filter((r) => r.emphasisKey !== undefined);
+    expect(tagged.length).toBe(3);
+    const base = geomEmphasisBase(0);
+    expect(tagged.map((r) => r.emphasisKey).sort((a, b) => a! - b!)).toEqual([
+      emphasisKeyFor(base, 0),
+      emphasisKeyFor(base, 1),
+      emphasisKeyFor(base, 2),
+    ]);
+    // Resolver mirrors the tag (ordinal = dataIndex).
+    const res = geom.emphasisResolution!(ctx)!;
+    expect(res.resolve({ geomKind: "bar", dataIndex: 2, data, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(base, 2),
+    );
+  });
+
+  test("compile no longer reads ctx.hovered for color (fills stable across hover)", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const plain = geom.compile(makeCtx(data));
+    const hovered = geom.compile({
+      ...makeCtx(data),
+      hovered: { geomKind: "bar", dataIndex: 0, data, x: 0, y: 0 },
+    });
+    const a = countStrokedRects(plain).allRects.map((r) => r.fill);
+    const b = countStrokedRects(hovered).allRects.map((r) => r.fill);
+    expect(a).toEqual(b);
+  });
+
+  test("stacked: selection rings draw one stroked rect per selected segment", () => {
+    const ctx = makeCtx(rows);
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const builders = geom.compile({
+      ...ctx,
+      selected: [
+        { geomKind: "bar", dataIndex: 0, seriesKey: "east", data: rows, x: 0, y: 0 },
+        { geomKind: "bar", dataIndex: 1, seriesKey: "west", data: rows, x: 0, y: 0 },
+      ],
+    });
+    const { stroked } = countStrokedRects(builders);
+    expect(stroked.length).toBe(2);
+  });
+
+  test("dodge: tags each segment with a per-segment emphasis key", () => {
+    const ctx = makeCtx(rows);
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] }, { position: "dodge" });
+    const builders = geom.compile(ctx);
+    const { stroked, allRects } = countStrokedRects(builders);
+    expect(stroked.length).toBe(0); // no hover halo
+    const tagged = allRects.filter((r) => r.emphasisKey !== undefined);
+    expect(tagged.length).toBe(4);
+  });
+
+  test("stacked: selected segments overlay a filled rect when selection dims base", () => {
+    const ctx = makeCtx(rows);
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const builders = geom.compile({
+      ...ctx,
+      selected: [{ geomKind: "bar", dataIndex: 0, seriesKey: "east", data: rows, x: 0, y: 0 }],
+    });
+    const { stroked } = countStrokedRects(builders);
+    expect(stroked.length).toBe(1);
+    expect(stroked[0]!.fill).toBeDefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Gap 2 — focus-halo overlay decorators. The marks-baked halo is gone; the
+// halo now rides hoverDecoration into the overlay layer. Mirrors point.test.ts.
+// ---------------------------------------------------------------------------
+
+interface CapturedRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  fill?: unknown;
+  stroke?: { r: number; g: number; b: number; a: number };
+  strokeWidth?: number;
+  emphasisKey?: number;
+}
+function decorateInto(
+  geom: ReturnType<typeof bar<Row>>,
+  ctx: CompileContext<Row>,
+  hit: { geomKind: string; dataIndex: number; seriesKey?: string; data: readonly unknown[] },
+): CapturedRect[] {
+  const out: CapturedRect[] = [];
+  const layer = { pushRect: (s: CapturedRect) => out.push(s) };
+  const deco = geom.hoverDecoration!(ctx)!;
+  deco.decorate(hit as never, layer as never);
+  return out;
+}
+
+describe("bar geom — focus halo decorator (Gap 2)", () => {
+  test("single: emits a stroke-only halo rect at the hovered bar, exempt from dim", () => {
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const ctx = makeCtx(data);
+    const deco = geom.hoverDecoration!(ctx)!;
+    expect(deco.geomKind).toBe("bar");
+    const rects = decorateInto(geom, ctx, {
+      geomKind: "bar",
+      dataIndex: 1,
+      data,
+    });
+    expect(rects.length).toBe(1);
+    const halo = rects[0]!;
+    // Stroke-only (no fill), width = theme halo width, key left default (exempt).
+    expect(halo.fill).toBeUndefined();
+    expect(halo.stroke).toBeDefined();
+    expect(halo.strokeWidth).toBe(themeDefault.interactions.hover.haloStrokeWidth);
+    expect(halo.emphasisKey).toBeUndefined();
+  });
+
+  test("single: hover on a foreign data array emits nothing", () => {
+    // The decorator guards on data identity; the mount's `decoratorFor` does the
+    // geomKind match before calling decorate (mirrors point.ts).
+    const geom = bar<Row>({ x: "cat", y: "val" });
+    const ctx = makeCtx(data);
+    expect(decorateInto(geom, ctx, { geomKind: "bar", dataIndex: 0, data: [] }).length).toBe(0);
+  });
+
+  test("stacked: halo rect for the hovered (dataIndex, seriesKey) segment", () => {
+    const rows: Row[] = [
+      { cat: "a", val: 0, group: "g", east: 4, west: 6 },
+      { cat: "b", val: 0, group: "g", east: 3, west: 5 },
+    ];
+    const geom = bar<Row>({ x: "cat", y: ["east", "west"] });
+    const ctx = makeCtx(rows);
+    const rects = decorateInto(geom, ctx, {
+      geomKind: "bar",
+      dataIndex: 0,
+      seriesKey: "west",
+      data: rows,
+    });
+    expect(rects.length).toBe(1);
+    expect(rects[0]!.fill).toBeUndefined();
+    expect(rects[0]!.strokeWidth).toBe(themeDefault.interactions.hover.haloStrokeWidth);
+    expect(rects[0]!.emphasisKey).toBeUndefined();
+    // A segment hit with no seriesKey draws nothing.
+    expect(decorateInto(geom, ctx, { geomKind: "bar", dataIndex: 0, data: rows }).length).toBe(0);
+  });
+});