@opendata-ai/openchart-engine 7.7.0 → 7.9.0

package/src/compiler/animation.ts

@@ -2,28 +2,53 @@
  * Animation resolver: normalizes AnimationSpec into fully resolved config.
  *
  * Handles the shorthand forms:
- * - true -> { enter: true } -> full defaults
- * - { enter: { duration: 800 } } -> merge with defaults
+ * - true -> all three phases with defaults
+ * - { enter: { duration: 800 } } -> merge with defaults per phase
  * - false/undefined -> undefined (no animation)
+ *
+ * Each phase resolves independently:
+ * - true/config-object -> resolved phase merged onto that phase's defaults
+ * - false -> phase absent
+ * - undefined -> phase present with defaults (animation: {} behaves like true)
+ *
+ * Returns undefined only when ALL phases resolve absent.
  */
 
 import type {
   AnimationConfig,
-  AnimationEase,
   AnimationPhaseConfig,
   AnimationSpec,
   AnimationStagger,
   ResolvedAnimation,
+  ResolvedAnimationPhase,
 } from '@opendata-ai/openchart-core';
 
 /** Default values for entrance animation. */
-const ENTER_DEFAULTS = {
+export const ENTER_DEFAULTS: ResolvedAnimationPhase = {
   duration: 500,
-  ease: 'smooth' as AnimationEase,
+  ease: 'smooth',
   staggerDelay: 80,
-  staggerOrder: 'index' as const,
-  annotationDelay: 200,
-} as const;
+  staggerOrder: 'index',
+};
+
+/** Default values for update (data transition) animation. */
+export const UPDATE_DEFAULTS: ResolvedAnimationPhase = {
+  duration: 500,
+  ease: 'smooth',
+  staggerDelay: 0,
+  staggerOrder: 'index',
+};
+
+/** Default values for exit animation. */
+export const EXIT_DEFAULTS: ResolvedAnimationPhase = {
+  duration: 300,
+  ease: 'smooth',
+  staggerDelay: 0,
+  staggerOrder: 'index',
+};
+
+/** Default annotation delay in ms after marks finish. */
+const DEFAULT_ANNOTATION_DELAY = 200;
 
 /** Maximum total stagger time in ms. Prevents 200-bar charts from taking 6s. */
 const MAX_TOTAL_STAGGER_MS = 2000;
@@ -35,35 +60,31 @@ const MAX_TOTAL_STAGGER_MS = 2000;
 export function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnimation | undefined {
   if (spec === undefined || spec === false) return undefined;
 
-  // true -> default enter animation
+  // true -> all three phases with defaults
   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,
+      enter: { ...ENTER_DEFAULTS },
+      update: { ...UPDATE_DEFAULTS },
+      exit: { ...EXIT_DEFAULTS },
+      annotationDelay: DEFAULT_ANNOTATION_DELAY,
     };
   }
 
   // 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 enter = resolvePhase(config.enter, ENTER_DEFAULTS);
+  const update = resolvePhase(config.update, UPDATE_DEFAULTS);
+  const exit = resolvePhase(config.exit, EXIT_DEFAULTS);
 
-  const enterConfig = resolvePhaseConfig(config.enter);
+  // Return undefined only when ALL phases resolve absent
+  if (!enter && !update && !exit) return undefined;
 
   return {
-    enabled: true,
-    duration: enterConfig.duration,
-    ease: enterConfig.ease,
-    staggerDelay: enterConfig.staggerDelay,
-    staggerOrder: enterConfig.staggerOrder,
-    annotationDelay: config.annotationDelay ?? ENTER_DEFAULTS.annotationDelay,
+    enter: enter ?? undefined,
+    update: update ?? undefined,
+    exit: exit ?? undefined,
+    annotationDelay: config.annotationDelay ?? DEFAULT_ANNOTATION_DELAY,
   };
 }
 
