insomni-plot 0.1.0-alpha.0

package/src/grammar/color-utils.d.ts

@@ -0,0 +1,29 @@
+import type { Color } from "insomni";
+import { type CategoricalPalette } from "../colors.ts";
+import type { ColorScale } from "./scales.ts";
+import type { Theme, ThemeAccentKey } from "./theme.ts";
+/** Multiply a color's alpha by `a`. Preserves rgb. */
+export declare function alphaize(c: Color, a: number): Color;
+/** Override a color's alpha to `a`. */
+export declare function withAlpha(c: Color, a: number): Color;
+/**
+ * Accent-key shorthand used by chart-level marks (`band`, `rule`, `interval`,
+ * `ribbon`). Literal {@link Color} values bypass theme resolution; accent
+ * keys resolve through `theme.accents`.
+ */
+export type ColorOrAccent = Color | ThemeAccentKey;
+export declare function isColor(v: unknown): v is Color;
+export declare function isAccentKey(v: unknown): v is ThemeAccentKey;
+/**
+ * Resolve a `Color | ThemeAccentKey | undefined` against the theme's accent
+ * palette. Returns `undefined` when the input is undefined; throws on an
+ * unknown string so typos surface at construction rather than rendering as
+ * silent transparent black.
+ */
+export declare function resolveAccent(value: ColorOrAccent | undefined, theme: Theme): Color | undefined;
+/**
+ * Resolve a per-series color function: prefer the chart-provided color scale
+ * (so auto-legend swatches stay in sync), otherwise fall back to a fresh
+ * categorical palette keyed on `fallbackKeys`.
+ */
+export declare function seriesColor(scale: ColorScale | undefined, palette: CategoricalPalette, fallbackKeys: readonly string[]): (key: string) => Color;

package/src/grammar/color-utils.test.ts

@@ -0,0 +1,53 @@
+import { rgba } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { isAccentKey, isColor, resolveAccent } from "./color-utils.ts";
+import { theme, themeDefault } from "./theme.ts";
+
+describe("resolveAccent", () => {
+  test("returns undefined for undefined input", () => {
+    expect(resolveAccent(undefined, themeDefault)).toBeUndefined();
+  });
+
+  test("passes through literal Color values", () => {
+    const c = rgba(0.1, 0.2, 0.3, 1);
+    expect(resolveAccent(c, themeDefault)).toBe(c);
+  });
+
+  test("resolves each accent key against theme.accents", () => {
+    expect(resolveAccent("positive", themeDefault)).toBe(themeDefault.accents.positive);
+    expect(resolveAccent("negative", themeDefault)).toBe(themeDefault.accents.negative);
+    expect(resolveAccent("warn", themeDefault)).toBe(themeDefault.accents.warn);
+    expect(resolveAccent("info", themeDefault)).toBe(themeDefault.accents.info);
+  });
+
+  test("picks up theme overrides", () => {
+    const customWarn = rgba(0.5, 0.5, 0.5, 1);
+    const t = theme({ accents: { warn: customWarn } });
+    // `theme()` deep-merges, so the resolved value is a structural copy, not
+    // the same reference as `customWarn`.
+    expect(resolveAccent("warn", t)).toEqual(customWarn);
+  });
+
+  test("throws on unknown string", () => {
+    expect(() => resolveAccent("good" as never, themeDefault)).toThrow(/unknown accent key/);
+  });
+});
+
+describe("isColor / isAccentKey", () => {
+  test("isColor distinguishes Color from accent string", () => {
+    expect(isColor(rgba(0, 0, 0, 1))).toBe(true);
+    expect(isColor("positive")).toBe(false);
+    expect(isColor(undefined)).toBe(false);
+  });
+
+  test("isAccentKey only matches the four known keys", () => {
+    expect(isAccentKey("positive")).toBe(true);
+    expect(isAccentKey("negative")).toBe(true);
+    expect(isAccentKey("warn")).toBe(true);
+    expect(isAccentKey("info")).toBe(true);
+    expect(isAccentKey("good")).toBe(false);
+    expect(isAccentKey("")).toBe(false);
+    expect(isAccentKey(rgba(0, 0, 0, 1))).toBe(false);
+  });
+});

package/src/grammar/color-utils.ts

