@opendata-ai/openchart-engine 6.3.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.3.0",
+    "@opendata-ai/openchart-core": "6.5.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/compile-animation.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Integration tests for animation in the chart compilation pipeline.
+ *
+ * Verifies that animation specs flow through compileChart() correctly:
+ * resolved animation on the layout, animationIndex on marks for value-based
+ * stagger ordering, and breakpoint override behavior.
+ */
+
+import type { ChartSpec } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const barSpec: ChartSpec = {
+  mark: 'bar',
+  data: [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 30 },
+    { name: 'C', value: 20 },
+  ],
+  encoding: {
+    x: { field: 'value', type: 'quantitative' },
+    y: { field: 'name', type: 'nominal' },
+  },
+};
+
+const columnSpec: ChartSpec = {
+  mark: 'bar',
+  data: [
+    { category: 'Q1', revenue: 100 },
+    { category: 'Q2', revenue: 300 },
+    { category: 'Q3', revenue: 200 },
+  ],
+  encoding: {
+    x: { field: 'category', type: 'nominal' },
+    y: { field: 'revenue', type: 'quantitative' },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compileChart with animation', () => {
+  it('includes resolved animation in layout when animation: true', () => {
+    const spec = { ...barSpec, animation: true } as ChartSpec;
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    expect(layout.animation).toBeDefined();
+    expect(layout.animation!.enabled).toBe(true);
+    expect(layout.animation!.duration).toBe(500);
+    expect(layout.animation!.ease).toBe('smooth');
+    expect(layout.animation!.staggerDelay).toBe(80);
+    expect(layout.animation!.staggerOrder).toBe('index');
+    expect(layout.animation!.annotationDelay).toBe(200);
+  });
+
+  it('omits animation from layout when animation is not specified', () => {
+    const layout = compileChart(barSpec, { width: 600, height: 400 });
+    expect(layout.animation).toBeUndefined();
+  });
+
+  it('omits animation from layout when animation is false', () => {
+    const spec = { ...barSpec, animation: false } as ChartSpec;
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.animation).toBeUndefined();
+  });
+
+  it('resolves custom animation config through compilation', () => {
+    const spec = {
+      ...barSpec,
+      animation: {
+        enter: { duration: 800, ease: 'smooth' as const },
+        annotationDelay: 500,
+      },
+    } as ChartSpec;
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    expect(layout.animation).toBeDefined();
+    expect(layout.animation!.duration).toBe(800);
+    expect(layout.animation!.ease).toBe('smooth');
+    expect(layout.animation!.annotationDelay).toBe(500);
+  });
+
+  it('computes animationIndex on marks when stagger order is value', () => {
+    const spec = {
+      ...columnSpec,
+      animation: {
+        enter: { stagger: { order: 'value' as const } },
+      },
+    } as ChartSpec;
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // Should have rect marks for the 3 data points
+    const rectMarks = layout.marks.filter((m) => m.type === 'rect');
+    expect(rectMarks.length).toBe(3);
+
+    // Each mark should have an animationIndex assigned
+    const indices = rectMarks.map(
+      (m) => (m as unknown as { animationIndex?: number }).animationIndex,
+    );
+    for (const idx of indices) {
+      expect(idx).toBeDefined();
+      expect(typeof idx).toBe('number');
+    }
+
+    // Indices should be unique and sequential (0, 1, 2)
+    const sorted = [...indices].sort((a, b) => a! - b!);
+    expect(sorted).toEqual([0, 1, 2]);
+  });
+
+  it('does not assign animationIndex when stagger order is index (default)', () => {
+    const spec = { ...columnSpec, animation: true } as ChartSpec;
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // With staggerOrder='index' (default), animationIndex is not explicitly set
+    const rectMarks = layout.marks.filter((m) => m.type === 'rect');
+    const indices = rectMarks.map(
+      (m) => (m as unknown as { animationIndex?: number }).animationIndex,
+    );
+    // Should all be undefined since value ordering isn't enabled
+    for (const idx of indices) {
+      expect(idx).toBeUndefined();
+    }
+  });
+
+  it('applies breakpoint animation override', () => {
+    // Compact breakpoint is < 400px width
+    const spec = {
+      ...barSpec,
+      animation: true,
+      overrides: {
+        compact: { animation: false },
+      },
+    } as ChartSpec;
+
+    // At compact width (< 400), the breakpoint override should disable animation.
+    // Breakpoint overrides take precedence over spec-level animation (matching
+    // how chrome, labels, legend, and annotation overrides work).
+    const layout = compileChart(spec, { width: 350, height: 400 });
+    expect(layout.animation).toBeUndefined();
+
+    // Test the case where spec-level animation is not set and override provides it
+    const specNoAnim = {
+      ...barSpec,
+      overrides: {
+        compact: { animation: true },
+      },
+    } as ChartSpec;
+    const layoutCompact = compileChart(specNoAnim, { width: 350, height: 400 });
+    expect(layoutCompact.animation).toBeDefined();
+    expect(layoutCompact.animation!.enabled).toBe(true);
+
+    // At full width (> 700), no override applies, so no animation
+    const layoutFull = compileChart(specNoAnim, { width: 800, height: 400 });
+    expect(layoutFull.animation).toBeUndefined();
+  });
+});

