insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,75 @@
+import type { Color } from "insomni";
+import { type BinClosed, type BinResult, type BinRule, type HistogramMeasure } from "../../stats/index.ts";
+export type { HistogramMeasure };
+import { type Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export type HistogramPosition = "identity" | "stack" | "dodge" | "fill";
+export interface HistogramChannels<T> {
+    /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+    x?: Aes<T, number>;
+    /** Numeric variable to bin. Provide one of `x` (vertical bars) or `y`. */
+    y?: Aes<T, number>;
+    /** Optional categorical group key — splits the sample into per-group bins. */
+    color?: Aes<T, unknown>;
+}
+export interface HistogramOptions {
+    /** Explicit bin count. Loses to `binwidth` and `breaks`. */
+    bins?: number;
+    /** Explicit bin width in data units. Beats `bins` and `rule`. */
+    binwidth?: number;
+    /** Fully explicit edge array. Beats every other bin selector. */
+    breaks?: readonly number[];
+    /**
+     * Auto-bin rule when none of `bins`, `binwidth`, `breaks` is set.
+     *
+     * - `"sturges"` (default) — R / ggplot default; works for ~normal data.
+     * - `"rice"` — slightly more bins.
+     * - `"scott"` — uses σ; good for normal-ish data.
+     * - `"fd"` — Freedman–Diaconis; robust to outliers.
+     */
+    rule?: BinRule;
+    /** Clip / extend the value-axis range used when computing edges. */
+    domain?: readonly [number, number];
+    /** Round outer edges + step to nice numbers. Default `true`. */
+    nice?: boolean;
+    /** Edge convention. Default `"left"` (`[x0, x1)` plus closed last bin). */
+    closed?: BinClosed;
+    /**
+     * Y measure. Default `"count"`.
+     *
+     * - `"count"` / `"frequency"` — raw bin count.
+     * - `"density"` — `count / (n · width)`. Integrates to 1 across bins.
+     * - `"proportion"` — `count / n`. Sums to 1 across bins (per group).
+     */
+    y?: HistogramMeasure;
+    /**
+     * Multi-group layout. Default `"stack"` when `color` channel is present,
+     * else `"identity"`.
+     *
+     * - `"identity"` — bars share a baseline of 0; useful with reduced
+     *   `fillAlpha` for an overlay effect.
+     * - `"stack"` — per-bin counts stacked.
+     * - `"dodge"` — sub-divide bin width across groups, side by side.
+     * - `"fill"` — stack normalized to `[0, 1]` per bin.
+     */
+    position?: HistogramPosition;
+    /** Render bars below the baseline (negate the count axis). Default `false`. */
+    mirror?: boolean;
+    /** Override theme `fillAlpha`. Lower this for `position: "identity"` overlays. */
+    fillAlpha?: number;
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    cornerRadius?: number;
+    /** Pixel gap between adjacent bars. Default `0` (continuous wall). */
+    gap?: number;
+    /** Inner-band padding for `position: "dodge"` (fraction of bin width). Default `0.05`. */
+    groupPadding?: number;
+    /** Optional per-bar label (uses bin midpoint + value). */
+    showCounts?: (value: number, bin: BinResult, key?: string) => string;
+    labelColor?: Color;
+    labelFontSize?: number;
+    /** Used by the auto-legend. */
+    label?: string;
+}
+export declare function histogram<T>(channels: HistogramChannels<T>, options?: HistogramOptions): Geom<T>;

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

@@ -0,0 +1,262 @@
+// @vitest-environment jsdom
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+import { plot } from "../chart.ts";
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { histogram } from "./histogram.ts";
+import { emphasisKeyFor, geomEmphasisBase } from "./emphasis.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  value: number;
+  group?: string;
+}
+
+const ROWS: Row[] = [
+  // Two groups with overlapping ranges so every bin has data from both.
+  ...Array.from({ length: 100 }, (_, i) => ({ value: i / 10, group: "A" }) as Row),
+  ...Array.from({ length: 100 }, (_, i) => ({ value: i / 10, group: "B" }) as Row),
+];
+
+function rectCount(svg: SVGSVGElement): number {
+  // The chart's background frame contributes one <rect>; subtract it before
+  // asserting on bar counts.
+  return svg.querySelectorAll("rect").length;
+}
+
+describe("histogram()", () => {
+  test("renders one rect per bin for a single distribution", () => {
+    const svg = plot({ data: ROWS, width: 400, height: 300 })
+      .layer(histogram({ x: "value" }, { bins: 10, nice: false }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    // 10 bins + 1 background; tolerate extra (axis frame). Must be ≥ 11.
+    expect(rectCount(svg)).toBeGreaterThanOrEqual(11);
+  });
+
+  test("explicit `breaks` overrides any rule and pins edges", () => {
+    const svg = plot({ data: ROWS, width: 320, height: 240 })
+      .layer(histogram({ x: "value" }, { breaks: [0, 5, 10] }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    expect(rectCount(svg)).toBeGreaterThanOrEqual(3);
+  });
+
+  test("dodge position renders one rect per (bin, group)", () => {
+    const baseline = plot({ data: ROWS, width: 320, height: 240 })
+      .layer(histogram({ x: "value" }, { bins: 4, nice: false, position: "stack" }))
+      .toSVG();
+    const dodged = plot({ data: ROWS, width: 320, height: 240 })
+      .layer(histogram({ x: "value", color: "group" }, { bins: 4, nice: false, position: "dodge" }))
+      .toSVG();
+    expect(rectCount(dodged)).toBeGreaterThan(rectCount(baseline));
+  });
+
+  test("identity overlay produces one rect per (bin, group) with shared baseline", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(
+          histogram(
+            { x: "value", color: "group" },
+            { bins: 8, nice: false, position: "identity", fillAlpha: 0.4 },
+          ),
+        )
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("fill position normalizes per bin", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(
+          histogram({ x: "value", color: "group" }, { bins: 8, nice: false, position: "fill" }),
+        )
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("density measure does not throw and renders bars", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(histogram({ x: "value" }, { bins: 10, nice: false, y: "density" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("mirror flips bars below baseline", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(histogram({ x: "value" }, { bins: 10, nice: false, mirror: true }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("horizontal orientation via `y` channel", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(histogram({ y: "value" }, { bins: 10, nice: false }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("rejects providing both `x` and `y`", () => {
+    expect(() =>
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      histogram({ x: "value", y: "value" } as any),
+    ).toThrow();
+  });
+
+  test("rejects empty channels", () => {
+    expect(() =>
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      histogram({} as any),
+    ).toThrow();
+  });
+
+  test("does not throw on empty data", () => {
+    expect(() =>
+      plot({ data: [] as Row[], width: 200, height: 200 })
+        .layer(histogram({ x: "value" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("does not throw on all-equal values", () => {
+    const flat: Row[] = Array.from({ length: 5 }, () => ({ value: 7 }));
+    expect(() =>
+      plot({ data: flat, width: 200, height: 200 })
+        .layer(histogram({ x: "value" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("two layers compose into a back-to-back mirrored histogram", () => {
+    const aOnly: Row[] = ROWS.filter((r) => r.group === "A");
+    const bOnly: Row[] = ROWS.filter((r) => r.group === "B");
+    expect(() =>
+      plot({ data: [...aOnly, ...bOnly], width: 400, height: 300 })
+        .layer(histogram({ x: "value" }, { bins: 12, nice: false }))
+        .layer(histogram({ x: "value" }, { bins: 12, nice: false, mirror: true }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("custom domain clips bins", () => {
+    expect(() =>
+      plot({ data: ROWS, width: 320, height: 240 })
+        .layer(histogram({ x: "value" }, { domain: [2, 8], bins: 6, nice: false }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("compileHitTest emits one hit per (group, bin)", () => {
+    const xAes = resolveAes<Row, unknown>("value");
+    // Synthesize a Y aes — histogram doesn't use it for layout but the
+    // pipeline expects a position scale built from data.
+    const xScale = buildPositionScale(xAes, ROWS, [0, 300], { domain: [0, 10] });
+    const yScale = buildPositionScale(xAes, ROWS, [200, 0], { domain: [0, 100] });
+    const scales: ScaleBundle = { x: xScale, y: yScale };
+    const ctx: CompileContext<Row> = {
+      data: ROWS,
+      scales,
+      plot: createFrame({ x: 50, y: 30, width: 300, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+    const geom = histogram<Row>(
+      { x: "value", color: "group" },
+      { bins: 4, nice: false, position: "dodge" },
+    );
+    const hits = geom.compileHitTest!(ctx)!;
+    expect(hits.geomKind).toBe("histogram");
+    // 4 bins × 2 groups = 8 hits (every bin has data from both groups).
+    expect(hits.dataIndex.length).toBe(8);
+    // Color channel should be present and surface the group key.
+    const colorAes = hits.channels.color!;
+    expect(colorAes.fn(ROWS[0]!, 0)).toBe("A");
+  });
+
+  test("tags each cell with a per-cell emphasis key (ordinal = flat cell index)", () => {
+    const xAes = resolveAes<Row, unknown>("value");
+    const xScale = buildPositionScale(xAes, ROWS, [0, 300], { domain: [0, 10] });
+    const yScale = buildPositionScale(xAes, ROWS, [200, 0], { domain: [0, 100] });
+    const scales: ScaleBundle = { x: xScale, y: yScale };
+    const ctx: CompileContext<Row> = {
+      data: ROWS,
+      scales,
+      plot: createFrame({ x: 50, y: 30, width: 300, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+      emphasisBase: geomEmphasisBase(2), // pretend this is geom index 2
+    };
+    const geom = histogram<Row>(
+      { x: "value", color: "group" },
+      { bins: 4, nice: false, position: "dodge" },
+    );
+    const rects: Array<{ emphasisKey?: number }> = [];
+    const layer = { pushRect: (s: { emphasisKey?: number }) => rects.push(s), pushText: () => {} };
+    for (const b of geom.compile(ctx)) b.addTo(layer as never);
+    const base = geomEmphasisBase(2);
+    const tagged = rects.filter((r) => r.emphasisKey !== undefined);
+    // 4 bins × 2 groups = 8 cells; keys are the flat cellN ordinals 0..7.
+    expect(tagged.length).toBe(8);
+    expect(tagged.map((r) => r.emphasisKey).sort((a, b) => a! - b!)).toEqual(
+      Array.from({ length: 8 }, (_, i) => emphasisKeyFor(base, i)),
+    );
+    // Resolver: a hit's dataIndex (= cellN) maps to the same key.
+    const res = geom.emphasisResolution!(ctx)!;
+    expect(res.resolve({ geomKind: "histogram", dataIndex: 5, data: ROWS, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(base, 5),
+    );
+  });
+});
+
+describe("histogram() — focus halo decorator (Gap 2)", () => {
+  function makeCtx(): CompileContext<Row> {
+    const xAes = resolveAes<Row, unknown>("value");
+    const xScale = buildPositionScale(xAes, ROWS, [0, 300], { domain: [0, 10] });
+    const yScale = buildPositionScale(xAes, ROWS, [200, 0], { domain: [0, 100] });
+    const scales: ScaleBundle = { x: xScale, y: yScale };
+    return {
+      data: ROWS,
+      scales,
+      plot: createFrame({ x: 50, y: 30, width: 300, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+  }
+  function decorate(dataIndex: number, hitData: readonly unknown[] = ROWS) {
+    const geom = histogram<Row>({ x: "value", color: "group" }, { bins: 4, nice: false });
+    const ctx = makeCtx();
+    const deco = geom.hoverDecoration!(ctx)!;
+    const rects: Array<{
+      fill?: unknown;
+      stroke?: unknown;
+      strokeWidth?: number;
+      emphasisKey?: number;
+    }> = [];
+    const layer = { pushRect: (s: never) => rects.push(s) };
+    deco.decorate({ geomKind: "histogram", 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(3);
+    expect(deco.geomKind).toBe("histogram");
+    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();
+  });
+
+  test("hover on a foreign data array emits nothing", () => {
+    expect(decorate(0, []).rects.length).toBe(0);
+  });
+
+  test("out-of-range cell index emits nothing", () => {
+    expect(decorate(9999).rects.length).toBe(0);
+  });
+});