@@ -0,0 +1,66 @@
+import type { Color } from "insomni";
+import { colorScale, type CategoricalPalette } from "../colors.ts";
+import type { ColorScale } from "./scales.ts";
+import type { Theme, ThemeAccentKey } from "./theme.ts";
+
+/** Multiply a color's alpha by `a`. Preserves rgb. */
+export function alphaize(c: Color, a: number): Color {
+  return { r: c.r, g: c.g, b: c.b, a: (c.a ?? 1) * a };
+}
+
+/** Override a color's alpha to `a`. */
+export function withAlpha(c: Color, a: number): Color {
+  return { r: c.r, g: c.g, b: c.b, a };
+}
+
+/**
+ * Accent-key shorthand used by chart-level marks (`band`, `rule`, `interval`,
+ * `ribbon`). Literal {@link Color} values bypass theme resolution; accent
+ * keys resolve through `theme.accents`.
+ */
+export type ColorOrAccent = Color | ThemeAccentKey;
+
+export function isColor(v: unknown): v is Color {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    typeof (v as { r?: unknown }).r === "number" &&
+    typeof (v as { g?: unknown }).g === "number" &&
+    typeof (v as { b?: unknown }).b === "number"
+  );
+}
+
+const ACCENT_KEYS: ReadonlySet<ThemeAccentKey> = new Set(["positive", "negative", "warn", "info"]);
+
+export function isAccentKey(v: unknown): v is ThemeAccentKey {
+  return typeof v === "string" && ACCENT_KEYS.has(v as ThemeAccentKey);
+}
+
+/**
+ * Resolve a `Color | ThemeAccentKey | undefined` against the theme's accent
+ * palette. Returns `undefined` when the input is undefined; throws on an
+ * unknown string so typos surface at construction rather than rendering as
+ * silent transparent black.
+ */
+export function resolveAccent(value: ColorOrAccent | undefined, theme: Theme): Color | undefined {
+  if (value === undefined) return undefined;
+  if (isColor(value)) return value;
+  if (isAccentKey(value)) return theme.accents[value];
+  throw new Error(
+    `resolveAccent: unknown accent key "${String(value)}" — expected positive | negative | warn | info, or a Color.`,
+  );
+}
+
+/**
+ * Resolve a per-series color function: prefer the chart-provided color scale
+ * (so auto-legend swatches stay in sync), otherwise fall back to a fresh
+ * categorical palette keyed on `fallbackKeys`.
+ */
+export function seriesColor(
+  scale: ColorScale | undefined,
+  palette: CategoricalPalette,
+  fallbackKeys: readonly string[],
+): (key: string) => Color {
+  if (scale) return (key: string) => scale.fn(key);
+  return colorScale(palette, fallbackKeys);
+}

package/src/grammar/constants.d.ts

@@ -0,0 +1,45 @@
+import type { DataPanBoundsOptions } from "../viewport.ts";
+export declare const DEFAULT_CHART_WIDTH = 800;
+export declare const DEFAULT_CHART_HEIGHT = 500;
+export declare const DEFAULT_PADDING = 16;
+export declare const DEFAULT_TICK_COUNT = 5;
+export declare const DEFAULT_ATLAS_SIZE = 1024;
+/** Default pan-bounds when panZoom is enabled without explicit bounds. */
+export declare const DEFAULT_PAN_BOUNDS: DataPanBoundsOptions;
+/** Half-padding fraction applied around the visible-Y extent when yFit is enabled. */
+export declare const DEFAULT_Y_FIT_PADDING = 0.05;
+/** Confidence-interval level used by aggregate/smooth when none is supplied. */
+export declare const DEFAULT_CI_LEVEL = 0.95;
+/** Default secondary-glyph scale relative to the base point in overlay geoms. */
+export declare const DEFAULT_OVERLAY_SCALE = 0.6;
+/** Facet layout defaults: gap between panels and strip dimensions. */
+export declare const DEFAULT_FACET_GAP = 12;
+export declare const DEFAULT_FACET_STRIP_HEIGHT = 22;
+export declare const DEFAULT_FACET_STRIP_FONT_SIZE = 11;
+/**
+ * Per-bucket sample-count threshold below which boxplot/violin geoms switch
+ * from the summary mark to drawing each raw point. Keeps tiny groups from
+ * showing a misleading shape built from <10 samples.
+ */
+export declare const DEFAULT_POINTS_THRESHOLD = 10;
+/**
+ * Default ridgeline ridge overlap as a multiple of one row's cell size.
+ * `2.5` lets each ridge rise 2.5 cells above its baseline before the next
+ * ridge sits on top.
+ */
+export declare const DEFAULT_OVERLAP = 2.5;
+/** Pixel gaps between layout regions inside `computeLayout`. */
+export declare const LAYOUT_GAP: {
+    /** Gap above the plot frame after title/legend reservation. */
+    readonly topReservation: 16;
+    /** Right margin inside the outer frame. */
+    readonly plotRight: 4;
+    /** Pixels between axis edge and plot frame. */
+    readonly axisToPlot: 4;
+    /** Pixels between title block and legend (when both present). */
+    readonly titleToLegend: 4;
+    /** Pixels between title and subtitle within title block. */
+    readonly subtitleGap: 8;
+    /** Pixels reserved below legend before plot frame. */
+    readonly legendToPlot: 12;
+};