package/src/annotations/compute.ts

@@ -363,6 +363,7 @@ function resolveTextAnnotation(
 
   return {
     type: 'text',
+    id: annotation.id,
     label,
     stroke: annotation.stroke,
     fill: annotation.fill,
@@ -447,6 +448,7 @@ function resolveRangeAnnotation(
 
   return {
     type: 'range',
+    id: annotation.id,
     rect,
     label,
     fill: annotation.fill ?? DEFAULT_RANGE_FILL,
@@ -528,6 +530,7 @@ function resolveRefLineAnnotation(
 
   return {
     type: 'refline',
+    id: annotation.id,
     line: { start, end },
     label,
     stroke: annotation.stroke ?? defaultStroke,

package/src/charts/bar/compute.ts

@@ -155,6 +155,8 @@ function computeStackedBars(
         cornerRadius: 0,
         data: row as Record<string, unknown>,
         aria,
+        orient: 'horizontal',
+        stackGroup: category,
       });
 
       cumulativeValue += value;
@@ -214,6 +216,7 @@ function computeSimpleBars(
       cornerRadius: 2,
       data: row as Record<string, unknown>,
       aria,
+      orient: 'horizontal',
     });
   }
 

package/src/charts/column/compute.ts

@@ -183,6 +183,7 @@ function computeSimpleColumns(
       cornerRadius: 2,
       data: row as Record<string, unknown>,
       aria,
+      orient: 'vertical',
     });
   }
 
@@ -233,6 +234,7 @@ function computeColoredColumns(
       cornerRadius: 2,
       data: row as Record<string, unknown>,
       aria,
+      orient: 'vertical',
     });
   }
 
@@ -287,6 +289,8 @@ function computeStackedColumns(
         cornerRadius: 0,
         data: row as Record<string, unknown>,
         aria,
+        orient: 'vertical',
+        stackGroup: category,
       });
 
       cumulativeValue += value;

package/src/compile.ts

@@ -12,6 +12,7 @@
  */
 
 import type {
+  AnimationSpec,
   ChartLayout,
   ChartSpec,
   CompileOptions,
@@ -82,6 +83,7 @@ for (const [type, renderer] of Object.entries(builtinRenderers)) {
   registerChartRenderer(type, renderer);
 }
 
+import { resolveAnimation } from './compiler/animation';
 import type { NormalizedChartSpec, NormalizedTableSpec } from './compiler/types';
 import { compileGraph as compileGraphImpl } from './graphs/compile-graph';
 import type { GraphCompilation } from './graphs/types';
@@ -275,6 +277,12 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     }
   }
 
