@opendata-ai/openchart-engine 6.3.0 → 6.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
-import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, LegendConfig, ThemeConfig, DarkMode, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, VizSpec, ScaleType, EncodingChannel, Rect, LayoutStrategy, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, AnimationSpec, ResolvedAnimation, MarkType, MarkDef, DataRow, Encoding, ChromeText, Annotation, LabelConfig, LegendConfig, ThemeConfig, DarkMode, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, VizSpec, ScaleType, EncodingChannel, Rect, LayoutStrategy, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
 export { ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, LayerSpec, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-core';
 import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
@@ -168,6 +168,25 @@ declare function compileTable(spec: unknown, options: CompileTableOptions): Tabl
  */
 declare function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation;
 
+/**
+ * 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)
+ */
+
+/**
+ * Resolve an AnimationSpec into a fully resolved config with all defaults filled.
+ * Returns undefined if animation is disabled (false or omitted).
+ */
+declare function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnimation | undefined;
+/**
+ * Clamp stagger delay so total stagger time doesn't exceed MAX_TOTAL_STAGGER_MS.
+ */
+declare function clampStaggerDelay(delay: number, elementCount: number): number;
+
 /** Chrome with all string values normalized to ChromeText objects. */
 interface NormalizedChrome {
     title?: ChromeText;
@@ -214,6 +233,7 @@ interface NormalizedTableSpec {
     stickyFirstColumn: boolean;
     compact: boolean;
     responsive: boolean;
+    animation?: AnimationSpec;
 }
 /** A GraphSpec with all optional fields filled with sensible defaults. */
 interface NormalizedGraphSpec {
@@ -510,4 +530,4 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
 
-export { type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, type GraphCompilation, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSpec, type NormalizedTableSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clearRenderers, compile, compileChart, compileGraph, compileLayer, compileTable, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };
+export { type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, type GraphCompilation, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSpec, type NormalizedTableSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clampStaggerDelay, clearRenderers, compile, compileChart, compileGraph, compileLayer, compileTable, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };

package/dist/index.js

@@ -209,6 +209,7 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark) {
   };
   return {
     type: "text",
+    id: annotation.id,
     label,
     stroke: annotation.stroke,
     fill: annotation.fill,
@@ -261,6 +262,7 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark) {
   const defaultOpacity = isDark ? 0.2 : DEFAULT_RANGE_OPACITY;
   return {
     type: "range",
+    id: annotation.id,
     rect,
     label,
     fill: annotation.fill ?? DEFAULT_RANGE_FILL,
@@ -314,6 +316,7 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark) {
   const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
   return {
     type: "refline",
+    id: annotation.id,
     line: { start, end },
     label,
     stroke: annotation.stroke ?? defaultStroke,
@@ -771,7 +774,9 @@ function computeStackedBars(data, valueField, categoryField, colorField, xScale,
         fill: color2,
         cornerRadius: 0,
         data: row,
-        aria
+        aria,
+        orient: "horizontal",
+        stackGroup: category
       });
       cumulativeValue += value;
     }
@@ -810,7 +815,8 @@ function computeSimpleBars(data, valueField, categoryField, xScale, yScale, band
       fill: color2,
       cornerRadius: 2,
       data: row,
-      aria
+      aria,
+      orient: "horizontal"
     });
   }
   return marks;
@@ -1048,7 +1054,8 @@ function computeSimpleColumns(data, categoryField, valueField, xScale, yScale, b
       fill: color2,
       cornerRadius: 2,
       data: row,
-      aria
+      aria,
+      orient: "vertical"
     });
   }
   return marks;
@@ -1078,7 +1085,8 @@ function computeColoredColumns(data, categoryField, valueField, colorField, xSca
       fill: color2,
       cornerRadius: 2,
       data: row,
-      aria
+      aria,
+      orient: "vertical"
     });
   }
   return marks;
@@ -1110,7 +1118,9 @@ function computeStackedColumns(data, categoryField, valueField, colorField, xSca
         fill: color2,
         cornerRadius: 0,
         data: row,
-        aria
+        aria,
+        orient: "vertical",
+        stackGroup: category
       });
       cumulativeValue += value;
     }
