insomni-plot 0.1.0-alpha.0

package/src/grammar/theme.ts

@@ -0,0 +1,490 @@
+// ---------------------------------------------------------------------------
+// Theme
+// ---------------------------------------------------------------------------
+// Visual style for a chart. Themes are values; live-toggle works because the
+// chart owns a `Signal<Theme>` (see chart.ts) and re-renders on `.set(...)`.
+
+import {
+  easeInOutCubic,
+  easeOutCubic,
+  easeOutQuad,
+  linear as linearEasing,
+  rgba,
+  type BlendSpace,
+  type Color,
+  type Easing,
+} from "insomni";
+import { category10, viridis, type CategoricalPalette, type ContinuousPalette } from "../colors.ts";
+import { DEFAULT_ACCESSIBILITY, 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];
+}
+
+// ---------------------------------------------------------------------------
+// Motion tokens
+// ---------------------------------------------------------------------------
+// Durations are milliseconds. Geoms and interaction primitives read these
+// names rather than hard-coded numbers so a single theme switch retunes the
+// whole chart's motion. `enabled: false` is the master kill — interactions
+// should snap rather than animate. Use `applyReducedMotion(theme)` to derive
+// a theme honoring `prefers-reduced-motion`.
+
+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 const defaultMotion: ThemeMotion = {
+  enabled: true,
+  duration: { fast: 120, base: 240, slow: 480 },
+  easing: {
+    standard: easeInOutCubic,
+    emphasized: easeOutCubic,
+    decelerate: easeOutQuad,
+    linear: linearEasing,
+  },
+  data: { duration: "base", easing: "emphasized" },
+  axis: { duration: "base", easing: "standard" },
+  tooltip: { showDelay: 0, hideDelay: 50, fadeMs: 80, settleDelay: 30 },
+};
+
+// ---------------------------------------------------------------------------
+// Interaction visuals — hover / selection emphasis tokens
+// ---------------------------------------------------------------------------
+// Geoms read these to render their hover halo and (optionally) dim the
+// non-hovered rows. Two complementary techniques compose: a halo that draws
+// the active row in a stronger stroke on top, and a dim factor applied to the
+// fill alpha of the others. Both are off by default for sparse marks (point,
+// line) and on for shape-based marks (bar, histogram, ridgeline, tile,
+// boxplot, violin) where overlap makes a point-only halo hard to read.
+//
+// `dim` is a multiplier applied to the resolved fill alpha of non-hovered
+// rows (1 = no dim, 0 = invisible). `haloStrokeWidth` is in CSS px.
+
+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 const defaultInteractions: ThemeInteractions = {
+  hover: { enabled: true, dim: 0.45, haloStrokeWidth: 2, durationMs: 120 },
+  selection: { enabled: true, dim: 0.3, haloStrokeWidth: 2 },
+  hoverSwapGraceMs: 50,
+  tooltipAccents: {
+    positive: rgba(0.45, 0.83, 0.58, 1),
+    negative: rgba(0.96, 0.55, 0.55, 1),
+  },
+};
+
+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;
+}
+
+const FONT_STACK = "system-ui, -apple-system, Inter, sans-serif";
+
+export const themeDefault: Theme = {
+  background: rgba(0.02, 0.04, 0.07, 1),
+  text: {
+    color: rgba(0.85, 0.9, 0.98, 1),
+    fontFamily: FONT_STACK,
+  },
+  title: {
+    fontSize: 14,
+    fontWeight: "600",
+    color: rgba(0.92, 0.95, 1, 1),
+  },
+  subtitle: {
+    fontSize: 14,
+    color: rgba(0.7, 0.78, 0.9, 0.9),
+  },
+  axis: {
+    color: rgba(0.6, 0.68, 0.78, 0.85),
+    gridColor: rgba(0.38, 0.5, 0.62, 0.18),
+    labelFontSize: 14,
+    labelColor: rgba(0.6, 0.68, 0.78, 0.85),
+    titleFontSize: 14,
+    titleColor: rgba(0.85, 0.9, 0.98, 1),
+  },
+  legend: {
+    fontSize: 14,
+    labelColor: rgba(0.85, 0.9, 0.98, 1),
+    swatchGap: 6,
+    entryGap: 14,
+  },
+  marks: {
+    pointRadius: 3,
+    pointStroke: rgba(1, 1, 1, 0.18),
+    pointStrokeWidth: 0.75,
+    strokeWidth: 1.5,
+    barCornerRadius: 1,
+    fillAlpha: 0.85,
+    labelFontSize: 14,
+    ruleStrokeWidth: 1,
+    ruleLabelInset: 4,
+    annotationFontSize: 14,
+    ribbonFillAlpha: 0.18,
+    bandFillAlpha: 0.08,
+    sizeRange: [2, 14],
+    alphaRange: [0.2, 1],
+  },
+  palettes: {
+    categorical: category10,
+    continuous: viridis,
+    diverging: viridis,
+  },
+  accents: {
+    positive: rgba(0.45, 0.83, 0.58, 1),
+    negative: rgba(0.96, 0.55, 0.55, 1),
+    warn: rgba(0.98, 0.78, 0.36, 1),
+    info: rgba(0.5, 0.72, 0.96, 1),
+  },
+  accessibility: DEFAULT_ACCESSIBILITY,
+  paletteBlendSpace: "oklch",
+  motion: defaultMotion,
+  interactions: defaultInteractions,
+};
+
+/**
+ * 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 const themeMinimalGrid: Theme = {
+  ...themeDefault,
+  background: rgba(1, 1, 1, 1),
+  text: { color: rgba(0.2, 0.22, 0.27, 1), fontFamily: FONT_STACK },
+  title: { fontSize: 14, fontWeight: "600", color: rgba(0.15, 0.17, 0.22, 1) },
+  subtitle: { fontSize: 14, color: rgba(0.4, 0.43, 0.5, 1) },
+  axis: {
+    color: rgba(0.6, 0.62, 0.68, 1),
+    gridColor: rgba(0.85, 0.87, 0.9, 1),
+    labelFontSize: 14,
+    labelColor: rgba(0.35, 0.38, 0.45, 1),
+    titleFontSize: 14,
+    titleColor: rgba(0.2, 0.22, 0.27, 1),
+  },
+  legend: {
+    fontSize: 14,
+    labelColor: rgba(0.2, 0.22, 0.27, 1),
+    swatchGap: 6,
+    entryGap: 14,
+  },
+  marks: {
+    ...themeDefault.marks,
+    pointStroke: undefined,
+    pointStrokeWidth: 0,
+    fillAlpha: 1,
+  },
+  accents: {
+    positive: rgba(0.16, 0.62, 0.36, 1),
+    negative: rgba(0.78, 0.22, 0.22, 1),
+    warn: rgba(0.85, 0.55, 0.1, 1),
+    info: rgba(0.18, 0.45, 0.78, 1),
+  },
+};
+
+export type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Date);
+}
+
+function deepMerge<T>(base: T, override: DeepPartial<T>): T {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return (override as T) ?? base;
+  }
+  const out = { ...base } as Record<string, unknown>;
+  for (const key of Object.keys(override)) {
+    const a = (base as Record<string, unknown>)[key];
+    const b = (override as Record<string, unknown>)[key];
+    if (b === undefined) continue;
+    if (isPlainObject(a) && isPlainObject(b)) {
+      out[key] = deepMerge(a, b as DeepPartial<unknown>);
+    } else {
+      out[key] = b;
+    }
+  }
+  return out as T;
+}
+
+/**
+ * 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 function theme(overrides: DeepPartial<Theme>, base: Theme = themeDefault): Theme {
+  return deepMerge(base, overrides);
+}
+
+// ---------------------------------------------------------------------------
+// Motion helpers
+// ---------------------------------------------------------------------------
+
+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 function resolveMotion(motion: ThemeMotion, channel: ThemeMotionChannel): ResolvedMotion {
+  return {
+    durationMs: motion.enabled ? motion.duration[channel.duration] : 0,
+    easing: motion.easing[channel.easing],
+  };
+}
+
+/**
+ * True when the runtime reports `prefers-reduced-motion: reduce`. SSR-safe:
+ * returns false when `window`/`matchMedia` are unavailable.
+ */
+export function prefersReducedMotion(): boolean {
+  if (typeof globalThis === "undefined") return false;
+  const w = (globalThis as { matchMedia?: (q: string) => { matches: boolean } }).matchMedia;
+  if (typeof w !== "function") return false;
+  return w("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * 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 function applyReducedMotion(t: Theme): Theme {
+  return {
+    ...t,
+    motion: {
+      ...t.motion,
+      enabled: false,
+      duration: { fast: 0, base: 0, slow: 0 },
+      tooltip: { showDelay: 0, hideDelay: 0, fadeMs: 0, settleDelay: 0 },
+    },
+  };
+}

package/src/heatmap/cpu.ts

@@ -0,0 +1,109 @@
+// ---------------------------------------------------------------------------
+// CPU heatmap renderer — used by the SVGRenderer path.
+// ---------------------------------------------------------------------------
+
+import { createLayer, type Layer } from "insomni";
+import { normalizeValue, type ResolvedSpec } from "./types.ts";
+
+/**
+ * CPU heatmap output: v3 `Layer`s of vector rects, consumed by the SVG export
+ * path and device-less consumers.
+ *
+ * The v1-only rasterized `ImageLayer` fast-path (dense grids / `svgExport:
+ * "image"`) was dropped in the v3 migration: v3's SVG renderer walks
+ * `Layer.pack` only and cannot emit `<image>`/sprite drawables, so that path
+ * silently rendered nothing post-migration. Dense grids now always emit vector
+ * rects (correct, if heavier). Re-introducing image export is future work on
+ * the v3 SVG backend (sprite → `<image>`).
+ */
+export type HeatmapCpuDrawable = Layer;
+
+export class HeatmapCpuRenderer<T> {
+  private readonly spec: ResolvedSpec<T>;
+  private data: readonly T[];
+  private bins: Float64Array;
+  private max = 0;
+  private dirty = true;
+
+  constructor(spec: ResolvedSpec<T>, data: readonly T[]) {
+    this.spec = spec;
+    this.data = data;
+    this.bins = new Float64Array(spec.nx * spec.ny);
+  }
+
+  setData(data: readonly T[]): void {
+    this.data = data;
+    this.dirty = true;
+  }
+
+  markDirty(): void {
+    this.dirty = true;
+  }
+
+  /** Largest bin weight after the most recent rebin. Useful for legend domains. */
+  getMax(): number {
+    if (this.dirty) this.rebin();
+    return this.max;
+  }
+
+  build(): readonly HeatmapCpuDrawable[] {
+    if (this.dirty) this.rebin();
+    const { nx, ny, frame, colorMap, normalize } = this.spec;
+    const max = this.max;
+
+    const layer = createLayer({ space: "ui" });
+    if (max <= 0) return [layer];
+
+    const cellW = frame.width / nx;
+    const cellH = frame.height / ny;
+    for (let iy = 0; iy < ny; iy++) {
+      for (let ix = 0; ix < nx; ix++) {
+        const v = this.bins[iy * nx + ix]!;
+        if (v <= 0) continue;
+        layer.pushRect({
+          x: frame.x + ix * cellW,
+          y: frame.y + iy * cellH,
+          width: cellW,
+          height: cellH,
+          fill: colorMap(normalizeValue(v, max, normalize)),
+        });
+      }
+    }
+    return [layer];
+  }
+
+  private rebin(): void {
+    const spec = this.spec;
+    const { nx, ny, x0, x1, y0, y1 } = spec;
+    const dx = x1 - x0;
+    const dy = y1 - y0;
+    const bins = this.bins;
+    bins.fill(0);
+
+    if (dx === 0 || dy === 0) {
+      this.max = 0;
+      this.dirty = false;
+      return;
+    }
+
+    let max = 0;
+    for (const datum of this.data) {
+      const xv = spec.x(datum);
+      const yv = spec.y(datum);
+      const tx = (xv - x0) / dx;
+      const ty = (yv - y0) / dy;
+      if (tx < 0 || tx >= 1 || ty < 0 || ty >= 1) continue;
+      const ix = Math.min(nx - 1, Math.floor(tx * nx));
+      // Flip iy so row 0 is the *top* of the frame visually — matches axis
+      // convention where higher data-y is drawn higher on screen.
+      const iy = ny - 1 - Math.min(ny - 1, Math.floor(ty * ny));
+      const idx = iy * nx + ix;
+      const w = spec.weight(datum);
+      const next = bins[idx]! + w;
+      bins[idx] = next;
+      if (next > max) max = next;
+    }
+    this.max = max;
+    this.dirty = false;
+  }
+}