@opendata-ai/openchart-engine 7.8.0 → 7.9.1

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[],

package/src/charts/dot/compute.ts

@@ -20,6 +20,7 @@ import type {
 } 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 { getColor, getSequentialColor, groupByField } from '../utils';
@@ -77,9 +78,11 @@ export function computeDotMarks(
   const isSequentialColor = colorEnc?.type === 'quantitative';
   const colorField = isSequentialColor ? undefined : colorEnc?.field;
 
+  let marks: (PointMark | RectMark)[];
+
   // Multi-series (categorical): dumbbell chart with connecting bars
   if (colorField) {
-    return computeDumbbellMarks(
+    marks = computeDumbbellMarks(
       spec.data,
       xChannel.field,
       yChannel.field,
@@ -89,20 +92,34 @@ export function computeDotMarks(
       bandwidth,
       scales,
     );
+  } else {
+    // Single series: lollipop stems from baseline
+    marks = computeLollipopMarks(
+      spec.data,
+      xChannel.field,
+      yChannel.field,
+      xScale,
+      yScale,
+      bandwidth,
+      baseline,
+      scales,
+      isSequentialColor,
+    );
   }
 
-  // Single series: lollipop stems from baseline
-  return computeLollipopMarks(
-    spec.data,
-    xChannel.field,
-    yChannel.field,
-    xScale,
-    yScale,
-    bandwidth,
-    baseline,
-    scales,
-    isSequentialColor,
-  );
+  // Stamp keys on point marks (skip rect stems/connectors)
+  const pointMarks = marks.filter((m): m is PointMark => m.type === 'point');
+  const rawKeys = pointMarks.map((m) => {
+    const cat = serializeKeyValue(m.data[yChannel.field]);
+    const series = colorField ? String(m.data[colorField] ?? '') : '';
+    return series ? `${series}|${cat}` : cat;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < pointMarks.length; i++) {
+    pointMarks[i].key = keys[i];
+  }
+
+  return marks;
 }
 
 // ---------------------------------------------------------------------------

package/src/charts/line/area.ts

@@ -24,6 +24,7 @@ import {
   stackOrderNone,
 } from 'd3-shape';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, scaleValue, sortByField } from '../utils';
@@ -235,8 +236,16 @@ function computeSingleArea(
       fillOpacity = 1;
     }
 
+    const keyField = encoding.key && 'field' in encoding.key ? encoding.key.field : undefined;
+    const rawPointKeys = validPoints.map((p) =>
+      keyField ? serializeKeyValue(p.row[keyField]) : serializeKeyValue(p.row[xChannel.field]),
+    );
+
     marks.push({
       type: 'area',
+      key: seriesKey === '__default__' ? 'area' : seriesKey,
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       topPoints,
       bottomPoints,
       path: pathStr,
@@ -402,8 +411,13 @@ function computeStackedArea(
       fillOpacity = 1;
     }
 
+    const rawPointKeys = validPoints.map((_p, idx) => serializeKeyValue(layer[idx]?.data.__x__));
+
     marks.push({
       type: 'area',
+      key: seriesKey,
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       topPoints,
       bottomPoints,
       path: pathStr,
@@ -464,6 +478,12 @@ export function computeAreaMarks(
     marks = computeSingleArea(spec, scales, chartArea);
   }
 
+  // Dedupe area mark keys
+  const areaKeys = dedupeKeys(marks.map((m) => m.key!));
+  marks.forEach((m, i) => {
+    m.key = areaKeys[i];
+  });
+
   const highlight = spec.highlight ?? [];
   if (highlight.length > 0) {
     const highlightSet = new Set(highlight);

package/src/charts/line/compute.ts

@@ -20,6 +20,7 @@ import type {
 import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import { line } from 'd3-shape';
 
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { getColor, getSequentialColor, groupByField, scaleValue, sortByField } from '../utils';
@@ -183,8 +184,16 @@ export function computeLineMarks(
     // Create the LineMark with the combined path points.
     // The points array includes all valid points across all segments.
     // dataPoints carries pixel coordinates + original data for voronoi tooltip overlay.
+    const keyField = encoding.key && 'field' in encoding.key ? encoding.key.field : undefined;
+    const rawPointKeys = pointsWithData.map((p) =>
+      keyField ? serializeKeyValue(p.row[keyField]) : serializeKeyValue(p.row[xChannel.field]),
+    );
+
     const lineMark: LineMark = {
       type: 'line',
+      key: seriesStyleKey ?? 'series',
+      pointKeys: dedupeKeys(rawPointKeys),
+      interpolate: spec.markDef.interpolate ?? 'monotone',
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
@@ -242,9 +251,15 @@ export function computeLineMarks(
         // color — no white halo, no hollow ring. Marked decorative because the
         // data point already exists on the line and gets described by the a11y
         // data table; the dot is purely visual.
+        const pointKey = keyField
+          ? serializeKeyValue(p.row[keyField])
+          : seriesStyleKey
+            ? `${seriesStyleKey}|${serializeKeyValue(p.row[xChannel.field])}`
+            : serializeKeyValue(p.row[xChannel.field]);
         if (isSingleEndpoint) {
           bucket.push({
             type: 'point',
+            key: pointKey,
             cx: p.x,
             cy: p.y,
             r: 3.5,
@@ -259,6 +274,7 @@ export function computeLineMarks(
         }
         const pointMark: PointMark = {
           type: 'point',
+          key: pointKey,
           cx: p.x,
           cy: p.y,
           r: visible ? DEFAULT_POINT_RADIUS : 0,
@@ -276,7 +292,25 @@ export function computeLineMarks(
     }
   }
 
-  return [...mutedMarks, ...highlightedMarks];
+  const allMarks = [...mutedMarks, ...highlightedMarks];
+
+  // Dedupe series-level keys across all line marks
+  const lineMarks = allMarks.filter((m): m is LineMark => m.type === 'line');
+  const lineKeys = dedupeKeys(lineMarks.map((m) => m.key!));
+  lineMarks.forEach((m, i) => {
+    m.key = lineKeys[i];
+  });
+
+  // Dedupe point mark keys
+  const pointMarks = allMarks.filter((m): m is PointMark => m.type === 'point');
+  if (pointMarks.length > 0) {
+    const pointKeys = dedupeKeys(pointMarks.map((m) => m.key ?? ''));
+    pointMarks.forEach((m, i) => {
+      m.key = pointKeys[i];
+    });
+  }
+
+  return allMarks;
 }
 
 // ---------------------------------------------------------------------------