insomni-plot 0.1.0-alpha.0

package/src/grammar/interactions/transitions.test.ts

@@ -0,0 +1,172 @@
+import { createInvalidator } from "insomni";
+import { linear } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import type { GeomFrame } from "../geoms/types.ts";
+import { createGrammarTransitions } from "./transitions.ts";
+
+function makeFrame(count: number, xVal = 0, yVal = 0, ids?: string[]): GeomFrame {
+  const x = new Float32Array(count).fill(xVal);
+  const y = new Float32Array(count).fill(yVal);
+  const rgba = new Float32Array(count * 4).fill(0.5);
+  const a = new Float32Array(count).fill(1);
+  return { count, x, y, rgba, a, ids };
+}
+
+describe("createGrammarTransitions", () => {
+  test("starts inactive with no stored frames", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+    expect(t.active).toBe(false);
+    expect(t.contextFor(0)).toBeUndefined();
+  });
+
+  test("storeFrame records a frame, notifyChange on empty store is a no-op", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+    // notifyChange before any frames = no-op (nothing to transition from)
+    t.notifyChange();
+    expect(t.active).toBe(false);
+
+    // storeFrame with no pending change: just stores, no transition
+    t.storeFrame(0, makeFrame(3, 10, 20));
+    expect(t.active).toBe(false);
+    expect(t.contextFor(0)).toBeUndefined();
+  });
+
+  test("notifyChange after storeFrame starts a transition", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    // First stable frame at x=10
+    t.storeFrame(0, makeFrame(2, 10, 0));
+    expect(t.active).toBe(false);
+
+    // Data changes → notify before pipeline runs
+    t.notifyChange();
+    expect(t.active).toBe(false); // transition hasn't started yet (waiting for first storeFrame)
+
+    // Pipeline compiles new data → store new frame at x=20
+    t.storeFrame(0, makeFrame(2, 20, 0));
+
+    // Now transition should be active
+    expect(t.active).toBe(true);
+
+    // contextFor returns the from-frame (old x=10) and t=0
+    const ctx = t.contextFor(0);
+    expect(ctx).toBeDefined();
+    expect(ctx!.t).toBe(0); // progress just started
+    expect(ctx!.from.x[0]).toBe(10); // from the OLD frame
+  });
+
+  test("step advances progress; transition ends at duration", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    t.storeFrame(0, makeFrame(1, 0, 0));
+    t.notifyChange();
+    t.storeFrame(0, makeFrame(1, 100, 0));
+
+    expect(t.active).toBe(true);
+
+    t.step(0.5);
+    const ctx = t.contextFor(0);
+    expect(ctx!.t).toBeCloseTo(0.5, 5);
+
+    t.step(0.5);
+    expect(t.active).toBe(false);
+    expect(t.contextFor(0)).toBeUndefined();
+  });
+
+  test("storeFrame during active transition does NOT clobber from-frame stable store", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    // Stable frame: x=10
+    t.storeFrame(0, makeFrame(1, 10, 0));
+    t.notifyChange();
+    // New frame: x=50
+    t.storeFrame(0, makeFrame(1, 50, 0));
+
+    expect(t.active).toBe(true);
+
+    // Mid-animation, another storeFrame arrives (e.g. same frame ticked)
+    t.step(0.25);
+    t.storeFrame(0, makeFrame(1, 50, 0)); // same new values, just updating stable store
+
+    // from-frame should still be x=10 (not 50)
+    const ctx = t.contextFor(0);
+    expect(ctx!.from.x[0]).toBe(10);
+  });
+
+  test("requestTransition behaves same as notifyChange + storeFrame", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    t.storeFrame(0, makeFrame(1, 5, 0));
+    t.requestTransition();
+    t.storeFrame(0, makeFrame(1, 15, 0));
+
+    expect(t.active).toBe(true);
+    const ctx = t.contextFor(0);
+    expect(ctx!.from.x[0]).toBe(5);
+  });
+
+  test("no context returned for layer with no stored from-frame", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    // Store for layer 0 only
+    t.storeFrame(0, makeFrame(1, 10, 0));
+    t.notifyChange();
+    t.storeFrame(0, makeFrame(1, 20, 0));
+
+    expect(t.active).toBe(true);
+    // Layer 1 has no stored frame
+    expect(t.contextFor(1)).toBeUndefined();
+    // Layer 0 has one
+    expect(t.contextFor(0)).toBeDefined();
+  });
+
+  test("scopes frames independently for faceted panels", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    t.storeFrame(0, makeFrame(1, 10, 0), "a");
+    t.storeFrame(0, makeFrame(1, 30, 0), "b");
+    t.notifyChange();
+    t.storeFrame(0, makeFrame(1, 20, 0), "a");
+    t.storeFrame(0, makeFrame(1, 40, 0), "b");
+
+    expect(t.active).toBe(true);
+    expect(t.contextFor(0, "a")!.from.x[0]).toBe(10);
+    expect(t.contextFor(0, "b")!.from.x[0]).toBe(30);
+    expect(t.contextFor(0, "c")).toBeUndefined();
+  });
+
+  test("contextFor resolves prior indices by stable ids when present", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 1, easing: linear, invalidator: inv });
+
+    t.storeFrame(0, makeFrame(2, 10, 0, ["a", "b"]));
+    t.notifyChange();
+    t.storeFrame(0, makeFrame(2, 20, 0, ["b", "a"]));
+
+    const ctx = t.contextFor(0)!;
+    expect(ctx.matchIndex("a")).toBe(0);
+    expect(ctx.matchIndex("b")).toBe(1);
+    expect(ctx.matchIndex("c")).toBeUndefined();
+  });
+
+  test("step returns true while active, false when done", () => {
+    const inv = createInvalidator(false);
+    const t = createGrammarTransitions({ duration: 0.5, easing: linear, invalidator: inv });
+
+    t.storeFrame(0, makeFrame(1));
+    t.notifyChange();
+    t.storeFrame(0, makeFrame(1));
+
+    expect(t.step(0.25)).toBe(true);
+    expect(t.step(0.25)).toBe(false);
+  });
+});