package/src/grammar/constants.ts

@@ -0,0 +1,61 @@
+// ---------------------------------------------------------------------------
+// Grammar-layer constants
+// ---------------------------------------------------------------------------
+// Sizes and spacings used by the chart pipeline that are NOT theme-able. Theme
+// covers visual appearance (fonts, colors, alphas); this file covers structural
+// layout numbers and pipeline defaults.
+
+import type { DataPanBoundsOptions } from "../viewport.ts";
+
+export const DEFAULT_CHART_WIDTH = 800;
+export const DEFAULT_CHART_HEIGHT = 500;
+export const DEFAULT_PADDING = 16;
+export const DEFAULT_TICK_COUNT = 5;
+export const DEFAULT_ATLAS_SIZE = 1024;
+
+/** Default pan-bounds when panZoom is enabled without explicit bounds. */
+export const DEFAULT_PAN_BOUNDS: DataPanBoundsOptions = { overshoot: 0.1 };
+
+/** Half-padding fraction applied around the visible-Y extent when yFit is enabled. */
+export const DEFAULT_Y_FIT_PADDING = 0.05;
+
+/** Confidence-interval level used by aggregate/smooth when none is supplied. */
+export const DEFAULT_CI_LEVEL = 0.95;
+
+/** Default secondary-glyph scale relative to the base point in overlay geoms. */
+export const DEFAULT_OVERLAY_SCALE = 0.6;
+
+/** Facet layout defaults: gap between panels and strip dimensions. */
+export const DEFAULT_FACET_GAP = 12;
+export const DEFAULT_FACET_STRIP_HEIGHT = 22;
+export const DEFAULT_FACET_STRIP_FONT_SIZE = 11;
+
+/**
+ * Per-bucket sample-count threshold below which boxplot/violin geoms switch
+ * from the summary mark to drawing each raw point. Keeps tiny groups from
+ * showing a misleading shape built from <10 samples.
+ */
+export const DEFAULT_POINTS_THRESHOLD = 10;
+
+/**
+ * Default ridgeline ridge overlap as a multiple of one row's cell size.
+ * `2.5` lets each ridge rise 2.5 cells above its baseline before the next
+ * ridge sits on top.
+ */
+export const DEFAULT_OVERLAP = 2.5;
+
+/** Pixel gaps between layout regions inside `computeLayout`. */
+export const LAYOUT_GAP = {
+  /** Gap above the plot frame after title/legend reservation. */
+  topReservation: 16,
+  /** Right margin inside the outer frame. */
+  plotRight: 4,
+  /** Pixels between axis edge and plot frame. */
+  axisToPlot: 4,
+  /** Pixels between title block and legend (when both present). */
+  titleToLegend: 4,
+  /** Pixels between title and subtitle within title block. */
+  subtitleGap: 8,
+  /** Pixels reserved below legend before plot frame. */
+  legendToPlot: 12,
+} as const;

package/src/grammar/coord.d.ts

