@opendata-ai/openchart-vanilla 8.0.0-rc.2 → 8.0.0-rc.21

package/src/story/index.ts

@@ -1,39 +0,0 @@
-/**
- * `@opendata-ai/openchart-vanilla/story`: scrollytelling story API.
- *
- * A story is a base spec plus an ordered list of steps; each step is a
- * deep-partial spec patch. Scrolling to step N applies patches 0..N to the
- * base and animates the diff -- marks morph when the data-update-transitions
- * gate passes, otherwise the whole chart crossfades so no step ever
- * visibly snaps. See plans/design-evolution/11-scrollytelling.md.
- */
-
-export type { Camera, CameraTarget, ViewBoxSize } from './camera-math';
-export {
-  camerasClose,
-  cameraTransform,
-  damp,
-  dampCamera,
-  FULL_VIEW,
-  fitTarget,
-  interpolateCamera,
-  scrubCamera,
-} from './camera-math';
-export { createChartStory } from './create-chart-story';
-export { crossfadeUpdate } from './crossfade';
-export type { ScrollyFrame, ScrollyFrameGeometry } from './progress-math';
-export { computeProgress, framesEqual, quantizeFrame } from './progress-math';
-export { isDataCameraTarget, resolveCameraTarget } from './resolve-camera-target';
-export type { ScrollDriver, ScrollDriverOptions, ScrollyProgressStore } from './scroll-driver';
-export { createScrollDriver } from './scroll-driver';
-export type { EasingFn, Tween, TweenConfig } from './tween';
-export { clamp01, createTween, easingFns, lerp, storyMotion } from './tween';
-export type {
-  ChartStoryInstance,
-  ChartStoryOptions,
-  StoryCameraStep,
-  StoryDataCameraTarget,
-  StorySpec,
-  StorySpecPatch,
-  StoryStep,
-} from './types';

package/src/story/progress-math.ts

@@ -1,85 +0,0 @@
-import { clamp01 } from './tween';
-
-/**
- * Pure math for continuous scrollytelling progress. The `ScrollDriver`
- * measures DOM rects and feeds them here. Ported from
- * opendata/shared/lib/scrolly/progress-math.ts.
- */
-
-export interface ScrollyFrame {
-  /** Geometric active step; -1 while the trigger line is above step 0 */
-  step: number;
-  /** 0..1 progress of the trigger line through the active step's span */
-  stepProgress: number;
-  /** 0..1 traversal from first step top to last step bottom */
-  progress: number;
-  direction: 'down' | 'up';
-}
-
-export type ScrollyFrameGeometry = Omit<ScrollyFrame, 'direction'>;
-
-/**
- * Compute the geometric frame from viewport-relative step tops.
- *
- * @param tops viewport-relative step top offsets, ordered by step index
- * @param lastBottom viewport-relative bottom of the final step
- * @param triggerY the trigger line's viewport y (innerHeight * triggerPosition)
- */
-export function computeProgress(
-  tops: number[],
-  lastBottom: number,
-  triggerY: number,
-): ScrollyFrameGeometry {
-  const n = tops.length;
-  if (n === 0 || triggerY < tops[0]!) {
-    return { step: -1, stepProgress: 0, progress: 0 };
-  }
-
-  let step = n - 1;
-  for (let i = 0; i < n - 1; i++) {
-    if (triggerY < tops[i + 1]!) {
-      step = i;
-      break;
-    }
-  }
-
-  const stepTop = tops[step]!;
-  const spanEnd = step < n - 1 ? tops[step + 1]! : lastBottom;
-  const span = Math.max(spanEnd - stepTop, 1);
-  const firstTop = tops[0]!;
-
-  return {
-    step,
-    stepProgress: clamp01((triggerY - stepTop) / span),
-    progress: clamp01((triggerY - firstTop) / Math.max(lastBottom - firstTop, 1)),
-  };
-}
-
-/**
- * Reduced-motion variant: no scrubbing. `stepProgress` pins to 0 and overall
- * progress quantizes to the step's start fraction, so consumers see discrete
- * snaps only.
- */
-export function quantizeFrame(
-  frame: ScrollyFrameGeometry,
-  totalSteps: number,
-): ScrollyFrameGeometry {
-  if (frame.step < 0 || totalSteps <= 0) {
-    return { step: frame.step, stepProgress: 0, progress: 0 };
-  }
-  return {
-    step: frame.step,
-    stepProgress: 0,
-    progress: clamp01(frame.step / totalSteps),
-  };
-}
-
-export function framesEqual(a: ScrollyFrame | null, b: ScrollyFrame): boolean {
-  return (
-    a !== null &&
-    a.step === b.step &&
-    a.stepProgress === b.stepProgress &&
-    a.progress === b.progress &&
-    a.direction === b.direction
-  );
-}