@@ -5989,7 +5999,8 @@ function normalizeTableSpec(spec, _warnings) {
     pagination: spec.pagination ?? false,
     stickyFirstColumn: spec.stickyFirstColumn ?? false,
     compact: spec.compact ?? false,
-    responsive: spec.responsive ?? true
+    responsive: spec.responsive ?? true,
+    animation: spec.animation
   };
 }
 function normalizeGraphSpec(spec, _warnings) {
@@ -6656,6 +6667,77 @@ ${errorMessages}`);
   return { spec: normalized, warnings };
 }
 
+// src/compiler/animation.ts
+var ENTER_DEFAULTS = {
+  duration: 500,
+  ease: "smooth",
+  staggerDelay: 80,
+  staggerOrder: "index",
+  annotationDelay: 200
+};
+var MAX_TOTAL_STAGGER_MS = 2e3;
+function resolveAnimation(spec) {
+  if (spec === void 0 || spec === false) return void 0;
+  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
+    };
+  }
+  const config = spec;
+  if (config.enter === false || config.enter === void 0 && !hasAnyPhase(config)) {
+    return void 0;
+  }
+  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
+  };
+}
+function clampStaggerDelay(delay, elementCount) {
+  if (elementCount <= 1) return 0;
+  return Math.min(delay, MAX_TOTAL_STAGGER_MS / elementCount);
+}
+function hasAnyPhase(config) {
+  return config.enter !== void 0 || config.update !== void 0 || config.exit !== void 0;
+}
+function resolvePhaseConfig(phase) {
+  if (phase === void 0 || phase === true) {
+    return {
+      duration: ENTER_DEFAULTS.duration,
+      ease: ENTER_DEFAULTS.ease,
+      staggerDelay: ENTER_DEFAULTS.staggerDelay,
+      staggerOrder: ENTER_DEFAULTS.staggerOrder
+    };
+  }
+  const cfg = phase;
+  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) {
+  if (stagger === false) return { delay: 0, order: "index" };
+  if (stagger === void 0 || stagger === true) {
+    return { delay: ENTER_DEFAULTS.staggerDelay, order: ENTER_DEFAULTS.staggerOrder };
+  }
+  return {
+    delay: stagger.delay ?? ENTER_DEFAULTS.staggerDelay,
+    order: stagger.order ?? ENTER_DEFAULTS.staggerOrder
+  };
+}
+
 // src/graphs/compile-graph.ts
 import { adaptTheme, computeChrome, resolveTheme } from "@opendata-ai/openchart-core";
 
@@ -8744,7 +8826,8 @@ function compileTableLayout(spec, options, theme) {
       caption,
       summary: `${resolvedColumns.length} columns, ${totalFiltered} rows`
     },
-    theme
+    theme,
+    animation: resolveAnimation(spec.animation)
   };
 }
 
@@ -9227,6 +9310,8 @@ function compileChart(spec, options) {
       };
     }
   }
+  const rawAnimationSpec = overrides?.[breakpoint]?.animation ?? rawSpec.animation;
+  const resolvedAnimation = resolveAnimation(rawAnimationSpec);
   const mergedThemeConfig = options.theme ? { ...chartSpec.theme, ...options.theme } : chartSpec.theme;
   let theme = resolveTheme2(mergedThemeConfig);
   if (options.darkMode) {
@@ -9357,6 +9442,37 @@ function compileChart(spec, options) {
     },
     chartSpec.data
   );
+  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.stackGroup) continue;
+      m.animationIndex = i;
+    }
+  }
+  if (resolvedAnimation?.enabled) {
+    const groupIndexMap = /* @__PURE__ */ new Map();
+    const groupStackPos = /* @__PURE__ */ new Map();
+    let nextGroupIndex = 0;
+    for (const mark of marks) {
+      if (mark.type === "rect" && mark.stackGroup) {
+        const rect = mark;
+        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,
@@ -9378,9 +9494,29 @@ function compileChart(spec, options) {
     dimensions: {
       width: options.width,
       height: options.height
-    }
+    },
+    animation: resolvedAnimation
   };
 }
+function getMarkPrimaryValue(mark) {
+  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;
+  }
+}
 function compileLayer(spec, options) {
   const leaves = flattenLayers(spec);
   if (leaves.length === 0) {
@@ -9451,6 +9587,7 @@ function compileGraph2(spec, options) {
   return compileGraph(spec, options);
 }
 export {
+  clampStaggerDelay,
   clearRenderers,
   compile,
   compileChart,
@@ -9462,6 +9599,7 @@ export {
   isConditionalValueDef,
   normalizeSpec,
   registerChartRenderer,
+  resolveAnimation,
   resolveConditionalValue,
   runBin,
   runCalculate,