insomni-plot 0.1.0-alpha.0

package/src/grammar/legend-merge.test.ts

@@ -0,0 +1,332 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveAes } from "./aes.ts";
+import type { PointSwatchSpec } from "../legend.ts";
+import type { LegendMergeChannel } from "./chart.ts";
+import { autoMergeChannels, composeMergedPointSwatch } from "./pipeline.ts";
+import {
+  buildBorderStyleScale,
+  buildCategoricalColorScale,
+  buildOverlayGlyphScale,
+  buildShapeScale,
+  buildSizeScale,
+  DEFAULT_BORDER_STYLE_PALETTE,
+  DEFAULT_OVERLAY_GLYPH_PALETTE,
+  type ScaleBundle,
+} from "./scales.ts";
+import { themeDefault } from "./theme.ts";
+
+interface Row {
+  category: string;
+  size: number;
+}
+
+const data: Row[] = [
+  { category: "a", size: 0 },
+  { category: "b", size: 5 },
+  { category: "c", size: 10 },
+];
+
+function makeScales(): ScaleBundle {
+  const catAes = resolveAes<Row, unknown>("category");
+  const sizeAes = resolveAes<Row, number>("size");
+  return {
+    // x/y are unused by composeMergedPointSwatch — supply trivial position scales.
+    x: {
+      kind: "position",
+      type: "linear",
+      dataType: "number",
+      axisScale: {} as never,
+      fn: () => 0,
+    },
+    y: {
+      kind: "position",
+      type: "linear",
+      dataType: "number",
+      axisScale: {} as never,
+      fn: () => 0,
+    },
+    color: buildCategoricalColorScale(["a", "b", "c"], themeDefault),
+    shape: buildShapeScale(catAes, data),
+    borderStyle: buildBorderStyleScale(catAes, data),
+    overlayGlyph: buildOverlayGlyphScale(catAes, data),
+    size: buildSizeScale(sizeAes, data),
+  };
+}
+
+function mergeSet(...chs: LegendMergeChannel[]): ReadonlySet<LegendMergeChannel> {
+  return new Set(chs);
+}
+
+const RED = { r: 1, g: 0, b: 0, a: 1 };
+
+describe("composeMergedPointSwatch", () => {
+  it("returns a point swatch with the given color and default radius when merge is empty", () => {
+    const s = makeScales();
+    const sw = composeMergedPointSwatch("a", RED, s, mergeSet(), themeDefault);
+    expect(sw.kind).toBe("point");
+    expect(sw.fill).toEqual(RED);
+    expect(sw.shape).toBeUndefined();
+    expect(sw.borderStyle).toBeUndefined();
+    expect(sw.overlayGlyph).toBeUndefined();
+  });
+
+  it("merges shape from the shape scale when 'shape' is listed", () => {
+    const s = makeScales();
+    const swA = composeMergedPointSwatch("a", RED, s, mergeSet("shape"), themeDefault);
+    const swB = composeMergedPointSwatch("b", RED, s, mergeSet("shape"), themeDefault);
+    expect(swA.shape).toBe(s.shape!.fn("a"));
+    expect(swB.shape).toBe(s.shape!.fn("b"));
+    expect(swA.shape).not.toBe(swB.shape);
+  });
+
+  it("merges borderStyle and sets stroke when the border is non-solid", () => {
+    const s = makeScales();
+    // Default palette index 1 is 'open' → stroke set, fill kept (legend draw layer
+    // treats 'open' by suppressing fill itself).
+    const sw = composeMergedPointSwatch("b", RED, s, mergeSet("borderStyle"), themeDefault);
+    expect(sw.borderStyle).toBe(DEFAULT_BORDER_STYLE_PALETTE[1]); // "open"
+    expect(sw.stroke).toEqual(RED);
+  });
+
+  it("does not set stroke when the merged borderStyle is 'solid'", () => {
+    const s = makeScales();
+    const sw = composeMergedPointSwatch("a", RED, s, mergeSet("borderStyle"), themeDefault);
+    expect(sw.borderStyle).toBe("solid");
+    expect(sw.stroke).toBeUndefined();
+  });
+
+  it("merges overlayGlyph from the overlay scale, skipping null slots", () => {
+    const s = makeScales();
+    const swA = composeMergedPointSwatch("a", RED, s, mergeSet("overlayGlyph"), themeDefault);
+    const swB = composeMergedPointSwatch("b", RED, s, mergeSet("overlayGlyph"), themeDefault);
+    // Default palette index 0 is null (most-common category has no overlay).
+    expect(DEFAULT_OVERLAY_GLYPH_PALETTE[0]).toBeNull();
+    expect(swA.overlayGlyph).toBeUndefined();
+    expect(swB.overlayGlyph).toBe(DEFAULT_OVERLAY_GLYPH_PALETTE[1]); // "plus"
+  });
+
+  it("merges size by sampling the scale at the numeric domain midpoint", () => {
+    const s = makeScales();
+    const sw = composeMergedPointSwatch("a", RED, s, mergeSet("size"), themeDefault);
+    const [d0, d1] = s.size!.domain;
+    const expected = s.size!.fn((d0 + d1) / 2) as number;
+    // Clamped to the legend swatch's [3, 9] range.
+    const clamped = Math.min(Math.max(expected, 3), 9);
+    expect(sw.radius).toBeCloseTo(clamped, 5);
+  });
+
+  it("composes all four categorical channels at once", () => {
+    const s = makeScales();
+    const sw: PointSwatchSpec = composeMergedPointSwatch(
+      "c",
+      RED,
+      s,
+      mergeSet("shape", "borderStyle", "overlayGlyph", "size"),
+      themeDefault,
+    );
+    expect(sw.shape).toBe(s.shape!.fn("c"));
+    expect(sw.borderStyle).toBe(s.borderStyle!.fn("c"));
+    expect(sw.overlayGlyph).toBe(s.overlayGlyph!.fn("c"));
+    expect(typeof sw.radius).toBe("number");
+  });
+
+  it("silently skips listed channels whose scale is absent on the bundle", () => {
+    const partial: ScaleBundle = {
+      x: {
+        kind: "position",
+        type: "linear",
+        dataType: "number",
+        axisScale: {} as never,
+        fn: () => 0,
+      },
+      y: {
+        kind: "position",
+        type: "linear",
+        dataType: "number",
+        axisScale: {} as never,
+        fn: () => 0,
+      },
+      color: buildCategoricalColorScale(["a"], themeDefault),
+      // shape/borderStyle/overlay/size all missing
+    };
+    const sw = composeMergedPointSwatch(
+      "a",
+      RED,
+      partial,
+      mergeSet("shape", "borderStyle", "overlayGlyph", "size"),
+      themeDefault,
+    );
+    expect(sw.shape).toBeUndefined();
+    expect(sw.borderStyle).toBeUndefined();
+    expect(sw.overlayGlyph).toBeUndefined();
+    // Default radius preserved.
+    expect(sw.radius).toBe(5);
+  });
+});
+
+describe("autoMergeChannels", () => {
+  it("returns shape/borderStyle/overlayGlyph when their domains match color's", () => {
+    const s = makeScales();
+    const out = autoMergeChannels(s.color!.domain, s);
+    expect(out).toEqual(["shape", "borderStyle", "overlayGlyph"]);
+  });
+
+  it("omits channels whose domain differs from color's", () => {
+    const s = makeScales();
+    // Swap shape scale for one with a different domain.
+    const shape = buildShapeScale(resolveAes<Row, unknown>("category"), data, {
+      domain: ["x", "y", "z"],
+    });
+    const out = autoMergeChannels(s.color!.domain, { ...s, shape });
+    expect(out).toEqual(["borderStyle", "overlayGlyph"]);
+  });
+
+  it("omits channels whose scale is absent", () => {
+    const s = makeScales();
+    const out = autoMergeChannels(s.color!.domain, { ...s, shape: undefined });
+    expect(out).toEqual(["borderStyle", "overlayGlyph"]);
+  });
+
+  it("returns empty when no non-color categorical channels are active", () => {
+    const s = makeScales();
+    const out = autoMergeChannels(s.color!.domain, {
+      ...s,
+      shape: undefined,
+      borderStyle: undefined,
+      overlayGlyph: undefined,
+    });
+    expect(out).toEqual([]);
+  });
+
+  it("skips empty-domain scales — no phantom merge when both color and channel are empty", () => {
+    const s = makeScales();
+    // Color scale with empty domain; shape scale also empty. domainsEqual([],[])
+    // would be true, but a merge with no entries is meaningless — guard returns [].
+    const emptyColor = buildCategoricalColorScale([], themeDefault);
+    const emptyShape = buildShapeScale(resolveAes<Row, unknown>("category"), []);
+    const out = autoMergeChannels(emptyColor.domain, {
+      ...s,
+      color: emptyColor,
+      shape: emptyShape,
+      borderStyle: undefined,
+      overlayGlyph: undefined,
+    });
+    expect(out).toEqual([]);
+  });
+
+  it("treats two Date arrays with equal instants as equal domains", () => {
+    const aes = resolveAes<{ d: Date }, unknown>("d");
+    const rows = [{ d: new Date(2026, 0, 1) }, { d: new Date(2026, 0, 2) }];
+    const colorDomain = [new Date(2026, 0, 1), new Date(2026, 0, 2)];
+    const shape = buildShapeScale(aes, rows);
+    const out = autoMergeChannels(colorDomain, {
+      color: buildCategoricalColorScale(colorDomain.map(String), themeDefault),
+      shape,
+    });
+    expect(out).toContain("shape");
+  });
+});
+
+describe("auto-merge end to end via plot.toSVG", () => {
+  it("merges color+shape automatically when both encode the same field", async () => {
+    const { plot } = await import("./chart.ts");
+    const { point } = await import("./geoms/index.ts");
+    // No explicit `.legend({ merge })`. Pipeline should detect the shared
+    // domain and emit one merged legend.
+    const svg = plot<Row>({ data, width: 400, height: 300 })
+      .layer(point<Row>({ x: "size", y: "size", color: "category", shape: "category" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+
+  it("explicit merge:[] disables auto-merge", async () => {
+    const { plot } = await import("./chart.ts");
+    const { point } = await import("./geoms/index.ts");
+    // Passing an empty `merge` is the way to opt out of auto-detection.
+    const svg = plot<Row>({ data, width: 400, height: 300 })
+      .layer(point<Row>({ x: "size", y: "size", color: "category", shape: "category" }))
+      .legend({ merge: [] })
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+});
+
+describe("buildBorderStyleScale", () => {
+  it("maps a categorical domain through the default palette", () => {
+    const scale = buildBorderStyleScale(resolveAes<Row, unknown>("category"), data);
+    expect(scale.domain).toEqual(["a", "b", "c"]);
+    expect(scale.fn("a")).toBe(DEFAULT_BORDER_STYLE_PALETTE[0]); // "solid"
+    expect(scale.fn("b")).toBe(DEFAULT_BORDER_STYLE_PALETTE[1]); // "open"
+    expect(scale.fn("c")).toBe(DEFAULT_BORDER_STYLE_PALETTE[2]); // "dashed"
+  });
+
+  it("falls back to the palette's first slot for unknown values", () => {
+    const scale = buildBorderStyleScale(resolveAes<Row, unknown>("category"), data);
+    expect(scale.fn("nope")).toBe(DEFAULT_BORDER_STYLE_PALETTE[0]);
+  });
+
+  it("respects an explicit palette and domain override", () => {
+    const scale = buildBorderStyleScale(resolveAes<Row, unknown>("category"), data, {
+      domain: ["b", "a"],
+      palette: ["dotted", "dashed"],
+    });
+    expect(scale.fn("b")).toBe("dotted");
+    expect(scale.fn("a")).toBe("dashed");
+  });
+});
+
+describe("LegendSpec.merge — end to end via chart.toSVG", () => {
+  it("renders a merged color+shape legend without throwing", async () => {
+    const { plot } = await import("./chart.ts");
+    const { point } = await import("./geoms/index.ts");
+    const svg = plot<Row>({ data, width: 400, height: 300 })
+      .layer(point<Row>({ x: "size", y: "size", color: "category", shape: "category" }))
+      .legend({ merge: ["color", "shape"] })
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+
+  it("merged borderStyle picks up scale-resolved values for non-literal categorical input", async () => {
+    const { plot } = await import("./chart.ts");
+    const { point } = await import("./geoms/index.ts");
+    const svg = plot<Row>({ data, width: 400, height: 300 })
+      .layer(point<Row>({ x: "size", y: "size", color: "category", borderStyle: "category" }))
+      .legend({ merge: ["color", "borderStyle"] })
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+
+  it("default behavior (no merge) still renders a color-only legend", async () => {
+    const { plot } = await import("./chart.ts");
+    const { point } = await import("./geoms/index.ts");
+    const svg = plot<Row>({ data, width: 400, height: 300 })
+      .layer(point<Row>({ x: "size", y: "size", color: "category", shape: "category" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+});
+
+describe("buildOverlayGlyphScale", () => {
+  it("maps a categorical domain through the default palette, allowing null entries", () => {
+    const scale = buildOverlayGlyphScale(resolveAes<Row, unknown>("category"), data);
+    expect(scale.fn("a")).toBeNull(); // first slot is null
+    expect(scale.fn("b")).toBe("plus");
+    expect(scale.fn("c")).toBe("cross");
+  });
+
+  it("returns null for unknown values", () => {
+    const scale = buildOverlayGlyphScale(resolveAes<Row, unknown>("category"), data);
+    expect(scale.fn("nope")).toBeNull();
+  });
+
+  it("respects an explicit palette with null suppressions", () => {
+    const scale = buildOverlayGlyphScale(resolveAes<Row, unknown>("category"), data, {
+      palette: ["star", null, "diamond"],
+    });
+    expect(scale.fn("a")).toBe("star");
+    expect(scale.fn("b")).toBeNull();
+    expect(scale.fn("c")).toBe("diamond");
+  });
+});

package/src/grammar/mount.d.ts

@@ -0,0 +1,78 @@
+import { type Frame } from "insomni";
+import type { MountedPlot, MountPlotOptions } from "./chart.ts";
+import { type ChartConfig } from "./pipeline.ts";
+import { type DataViewport } from "../viewport.ts";
+import type { Coord } from "./coord.ts";
+import type { PanZoomConfig } from "./chart.ts";
+import type { DataPanBoundsOptions } from "../viewport.ts";
+import type { AxisSelection } from "../interactions.ts";
+/**
+ * Internal entry. `chart.mount(canvas, opts)` calls this with its frozen
+ * config + the user-provided mount options.
+ */
+export declare function mountChart<T>(config: ChartConfig<T>, canvas: HTMLCanvasElement, opts?: MountPlotOptions<T>): MountedPlot<T>;
+interface ResolvedPanZoom {
+    minZoom: number;
+    maxZoom: number;
+    panBounds: DataPanBoundsOptions | undefined;
+    pan: AxisSelection;
+    zoom: AxisSelection;
+    /** Half-padding fraction applied around the visible-Y extent, or null when yFit is off. */
+    yFitPadding: number | null;
+}
+declare function resolvePanZoom(input: boolean | PanZoomConfig | undefined): ResolvedPanZoom | null;
+/**
+ * Walk each layer's x/y accessors, find data points whose X falls inside
+ * `visibleX`, and return `[yMin - pad, yMax + pad]`. Returns `null` when no
+ * layer / no point falls in range — callers should keep the previous Y
+ * window rather than collapsing.
+ */
+declare function computeVisibleYExtent<T>(layers: ReadonlyArray<{
+    channels: {
+        x?: unknown;
+        y?: unknown;
+    };
+}>, data: readonly T[], visibleX: readonly [number, number], padding: number): readonly [number, number] | null;
+/**
+ * Screen → data primitive backing `MountedPlot.pickAt`. Extracted so it can be
+ * unit-tested without spinning up a full mount (WebGPU device, layers, etc.).
+ *
+ * Returns `null` when the point is outside the frame, when `coord.unproject`
+ * rejects the point (polar outside the radius band), when scales are not yet
+ * available (pre-first-draw), or when either position scale lacks `invert`
+ * (band scales — band → continuous picking is a separate problem).
+ */
+declare function screenToData(canvasX: number, canvasY: number, ctx: {
+    frame: Frame;
+    scales: import("./geoms/types.ts").ScaleBundle | null;
+    coord: Coord;
+}): {
+    plotFrameX: number;
+    plotFrameY: number;
+    dataX: number;
+    dataY: number;
+    frame: Frame;
+} | null;
+/** @internal — exposed for unit tests only. */
+export declare const __test__: {
+    resolvePanZoom: typeof resolvePanZoom;
+    computeVisibleYExtent: typeof computeVisibleYExtent;
+    wrapViewportThroughCoord: typeof wrapViewportThroughCoord;
+    screenToData: typeof screenToData;
+};
+/**
+ * Wrap a `DataViewport` so pan/zoom calls flow through `coord.handlePan` /
+ * `coord.handleZoom`. The wrapper is `Object.create(underlying)` — every
+ * untouched member (state, visibleXDomain, absoluteFrame, setFrame, …)
+ * resolves through the prototype, so the wrapper stays in lockstep with the
+ * underlying `DataViewport` API. Only `panBy` and `zoomAt` are overridden.
+ *
+ * `getCoord` is called at-the-event-time so `update()` swapping the chart
+ * spec (and its `coord`) takes effect on the next interaction without a
+ * remount. `invalidate` fires after each routed call because polar's
+ * `handlePan` may mutate its own `startAngle` without touching the viewport —
+ * which means the viewport's own `onChange` won't fire, and the rAF loop
+ * needs an explicit kick to re-draw the rotated chart.
+ */
+declare function wrapViewportThroughCoord<X, Y>(underlying: DataViewport<X, Y>, getCoord: () => Coord, invalidate: () => void): DataViewport<X, Y>;
+export {};