insomni-plot 0.1.0-alpha.0

package/src/grammar/profiling.d.ts

@@ -0,0 +1,8 @@
+export interface RecorderHook {
+    recordCpu(name: string, durationMs: number): void;
+    recordGpu(name: string, startNs: number, endNs: number): void;
+}
+/** Inject a recorder (e.g. devtools' `recordCpu`/`recordGpu`). Pass `null` to reset to no-op. */
+export declare function setRecorderHook(rec: RecorderHook | null): void;
+export declare function recordCpu(name: string, durationMs: number): void;
+export declare function recordGpu(name: string, startNs: number, endNs: number): void;

package/src/grammar/profiling.ts

@@ -0,0 +1,24 @@
+export interface RecorderHook {
+  recordCpu(name: string, durationMs: number): void;
+  recordGpu(name: string, startNs: number, endNs: number): void;
+}
+
+const NOOP: RecorderHook = {
+  recordCpu() {},
+  recordGpu() {},
+};
+
+let _rec: RecorderHook = NOOP;
+
+/** Inject a recorder (e.g. devtools' `recordCpu`/`recordGpu`). Pass `null` to reset to no-op. */
+export function setRecorderHook(rec: RecorderHook | null): void {
+  _rec = rec ?? NOOP;
+}
+
+export function recordCpu(name: string, durationMs: number): void {
+  _rec.recordCpu(name, durationMs);
+}
+
+export function recordGpu(name: string, startNs: number, endNs: number): void {
+  _rec.recordGpu(name, startNs, endNs);
+}

package/src/grammar/scales.d.ts