@@ -0,0 +1,183 @@
+import { type GlyphAtlas, type Layer } from "insomni";
+import { type AxisOptions } from "../axis.ts";
+import type { ScaleBundle } from "./geoms/types.ts";
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * Inputs to `Coord.renderAxes`. The pipeline owns scale construction and
+ * layout; the coord owns axis dispatch (Cartesian → bottom + left; polar →
+ * angular ring + radial spokes).
+ */
+export interface CoordAxesArgs {
+    axisLayer: Layer;
+    scales: ScaleBundle;
+    /** Inner plot frame — coords project relative to this. */
+    plotFrame: import("insomni").Frame;
+    /** True when the chart actually has a column on this channel. Skipped axes are not drawn. */
+    hasX: boolean;
+    hasY: boolean;
+    xAxisOptions: AxisOptions<unknown>;
+    yAxisOptions: AxisOptions<unknown>;
+    atlas: GlyphAtlas | undefined;
+}
+/**
+ * Inputs to `Coord.handlePan`. The mount / interactions layer passes a pointer
+ * delta in plot-frame pixels plus the active plot frame and a viewport handle
+ * the coord can use to mutate scale state. Cartesian delegates the whole
+ * thing to `viewport.panBy(dx, dy)`; polar decomposes into tangential
+ * (rotate `startAngle`) and radial (translate radius domain via the viewport).
+ */
+export interface CoordPanArgs {
+    dx: number;
+    dy: number;
+    /** Plot frame in absolute layer-pixel space (x, y are screen-space origin). */
+    plotFrame: import("insomni").Frame;
+    /** Viewport handle for scale-domain mutations. */
+    viewport: CoordViewportHandle;
+}
+export interface CoordZoomArgs {
+    /**
+     * Multiplicative zoom factor — `> 1` zooms in, `< 1` zooms out. May be a
+     * scalar (both axes) or a `{ x?, y? }` per-axis form (matches
+     * `viewport.zoomAt` and the masking that `bindDataViewport` performs).
+     */
+    factor: number | {
+        x?: number;
+        y?: number;
+    };
+    /** Cursor position in absolute layer-pixel space (matches `viewport.zoomAt`). */
+    cx: number;
+    cy: number;
+    plotFrame: import("insomni").Frame;
+    viewport: CoordViewportHandle;
+}
+/**
+ * Minimal facade over `DataViewport` so the coord can mutate scale state
+ * without depending on the full viewport surface. The two methods polar
+ * uses (`panBy`, `zoomAt`) match `DataViewport` semantics 1:1; Cartesian's
+ * implementation forwards through them so behavior is byte-identical to the
+ * pre-`handlePan` path.
+ */
+export interface CoordViewportHandle {
+    panBy(dxPx: number, dyPx: number): void;
+    zoomAt(anchorSx: number, anchorSy: number, factor: number | {
+        x?: number;
+        y?: number;
+    }): void;
+}
+/**
+ * A coordinate system. Polar / cartesian today; future room for log-polar /
+ * geographic projections behind the same interface.
+ */
+export interface Coord {
+    readonly kind: "cartesian" | "polar";
+    /**
+     * Bind the coord to a specific plot frame for the upcoming render.
+     * Polar's `project` / `segment` / `renderAxes` need the plot-frame
+     * dimensions and centre to compute (cx, cy) and the default outerRadius.
+     * Called by the pipeline once per panel (faceted) or once per chart
+     * (unfaceted) before any `project` / `renderAxes` call. Cartesian no-ops.
+     */
+    bindFrame(plotFrame: import("insomni").Frame): void;
+    /**
+     * Map a single point from plot-frame pixel space (0..plotFrame.width on x,
+     * 0..plotFrame.height on y — i.e. the raw output of `xScale.fn` / `yScale.fn`)
+     * to layer-pixel space (still relative to the plot frame's origin —
+     * `plot.topLeft` offsets are applied later by each geom).
+     *
+     * Cartesian: identity. Polar: (θ, r) → (cx + r·cosθ, cy + r·sinθ).
+     */
+    project(p: Point): Point;
+    /**
+     * Tessellate a polyline segment between two points in plot-frame pixel
+     * space. Returns the projected pixel points (including both endpoints).
+     * Cartesian returns `[project(p1), project(p2)]`; polar returns ~N points
+     * along the arc.
+     */
+    segment(p1: Point, p2: Point): Point[];
+    /**
+     * Render axes into `args.axisLayer`. Cartesian draws bottom (x) + left (y);
+     * polar draws an angular ring (spokes) + radial concentric circles.
+     */
+    renderAxes(args: CoordAxesArgs): void;
+    /**
+     * Inverse of `project`, for hit-testing / tooltips. Cartesian is the
+     * identity within the plot frame. Polar inverts (θ, r) and returns `null`
+     * when the projected point is outside `[innerRadius, outerRadius]`.
+     */
+    unproject(p: Point): Point | null;
+    /**
+     * Translate a pointer pan delta into scale-domain mutations.
+     * Cartesian forwards to `viewport.panBy(dx, dy)` — byte-identical to the
+     * pre-coord path. Polar decomposes the delta relative to the plot centre
+     * into tangential (rotate `startAngle`) and radial (translate the radius
+     * scale via `viewport.panBy(0, radial_dy)`) components.
+     */
+    handlePan(args: CoordPanArgs): void;
+    /**
+     * Translate a zoom factor + anchor into scale-domain mutations.
+     * Cartesian forwards to `viewport.zoomAt(cx, cy, factor)`. Polar scales the
+     * radius domain around the cursor's data-space radius; angle scale
+     * unchanged.
+     */
+    handleZoom(args: CoordZoomArgs): void;
+}
+/**
+ * Default coord — identity projection, current axis behavior. Plot's existing
+ * pipeline behaves exactly as it did before the `Coord` interface was added
+ * when this is in use.
+ */
+export declare function coordCartesian(): Coord;
+export interface CoordPolarOptions {
+    /** Angle (radians) where the angular axis starts. Default `-π/2` (top). */
+    startAngle?: number;
+    /** Angle where the angular axis ends. Default `startAngle + 2π` (full circle). */
+    endAngle?: number;
+    /**
+     * Convenience for non-full-circle layouts: the gap (in radians) between
+     * `startAngle` and `endAngle`. `openAngle: 0` ↔ full circle;
+     * `openAngle: π/4` ↔ fan with a 45° gap at the start. Ignored when
+     * `endAngle` is provided.
+     */
+    openAngle?: number;
+    /** `1` (default, CCW) or `-1` (CW). */
+    direction?: 1 | -1;
+    /** Inner radius in pixels. Default `0`. */
+    innerRadius?: number;
+    /**
+     * Outer radius in pixels. Default `min(plotFrame.width, plotFrame.height) / 2`
+     * — resolved lazily on `bindFrame`.
+     */
+    outerRadius?: number;
+    /** Which channel maps to θ. Default `'y'` (gheatmap/circular-tree convention). */
+    angleChannel?: "x" | "y";
+    /** Angular tessellation step (radians) for `segment` and circular axes. Default ~1°. */
+    quality?: number;
+}
+/**
+ * Polar projection. See {@link CoordPolarOptions}.
+ *
+ * Each call returns a fresh stateful coord so the same `coordPolar({...})`
+ * expression can be reused safely. `bindFrame` mutates the centre and the
+ * default `outerRadius`.
+ */
+export declare function coordPolar(opts?: CoordPolarOptions): Coord;
+/**
+ * Convenience polar coord: full circle, root at centre. Equivalent to
+ * `coordPolar({ openAngle: 0, innerRadius: 0 })`.
+ */
+export declare function coordRadial(opts?: Omit<CoordPolarOptions, "openAngle" | "innerRadius">): Coord;
+/**
+ * Pin a coord to one plot frame (faceted panels). The facet loop mutates a
+ * SINGLE shared stateful coord via `bindFrame(panel.frame)` per panel; that's
+ * fine for the synchronous mark-push path (compiled right after the bind), but
+ * a geom's `hoverDecoration` closure captures `ctx.coord` and runs LATER (at
+ * hover, from the mount) — by then the shared coord is bound to the LAST
+ * panel's frame, so a polar halo would project against the wrong centre. This
+ * wrapper re-binds the underlying coord to THIS panel's frame before every
+ * frame-dependent delegate, so each panel's closures see a panel-stable
+ * projection. Cartesian's `bindFrame` is a no-op so this is zero-cost there.
+ */
+export declare function frameBoundCoord(coord: Coord, frame: import("insomni").Frame): Coord;