+  // Resolve animation spec. Breakpoint override wins over base spec (matching
+  // chrome, labels, legend, and annotation override precedence).
+  const rawAnimationSpec = ((overrides?.[breakpoint] as Record<string, unknown> | undefined)
+    ?.animation ?? rawSpec.animation) as AnimationSpec | undefined;
+  const resolvedAnimation = resolveAnimation(rawAnimationSpec);
+
   // Resolve theme: merge spec-level theme with options-level overrides
   const mergedThemeConfig = options.theme
     ? { ...chartSpec.theme, ...options.theme }
@@ -468,6 +476,46 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     chartSpec.data,
   );
 
+  // Assign animationIndex for stagger ordering when animation is enabled
+  // Assign animationIndex for value-based stagger ordering. Skip stacked rects
+  // since they get group-based indices below (avoids wasted work that gets overwritten).
+  if (resolvedAnimation?.enabled && resolvedAnimation.staggerOrder === 'value') {
+    const indexed = marks.map((m, i) => ({ mark: m, idx: i }));
+    indexed.sort((a, b) => {
+      const av = getMarkPrimaryValue(a.mark);
+      const bv = getMarkPrimaryValue(b.mark);
+      return av - bv;
+    });
+    for (let i = 0; i < indexed.length; i++) {
+      const m = indexed[i].mark;
+      if (m.type === 'rect' && (m as RectMark).stackGroup) continue;
+      m.animationIndex = i;
+    }
+  }
+
+  // For stacked bars/columns, assign the same animationIndex to all segments
+  // sharing a stackGroup so they animate as one contiguous bar per category.
+  // Also compute stackPos (segment position within each group: 0, 1, 2...)
+  // so the renderer can chain segment animations sequentially.
+  if (resolvedAnimation?.enabled) {
+    const groupIndexMap = new Map<string, number>();
+    const groupStackPos = new Map<string, number>();
+    let nextGroupIndex = 0;
+    for (const mark of marks) {
+      if (mark.type === 'rect' && (mark as RectMark).stackGroup) {
+        const rect = mark as RectMark;
+        const group = rect.stackGroup!;
+        if (!groupIndexMap.has(group)) {
+          groupIndexMap.set(group, nextGroupIndex++);
+        }
+        rect.animationIndex = groupIndexMap.get(group)!;
+        const pos = groupStackPos.get(group) ?? 0;
+        rect.stackPos = pos;
+        groupStackPos.set(group, pos + 1);
+      }
+    }
+  }
+
   return {
     area: chartArea,
     chrome: dims.chrome,
@@ -490,9 +538,27 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       width: options.width,
       height: options.height,
     },
+    animation: resolvedAnimation,
   };
 }
 
