insomni-plot 0.1.0-alpha.0

package/src/grammar/svg.d.ts

@@ -0,0 +1,3 @@
+import { type GlyphAtlas } from "insomni";
+import { type ChartConfig } from "./pipeline.ts";
+export declare function renderSVG<T>(config: ChartConfig<T>, width: number | undefined, height: number | undefined, externalAtlas?: GlyphAtlas): SVGSVGElement;

package/src/grammar/svg.ts

@@ -0,0 +1,39 @@
+// ---------------------------------------------------------------------------
+// Static SVG export — runs the pipeline once into an off-DOM SVG renderer.
+// ---------------------------------------------------------------------------
+
+import { createLayer, createSVGRenderer, type GlyphAtlas } from "insomni";
+import { sharedCpuGlyphAtlas } from "insomni/text-ttf";
+import { DEFAULT_CHART_HEIGHT, DEFAULT_CHART_WIDTH } from "./constants.ts";
+import { currentData, runPipeline, type ChartConfig } from "./pipeline.ts";
+
+export function renderSVG<T>(
+  config: ChartConfig<T>,
+  width: number | undefined,
+  height: number | undefined,
+  externalAtlas?: GlyphAtlas,
+): SVGSVGElement {
+  const w = width ?? config.width ?? DEFAULT_CHART_WIDTH;
+  const h = height ?? config.height ?? DEFAULT_CHART_HEIGHT;
+  const renderer = createSVGRenderer({ width: w, height: h, dpr: 1 });
+  renderer.setBackground(config.background ?? config.theme.background);
+
+  // SVG path: resolve the glyph atlas for text rendering (axis labels,
+  // legend, title, value-label annotations). `externalAtlas` and
+  // `config.externalAtlas` take precedence; when neither is supplied,
+  // `sharedCpuGlyphAtlas()` provides a zero-GPU default backed by the bundled
+  // Lato subset — so `chart.toSVG()` emits `<text>` elements with no extra
+  // setup from the caller.
+  const atlas = externalAtlas ?? config.externalAtlas ?? sharedCpuGlyphAtlas();
+
+  const axisLayer = createLayer({ space: "ui", atlas, retainAllPushRecords: true });
+  const marksLayer = createLayer({ space: "ui", atlas, retainAllPushRecords: true });
+  const hudLayer = createLayer({ space: "ui", atlas, retainAllPushRecords: true });
+
+  const snapshot: ChartConfig<T> = { ...config, width: w, height: h };
+  runPipeline(snapshot, currentData(config.data), axisLayer, marksLayer, hudLayer, atlas);
+  // v3 SVG renders shapes in pixel space; `ui`-space layers are scaled by dpr
+  // (1 here). `.element()` is a METHOD on the v3 backend (was a getter in v1).
+  renderer.render([axisLayer, marksLayer, hudLayer]);
+  return renderer.element();
+}

package/src/grammar/theme.d.ts