package/src/story/resolve-camera-target.ts

@@ -1,119 +0,0 @@
-/**
- * Resolves data-coordinate camera targets (`{ x: [a, b], y: [c, d] }`) to
- * viewBox-space `CameraTarget` rects using the compiled chart's axis ticks.
- *
- * There is no raw d3 scale on `ChartLayout` (by design -- the compiled
- * layout is the public surface, not engine internals), so resolution works
- * off `AxisTick[]`, which pairs each tick's raw data `value` with its pixel
- * `position`:
- *   - Exact tick match (ordinal/categorical values, or a quantitative value
- *     that happens to land on a tick): use that tick's position directly.
- *   - Otherwise linear interpolation between the two nearest ticks by data
- *     value. Works for quantitative and temporal axes (temporal values are
- *     compared as timestamps). Ordinal axes with no exact match have no
- *     well-ordered "between" and fall back to the nearest tick.
- */
-
-import type { AxisLayout, AxisTick, ChartLayout } from '@opendata-ai/openchart-core';
-import type { CameraTarget } from './camera-math';
-import type { StoryDataCameraTarget } from './types';
-
-const DEFAULT_PADDING = 24;
-
-/** Coerce a tick value (string, number, Date, ISO string) to a comparable number. */
-function toComparable(value: unknown): number | null {
-  if (typeof value === 'number') return value;
-  if (value instanceof Date) return value.getTime();
-  if (typeof value === 'string') {
-    const asDate = Date.parse(value);
-    if (!Number.isNaN(asDate)) return asDate;
-  }
-  return null;
-}
-
-/** Resolve one data value to a pixel position along an axis, or null if unresolvable. */
-function resolveOnAxis(axis: AxisLayout, target: unknown): number | null {
-  const ticks = axis.ticks;
-  if (ticks.length === 0) return null;
-
-  const exact = ticks.find((t) => t.value === target);
-  if (exact) return exact.position;
-
-  const targetNum = toComparable(target);
-  if (targetNum === null) return null;
-
-  // Ticks with comparable numeric values, sorted by data value.
-  const numeric: Array<{ tick: AxisTick; value: number }> = [];
-  for (const tick of ticks) {
-    const v = toComparable(tick.value);
-    if (v !== null) numeric.push({ tick, value: v });
-  }
-  if (numeric.length === 0) return null;
-  numeric.sort((a, b) => a.value - b.value);
-
-  if (targetNum <= numeric[0]!.value) return numeric[0]!.tick.position;
-  const last = numeric.at(-1)!;
-  if (targetNum >= last.value) return last.tick.position;
-
-  for (let i = 0; i < numeric.length - 1; i++) {
-    const lo = numeric[i]!;
-    const hi = numeric[i + 1]!;
-    if (targetNum >= lo.value && targetNum <= hi.value) {
-      const span = hi.value - lo.value;
-      const t = span === 0 ? 0 : (targetNum - lo.value) / span;
-      return lo.tick.position + t * (hi.tick.position - lo.tick.position);
-    }
-  }
-  return null;
-}
-
-/**
- * Resolve a data-coordinate camera target to viewBox space. Falls back to
- * the full chart area (padded) for axes that are missing or unresolvable,
- * so a malformed target degrades to "camera does nothing" rather than
- * throwing mid-scroll.
- */
-export function resolveCameraTarget(
-  layout: ChartLayout,
-  target: StoryDataCameraTarget,
-): CameraTarget {
-  const area = layout.area;
-  const padding = target.padding ?? DEFAULT_PADDING;
-
-  let x1 = area.x;
-  let x2 = area.x + area.width;
-  if (target.x && layout.axes.x) {
-    const a = resolveOnAxis(layout.axes.x, target.x[0]);
-    const b = resolveOnAxis(layout.axes.x, target.x[1]);
-    if (a !== null && b !== null) {
-      x1 = Math.min(a, b);
-      x2 = Math.max(a, b);
-    }
-  }
-
-  let y1 = area.y;
-  let y2 = area.y + area.height;
-  if (target.y && layout.axes.y) {
-    const a = resolveOnAxis(layout.axes.y, target.y[0]);
-    const b = resolveOnAxis(layout.axes.y, target.y[1]);
-    if (a !== null && b !== null) {
-      y1 = Math.min(a, b);
-      y2 = Math.max(a, b);
-    }
-  }
-
-  return {
-    x: x1,
-    y: y1,
-    width: Math.max(x2 - x1, 1),
-    height: Math.max(y2 - y1, 1),
-    padding,
-  };
-}
-
-/** Type guard: a camera step given in data coordinates vs. raw viewBox `CameraTarget`. */
-export function isDataCameraTarget(
-  value: StoryDataCameraTarget | CameraTarget,
-): value is StoryDataCameraTarget {
-  return !('width' in value) && !('height' in value);
-}