@@ -0,0 +1,188 @@
+import type { Color } from "insomni";
+import { type BandScale, type ContinuousScale, type NumericRange, type TimeScale } from "../scales.ts";
+import { type CategoricalPalette, type ContinuousPalette } from "../colors.ts";
+import { type PointBorderStyle, type PointShapeKind } from "../marks.ts";
+import { type ChannelDataType, type ResolvedAes } from "./aes.ts";
+import type { Theme } from "./theme.ts";
+export type { ScaleBundle } from "./geoms/types.ts";
+export type Channel = "x" | "y" | "color" | "size" | "shape" | "alpha" | "borderStyle" | "overlayGlyph";
+export type PositionScaleType = "linear" | "log" | "sqrt" | "time" | "band";
+export type ColorScaleType = "categorical" | "continuous" | "diverging";
+interface BasePositionScaleOptions {
+    range?: NumericRange;
+    nice?: boolean;
+    padding?: number;
+}
+/**
+ * `"nice"` is sugar for the existing `nice: true` flag — set as the domain
+ * shortcut so consumers don't need a second toggle when the only reason to
+ * touch `domain` was to pad it to round values. The data extent still
+ * derives the underlying numbers; `"nice"` just toggles the rounding.
+ */
+export type NumericDomainShortcut = "nice";
+export interface NumericPositionScaleOptions extends BasePositionScaleOptions {
+    type?: "linear" | "log" | "sqrt";
+    domain?: readonly [number, number] | NumericDomainShortcut;
+}
+export interface TimePositionScaleOptions extends BasePositionScaleOptions {
+    type?: "time";
+    domain?: readonly [Date, Date];
+}
+export interface BandPositionScaleOptions extends BasePositionScaleOptions {
+    type?: "band";
+    domain?: readonly string[];
+}
+export type PositionScaleOptions = NumericPositionScaleOptions | TimePositionScaleOptions | BandPositionScaleOptions;
+export interface CategoricalColorScaleOptions<T> {
+    type?: "categorical";
+    domain?: readonly T[];
+    palette?: CategoricalPalette;
+}
+/**
+ * Color-scale domain shortcuts.
+ *
+ * - `"nice"`: alias for the existing `nice: true` flag on continuous color
+ *   scales — pad the data extent to round values.
+ * - `"quantile"`: bucket the data into N quantile bins (default 5). The
+ *   returned scale's `type` becomes `"categorical"` with bucket-label
+ *   domain entries (`"Q1".."QN"`), and the palette is sampled at N evenly
+ *   spaced stops along the chart's continuous palette so the color
+ *   gradient reads as ordinal magnitude rather than nominal category.
+ */
+export type ColorDomainShortcut = "nice" | "quantile";
+export interface ContinuousColorScaleOptions {
+    type: "continuous" | "diverging";
+    domain?: readonly [number, number] | ColorDomainShortcut;
+    palette?: ContinuousPalette;
+    /**
+     * Extend the inferred domain outward to "nice" round values (e.g. data
+     * extent `[-2.8, 1.9]` → `[-3, 2]`). Same algorithm position scales use
+     * via `nice: true`. Ignored when `domain` is set explicitly to a tuple.
+     * Equivalent to `domain: "nice"` — keep one form per chart for clarity.
+     */
+    nice?: boolean;
+    /**
+     * Number of quantile buckets to use when `domain: "quantile"`. Default 5
+     * (quintiles). Ignored otherwise.
+     */
+    quantiles?: number;
+    /**
+     * Override the color space used to interpolate the palette stops.
+     * Falls back to `theme.paletteBlendSpace` (default `"oklch"`).
+     */
+    blendSpace?: import("insomni").BlendSpace;
+}
+export type ColorScaleOptions<T> = CategoricalColorScaleOptions<T> | ContinuousColorScaleOptions;
+export interface SizeScaleOptions {
+    type?: "linear" | "sqrt";
+    domain?: readonly [number, number];
+    range?: readonly [number, number];
+}
+export interface AlphaScaleOptions {
+    domain?: readonly [number, number];
+    range?: readonly [number, number];
+}
+export interface ShapeScaleOptions {
+    /** Explicit category order (default: order of first appearance). */
+    domain?: readonly unknown[];
+    /** Override the shape palette. Default: `POINT_SHAPE_PALETTE` from `marks`. */
+    palette?: readonly PointShapeKind[];
+}
+export interface BorderStyleScaleOptions {
+    /** Explicit category order (default: order of first appearance). */
+    domain?: readonly unknown[];
+    /** Override the border-style palette. Default: `DEFAULT_BORDER_STYLE_PALETTE`. */
+    palette?: readonly PointBorderStyle[];
+}
+export interface OverlayGlyphScaleOptions {
+    /** Explicit category order (default: order of first appearance). */
+    domain?: readonly unknown[];
+    /**
+     * Override the overlay palette. Default: a small subset of
+     * `POINT_SHAPE_PALETTE` excluding `circle` so the overlay is visually
+     * distinct from the typical base shape. Use `null` entries to suppress an
+     * overlay for that domain value.
+     */
+    palette?: readonly (PointShapeKind | null)[];
+}
+export type ScaleOptions = PositionScaleOptions | ColorScaleOptions<unknown> | SizeScaleOptions | AlphaScaleOptions | ShapeScaleOptions | BorderStyleScaleOptions | OverlayGlyphScaleOptions;
+/** A scale callable: any value → number (or color, for color channels). */
+export type ScaleFn<In, Out> = (value: In) => Out;
+export interface PositionScale {
+    readonly kind: "position";
+    readonly type: PositionScaleType;
+    readonly dataType: ChannelDataType;
+    /** Pixel-space transform within the plot frame. */
+    readonly fn: ScaleFn<unknown, number>;
+    /** Underlying scale for axis builders. */
+    readonly axisScale: ContinuousScale | TimeScale | BandScale<string>;
+}
+export interface ColorScale {
+    readonly kind: "color";
+    readonly dataType: ChannelDataType;
+    readonly type: ColorScaleType;
+    readonly fn: ScaleFn<unknown, Color>;
+    readonly domain: readonly unknown[];
+    /** Original palette — present for continuous/diverging scales (used by the color-bar legend). */
+    readonly palette?: ContinuousPalette | CategoricalPalette;
+}
+export interface SizeScale {
+    readonly kind: "size";
+    readonly fn: ScaleFn<unknown, number>;
+    readonly domain: readonly [number, number];
+    readonly range: readonly [number, number];
+}
+export interface AlphaScale {
+    readonly kind: "alpha";
+    readonly fn: ScaleFn<unknown, number>;
+    readonly domain: readonly [number, number];
+    readonly range: readonly [number, number];
+}
+export interface ShapeScale {
+    readonly kind: "shape";
+    readonly fn: ScaleFn<unknown, PointShapeKind>;
+    readonly domain: readonly unknown[];
+    readonly palette: readonly PointShapeKind[];
+}
+export interface BorderStyleScale {
+    readonly kind: "borderStyle";
+    readonly fn: ScaleFn<unknown, PointBorderStyle>;
+    readonly domain: readonly unknown[];
+    readonly palette: readonly PointBorderStyle[];
+}
+export interface OverlayGlyphScale {
+    readonly kind: "overlayGlyph";
+    readonly fn: ScaleFn<unknown, PointShapeKind | null>;
+    readonly domain: readonly unknown[];
+    readonly palette: readonly (PointShapeKind | null)[];
+}
+export type ResolvedScale = PositionScale | ColorScale | SizeScale | AlphaScale | ShapeScale | BorderStyleScale | OverlayGlyphScale;
+/**
+ * Numeric extent over an arbitrary value array. Non-numeric values are skipped.
+ * Falls back to `[0, 1]` for empty / non-numeric input. Expands a degenerate
+ * single-point domain by ±1 so downstream scales don't divide by zero.
+ */
+export declare function numericExtent(values: readonly unknown[]): [number, number];
+export declare function readNumericDomain(scale: PositionScaleOptions | undefined, axis: "x" | "y"): readonly [number, number];
+export declare function readContinuousType(scale: PositionScaleOptions | undefined): "linear" | "log" | "sqrt";
+export declare function buildPositionScale<T>(aes: ResolvedAes<T, unknown>, data: readonly T[], range: NumericRange, options?: PositionScaleOptions): PositionScale;
+export declare function buildColorScale<T>(aes: ResolvedAes<T, unknown>, data: readonly T[], theme: Theme, options?: ColorScaleOptions<unknown>): ColorScale;
+/**
+ * Build a categorical color scale from an explicit key list. Shared between
+ * `buildColorScale` (data-derived domain) and the chart pipeline's implicit
+ * series scale (keys = column names). User-supplied `options.palette` /
+ * `options.domain` win over the inferred values.
+ */
+export declare function buildCategoricalColorScale(keys: readonly unknown[], theme: Theme, options?: ColorScaleOptions<unknown>, dataType?: ChannelDataType): ColorScale;
+export declare function buildSizeScale<T>(aes: ResolvedAes<T, number>, data: readonly T[], options?: SizeScaleOptions): SizeScale;
+export declare function buildAlphaScale<T>(aes: ResolvedAes<T, number>, data: readonly T[], options?: AlphaScaleOptions): AlphaScale;
+export declare function buildShapeScale<T>(aes: ResolvedAes<T, unknown>, data: readonly T[], options?: ShapeScaleOptions): ShapeScale;
+export declare const DEFAULT_BORDER_STYLE_PALETTE: readonly PointBorderStyle[];
+export declare function buildBorderStyleScale<T>(aes: ResolvedAes<T, unknown>, data: readonly T[], options?: BorderStyleScaleOptions): BorderStyleScale;
+/**
+ * Default overlay palette. First slot is `null` so the most-common category
+ * gets no overlay — overlays are typically a minority styling for flagged /
+ * exceptional rows. The remaining slots are visually distinct glyphs.
+ */
+export declare const DEFAULT_OVERLAY_GLYPH_PALETTE: readonly (PointShapeKind | null)[];
+export declare function buildOverlayGlyphScale<T>(aes: ResolvedAes<T, unknown>, data: readonly T[], options?: OverlayGlyphScaleOptions): OverlayGlyphScale;