@@ -0,0 +1,261 @@
+import { type BlendSpace, type Color, type Easing } from "insomni";
+import { type CategoricalPalette, type ContinuousPalette } from "../colors.ts";
+import { type Accessibility, type TextEffects } from "./accessibility.ts";
+export type { Accessibility, AccessibilityMode, TextEffects } from "./accessibility.ts";
+export interface ThemeText {
+    color: Color;
+    fontFamily: string;
+}
+export interface ThemeTitle {
+    fontSize: number;
+    fontWeight: string;
+    color: Color;
+}
+export interface ThemeSubtitle {
+    fontSize: number;
+    color: Color;
+}
+export interface ThemeAxis {
+    color: Color;
+    gridColor: Color;
+    labelFontSize: number;
+    labelColor: Color;
+    titleFontSize: number;
+    titleColor: Color;
+}
+export interface ThemeLegend {
+    fontSize: number;
+    labelColor: Color;
+    swatchGap: number;
+    entryGap: number;
+}
+export interface ThemeMarks {
+    pointRadius: number;
+    pointStroke: Color | undefined;
+    pointStrokeWidth: number;
+    /**
+     * Default stroke width for line-based marks (`line`, `smooth`, `statRolling`,
+     * `area` outline, `aggregate` line geom). Geom-level `strokeWidth` options
+     * override this token per layer.
+     */
+    strokeWidth: number;
+    barCornerRadius: number;
+    fillAlpha: number;
+    /** Font size for value/total labels rendered alongside marks (bar, text). */
+    labelFontSize: number;
+    /** Default stroke width for `rule()` lines. */
+    ruleStrokeWidth: number;
+    /** Default label inset for `rule()` annotations. */
+    ruleLabelInset: number;
+    /** Default font size for inline annotations (rule, band labels). */
+    annotationFontSize: number;
+    /** Default fill alpha for `ribbon()`. */
+    ribbonFillAlpha: number;
+    /** Default fill alpha for `band()` highlight regions. */
+    bandFillAlpha: number;
+    /** Default size-channel pixel range. */
+    sizeRange: readonly [number, number];
+    /** Default alpha-channel range. */
+    alphaRange: readonly [number, number];
+}
+export type ThemeDurationKey = "fast" | "base" | "slow";
+export type ThemeEasingKey = "standard" | "emphasized" | "decelerate" | "linear";
+export interface ThemeDurations {
+    fast: number;
+    base: number;
+    slow: number;
+}
+export interface ThemeEasings {
+    standard: Easing;
+    emphasized: Easing;
+    decelerate: Easing;
+    linear: Easing;
+}
+export interface ThemeMotionChannel {
+    duration: ThemeDurationKey;
+    easing: ThemeEasingKey;
+}
+export interface ThemeMotionTooltip {
+    showDelay: number;
+    hideDelay: number;
+    fadeMs: number;
+    /**
+     * Hover-intent settle (ms). Rapid enter/leave/switch events are coalesced —
+     * the tooltip only commits a show/hide after the cursor holds a target this
+     * long. Prevents an overlay re-render per cell while sweeping across a dense
+     * mark grid or through gaps. 0 disables (commit immediately).
+     */
+    settleDelay: number;
+}
+export interface ThemeMotion {
+    /** Master switch. False → snap, no scheduled motion. */
+    enabled: boolean;
+    duration: ThemeDurations;
+    easing: ThemeEasings;
+    /** Data update / scale change transitions. */
+    data: ThemeMotionChannel;
+    /** Axis tick / domain transitions. */
+    axis: ThemeMotionChannel;
+    tooltip: ThemeMotionTooltip;
+}
+export declare const defaultMotion: ThemeMotion;
+export interface ThemeInteractionEmphasis {
+    /** Master enable. `false` skips both halo and dim. */
+    enabled: boolean;
+    /** Multiplier on non-active rows' fill alpha. `1` = no dim. */
+    dim: number;
+    /** Halo stroke width in CSS px. `0` skips the halo. */
+    haloStrokeWidth: number;
+    /**
+     * Halo ring color. When omitted, geoms fall back to a high-contrast
+     * foreground (`theme.text.color`) so the focus ring reads against the
+     * marks rather than blending in with the datum's own color. Set a `Color`
+     * to pin the ring (e.g. a brand accent).
+     */
+    haloColor?: Color;
+    /**
+     * Duration (ms) of the GPU dim animation driven through the core's emphasis
+     * uniform (P5-T3). On a hover hit-change over a dim-participating geom the
+     * mount ramps the emphasis `t` 0→1 (ease-out cubic) over this window; on
+     * hover exit it ramps t→0. Only consumed by `hover` (selection dim stays a
+     * compile-time treatment). `<= 0` snaps. Default ~120ms.
+     */
+    durationMs?: number;
+}
+/**
+ * Semantic row-tint tokens for tooltip rows that use the
+ * `accent: "positive" | "negative" | "neutral"` shorthand. `neutral` is
+ * intentionally omitted — it means "no override, use the default row text
+ * color from the underlying tooltip style." Consumers can also pass a raw
+ * `Color` per row to bypass these tokens entirely.
+ */
+export interface ThemeTooltipAccents {
+    positive: Color;
+    negative: Color;
+}
+export interface ThemeInteractions {
+    /** Visual treatment applied while a row is hovered. */
+    hover: ThemeInteractionEmphasis;
+    /** Visual treatment applied while rows are selected. */
+    selection: ThemeInteractionEmphasis;
+    /**
+     * Grace window (ms) applied when hover transitions to "nothing" before
+     * propagating the null state to dim/halo and crosshair. If a new hit lands
+     * within this window, the swap goes directly from prev → next without
+     * passing through null — eliminates the un-dim → re-dim flash when the
+     * cursor crosses between adjacent or near-adjacent geoms. `0` disables.
+     */
+    hoverSwapGraceMs: number;
+    /** Semantic row colors for the tooltip `accent` shorthand. */
+    tooltipAccents: ThemeTooltipAccents;
+}
+export declare const defaultInteractions: ThemeInteractions;
+export interface ThemePalettes {
+    categorical: CategoricalPalette;
+    continuous: ContinuousPalette;
+    diverging: ContinuousPalette;
+}
+/**
+ * Semantic accent palette consumed by chart-level marks that carry meaning
+ * (reference regions, threshold rules, callouts, tooltip rows). Geoms that
+ * accept an accent key (`fill: "positive"`, `stroke: "warn"`) resolve through
+ * this block; literal `Color` values still bypass it.
+ *
+ * Naming exception to the "name geoms by what they are, not what they do"
+ * principle: these tokens exist explicitly to carry semantics. The names
+ * follow conventional status vocabulary so any reader can predict the role.
+ *
+ * `neutral` is intentionally omitted — it means "no override, use the
+ * surrounding default" (mark fill, axis label color, …) so consumers can fall
+ * back without spelling out a token.
+ *
+ * Distinct from {@link ThemeTooltipAccents} (under `interactions.tooltipAccents`)
+ * which is sized for tooltip-text contrast and may differ in luminance.
+ */
+export interface ThemeAccents {
+    positive: Color;
+    negative: Color;
+    warn: Color;
+    info: Color;
+}
+export type ThemeAccentKey = keyof ThemeAccents;
+export interface Theme {
+    background: Color;
+    text: ThemeText;
+    title: ThemeTitle;
+    subtitle: ThemeSubtitle;
+    axis: ThemeAxis;
+    legend: ThemeLegend;
+    marks: ThemeMarks;
+    palettes: ThemePalettes;
+    /** Semantic accent palette for chart-level marks (reference regions, threshold rules, callouts). */
+    accents: ThemeAccents;
+    /**
+     * Text-readability policy. Applied at every draw site where the chart
+     * knows the local background color (titles/axis/legend versus the panel
+     * background; tile labels versus their cell color).
+     */
+    accessibility: Accessibility;
+    /**
+     * Default text effects (outline / drop shadow). API stub today — the SDF
+     * text path doesn't render these yet. See
+     * dev_docs/2026-04-30-text-accessibility.md.
+     */
+    textEffects?: TextEffects;
+    /**
+     * Color space used to interpolate continuous palettes (`viridis`, etc.)
+     * when sampled by color scales and color bars. `oklch` is the default —
+     * perceptually uniform with hue preserved along the gradient. Override
+     * per chart (`theme({ paletteBlendSpace: "srgb" })`) or per call (the
+     * `blendSpace` option on color-scale and `colorBar` specs).
+     */
+    paletteBlendSpace: BlendSpace;
+    /**
+     * Motion tokens — durations, easings, and per-channel defaults consumed by
+     * interactions (hover, tooltip), data transitions, and axis updates. See
+     * {@link defaultMotion} and {@link applyReducedMotion}.
+     */
+    motion: ThemeMotion;
+    /**
+     * Hover / selection emphasis tokens. Geoms read these to render the active
+     * row's halo and optionally dim the rest. See {@link defaultInteractions}.
+     */
+    interactions: ThemeInteractions;
+}
+export declare const themeDefault: Theme;
+/**
+ * Light/minimal theme — white plot background, soft gray gridlines, dark
+ * labels. Pairs well with the `category10` palette and is a good default for
+ * scatter / smooth charts that should read like a ggplot2 / R reference.
+ */
+export declare const themeMinimalGrid: Theme;
+export type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+/**
+ * Compose a theme by deep-merging overrides into a base theme. Accepts a
+ * shallow override on any nested group (e.g. `{ marks: { strokeWidth: 2 } }`).
+ */
+export declare function theme(overrides: DeepPartial<Theme>, base?: Theme): Theme;
+export interface ResolvedMotion {
+    /** Duration in milliseconds. 0 when motion is disabled. */
+    durationMs: number;
+    easing: Easing;
+}
+/**
+ * Resolve a motion channel into concrete numbers using the theme's duration
+ * and easing tables. When `motion.enabled` is false, duration collapses to 0
+ * so callers can branch on `durationMs <= 0` to snap.
+ */
+export declare function resolveMotion(motion: ThemeMotion, channel: ThemeMotionChannel): ResolvedMotion;
+/**
+ * True when the runtime reports `prefers-reduced-motion: reduce`. SSR-safe:
+ * returns false when `window`/`matchMedia` are unavailable.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Return a theme with motion disabled and tooltip delays/fade zeroed. Apply
+ * to honor the user's `prefers-reduced-motion` setting. Keeps easings intact
+ * so callers that ignore `enabled` and read durations directly still work.
+ */
+export declare function applyReducedMotion(t: Theme): Theme;