@@ -75,48 +96,47 @@ export function clampStaggerDelay(delay: number, elementCount: number): number {
   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';
-}
+/**
+ * Resolve a single animation phase.
+ * - false -> null (phase absent)
+ * - undefined -> phase present with defaults
+ * - true -> phase present with defaults
+ * - config object -> merge with defaults
+ */
+function resolvePhase(
+  phase: AnimationPhaseConfig | boolean | undefined,
+  defaults: ResolvedAnimationPhase,
+): ResolvedAnimationPhase | null {
+  if (phase === false) return null;
 
-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,
-    };
+    return { ...defaults };
   }
 
   const cfg = phase as AnimationPhaseConfig;
-  const stagger = resolveStagger(cfg.stagger);
+  const stagger = resolveStagger(cfg.stagger, defaults);
 
   return {
-    duration: cfg.duration ?? ENTER_DEFAULTS.duration,
-    ease: cfg.ease ?? ENTER_DEFAULTS.ease,
+    duration: cfg.duration ?? defaults.duration,
+    ease: cfg.ease ?? defaults.ease,
     staggerDelay: stagger.delay,
     staggerOrder: stagger.order,
   };
 }
 
-function resolveStagger(stagger: AnimationStagger | boolean | undefined): {
+function resolveStagger(
+  stagger: AnimationStagger | boolean | undefined,
+  defaults: ResolvedAnimationPhase,
+): {
   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: defaults.staggerDelay, order: defaults.staggerOrder };
   }
   return {
-    delay: stagger.delay ?? ENTER_DEFAULTS.staggerDelay,
-    order: stagger.order ?? ENTER_DEFAULTS.staggerOrder,
+    delay: stagger.delay ?? defaults.staggerDelay,
+    order: stagger.order ?? defaults.staggerOrder,
   };
 }

package/src/compiler/keys.ts

@@ -0,0 +1,54 @@
+/**
+ * Mark key utilities for data-update transitions.
+ *
+ * Keys uniquely identify marks across data updates so the renderer can
+ * match old marks to new marks and animate the difference. Each chart
+ * type stamps keys during its compute phase; these helpers provide the
+ * shared serialization and deduplication logic.
+ */
+
+/** Sentinel string for null/undefined values. Uses a Unicode symbol
+ *  that won't collide with real data values. */
+const NULL_KEY = '∅';
+
+/**
+ * Serialize a datum value into a stable key fragment.
+ * - Date -> epoch ms string (avoids locale-dependent Date.toString)
+ * - number/string/boolean -> String(v)
+ * - null/undefined -> null sentinel
+ */
+export function serializeKeyValue(v: unknown): string {
+  if (v === null || v === undefined) return NULL_KEY;
+  if (v instanceof Date) return String(v.getTime());
+  return String(v);
+}
+
+/**
+ * Append occurrence suffixes to duplicate keys, in order.
+ *
+ * Only keys that appear more than once get suffixed. Unique keys pass
+ * through unchanged so keys remain human-readable when possible.
+ * Uses SOH (\x01) as separator to avoid collisions with real data values.
+ */
+export function dedupeKeys(keys: string[]): string[] {
+  // Count occurrences
+  const counts = new Map<string, number>();
+  for (const k of keys) {
+    counts.set(k, (counts.get(k) ?? 0) + 1);
+  }
+
+  // Assign suffixes only to duplicates
+  const seen = new Map<string, number>();
+  const result: string[] = [];
+  for (const k of keys) {
+    if (counts.get(k)! > 1) {
+      const idx = seen.get(k) ?? 0;
+      result.push(`${k}\x01${idx}`);
+      seen.set(k, idx + 1);
+    } else {
+      result.push(k);
+    }
+  }
+
+  return result;
+}

package/src/compiler/normalize.ts