package/src/story/scroll-driver.ts

@@ -1,206 +0,0 @@
-/**
- * Framework-agnostic scroll-step driver: element registry + rAF-throttled
- * scroll handler + subscription store. Ported from the React
- * `use-scroll-steps` hook in opendata/shared; the store design (60fps
- * frames as subscriptions, never framework state) carries over unchanged
- * because vanilla, React, Vue, and Svelte all want the same contract.
- *
- * Measurement is lazy: with zero subscribers the scroll handler does no
- * rect reads.
- */
-
-import { computeProgress, framesEqual, quantizeFrame, type ScrollyFrame } from './progress-math';
-
-export interface ScrollyProgressStore {
-  /** Latest frame; `{step: -1, ...}` sentinel before any measurement */
-  get(): ScrollyFrame;
-  /** Emits the current frame immediately on subscribe, then on every change */
-  subscribe(cb: (frame: ScrollyFrame) => void): () => void;
-}
-
-export interface ScrollDriverOptions {
-  /** Fraction of viewport height where the trigger line sits. Default 0.4 */
-  triggerPosition?: number;
-}
-
-export interface ScrollDriver {
-  /** Register the scrolling container that wraps all steps. */
-  setContainer(el: HTMLElement | null): void;
-  /** Register a step element by index. Pass `null` to unregister. */
-  registerStep(index: number, el: HTMLElement | null): void;
-  /** Continuous progress as a subscription store. */
-  progress: ScrollyProgressStore;
-  /** Scroll a step into view (center). Honors reduced motion. */
-  scrollToStep(index: number): void;
-  /** Force a re-measurement (e.g. after layout changes). */
-  measure(): void;
-  /** Tear down scroll/resize listeners and the reduced-motion media query. */
-  destroy(): void;
-}
-
-const SENTINEL_FRAME: ScrollyFrame = {
-  step: -1,
-  stepProgress: 0,
-  progress: 0,
-  direction: 'down',
-};
-
-/**
- * Create a scroll-step driver. Framework wrappers (React/Vue/Svelte hooks)
- * are thin adapters over this: they own component lifecycle, this owns the
- * measurement/subscription machinery.
- */
-export function createScrollDriver(options: ScrollDriverOptions = {}): ScrollDriver {
-  const triggerPosition = options.triggerPosition ?? 0.4;
-
-  let container: HTMLElement | null = null;
-  const steps = new Map<number, HTMLElement>();
-  const subscribers = new Set<(frame: ScrollyFrame) => void>();
-
-  let frame: ScrollyFrame = SENTINEL_FRAME;
-  let direction: 'down' | 'up' = 'down';
-  // Direction is tracked from the container's viewport-relative position, NOT
-  // window.scrollY: in a host that scrolls an inner container rather than the
-  // page (Ladle, modals, dashboard panes, most app shells) window.scrollY is
-  // pinned at 0 and would report no movement. The container's rect top moves
-  // whenever ANY ancestor scrolls, so it works in both cases.
-  let lastTop: number | null = null;
-  let reducedMotion = false;
-  let ticking = false;
-
-  const measureAndEmit = () => {
-    if (subscribers.size === 0) return;
-    if (!container || steps.size === 0) return;
-    if (typeof window === 'undefined') return;
-
-    const viewportH = window.innerHeight;
-    const containerRect = container.getBoundingClientRect();
-    // Skip when the story is more than a viewport away in either direction.
-    if (containerRect.bottom < -viewportH || containerRect.top > viewportH * 2) return;
-
-    const count = steps.size;
-    const tops: number[] = new Array(count);
-    let lastBottom = 0;
-    for (let i = 0; i < count; i++) {
-      const el = steps.get(i);
-      if (!el) return; // sparse registration mid-mount; wait for the next tick
-      const rect = el.getBoundingClientRect();
-      tops[i] = rect.top;
-      if (i === count - 1) lastBottom = rect.bottom;
-    }
-
-    const triggerY = viewportH * triggerPosition;
-    let geometry = computeProgress(tops, lastBottom, triggerY);
-    if (reducedMotion) {
-      geometry = quantizeFrame(geometry, count);
-    }
-
-    const next: ScrollyFrame = { ...geometry, direction };
-    if (framesEqual(frame, next)) return;
-    frame = next;
-    for (const cb of subscribers) cb(frame);
-  };
-
-  const onScroll = () => {
-    if (ticking) return;
-    ticking = true;
-    requestAnimationFrame(() => {
-      // The container rising up the viewport (top decreasing) means the reader
-      // is moving down through the story.
-      const currentTop = container?.getBoundingClientRect().top ?? null;
-      if (currentTop !== null && lastTop !== null) {
-        const delta = lastTop - currentTop;
-        if (delta > 5 || delta < -5) {
-          direction = delta > 5 ? 'down' : 'up';
-        }
-      }
-      lastTop = currentTop;
-      ticking = false;
-      measureAndEmit();
-    });
-  };
-
-  let mediaQuery: MediaQueryList | null = null;
-  const onReducedMotionChange = (e: MediaQueryListEvent) => {
-    reducedMotion = e.matches;
-    measureAndEmit();
-  };
-
-  if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
-    mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
-    reducedMotion = mediaQuery.matches;
-    mediaQuery.addEventListener('change', onReducedMotionChange);
-  }
-
-  if (typeof window !== 'undefined') {
-    // Capture phase on the document, not just `window` scroll. Scroll events do
-    // not bubble, so a window listener ONLY fires when the page itself scrolls.
-    // Any host that scrolls an inner container instead — Ladle (which sets
-    // `body { overflow: hidden }`), modals, dashboard panes, most app shells —
-    // would never notify the driver and the story sat frozen on step 0.
-    // Capturing on the document sees scroll from any ancestor, and the
-    // measurement below is already viewport-relative (getBoundingClientRect vs
-    // innerHeight), so it needs no other change to work in both layouts.
-    document.addEventListener('scroll', onScroll, { passive: true, capture: true });
-    window.addEventListener('resize', onScroll, { passive: true });
-  }
-
-  const progress: ScrollyProgressStore = {
-    get: () => frame,
-    subscribe: (cb) => {
-      // Refresh `frame` from current geometry BEFORE registering `cb`, so the
-      // measure pass notifies only existing subscribers. Then hand the new
-      // subscriber the current frame exactly once. Registering after the
-      // measure avoids the double-invoke that happened when measureAndEmit
-      // changed the frame (looping over cb) and the explicit cb(frame) fired again.
-      measureAndEmit();
-      subscribers.add(cb);
-      cb(frame);
-      return () => {
-        subscribers.delete(cb);
-      };
-    },
-  };
-
-  return {
-    setContainer(el) {
-      container = el;
-      // Seed the direction baseline so the first scroll compares against a real
-      // position rather than reporting a spurious jump from null.
-      lastTop = el?.getBoundingClientRect().top ?? null;
-      measureAndEmit();
-    },
-    registerStep(index, el) {
-      if (el) {
-        steps.set(index, el);
-      } else {
-        steps.delete(index);
-      }
-      measureAndEmit();
-    },
-    progress,
-    scrollToStep(index) {
-      const el = steps.get(index);
-      if (!el) return;
-      el.scrollIntoView({
-        block: 'center',
-        behavior: reducedMotion ? 'auto' : 'smooth',
-      });
-    },
-    measure() {
-      measureAndEmit();
-    },
-    destroy() {
-      if (typeof window !== 'undefined') {
-        // `capture: true` must match the addEventListener call or the listener
-        // is not removed.
-        document.removeEventListener('scroll', onScroll, { capture: true });
-        window.removeEventListener('resize', onScroll);
-      }
-      mediaQuery?.removeEventListener('change', onReducedMotionChange);
-      subscribers.clear();
-      steps.clear();
-      container = null;
-    },
-  };
-}