package/src/grammar/theme.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import {
+  applyReducedMotion,
+  defaultInteractions,
+  defaultMotion,
+  prefersReducedMotion,
+  resolveMotion,
+  theme,
+  themeDefault,
+  themeMinimalGrid,
+} from "./theme.ts";
+
+describe("theme — interactions.hover.durationMs (P5-T3)", () => {
+  test("default hover emphasis carries a ~120ms GPU-dim duration", () => {
+    expect(defaultInteractions.hover.durationMs).toBe(120);
+    expect(themeDefault.interactions.hover.durationMs).toBe(120);
+  });
+
+  test("selection emphasis has no durationMs (selection dim stays compile-time)", () => {
+    expect(defaultInteractions.selection.durationMs).toBeUndefined();
+  });
+});
+
+describe("theme — motion tokens", () => {
+  test("themeDefault carries defaultMotion", () => {
+    expect(themeDefault.motion).toBe(defaultMotion);
+    expect(themeDefault.motion.enabled).toBe(true);
+    expect(themeDefault.motion.duration.fast).toBe(120);
+    expect(themeDefault.motion.duration.base).toBe(240);
+    expect(themeDefault.motion.duration.slow).toBe(480);
+  });
+
+  test("themeMinimalGrid inherits motion via spread", () => {
+    expect(themeMinimalGrid.motion).toBe(defaultMotion);
+  });
+
+  test("resolveMotion looks up named duration + easing when enabled", () => {
+    const r = resolveMotion(defaultMotion, { duration: "fast", easing: "standard" });
+    expect(r.durationMs).toBe(120);
+    expect(r.easing).toBe(defaultMotion.easing.standard);
+  });
+
+  test("resolveMotion collapses duration to 0 when disabled", () => {
+    const m = { ...defaultMotion, enabled: false };
+    const r = resolveMotion(m, m.data);
+    expect(r.durationMs).toBe(0);
+    expect(r.easing).toBe(defaultMotion.easing.emphasized);
+  });
+
+  test("applyReducedMotion zeros durations + tooltip delays, keeps easings", () => {
+    const reduced = applyReducedMotion(themeDefault);
+    expect(reduced.motion.enabled).toBe(false);
+    expect(reduced.motion.duration).toEqual({ fast: 0, base: 0, slow: 0 });
+    expect(reduced.motion.tooltip).toEqual({
+      showDelay: 0,
+      hideDelay: 0,
+      fadeMs: 0,
+      settleDelay: 0,
+    });
+    expect(reduced.motion.easing.standard).toBe(defaultMotion.easing.standard);
+    // original is untouched
+    expect(themeDefault.motion.duration.fast).toBe(120);
+  });
+
+  test("theme() override merges motion field", () => {
+    const t = theme({ motion: { duration: { fast: 50, base: 100, slow: 200 } } });
+    expect(t.motion.duration.fast).toBe(50);
+    expect(t.motion.enabled).toBe(true);
+    // other channels untouched
+    expect(t.motion.data.duration).toBe("base");
+  });
+
+  test("prefersReducedMotion returns false when matchMedia missing", () => {
+    // jsdom typically lacks matchMedia by default; if present, this just
+    // exercises the call path without asserting the boolean.
+    const result = prefersReducedMotion();
+    expect(typeof result).toBe("boolean");
+  });
+});
+
+describe("theme — semantic accents", () => {
+  test("themeDefault carries the four semantic accent tokens", () => {
+    expect(themeDefault.accents).toBeDefined();
+    expect(themeDefault.accents.positive).toBeDefined();
+    expect(themeDefault.accents.negative).toBeDefined();
+    expect(themeDefault.accents.warn).toBeDefined();
+    expect(themeDefault.accents.info).toBeDefined();
+  });
+
+  test("themeMinimalGrid overrides accents for light-background contrast", () => {
+    // Light theme picks higher-saturation values than the dark theme so
+    // shaded regions still read on white. Sanity-check that the override
+    // happened — the green channel of `positive` differs between themes.
+    expect(themeMinimalGrid.accents.positive).not.toBe(themeDefault.accents.positive);
+  });
+
+  test("theme() override merges accents field", () => {
+    const customRed = { r: 1, g: 0, b: 0, a: 1 };
+    const t = theme({ accents: { negative: customRed } });
+    expect(t.accents.negative).toEqual(customRed);
+    // other accents preserved
+    expect(t.accents.positive).toBe(themeDefault.accents.positive);
+  });
+});