@@ -132,7 +132,7 @@ function inferFieldType(data: DataRow[], field: string): FieldType {
 function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: string[]): Encoding {
   const result = { ...encoding };
 
-  for (const channel of ['x', 'y', 'color', 'size', 'detail'] as const) {
+  for (const channel of ['x', 'y', 'color', 'size', 'detail', 'key'] as const) {
     const spec = result[channel];
     if (!spec) continue;
 

package/src/index.ts

@@ -26,7 +26,25 @@ export {
 // Animation resolution
 // ---------------------------------------------------------------------------
 
-export { clampStaggerDelay, resolveAnimation } from './compiler/animation';
+export {
+  clampStaggerDelay,
+  ENTER_DEFAULTS,
+  EXIT_DEFAULTS,
+  resolveAnimation,
+  UPDATE_DEFAULTS,
+} from './compiler/animation';
+
+// ---------------------------------------------------------------------------
+// Mark keying for data-update transitions
+// ---------------------------------------------------------------------------
+
+export { dedupeKeys, serializeKeyValue } from './compiler/keys';
+
+// ---------------------------------------------------------------------------
+// Geometry helpers for path reconstruction
+// ---------------------------------------------------------------------------
+
+export { buildAreaPath, buildLinePath } from './charts/line/curves';
 
 // ---------------------------------------------------------------------------
 // Graph compilation types

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

@@ -209,9 +209,9 @@ describe('compileTable', () => {
   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);
+    expect(layout.animation!.enter).toBeDefined();
+    expect(layout.animation!.enter!.duration).toBe(500);
+    expect(layout.animation!.enter!.staggerDelay).toBe(80);
   });
 
   it('includes resolved animation with custom config', () => {
@@ -220,8 +220,8 @@ describe('compileTable', () => {
       baseOptions,
     );
     expect(layout.animation).toBeDefined();
-    expect(layout.animation!.duration).toBe(800);
-    expect(layout.animation!.ease).toBe('snappy');
+    expect(layout.animation!.enter!.duration).toBe(800);
+    expect(layout.animation!.enter!.ease).toBe('snappy');
   });
 
   it('does not include animation when spec omits it', () => {

package/src/tilemap/compile-tilemap.ts

@@ -38,6 +38,7 @@ import {
   computeChrome,
   estimateTextWidth,
   formatNumber,
+  pickLabelColor,
   resolveTheme,
   SEQUENTIAL_PALETTES,
 } from '@opendata-ai/openchart-core';
@@ -226,6 +227,7 @@ function compileQuantitative(
         formattedValue,
         hasData,
         theme,
+        isDarkMode: !!isDarkMode,
       }),
     );
   }
@@ -397,6 +399,7 @@ function compileCategorical(
         formattedValue,
         hasData,
         theme,
+        isDarkMode: !!isDarkMode,
         category: hasData ? category : undefined,
       }),
     );
@@ -488,6 +491,7 @@ interface TileMarkOptions {
   formattedValue: string;
   hasData: boolean;
   theme: ResolvedTheme;
+  isDarkMode: boolean;
   category?: string | null;
 }
 
@@ -505,16 +509,20 @@ function buildTileMark(opts: TileMarkOptions): TileMapTileMark {
     formattedValue,
     hasData,
     theme,
+    isDarkMode,
     category,
   } = opts;
   const tileCenterX = gridOffsetX + pos.x + tileSize / 2;
   const tileTopY = gridOffsetY + pos.y;
 
+  const textColor = hasData ? pickLabelColor(fill, isDarkMode) : '#ffffff';
+  const isLightText = textColor === '#ffffff';
+
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
     fontSize: tileSize > 24 ? 10 : 7,
     fontWeight: 700,
-    fill: '#ffffff',
+    fill: textColor,
     lineHeight: 1.2,
   };
 
@@ -522,7 +530,7 @@ function buildTileMark(opts: TileMarkOptions): TileMapTileMark {
     fontFamily: theme.fonts.family,
     fontSize: tileSize > 24 ? 10 : 7,
     fontWeight: 300,
-    fill: 'rgba(255,255,255,0.6)',
+    fill: isLightText ? 'rgba(255,255,255,0.6)' : 'rgba(0,0,0,0.45)',
     lineHeight: 1.2,
   };