package/src/grammar/interactions/transitions.ts

@@ -0,0 +1,160 @@
+// ---------------------------------------------------------------------------
+// GrammarTransitions — data/scale animated transitions for the chart pipeline
+// ---------------------------------------------------------------------------
+// Manages a single 0→1 progress tween that drives all channel interpolation
+// in geom compile methods. Geoms call `captureFrame` to snapshot their current
+// state; `notifyChange` snapshots those frames as "from" before the next data
+// compile runs; then `contextFor` provides the ActiveTransition to each geom
+// during the animated compile passes.
+
+import { transition, type Transition, type Easing } from "insomni";
+import type { Invalidator } from "insomni";
+import type { ActiveTransition, GeomFrame } from "../geoms/types.ts";
+
+export interface TransitionsOptions {
+  /** Duration in seconds. */
+  duration: number;
+  easing: Easing;
+  invalidator: Invalidator;
+}
+
+export interface GrammarTransitions {
+  /** Advance the progress tween. Returns true while a transition is active. */
+  step(dt: number): boolean;
+  /**
+   * Signal that data/config has changed. If stored frames exist, snapshots
+   * them as "from" frames before the new pipeline compiles.
+   */
+  notifyChange(): void;
+  /**
+   * Returns the active transition context for geom at layer index `i`,
+   * or undefined when no transition is running or no stored frame exists.
+   */
+  contextFor(layerIndex: number, scope?: unknown): ActiveTransition | undefined;
+  /**
+   * Store the current compiled frame for future "from" use.
+   * Always updates the stable store. If a transition was just signalled,
+   * kicks off the progress tween.
+   */
+  storeFrame(layerIndex: number, frame: GeomFrame, scope?: unknown): void;
+  /** True while a transition is running. */
+  readonly active: boolean;
+  /** Imperatively request a transition on next draw, even without a data change. */
+  requestTransition(): void;
+}
+
+export function createGrammarTransitions(opts: TransitionsOptions): GrammarTransitions {
+  const ROOT_SCOPE = Symbol("root");
+  // oxlint-disable-next-line no-redundant-type-constituents -- unknown subsumes typeof ROOT_SCOPE; kept for documentation intent (keys are either the root symbol or a caller-supplied scope value)
+  type ScopeKey = typeof ROOT_SCOPE | unknown;
+  // Stored frames from the last stable (non-animating) compile, keyed by scope + layer index.
+  const stored = new Map<ScopeKey, Map<number, GeomFrame>>();
+  // From-frames captured when a transition starts (snapshotted from `stored`).
+  const fromFrames = new Map<ScopeKey, Map<number, GeomFrame>>();
+  // Whether a change notification arrived and is waiting for the first storeFrame.
+  let transitionStarting = false;
+
+  // Duration must be > 0. If motion is disabled the caller passes a near-zero value.
+  const durationSec = Math.max(opts.duration, 0.001);
+
+  // Single progress transition: 0 → 1.
+  // Starts at 1 (not animating) so the first frame is instant.
+  const progress: Transition<number> = transition({
+    initial: 1,
+    duration: durationSec,
+    easing: opts.easing,
+    invalidator: opts.invalidator,
+  });
+
+  function normalizeScope(scope: unknown): ScopeKey {
+    return scope === undefined ? ROOT_SCOPE : scope;
+  }
+
+  function frameFor(
+    source: Map<ScopeKey, Map<number, GeomFrame>>,
+    scope: unknown,
+    layerIndex: number,
+  ): GeomFrame | undefined {
+    return source.get(normalizeScope(scope))?.get(layerIndex);
+  }
+
+  function setFrame(
+    target: Map<ScopeKey, Map<number, GeomFrame>>,
+    scope: unknown,
+    layerIndex: number,
+    frame: GeomFrame,
+  ): void {
+    const scopeKey = normalizeScope(scope);
+    let scoped = target.get(scopeKey);
+    if (!scoped) {
+      scoped = new Map<number, GeomFrame>();
+      target.set(scopeKey, scoped);
+    }
+    scoped.set(layerIndex, frame);
+  }
+
+  function copyFrames(
+    source: Map<ScopeKey, Map<number, GeomFrame>>,
+    target: Map<ScopeKey, Map<number, GeomFrame>>,
+  ): void {
+    target.clear();
+    for (const [scope, scoped] of source) {
+      target.set(scope, new Map(scoped));
+    }
+  }
+
+  return {
+    get active() {
+      return progress.active;
+    },
+
+    step(dt) {
+      if (dt <= 0) return progress.active;
+      progress.step(dt);
+      return progress.active;
+    },
+
+    notifyChange() {
+      if (stored.size === 0) return; // No stored frames = first draw, nothing to transition from.
+      // Snapshot stored → fromFrames BEFORE the new data compiles.
+      copyFrames(stored, fromFrames);
+      transitionStarting = true;
+    },
+
+    requestTransition() {
+      if (stored.size === 0) return;
+      copyFrames(stored, fromFrames);
+      transitionStarting = true;
+    },
+
+    contextFor(layerIndex, scope) {
+      if (!progress.active) return undefined;
+      const from = frameFor(fromFrames, scope, layerIndex);
+      if (!from) return undefined;
+      const idToIndex = from.ids ? new Map(from.ids.map((id, i) => [id, i] as const)) : null;
+      return {
+        t: progress.value,
+        from,
+        matchIndex(key, fallbackIndex) {
+          if (idToIndex) return idToIndex.get(key);
+          return fallbackIndex !== undefined && fallbackIndex < from.count
+            ? fallbackIndex
+            : undefined;
+        },
+      };
+    },
+
+    storeFrame(layerIndex, frame, scope) {
+      // Always update the stable store with the latest compiled frame so future
+      // transitions have current data as their "from".
+      setFrame(stored, scope, layerIndex, frame);
+      // If a change was signalled, kick off the tween on the first storeFrame call.
+      if (transitionStarting) {
+        transitionStarting = false;
+        progress.setValue(0);
+        progress.setTarget(1);
+        opts.invalidator.invalidate();
+      }
+    },
+  };
+}

