@opendata-ai/openchart-engine 7.7.0 → 7.9.0

package/package.json

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

package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap

@@ -224,6 +224,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
       },
       "fill": "#06b6d4",
       "height": 57.45223880597016,
+      "key": "|A",
       "label": {
         "connector": undefined,
         "style": {
@@ -258,6 +259,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
       },
       "fill": "#06b6d4",
       "height": 57.45223880597016,
+      "key": "|B",
       "label": {
         "connector": undefined,
         "style": {
@@ -292,6 +294,7 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
       },
       "fill": "#06b6d4",
       "height": 57.45223880597016,
+      "key": "|C",
       "label": {
         "connector": undefined,
         "style": {
@@ -1037,8 +1040,14 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
           "y": 105.2,
         },
       ],
+      "interpolate": "monotone",
+      "key": "US",
       "opacity": undefined,
       "path": "M47,334.25L651.761,105.2",
+      "pointKeys": [
+        "2020-01-01",
+        "2021-01-01",
+      ],
       "points": [
         {
           "x": 47,
@@ -1129,8 +1138,14 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
           "y": 143.375,
         },
       ],
+      "interpolate": "monotone",
+      "key": "UK",
       "opacity": undefined,
       "path": "M47,296.075L651.761,143.375",
+      "pointKeys": [
+        "2020-01-01",
+        "2021-01-01",
+      ],
       "points": [
         {
           "x": 47,
@@ -1221,8 +1236,14 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
           "y": 242.62999999999997,
         },
       ],
+      "interpolate": "monotone",
+      "key": "FR",
       "opacity": undefined,
       "path": "M47,349.52L651.761,242.63",
+      "pointKeys": [
+        "2020-01-01",
+        "2021-01-01",
+      ],
       "points": [
         {
           "x": 47,
@@ -1313,8 +1334,14 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
           "y": 196.82,
         },
       ],
+      "interpolate": "monotone",
+      "key": "DE",
       "opacity": undefined,
       "path": "M47,318.98L651.761,196.82",
+      "pointKeys": [
+        "2020-01-01",
+        "2021-01-01",
+      ],
       "points": [
         {
           "x": 47,
@@ -1804,6 +1831,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
         "type": "linear",
       },
       "height": 101.27142857142857,
+      "key": "|A",
       "label": {
         "connector": undefined,
         "style": {
@@ -1849,6 +1877,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
         "type": "linear",
       },
       "height": 185.6642857142857,
+      "key": "|B",
       "label": {
         "connector": undefined,
         "style": {
@@ -1894,6 +1923,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
         "type": "linear",
       },
       "height": 236.29999999999998,
+      "key": "|C",
       "label": {
         "connector": undefined,
         "style": {
@@ -1939,6 +1969,7 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
         "type": "linear",
       },
       "height": 151.90714285714287,
+      "key": "|D",
       "label": {
         "connector": undefined,
         "style": {

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

@@ -50,11 +50,11 @@ describe('compileChart with animation', () => {
     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!.enter).toBeDefined();
+    expect(layout.animation!.enter!.duration).toBe(500);
+    expect(layout.animation!.enter!.ease).toBe('smooth');
+    expect(layout.animation!.enter!.staggerDelay).toBe(80);
+    expect(layout.animation!.enter!.staggerOrder).toBe('index');
     expect(layout.animation!.annotationDelay).toBe(200);
   });
 
@@ -80,8 +80,8 @@ describe('compileChart with animation', () => {
     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!.enter!.duration).toBe(800);
+    expect(layout.animation!.enter!.ease).toBe('smooth');
     expect(layout.animation!.annotationDelay).toBe(500);
   });
 
@@ -152,7 +152,7 @@ describe('compileChart with animation', () => {
     } as ChartSpec;
     const layoutCompact = compileChart(specNoAnim, { width: 350, height: 400 });
     expect(layoutCompact.animation).toBeDefined();
-    expect(layoutCompact.animation!.enabled).toBe(true);
+    expect(layoutCompact.animation!.enter).toBeDefined();
 
     // At full width (> 700), no override applies, so no animation
     const layoutFull = compileChart(specNoAnim, { width: 800, height: 400 });

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

@@ -943,7 +943,7 @@ describe('compileChart', () => {
     };
     const layout = compileChart(spec, { width: 320, height: 200 });
     expect(layout.display).toBe('sparkline');
-    expect(layout.animation?.enabled).toBe(true);
+    expect(layout.animation?.enter).toBeDefined();
   });
 
   it('breakpoint chrome wins when top-level is sparkline', () => {
@@ -1012,8 +1012,8 @@ describe('compileChart', () => {
       { ...lineSpec, display: 'sparkline' as const, animation: true },
       { width: 400, height: 80 },
     );
-    expect(layout.animation?.enabled).toBe(true);
-    expect(layout.animation?.duration).toBe(1100);
+    expect(layout.animation?.enter).toBeDefined();
+    expect(layout.animation?.enter?.duration).toBe(1100);
   });
 
   it('sparkline + animation: { enter: { duration: 500 } } respects user duration', () => {
@@ -1025,12 +1025,12 @@ describe('compileChart', () => {
       },
       { width: 400, height: 80 },
     );
-    expect(layout.animation?.duration).toBe(500);
+    expect(layout.animation?.enter?.duration).toBe(500);
   });
 
   it('full mode + animation: true uses default 500ms (sparkline bump does not leak)', () => {
     const layout = compileChart({ ...lineSpec, animation: true }, { width: 600, height: 400 });
-    expect(layout.animation?.duration).toBe(500);
+    expect(layout.animation?.enter?.duration).toBe(500);
   });
 
   // ---------------------------------------------------------------------------

package/src/__tests__/mark-keys.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Integration tests for mark key stamping across chart types.
+ *
+ * Verifies that compileChart() stamps stable `key` fields on marks
+ * for data-update transitions. Each chart type has its own keying
+ * strategy; these tests verify the end-to-end pipeline.
+ */
+
+import type { ChartSpec } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../compile';
+
+const dims = { width: 600, height: 400 };
+
+// ---------------------------------------------------------------------------
+// Column chart keys
+// ---------------------------------------------------------------------------
+
+describe('column chart mark keys', () => {
+  it('stamps unique keys on simple column marks', () => {
+    const spec: ChartSpec = {
+      mark: 'bar',
+      data: [
+        { category: 'A', value: 10 },
+        { category: 'B', value: 20 },
+        { category: 'C', value: 30 },
+      ],
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const rects = layout.marks.filter((m) => m.type === 'rect');
+    expect(rects.length).toBe(3);
+
+    for (const m of rects) {
+      expect((m as { key?: string }).key).toBeDefined();
+    }
+
+    const keys = rects.map((m) => (m as { key?: string }).key);
+    expect(new Set(keys).size).toBe(3);
+  });
+
+  it('deduplicates keys for duplicate category values', () => {
+    const spec: ChartSpec = {
+      mark: 'bar',
+      data: [
+        { category: 'A', value: 10 },
+        { category: 'A', value: 20 },
+        { category: 'B', value: 30 },
+      ],
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const rects = layout.marks.filter((m) => m.type === 'rect');
+    const keys = rects.map((m) => (m as { key?: string }).key);
+    // All keys must be unique even with duplicate categories
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('stamps keys on grouped columns', () => {
+    const spec: ChartSpec = {
+      mark: 'bar',
+      data: [
+        { category: 'Q1', series: 'Revenue', value: 100 },
+        { category: 'Q1', series: 'Cost', value: 60 },
+        { category: 'Q2', series: 'Revenue', value: 150 },
+        { category: 'Q2', series: 'Cost', value: 90 },
+      ],
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'series', type: 'nominal' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const rects = layout.marks.filter((m) => m.type === 'rect');
+    expect(rects.length).toBeGreaterThanOrEqual(4);
+
+    const keys = rects.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bar chart keys
+// ---------------------------------------------------------------------------
+
+describe('bar chart mark keys', () => {
+  it('stamps unique keys on horizontal bar marks', () => {
+    const spec: ChartSpec = {
+      mark: 'bar',
+      data: [
+        { name: 'Alpha', value: 10 },
+        { name: 'Beta', value: 30 },
+        { name: 'Gamma', value: 20 },
+      ],
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'name', type: 'nominal' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const rects = layout.marks.filter((m) => m.type === 'rect');
+    const keys = rects.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Line chart keys
+// ---------------------------------------------------------------------------
+
+describe('line chart mark keys', () => {
+  it('stamps key on line marks for multi-series', () => {
+    const spec: ChartSpec = {
+      mark: 'line',
+      data: [
+        { date: '2020-01-01', value: 10, country: 'US' },
+        { date: '2021-01-01', value: 40, country: 'US' },
+        { date: '2020-01-01', value: 15, country: 'UK' },
+        { date: '2021-01-01', value: 35, country: 'UK' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const lines = layout.marks.filter((m) => m.type === 'line');
+    expect(lines.length).toBe(2);
+
+    const keys = lines.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(2);
+  });
+
+  it('stamps pointKeys on line marks with temporal x', () => {
+    const spec: ChartSpec = {
+      mark: 'line',
+      data: [
+        { date: '2020-01-01', value: 10 },
+        { date: '2021-01-01', value: 40 },
+        { date: '2022-01-01', value: 25 },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const lines = layout.marks.filter((m) => m.type === 'line');
+    expect(lines.length).toBe(1);
+
+    const line = lines[0] as { pointKeys?: string[] };
+    expect(line.pointKeys).toBeDefined();
+    expect(line.pointKeys!.length).toBe(3);
+
+    // Each point key should be a unique, defined string
+    for (const pk of line.pointKeys!) {
+      expect(pk).toBeDefined();
+      expect(typeof pk).toBe('string');
+    }
+    expect(new Set(line.pointKeys!).size).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scatter chart keys
+// ---------------------------------------------------------------------------
+
+describe('scatter chart mark keys', () => {
+  it('stamps keys on scatter point marks', () => {
+    const spec: ChartSpec = {
+      mark: 'point',
+      data: [
+        { x: 10, y: 20, label: 'A' },
+        { x: 30, y: 40, label: 'B' },
+        { x: 50, y: 60, label: 'C' },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const points = layout.marks.filter((m) => m.type === 'point');
+    expect(points.length).toBe(3);
+
+    const keys = points.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(3);
+  });
+
+  it('uses encoding.key field when specified', () => {
+    const spec: ChartSpec = {
+      mark: 'point',
+      data: [
+        { x: 10, y: 20, id: 'item-1' },
+        { x: 30, y: 40, id: 'item-2' },
+        { x: 50, y: 60, id: 'item-3' },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' },
+        y: { field: 'y', type: 'quantitative' },
+        key: { field: 'id' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const points = layout.marks.filter((m) => m.type === 'point');
+    const keys = points.map((m) => (m as { key?: string }).key);
+
+    expect(keys).toContain('item-1');
+    expect(keys).toContain('item-2');
+    expect(keys).toContain('item-3');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Pie chart keys
+// ---------------------------------------------------------------------------
+
+describe('pie chart mark keys', () => {
+  it('stamps keys on arc marks', () => {
+    const spec: ChartSpec = {
+      mark: 'arc',
+      data: [
+        { category: 'Desktop', share: 60 },
+        { category: 'Mobile', share: 30 },
+        { category: 'Tablet', share: 10 },
+      ],
+      encoding: {
+        y: { field: 'share', type: 'quantitative' },
+        color: { field: 'category', type: 'nominal' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const arcs = layout.marks.filter((m) => m.type === 'arc');
+    expect(arcs.length).toBe(3);
+
+    const keys = arcs.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Area chart keys
+// ---------------------------------------------------------------------------
+
+describe('area chart mark keys', () => {
+  it('stamps key on area marks', () => {
+    const spec: ChartSpec = {
+      mark: 'area',
+      data: [
+        { date: '2020-01-01', value: 10, series: 'A' },
+        { date: '2021-01-01', value: 40, series: 'A' },
+        { date: '2020-01-01', value: 15, series: 'B' },
+        { date: '2021-01-01', value: 35, series: 'B' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'series', type: 'nominal' },
+      },
+    };
+    const layout = compileChart(spec, dims);
+    const areas = layout.marks.filter((m) => m.type === 'area');
+    expect(areas.length).toBe(2);
+
+    const keys = areas.map((m) => (m as { key?: string }).key);
+    for (const k of keys) {
+      expect(k).toBeDefined();
+    }
+    expect(new Set(keys).size).toBe(2);
+  });
+});

package/src/charts/__tests__/post-process.test.ts

@@ -120,11 +120,7 @@ describe('assignAnimationIndices', () => {
       { type: 'rect', x: 0, y: 0, width: 10, height: 50, fill: '#000' } as RectMark,
     ];
     const animation: ResolvedAnimation = {
-      enabled: true,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 50,
-      staggerOrder: 'value',
+      enter: { duration: 500, ease: 'smooth', staggerDelay: 50, staggerOrder: 'value' },
       annotationDelay: 0,
     };
     assignAnimationIndices(marks, animation);
@@ -165,11 +161,7 @@ describe('assignAnimationIndices', () => {
       } as RectMark,
     ];
     const animation: ResolvedAnimation = {
-      enabled: true,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 50,
-      staggerOrder: 'value',
+      enter: { duration: 500, ease: 'smooth', staggerDelay: 50, staggerOrder: 'value' },
       annotationDelay: 0,
     };
     assignAnimationIndices(marks, animation);
@@ -205,11 +197,7 @@ describe('assignAnimationIndices', () => {
       } as RectMark,
     ];
     const animation: ResolvedAnimation = {
-      enabled: true,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 50,
-      staggerOrder: 'value',
+      enter: { duration: 500, ease: 'smooth', staggerDelay: 50, staggerOrder: 'value' },
       annotationDelay: 0,
     };
     assignAnimationIndices(marks, animation);
@@ -226,16 +214,11 @@ describe('assignAnimationIndices', () => {
     expect(marks[0].animationIndex).toBeUndefined();
   });
 
-  it('is a no-op when animation is disabled', () => {
+  it('is a no-op when animation has no enter phase', () => {
     const marks: Mark[] = [
       { type: 'rect', x: 0, y: 0, width: 10, height: 30, fill: '#000' } as RectMark,
     ];
     const animation: ResolvedAnimation = {
-      enabled: false,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 50,
-      staggerOrder: 'value',
       annotationDelay: 0,
     };
     assignAnimationIndices(marks, animation);
@@ -244,11 +227,7 @@ describe('assignAnimationIndices', () => {
 
   it('handles empty marks array', () => {
     const animation: ResolvedAnimation = {
-      enabled: true,
-      duration: 500,
-      ease: 'smooth',
-      staggerDelay: 50,
-      staggerOrder: 'value',
+      enter: { duration: 500, ease: 'smooth', staggerDelay: 50, staggerOrder: 'value' },
       annotationDelay: 0,
     };
     const marks: Mark[] = [];

package/src/charts/bar/compute.ts

@@ -19,6 +19,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import { isGradientDef, NARROW_VIEWPORT_MAX } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
@@ -194,9 +195,26 @@ export function computeBarMarks(
     }
   }
 
+  // Stamp identity keys for data-update transitions
+  const categoryField = yChannel.field;
+  stampBarKeys(marks, categoryField, colorField);
+
   return applyMarkDefOverrides(marks, spec, bandwidth);
 }
 
+/** Stamp stable identity keys on bar marks for data-update transitions. */
+function stampBarKeys(marks: RectMark[], categoryField: string, colorField?: string): void {
+  const rawKeys = marks.map((m) => {
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    const cat = serializeKeyValue(m.data[categoryField]);
+    return `${series}|${cat}`;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+}
+
 /** Compute stacked horizontal bars with support for zero/normalize/center modes. */
 function computeStackedBars(
   data: DataRow[],

package/src/charts/column/compute.ts

@@ -22,6 +22,7 @@ import type {
 } from '@opendata-ai/openchart-core';
 import { isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
@@ -163,9 +164,26 @@ export function computeColumnMarks(
     );
   }
 
+  // Stamp identity keys for data-update transitions
+  const categoryField = xChannel.field;
+  stampColumnKeys(marks, categoryField, colorField);
+
   return applyMarkDefOverrides(marks, spec, bandwidth);
 }
 
+/** Stamp stable identity keys on column marks for data-update transitions. */
+function stampColumnKeys(marks: RectMark[], categoryField: string, colorField?: string): void {
+  const rawKeys = marks.map((m) => {
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    const cat = serializeKeyValue(m.data[categoryField]);
+    return `${series}|${cat}`;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+}
+
 /** Compute simple (non-grouped) vertical columns. */
 function computeSimpleColumns(
   data: DataRow[],