+/** Extract the primary quantitative value from a mark for value-based stagger ordering. */
+function getMarkPrimaryValue(mark: Mark): number {
+  switch (mark.type) {
+    case 'rect':
+      return mark.height; // bar height is the primary value encoding
+    case 'point':
+      return mark.cy; // y position for scatter
+    case 'arc':
+      return mark.endAngle - mark.startAngle; // arc angle extent
+    case 'line':
+    case 'area':
+      return 0; // series marks don't have individual values
+    default:
+      return 0;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer compilation
 // ---------------------------------------------------------------------------

package/src/compiler/__tests__/animation.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Tests for the animation resolver: resolveAnimation() and clampStaggerDelay().
+ *
+ * These are pure functions that normalize the various AnimationSpec shorthand
+ * forms into a fully resolved config with all defaults filled in.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { clampStaggerDelay, resolveAnimation } from '../animation';
+
+// ---------------------------------------------------------------------------
+// resolveAnimation
+// ---------------------------------------------------------------------------
+
+describe('resolveAnimation', () => {
+  it('returns undefined for false', () => {
+    expect(resolveAnimation(false)).toBeUndefined();
+  });
+
+  it('returns undefined for undefined', () => {
+    expect(resolveAnimation(undefined)).toBeUndefined();
+  });
+
+  it('returns defaults for true', () => {
+    const result = resolveAnimation(true);
+    expect(result).toEqual({
+      enabled: true,
+      duration: 500,
+      ease: 'smooth',
+      staggerDelay: 80,
+      staggerOrder: 'index',
+      annotationDelay: 200,
+    });
+  });
+
+  it('resolves AnimationConfig with enter: true', () => {
+    const result = resolveAnimation({ enter: true });
+    expect(result).toBeDefined();
+    expect(result!.enabled).toBe(true);
+    expect(result!.duration).toBe(500);
+    expect(result!.ease).toBe('smooth');
+    expect(result!.staggerDelay).toBe(80);
+    expect(result!.staggerOrder).toBe('index');
+    expect(result!.annotationDelay).toBe(200);
+  });
+
+  it('resolves custom enter config', () => {
+    const result = resolveAnimation({
+      enter: {
+        duration: 800,
+        ease: 'smooth',
+        stagger: { delay: 40, order: 'value' },
+      },
+    });
+    expect(result).toBeDefined();
+    expect(result!.duration).toBe(800);
+    expect(result!.ease).toBe('smooth');
+    expect(result!.staggerDelay).toBe(40);
+    expect(result!.staggerOrder).toBe('value');
+  });
+
+  it('returns undefined when enter is false', () => {
+    expect(resolveAnimation({ enter: false })).toBeUndefined();
+  });
+
+  it('resolves stagger: false to staggerDelay: 0', () => {
+    const result = resolveAnimation({ enter: { stagger: false } });
+    expect(result).toBeDefined();
+    expect(result!.staggerDelay).toBe(0);
+  });
+
+  it('uses custom annotationDelay', () => {
+    const result = resolveAnimation({ enter: true, annotationDelay: 500 });
+    expect(result).toBeDefined();
+    expect(result!.annotationDelay).toBe(500);
+  });
+
+  it('returns undefined when no phase is specified', () => {
+    // Empty config with no enter/update/exit should not produce animation
+    expect(resolveAnimation({})).toBeUndefined();
+  });
+
+  it('preserves default annotationDelay when not overridden', () => {
+    const result = resolveAnimation({ enter: { duration: 1000 } });
+    expect(result!.annotationDelay).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// clampStaggerDelay
+// ---------------------------------------------------------------------------
+
+describe('clampStaggerDelay', () => {
+  it('returns 0 for single element', () => {
+    expect(clampStaggerDelay(30, 1)).toBe(0);
+  });
+
+  it('returns 0 for zero elements', () => {
+    expect(clampStaggerDelay(30, 0)).toBe(0);
+  });
+
+  it('returns delay unchanged for small counts', () => {
+    // 30 * 10 = 300, well under 2000ms cap
+    expect(clampStaggerDelay(30, 10)).toBe(30);
+  });
+
+  it('clamps delay for large counts', () => {
+    // 30 * 200 = 6000 > 2000, so clamp to 2000/200 = 10
+    expect(clampStaggerDelay(30, 200)).toBe(10);
+  });
+
+  it('clamps to cap total at 2000ms', () => {
+    // 50 * 100 = 5000 > 2000, so clamp to 2000/100 = 20
+    expect(clampStaggerDelay(50, 100)).toBe(20);
+  });
+
+  it('does not increase delay when already under the cap', () => {
+    // 5 * 50 = 250 < 2000, keeps at 5
+    expect(clampStaggerDelay(5, 50)).toBe(5);
+  });
+});

package/src/compiler/animation.ts

@@ -0,0 +1,122 @@
+/**
+ * Animation resolver: normalizes AnimationSpec into fully resolved config.
+ *
+ * Handles the shorthand forms:
+ * - true -> { enter: true } -> full defaults
+ * - { enter: { duration: 800 } } -> merge with defaults
+ * - false/undefined -> undefined (no animation)
+ */
+
+import type {
+  AnimationConfig,
+  AnimationEase,
+  AnimationPhaseConfig,
+  AnimationSpec,
+  AnimationStagger,
+  ResolvedAnimation,
+} from '@opendata-ai/openchart-core';
+
+/** Default values for entrance animation. */
+const ENTER_DEFAULTS = {
+  duration: 500,
+  ease: 'smooth' as AnimationEase,
+  staggerDelay: 80,
+  staggerOrder: 'index' as const,
+  annotationDelay: 200,
+} as const;
+
+/** Maximum total stagger time in ms. Prevents 200-bar charts from taking 6s. */
+const MAX_TOTAL_STAGGER_MS = 2000;
+
+/**
+ * Resolve an AnimationSpec into a fully resolved config with all defaults filled.
+ * Returns undefined if animation is disabled (false or omitted).
+ */
+export function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnimation | undefined {
+  if (spec === undefined || spec === false) return undefined;
+
+  // true -> default enter animation
+  if (spec === true) {
+    return {
+      enabled: true,
+      duration: ENTER_DEFAULTS.duration,
+      ease: ENTER_DEFAULTS.ease,
+      staggerDelay: ENTER_DEFAULTS.staggerDelay,
+      staggerOrder: ENTER_DEFAULTS.staggerOrder,
+      annotationDelay: ENTER_DEFAULTS.annotationDelay,
+    };
+  }
+
+  // AnimationConfig object
+  const config = spec as AnimationConfig;
+
+  // If no enter phase specified or enter is false, no animation
+  if (config.enter === false || (config.enter === undefined && !hasAnyPhase(config))) {
+    return undefined;
+  }
+
+  const enterConfig = resolvePhaseConfig(config.enter);
+
+  return {
+    enabled: true,
+    duration: enterConfig.duration,
+    ease: enterConfig.ease,
+    staggerDelay: enterConfig.staggerDelay,
+    staggerOrder: enterConfig.staggerOrder,
+    annotationDelay: config.annotationDelay ?? ENTER_DEFAULTS.annotationDelay,
+  };
+}
+
+/**
+ * Clamp stagger delay so total stagger time doesn't exceed MAX_TOTAL_STAGGER_MS.
+ */
+export function clampStaggerDelay(delay: number, elementCount: number): number {
+  if (elementCount <= 1) return 0;
+  return Math.min(delay, MAX_TOTAL_STAGGER_MS / elementCount);
+}
+
+function hasAnyPhase(config: AnimationConfig): boolean {
+  return config.enter !== undefined || config.update !== undefined || config.exit !== undefined;
+}
+
+interface ResolvedPhase {
+  duration: number;
+  ease: AnimationEase;
+  staggerDelay: number;
+  staggerOrder: 'index' | 'value' | 'reverse';
+}
+
+function resolvePhaseConfig(phase: AnimationPhaseConfig | boolean | undefined): ResolvedPhase {
+  if (phase === undefined || phase === true) {
+    return {
+      duration: ENTER_DEFAULTS.duration,
+      ease: ENTER_DEFAULTS.ease,
+      staggerDelay: ENTER_DEFAULTS.staggerDelay,
+      staggerOrder: ENTER_DEFAULTS.staggerOrder,
+    };
+  }
+
+  const cfg = phase as AnimationPhaseConfig;
+  const stagger = resolveStagger(cfg.stagger);
+
+  return {
+    duration: cfg.duration ?? ENTER_DEFAULTS.duration,
+    ease: cfg.ease ?? ENTER_DEFAULTS.ease,
+    staggerDelay: stagger.delay,
+    staggerOrder: stagger.order,
+  };
+}
+
+function resolveStagger(stagger: AnimationStagger | boolean | undefined): {
+  delay: number;
+  order: 'index' | 'value' | 'reverse';
+} {
+  if (stagger === false) return { delay: 0, order: 'index' };
+  if (stagger === undefined || stagger === true) {
+    return { delay: ENTER_DEFAULTS.staggerDelay, order: ENTER_DEFAULTS.staggerOrder };
+  }
+  return {
+    delay: stagger.delay ?? ENTER_DEFAULTS.staggerDelay,
+    order: stagger.order ?? ENTER_DEFAULTS.staggerOrder,
+  };
+}

package/src/compiler/normalize.ts

@@ -229,6 +229,7 @@ function normalizeTableSpec(spec: TableSpec, _warnings: string[]): NormalizedTab
     stickyFirstColumn: spec.stickyFirstColumn ?? false,
     compact: spec.compact ?? false,
     responsive: spec.responsive ?? true,
+    animation: spec.animation,
   };
 }
 

package/src/compiler/types.ts

@@ -8,6 +8,7 @@
 
 import type {
   AggregateOp,
+  AnimationSpec,
   Annotation,
   AxisConfig,
   ChromeText,
@@ -95,6 +96,7 @@ export interface NormalizedTableSpec {
   stickyFirstColumn: boolean;
   compact: boolean;
   responsive: boolean;
+  animation?: AnimationSpec;
 }
 
 /** A GraphSpec with all optional fields filled with sensible defaults. */

package/src/index.ts

@@ -14,6 +14,12 @@
 
 export { compileChart, compileGraph, compileLayer, compileTable } from './compile';
 
+// ---------------------------------------------------------------------------
+// Animation resolution
+// ---------------------------------------------------------------------------
+
+export { clampStaggerDelay, resolveAnimation } from './compiler/animation';
+
 // ---------------------------------------------------------------------------
 // Graph compilation types
 // ---------------------------------------------------------------------------

package/src/tables/__tests__/compile-table.test.ts

@@ -205,4 +205,32 @@ describe('compileTable', () => {
     const layout = compileTable(baseSpec, { ...baseOptions, darkMode: true });
     expect(layout.theme.isDark).toBe(true);
   });
+
+  it('includes resolved animation when spec has animation: true', () => {
+    const layout = compileTable({ ...baseSpec, animation: true }, baseOptions);
+    expect(layout.animation).toBeDefined();
+    expect(layout.animation!.enabled).toBe(true);
+    expect(layout.animation!.duration).toBe(500);
+    expect(layout.animation!.staggerDelay).toBe(80);
+  });
+
+  it('includes resolved animation with custom config', () => {
+    const layout = compileTable(
+      { ...baseSpec, animation: { enter: { duration: 800, ease: 'snappy' } } },
+      baseOptions,
+    );
+    expect(layout.animation).toBeDefined();
+    expect(layout.animation!.duration).toBe(800);
+    expect(layout.animation!.ease).toBe('snappy');
+  });
+
+  it('does not include animation when spec omits it', () => {
+    const layout = compileTable(baseSpec, baseOptions);
+    expect(layout.animation).toBeUndefined();
+  });
+
+  it('does not include animation when spec has animation: false', () => {
+    const layout = compileTable({ ...baseSpec, animation: false }, baseOptions);
+    expect(layout.animation).toBeUndefined();
+  });
 });

package/src/tables/compile-table.ts

@@ -19,6 +19,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import { computeChrome, estimateTextWidth } from '@opendata-ai/openchart-core';
 
+import { resolveAnimation } from '../compiler/animation';
 import type { NormalizedTableSpec } from '../compiler/types';
 import { computeBarCell, computeColumnMax, computeColumnMin } from './bar-column';
 import { computeCategoryColors } from './category-colors';
@@ -416,5 +417,6 @@ export function compileTableLayout(
       summary: `${resolvedColumns.length} columns, ${totalFiltered} rows`,
     },
     theme,
+    animation: resolveAnimation(spec.animation),
   };
 }