package/src/story/story-camera.ts

@@ -1,49 +0,0 @@
-/**
- * Applies the scrollytelling camera transform to a mounted chart's marks
- * group (`[data-oc-marks-group]`, stamped by svg-renderer.ts). Re-finds the
- * group on every apply since `ChartInstance.update()` tears down and
- * rebuilds the SVG on every render -- the previous group reference goes
- * stale the instant a step patch triggers a re-render.
- *
- * DO NOT USE THIS TO "ZOOM IN" ON A CARTESIAN CHART.
- *
- * This is a geometric magnification of the marks group and nothing else. The
- * axes, gridlines, and annotations are siblings of that group, so they do not
- * move: zoom a line chart to 2010-2020 and the lines blow up while the x-axis
- * still reads 2000-2020 and every annotation drifts off its data point. Stroke
- * widths scale with the transform too, so the lines visibly fatten. The chart
- * ends up misrepresenting its own axis.
- *
- * To zoom a cartesian chart, narrow the scale domain instead and let the engine
- * recompile:
- *
- *   { spec: { encoding: { x: { scale: { domain: ['2019', ...], clip: true } } } } }
- *
- * That relabels the axis, re-anchors annotations, keeps stroke widths constant,
- * and still morphs (the field identity is unchanged, so `canTransitionSpecShape`
- * passes and the marks FLIP-tween into the new scale).
- *
- * The camera remains useful where there is no axis to contradict -- graph and
- * other non-cartesian views, where magnifying the geometry IS the intent.
- */
-
-import { type Camera, cameraTransform, FULL_VIEW, type ViewBoxSize } from './camera-math';
-
-/** Read the current SVG's viewBox as a `ViewBoxSize`, or null if not yet rendered. */
-export function readViewBox(container: HTMLElement): ViewBoxSize | null {
-  const svg = container.querySelector('svg');
-  const viewBoxAttr = svg?.getAttribute('viewBox');
-  if (!viewBoxAttr) return null;
-  const parts = viewBoxAttr.split(/\s+/).map(Number);
-  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return null;
-  return { width: parts[2]!, height: parts[3]! };
-}
-
-/** Apply a camera transform to the current marks group, if the chart is rendered. */
-export function applyStoryCamera(container: HTMLElement, camera: Camera, vb: ViewBoxSize): void {
-  const marksGroup = container.querySelector('[data-oc-marks-group]');
-  if (!marksGroup) return;
-  marksGroup.setAttribute('transform', cameraTransform(camera, vb));
-}
-
-export { FULL_VIEW };

