insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,57 @@
+import { type Color } from "insomni";
+import { type PointBorderStyle, type PointShapeKind } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+export interface PointChannels<T> {
+    x: Aes<T, number | Date>;
+    y: Aes<T, number | Date>;
+    color?: Aes<T, unknown>;
+    size?: Aes<T, number>;
+    /**
+     * Categorical shape mapping. Values are looked up in the active shape scale
+     * — by default a built-in palette (`POINT_SHAPE_PALETTE`). Pass a literal
+     * `PointShapeKind` accessor and `.scale("shape", { palette: [...] })` to
+     * customize. When the value is already a `PointShapeKind`, it's used as-is.
+     */
+    shape?: Aes<T, unknown>;
+    alpha?: Aes<T, number>;
+    /**
+     * Per-datum border treatment. The accessor may return either a resolved
+     * {@link PointBorderStyle} (used as-is) or any other categorical value that
+     * gets routed through the active `borderStyle` scale (default palette:
+     * `solid`, `open`, `dashed`, `dotted`). Configure a custom mapping with
+     * `.scale("borderStyle", { palette: [...] })`.
+     */
+    borderStyle?: Aes<T, unknown>;
+    /**
+     * Optional secondary glyph overlaid on the base shape at the same anchor.
+     * Accepts either a resolved {@link PointShapeKind}/`null`, or a categorical
+     * value routed through the `overlayGlyph` scale (default palette starts
+     * with `null` so the most-common category gets no overlay). Configure with
+     * `.scale("overlayGlyph", { palette: [...] })`.
+     */
+    overlayGlyph?: Aes<T, unknown>;
+    /** Overlay radius as a fraction of base radius. Default `0.6`. */
+    overlayScale?: Aes<T, number>;
+}
+export interface PointOptions {
+    /** Constant fill if color channel is absent. */
+    fill?: Color;
+    /** Constant point radius if size channel is absent. */
+    radius?: number;
+    /** Override theme stroke. */
+    stroke?: Color | null;
+    /** Override theme stroke width. */
+    strokeWidth?: number;
+    /** Constant shape if shape channel is absent. */
+    shape?: PointShapeKind;
+    /** Constant border style if border-style channel is absent. */
+    borderStyle?: PointBorderStyle;
+    /** Constant overlay glyph if overlay-glyph channel is absent. */
+    overlayGlyph?: PointShapeKind | null;
+    /** Constant overlay scale if overlay-scale channel is absent. */
+    overlayScale?: number;
+    /** Display label for legend (defaults to color column name). */
+    label?: string;
+}
+export declare function point<T>(channels: PointChannels<T>, options?: PointOptions): Geom<T>;

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

@@ -0,0 +1,163 @@
+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 { point } from "./point.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+  category: string;
+}
+
+const data: Row[] = [
+  { x: 0, y: 0, category: "a" },
+  { x: 5, y: 10, category: "b" },
+  { x: 10, y: 20, category: "a" },
+];
+
+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]);
+  const yScale = buildPositionScale(yAes, rows, [200, 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,
+  };
+}
+
+function makeCtxWithDomains(
+  rows: readonly Row[],
+  xDomain: [number, number],
+  yDomain: [number, number],
+): CompileContext<Row> {
+  const xAes = resolveAes<Row, unknown>("x");
+  const yAes = resolveAes<Row, unknown>("y");
+  const xScale = buildPositionScale(xAes, rows, [0, 100], { domain: xDomain });
+  const yScale = buildPositionScale(yAes, rows, [200, 0], { domain: yDomain });
+  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,
+  };
+}
+
+function fakeCircleLayer(): {
+  circles: Array<{ cx: number; cy: number; radius: number }>;
+  layer: { pushCircle: (shape: { cx: number; cy: number; radius: number }) => void };
+} {
+  const circles: Array<{ cx: number; cy: number; radius: number }> = [];
+  return {
+    circles,
+    layer: {
+      pushCircle(shape) {
+        circles.push(shape);
+      },
+    },
+  };
+}
+
+describe("point geom — compileHitTest", () => {
+  test("emits absolute element-CSS-px positions per datum", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx(data));
+    expect(hits).not.toBeNull();
+    expect(hits!.geomKind).toBe("point");
+    expect(hits!.dataIndex.length).toBe(3);
+    // x=0 maps to xScale start (0), so absolute = plot.x + 0 = 50
+    expect(hits!.positions[0]).toBeCloseTo(50, 3);
+    // y=0 maps to yScale start = 200, absolute = plot.y + 200 = 230
+    expect(hits!.positions[1]).toBeCloseTo(230, 3);
+    // x=10 maps to xScale end = 100, absolute = 50 + 100 = 150
+    expect(hits!.positions[4]).toBeCloseTo(150, 3);
+    // y=20 maps to yScale end = 0, absolute = 30 + 0 = 30
+    expect(hits!.positions[5]).toBeCloseTo(30, 3);
+  });
+
+  test("dataIndex maps each hit back to original data index (preserves order with all-finite data)", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(Array.from(hits.dataIndex)).toEqual([0, 1, 2]);
+  });
+
+  test("filters non-finite positions", () => {
+    const dirty: Row[] = [
+      { x: 0, y: 0, category: "a" },
+      { x: NaN, y: 5, category: "b" },
+      { x: 10, y: 20, category: "a" },
+    ];
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx(dirty))!;
+    expect(hits.dataIndex.length).toBe(2);
+    expect(Array.from(hits.dataIndex)).toEqual([0, 2]);
+  });
+
+  test("captures resolved channels with column metadata for tooltip labels", () => {
+    const geom = point<Row>({ x: "x", y: "y", color: "category" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.channels.x?.kind).toBe("column");
+    expect(hits.channels.x?.column).toBe("x");
+    expect(hits.channels.color?.kind).toBe("column");
+    expect(hits.channels.color?.column).toBe("category");
+  });
+
+  test("returns null for empty data", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx([]));
+    expect(hits).toBeNull();
+  });
+
+  test("pickRadius scales with theme.marks.pointRadius and grows with size channel", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const hits = geom.compileHitTest!(makeCtx(data))!;
+    expect(hits.pickRadius).toBeGreaterThanOrEqual(8);
+  });
+
+  test("compile path still produces marks (compileHitTest is non-destructive)", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const ctx = makeCtx(data);
+    const builders = geom.compile(ctx);
+    expect(builders.length).toBeGreaterThan(0);
+  });
+
+  test("compile uses transitionKey to match reordered rows", () => {
+    const geom = point<Row>({ x: "x", y: "y" });
+    const fromRows: Row[] = [
+      { x: 0, y: 0, category: "a" },
+      { x: 20, y: 20, category: "b" },
+    ];
+    const toRows: Row[] = [
+      { x: 10, y: 20, category: "b" },
+      { x: 20, y: 0, category: "a" },
+    ];
+    const from = geom.captureFrame!({
+      ...makeCtxWithDomains(fromRows, [0, 20], [0, 20]),
+      transitionKey: (d) => d.category,
+    })!;
+    const builders = geom.compile({
+      ...makeCtxWithDomains(toRows, [0, 20], [0, 20]),
+      transitionKey: (d) => d.category,
+      activeTransition: {
+        t: 0.5,
+        from,
+        matchIndex: (key) => from.ids?.indexOf(key),
+      },
+    });
+    const { circles, layer } = fakeCircleLayer();
+    for (const builder of builders) builder.addTo(layer as never);
+    expect(circles).toHaveLength(2);
+    expect(circles[0]!.cx).toBeCloseTo(125, 3);
+    expect(circles[1]!.cx).toBeCloseTo(100, 3);
+  });
+});