package/src/grammar/scales.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "./aes.ts";
+import { buildColorScale, buildPositionScale } from "./scales.ts";
+import { themeDefault } from "./theme.ts";
+
+interface Row {
+  v: number;
+}
+
+describe("buildPositionScale — log/sqrt", () => {
+  const aes = resolveAes<Row, unknown>("v");
+
+  test("type: 'log' returns a log-scale position with log-aware ticks", () => {
+    const data: Row[] = [{ v: 1 }, { v: 10 }, { v: 100 }, { v: 1000 }];
+    const scale = buildPositionScale(aes, data, [0, 300], { type: "log", domain: [1, 1000] });
+    expect(scale.type).toBe("log");
+    // pixel midpoint of [1, 1000] in log space is √(1·1000) ≈ 31.62.
+    expect(scale.fn(31.622776601683793)).toBeCloseTo(150, 1);
+    // Log-aware ticks land on round powers, not linear spacing.
+    const axisScale = scale.axisScale as { ticks: (count?: number) => readonly number[] };
+    const ticks = axisScale.ticks(4);
+    expect(ticks).toContain(1);
+    expect(ticks).toContain(10);
+    expect(ticks).toContain(100);
+    expect(ticks).toContain(1000);
+  });
+
+  test("type: 'log' throws for a domain that straddles or touches zero", () => {
+    const data: Row[] = [{ v: -1 }, { v: 1 }];
+    expect(() => buildPositionScale(aes, data, [0, 100], { type: "log" })).toThrow(/Log scale/);
+    expect(() => buildPositionScale(aes, data, [0, 100], { type: "log", domain: [0, 10] })).toThrow(
+      /Log scale/,
+    );
+  });
+
+  test("type: 'sqrt' preserves square-root spacing on the position scale", () => {
+    const data: Row[] = [{ v: 0 }, { v: 100 }];
+    const scale = buildPositionScale(aes, data, [0, 100], { type: "sqrt", domain: [0, 100] });
+    expect(scale.type).toBe("sqrt");
+    // sqrt(25)/sqrt(100) = 0.5 → midpoint of range.
+    expect(scale.fn(25)).toBeCloseTo(50, 1);
+  });
+
+  test("default numeric scale stays linear when no type is set", () => {
+    const data: Row[] = [{ v: 0 }, { v: 100 }];
+    const scale = buildPositionScale(aes, data, [0, 100], { domain: [0, 100] });
+    expect(scale.type).toBe("linear");
+    expect(scale.fn(50)).toBeCloseTo(50, 1);
+  });
+});
+
+describe("buildPositionScale — domain shortcuts", () => {
+  const aes = resolveAes<Row, unknown>("v");
+
+  test("domain: 'nice' pads the data extent to round values", () => {
+    const data: Row[] = [{ v: -2.8 }, { v: 1.9 }];
+    const scale = buildPositionScale(aes, data, [0, 100], { domain: "nice" });
+    const [lo, hi] = scale.axisScale.domain as readonly [number, number];
+    expect(lo).toBeLessThanOrEqual(-2.8);
+    expect(hi).toBeGreaterThanOrEqual(1.9);
+    // niceNumeric collapses fractional bounds to round values.
+    expect(lo).toBe(-3);
+    expect(hi).toBe(2);
+  });
+
+  test("explicit tuple domain still wins over the 'nice' shortcut behavior", () => {
+    const data: Row[] = [{ v: 0 }, { v: 100 }];
+    const scale = buildPositionScale(aes, data, [0, 100], { domain: [12, 88] });
+    expect(scale.axisScale.domain).toEqual([12, 88]);
+  });
+});
+
+describe("buildColorScale — domain shortcuts", () => {
+  const aes = resolveAes<Row, unknown>("v");
+
+  test("domain: 'quantile' buckets the data and returns a categorical scale", () => {
+    // 10 values, quintiles → 5 buckets of 2 values each.
+    const data: Row[] = Array.from({ length: 10 }, (_, i) => ({ v: i + 1 }));
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "quantile",
+      quantiles: 5,
+    });
+    expect(scale.type).toBe("categorical");
+    expect(scale.domain).toEqual(["Q1", "Q2", "Q3", "Q4", "Q5"]);
+    // Lowest value lands in Q1; highest in Q5; bucket colors should differ
+    // (sampled at distinct stops along the continuous palette).
+    const lo = scale.fn(1);
+    const hi = scale.fn(10);
+    expect(lo).not.toEqual(hi);
+    // The mid-range value lands in the middle bucket.
+    const mid = scale.fn(5);
+    expect(mid).not.toEqual(lo);
+    expect(mid).not.toEqual(hi);
+  });
+
+  test("domain: 'quantile' default count is 5 quintiles", () => {
+    const data: Row[] = Array.from({ length: 20 }, (_, i) => ({ v: i }));
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "quantile",
+    });
+    expect(scale.domain.length).toBe(5);
+  });
+
+  test("domain: 'nice' on continuous color scale pads to round values", () => {
+    const data: Row[] = [{ v: -2.8 }, { v: 1.9 }];
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "nice",
+    });
+    expect(scale.type).toBe("continuous");
+    expect(scale.domain).toEqual([-3, 2]);
+  });
+
+  test("non-finite input on a quantile scale falls back to the first bucket", () => {
+    const data: Row[] = [{ v: 1 }, { v: 2 }, { v: 3 }];
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "quantile",
+      quantiles: 3,
+    });
+    expect(() => scale.fn(Number.NaN)).not.toThrow();
+    expect(scale.fn(Number.NaN)).toEqual(scale.fn(-Infinity));
+  });
+
+  test("domain: 'quantile' dedupes tied interior breakpoints into reachable buckets", () => {
+    // Low-cardinality data: a 0, eight 5s, and a 10. Every quintile breakpoint
+    // (p=0.2/0.4/0.6/0.8) lands on 5 — raw breakpoints are [5, 5, 5, 5].
+    // Asking for 5 buckets is meaningless: four identical breakpoints would
+    // leave three buckets unreachable (no value can be > 5 AND <= 5), skewing
+    // the palette. Deduping to the single distinct interior breakpoint (5)
+    // yields exactly 2 reachable buckets: {0, 5} in Q1, {10} in Q2.
+    const data: Row[] = [
+      { v: 0 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 5 },
+      { v: 10 },
+    ];
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "quantile",
+      quantiles: 5,
+    });
+    // 1 distinct interior breakpoint (5) → 2 reachable buckets, labelled Q1..Q2.
+    expect(scale.domain).toEqual(["Q1", "Q2"]);
+
+    // Every reachable bucket is actually produced by some input value — none
+    // is an unreachable, palette-skewing dead bucket.
+    const reached = new Set<string>();
+    for (const v of [0, 5, 10]) reached.add(JSON.stringify(scale.fn(v)));
+    expect(reached.size).toBe(2);
+
+    // Left-closed: a value exactly on the breakpoint (5) falls into the lower
+    // bucket alongside the minimum; only the tail (10) reaches Q2.
+    const lo = scale.fn(0);
+    const hi = scale.fn(10);
+    expect(scale.fn(5)).toEqual(lo);
+    expect(lo).not.toEqual(hi);
+  });
+
+  test("domain: 'quantile' on all-equal data collapses to one bucket", () => {
+    // No interior breakpoints (min === max) → a single reachable bucket
+    // rather than five identical-but-nominally-distinct ones.
+    const data: Row[] = Array.from({ length: 8 }, () => ({ v: 5 }));
+    const scale = buildColorScale(aes, data, themeDefault, {
+      type: "continuous",
+      domain: "quantile",
+      quantiles: 5,
+    });
+    expect(scale.domain).toEqual(["Q1"]);
+    expect(scale.fn(5)).toEqual(scale.fn(5));
+  });
+});