package/src/story/tween.ts

@@ -1,112 +0,0 @@
-/**
- * Numeric rAF tweening for scrollytelling story steps.
- *
- * Owns imperative numeric interpolation: the story driver and camera math
- * mutate scalar/vector values per frame using these primitives instead of
- * hand-rolling rAF loops. Ported from opendata/shared/lib/tween.ts.
- *
- * Everything here is SSR-safe: no `window`/`performance` access at module
- * scope. Callers are expected to invoke these client-side.
- */
-
-export const clamp01 = (t: number): number => Math.min(1, Math.max(0, t));
-
-export const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
-
-export type EasingFn = (t: number) => number;
-
-export const easingFns = {
-  linear: (t: number) => t,
-  easeOutCubic: (t: number) => 1 - (1 - t) ** 3,
-  easeInOutCubic: (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - (-2 * t + 2) ** 3 / 2),
-  easeOutQuint: (t: number) => 1 - (1 - t) ** 5,
-} as const satisfies Record<string, EasingFn>;
-
-/**
- * Duration tokens (ms) for story state changes. Use these instead of
- * arbitrary numbers so all stories share one timing scale.
- */
-export const storyMotion = {
-  /** Small opacity/emphasis shifts */
-  fast: 300,
-  /** Step state transitions */
-  base: 500,
-  /** Whole-chart crossfade fallback (steps outside the morph gate) */
-  crossfade: 400,
-  /** Step-mode camera transitions */
-  camera: 600,
-  /** Scrub-mode camera damping time constant */
-  cameraTau: 100,
-} as const;
-
-export interface TweenConfig<T> {
-  initial: T;
-  lerp: (a: T, b: T, t: number) => T;
-  /** Default `storyMotion.base` */
-  duration?: number;
-  /** Default `easingFns.easeOutCubic` */
-  ease?: EasingFn;
-  onFrame: (value: T) => void;
-}
-
-export interface Tween<T> {
-  /**
-   * Retarget the tween. If a tween is mid-flight, the new tween starts FROM
-   * THE LIVE INTERPOLATED VALUE, not the previous target -- fast retargeting
-   * never jumps. `snap: true` applies the target synchronously with no rAF.
-   */
-  to: (target: T, opts?: { snap?: boolean }) => void;
-  get: () => T;
-  cancel: () => void;
-}
-
-/**
- * Retargetable tween over an arbitrary shape T.
- */
-export function createTween<T>(config: TweenConfig<T>): Tween<T> {
-  const {
-    lerp: lerpT,
-    duration = storyMotion.base,
-    ease = easingFns.easeOutCubic,
-    onFrame,
-  } = config;
-
-  let current = config.initial;
-  let rafId = 0;
-  let running = false;
-
-  const stop = () => {
-    if (running) {
-      cancelAnimationFrame(rafId);
-      running = false;
-    }
-  };
-
-  const to = (target: T, opts?: { snap?: boolean }) => {
-    stop();
-    if (opts?.snap || duration <= 0) {
-      current = target;
-      onFrame(current);
-      return;
-    }
-
-    const from = current;
-    const start = performance.now();
-    running = true;
-
-    const tick = (now: number) => {
-      const t = clamp01((now - start) / duration);
-      current = lerpT(from, target, ease(t));
-      onFrame(current);
-      if (t < 1) {
-        rafId = requestAnimationFrame(tick);
-      } else {
-        running = false;
-      }
-    };
-
-    rafId = requestAnimationFrame(tick);
-  };
-
-  return { to, get: () => current, cancel: stop };
-}