package/src/grammar/layout.d.ts

@@ -0,0 +1,68 @@
+import { type Frame, type GlyphAtlas, type Padding } from "insomni";
+import { type AxisOptions } from "../axis.ts";
+import type { Theme } from "./theme.ts";
+/** Pixel size of a reserved side slot. */
+export interface SlotSize {
+    width: number;
+    height: number;
+}
+export interface SlotMap {
+    top?: SlotSize;
+    right?: SlotSize;
+    bottom?: SlotSize;
+    left?: SlotSize;
+}
+export interface SlotAnchors {
+    /** Top-left of the top slot (full outer width above the plot). */
+    top?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Top-left of the right slot (full plot height to the right of the plot). */
+    right?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    bottom?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    left?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface PlotLayout {
+    /** Full canvas frame (outermost). */
+    readonly viewport: Frame;
+    /** Inset frame after the chart's outer padding. */
+    readonly outer: Frame;
+    /** Inner plot frame where marks render — axes + slots carved out. */
+    readonly plot: Frame;
+    /** Top-left + size of each reserved slot, when reserved. */
+    readonly slots: SlotAnchors;
+}
+export interface LayoutInput {
+    width: number;
+    height: number;
+    /** Outer-frame inset, in pixels. Default 16. */
+    padding?: Padding;
+    theme: Theme;
+    atlas: GlyphAtlas | undefined;
+    /** Sample tick values used to measure axis label width before we know domains. */
+    xSample: readonly (number | string | Date)[];
+    ySample: readonly (number | string | Date)[];
+    xAxisOptions?: AxisOptions<unknown>;
+    yAxisOptions?: AxisOptions<unknown>;
+    /** Reserved space on each side of the plot frame. */
+    slots?: SlotMap;
+}
+export declare function computeLayout(input: LayoutInput): PlotLayout;

package/src/grammar/layout.ts

@@ -0,0 +1,186 @@
+// ---------------------------------------------------------------------------
+// Layout — turn outer frame + measured axes + slot reservations into a plot frame
+// ---------------------------------------------------------------------------
+// Two-pass measure (matches what every demo does today):
+//   1. Build axes against placeholder scales just to measure label widths.
+//   2. Subtract those widths + slot reservations (top/right/bottom/left) from
+//      the outer frame to get the plot frame; rebuild axes against real scales.
+//
+// Slots replace the per-feature reservation API (title height, legend
+// height/width). Whoever owns a slot — the pipeline composes title + legend
+// as `Placeable`s and measures the outer bbox per side — passes the resulting
+// width/height in here. Layout doesn't know what's in the slot, only how
+// much room it needs.
+
+import { viewportFrame, type Frame, type GlyphAtlas, type Padding } from "insomni";
+import { bottomAxis, leftAxis, type AxisMeasurement, type AxisOptions } from "../axis.ts";
+import { bandScale, linearScale } from "../scales.ts";
+import { DEFAULT_PADDING, LAYOUT_GAP } from "./constants.ts";
+import type { Theme } from "./theme.ts";
+
+/** Pixel size of a reserved side slot. */
+export interface SlotSize {
+  width: number;
+  height: number;
+}
+
+export interface SlotMap {
+  top?: SlotSize;
+  right?: SlotSize;
+  bottom?: SlotSize;
+  left?: SlotSize;
+}
+
+export interface SlotAnchors {
+  /** Top-left of the top slot (full outer width above the plot). */
+  top?: { x: number; y: number; width: number; height: number };
+  /** Top-left of the right slot (full plot height to the right of the plot). */
+  right?: { x: number; y: number; width: number; height: number };
+  bottom?: { x: number; y: number; width: number; height: number };
+  left?: { x: number; y: number; width: number; height: number };
+}
+
+export interface PlotLayout {
+  /** Full canvas frame (outermost). */
+  readonly viewport: Frame;
+  /** Inset frame after the chart's outer padding. */
+  readonly outer: Frame;
+  /** Inner plot frame where marks render — axes + slots carved out. */
+  readonly plot: Frame;
+  /** Top-left + size of each reserved slot, when reserved. */
+  readonly slots: SlotAnchors;
+}
+
+export interface LayoutInput {
+  width: number;
+  height: number;
+  /** Outer-frame inset, in pixels. Default 16. */
+  padding?: Padding;
+  theme: Theme;
+  atlas: GlyphAtlas | undefined;
+  /** Sample tick values used to measure axis label width before we know domains. */
+  xSample: readonly (number | string | Date)[];
+  ySample: readonly (number | string | Date)[];
+  xAxisOptions?: AxisOptions<unknown>;
+  yAxisOptions?: AxisOptions<unknown>;
+  /** Reserved space on each side of the plot frame. */
+  slots?: SlotMap;
+}
+
+export function computeLayout(input: LayoutInput): PlotLayout {
+  const { width, height, padding = DEFAULT_PADDING } = input;
+
+  const viewport = viewportFrame(width, height);
+  const outer = viewport.padded(padding);
+
+  const xMeasure = measureAxis("x", input);
+  const yMeasure = measureAxis("y", input);
+
+  const slots = input.slots ?? {};
+  const topSlotH = slots.top?.height ?? 0;
+  const rightSlotW = slots.right?.width ?? 0;
+  const bottomSlotH = slots.bottom?.height ?? 0;
+  const leftSlotW = slots.left?.width ?? 0;
+
+  // Each populated slot is followed by its own gap before the plot edge.
+  // Empty slots contribute 0.
+  const topGap = topSlotH > 0 ? LAYOUT_GAP.legendToPlot : 0;
+  const rightGap = rightSlotW > 0 ? LAYOUT_GAP.legendToPlot : 0;
+  const bottomGap = bottomSlotH > 0 ? LAYOUT_GAP.legendToPlot : 0;
+  const leftGap = leftSlotW > 0 ? LAYOUT_GAP.legendToPlot : 0;
+
+  // Vertical y-axis title sits above the axis along the value range; that
+  // overhead must be reserved on top *in addition to* the top slot. This
+  // remains an axis-specific special case — see dev_docs entry on
+  // "axialTitleOverhead" for why.
+  const plot = outer.padded({
+    top: topSlotH + topGap + LAYOUT_GAP.topReservation + yMeasure.axialTitleOverhead,
+    right: rightSlotW + rightGap + LAYOUT_GAP.plotRight,
+    bottom: xMeasure.thickness + LAYOUT_GAP.axisToPlot + bottomSlotH + bottomGap,
+    left: yMeasure.thickness + LAYOUT_GAP.axisToPlot + leftSlotW + leftGap,
+  });
+
+  const slotAnchors: SlotAnchors = {};
+  if (topSlotH > 0) {
+    slotAnchors.top = {
+      x: outer.x,
+      y: outer.y,
+      width: outer.width,
+      height: topSlotH,
+    };
+  }
+  if (rightSlotW > 0) {
+    slotAnchors.right = {
+      x: plot.x + plot.width + rightGap,
+      y: plot.y,
+      width: rightSlotW,
+      height: plot.height,
+    };
+  }
+  if (bottomSlotH > 0) {
+    slotAnchors.bottom = {
+      x: outer.x,
+      y: plot.y + plot.height + xMeasure.thickness + LAYOUT_GAP.axisToPlot + bottomGap,
+      width: outer.width,
+      height: bottomSlotH,
+    };
+  }
+  if (leftSlotW > 0) {
+    slotAnchors.left = {
+      x: outer.x,
+      y: plot.y,
+      width: leftSlotW,
+      height: plot.height,
+    };
+  }
+
+  return { viewport, outer, plot, slots: slotAnchors };
+}
+
+function measureAxis(channel: "x" | "y", input: LayoutInput): AxisMeasurement {
+  // Approximate. We don't know the real domain yet, so use an order-of-magnitude
+  // sample to size labels and pick a thickness that comfortably fits.
+  if (!input.atlas) {
+    const labelHeight = input.theme.axis.labelFontSize;
+    return {
+      thickness: channel === "x" ? 36 : 48,
+      maxLabelWidth: 0,
+      labelHeight,
+      hasTitle: false,
+      titleHeight: 0,
+      axialTitleOverhead: 0,
+    };
+  }
+  const sample = channel === "x" ? input.xSample : input.ySample;
+  const numericSample = sample.filter((v) => typeof v === "number") as number[];
+  const stringSample = sample.filter((v) => typeof v === "string") as string[];
+  const lo = numericSample.length ? Math.min(...numericSample) : 0;
+  const hi = numericSample.length ? Math.max(...numericSample) : 1;
+
+  const opts = channel === "x" ? (input.xAxisOptions ?? {}) : (input.yAxisOptions ?? {});
+  const enriched: AxisOptions<unknown> = {
+    ...opts,
+    atlas: input.atlas,
+    labelFontSize: opts.labelFontSize ?? input.theme.axis.labelFontSize,
+    labelColor: opts.labelColor ?? input.theme.axis.labelColor,
+    titleColor: opts.titleColor ?? input.theme.axis.titleColor,
+    titleFontSize: opts.titleFontSize ?? input.theme.axis.titleFontSize,
+  };
+
+  // For categorical samples we measure against the *actual* category strings
+  // via a band scale — using a numeric placeholder underestimates label width
+  // (numeric ticks are far shorter than e.g. "Almost Certainly") and labels
+  // overflow the canvas. Dedupe in case the sample has repeats.
+  if (stringSample.length > 0) {
+    const uniqueStrings = Array.from(new Set(stringSample));
+    const band = bandScale(uniqueStrings, [0, 100]);
+    return channel === "x"
+      ? bottomAxis(band, enriched as AxisOptions<string>).measure(input.atlas)
+      : leftAxis(band, enriched as AxisOptions<string>).measure(input.atlas);
+  }
+
+  const placeholder = linearScale([lo, hi === lo ? hi + 1 : hi], [0, 100]);
+  return channel === "x"
+    ? bottomAxis(placeholder, enriched).measure(input.atlas)
+    : leftAxis(placeholder, enriched).measure(input.atlas);
+}