package/src/story/types.ts

@@ -1,76 +0,0 @@
-import type {
-  ChartSpec,
-  DataRow,
-  GraphSpec,
-  LayerSpec,
-  MapSpec,
-} from '@opendata-ai/openchart-core';
-import type { CameraTarget } from './camera-math';
-
-/** A spec a story can drive: same union `ChartInstance.update()` accepts. */
-export type StorySpec<TData extends DataRow = DataRow> =
-  | ChartSpec<TData>
-  | LayerSpec<TData>
-  | GraphSpec
-  | MapSpec;
-
-/** Deep-partial patch applied onto the accumulated spec at each step. */
-export type StorySpecPatch = Record<string, unknown>;
-
-/**
- * One step in a story. Patches are cumulative: step N's effective spec is
- * the base spec with patches 0..N applied in order.
- */
-export interface StoryStep {
-  /** Deep-partial patch merged onto the running spec. Omit for a no-op step. */
-  spec?: StorySpecPatch;
-  /**
-   * Emphasis sugar: sets `encoding.color.highlight`. Equivalent to
-   * `spec: { encoding: { color: { highlight: [...] } } }` but doesn't
-   * require the caller to know the color field is nested under `encoding`.
-   * Pass `null` to clear a highlight set by an earlier step.
-   */
-  highlight?: string[] | null;
-  /**
-   * Pan/zoom the camera to a data-coordinate region (resolved via the
-   * chart's compiled scales) or a raw viewBox-space `CameraTarget`. Pass
-   * `null`/omit to return to the full viewBox.
-   */
-  camera?: StoryCameraStep | null;
-}
-
-/** Data-coordinate camera target: resolved to viewBox space via the chart's scales. */
-export interface StoryDataCameraTarget {
-  /** x-domain range to frame, in data units (or category names for ordinal scales). */
-  x?: [unknown, unknown];
-  /** y-domain range to frame, in data units (or category names for ordinal scales). */
-  y?: [unknown, unknown];
-  /** ViewBox units of padding added around the resolved rect. Default 24. */
-  padding?: number;
-}
-
-export type StoryCameraStep = StoryDataCameraTarget | CameraTarget;
-
-export interface ChartStoryOptions<TData extends DataRow = DataRow> {
-  spec: StorySpec<TData>;
-  steps: StoryStep[];
-  /** Fraction of viewport height where the scroll trigger line sits. Default 0.4. */
-  triggerPosition?: number;
-  /** Camera driving mode. Step mode (default) eases on step change; scrub follows scroll continuously. */
-  cameraMode?: 'step' | 'scrub';
-}
-
-export interface ChartStoryInstance {
-  /** Jump directly to a step index, applying patches 0..n and animating the diff. */
-  goTo(index: number): void;
-  /** Register a step element so the built-in scroll driver advances the story on scroll. */
-  registerStep(index: number, el: HTMLElement | null): (el: HTMLElement | null) => void;
-  /** Register the scrolling container that wraps all step elements. */
-  setContainer(el: HTMLElement | null): void;
-  /** Current step index. -1 before any step has activated. */
-  readonly currentStep: number;
-  /** Total number of steps. */
-  readonly totalSteps: number;
-  /** Tear down the scroll driver, camera, and underlying chart instance. */
-  destroy(): void;
-}