@opendata-ai/openchart-core 6.3.0 → 6.5.0

package/src/types/layout.ts

@@ -217,6 +217,8 @@ export interface LineMark {
   label?: ResolvedLabel;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -257,6 +259,8 @@ export interface AreaMark {
   }>;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -287,6 +291,14 @@ export interface RectMark {
   label?: ResolvedLabel;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
+  /** Bar orientation for animation direction. Set by the engine based on encoding. */
+  orient?: 'horizontal' | 'vertical';
+  /** Stacking group key (e.g. category name). Segments sharing this key animate together. */
+  stackGroup?: string;
+  /** Position of this segment within its stack group (0, 1, 2...). Set by engine for stacked bars. */
+  stackPos?: number;
 }
 
 /**
@@ -321,6 +333,8 @@ export interface ArcMark {
   label?: ResolvedLabel;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -349,6 +363,8 @@ export interface PointMark {
   label?: ResolvedLabel;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -381,6 +397,8 @@ export interface TextMarkLayout {
   label?: ResolvedLabel;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -409,6 +427,8 @@ export interface RuleMarkLayout {
   data: Record<string, unknown>;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /**
@@ -435,6 +455,8 @@ export interface TickMarkLayout {
   data: Record<string, unknown>;
   /** Accessibility attributes. */
   aria: MarkAria;
+  /** Index for stagger animation ordering. */
+  animationIndex?: number;
 }
 
 /** Discriminated union of all mark types. */
@@ -490,6 +512,8 @@ export interface ResolvedLabel {
 export interface ResolvedAnnotation {
   /** Original annotation type. */
   type: 'text' | 'range' | 'refline';
+  /** Stable identifier from the spec annotation, for selection/edit callbacks. */
+  id?: string;
   /** Label text (if any). */
   label?: ResolvedLabel;
   /** For range: the highlighted rectangle in pixel coordinates. */
@@ -584,6 +608,26 @@ export interface A11yMetadata {
   keyboardNavigable: boolean;
 }
 
+// ---------------------------------------------------------------------------
+// Animation (resolved)
+// ---------------------------------------------------------------------------
+
+/** Resolved entrance animation config with all defaults applied. */
+export interface ResolvedAnimation {
+  /** Whether entrance animation is enabled. */
+  enabled: boolean;
+  /** Duration in ms. */
+  duration: number;
+  /** Easing preset name. */
+  ease: import('./spec').AnimationEase;
+  /** Stagger delay between elements in ms. */
+  staggerDelay: number;
+  /** Stagger ordering. */
+  staggerOrder: 'index' | 'value' | 'reverse';
+  /** Delay before annotations animate in (ms after marks). */
+  annotationDelay: number;
+}
+
 // ---------------------------------------------------------------------------
 // ChartLayout (the main engine output for charts)
 // ---------------------------------------------------------------------------
@@ -620,6 +664,8 @@ export interface ChartLayout {
   theme: ResolvedTheme;
   /** Total SVG dimensions. */
   dimensions: { width: number; height: number };
+  /** Resolved animation config. Present only when animation is enabled. */
+  animation?: ResolvedAnimation;
 }
 
 // ---------------------------------------------------------------------------
@@ -794,6 +840,8 @@ export interface TableLayout {
   a11y: { caption: string; summary: string };
   /** The resolved theme. */
   theme: ResolvedTheme;
+  /** Resolved animation config. Present only when animation is enabled. */
+  animation?: ResolvedAnimation;
 }
 
 // ---------------------------------------------------------------------------

package/src/types/spec.ts

@@ -382,6 +382,8 @@ export type AnnotationAnchor = 'top' | 'bottom' | 'left' | 'right' | 'auto';
 
 /** Base properties shared by all annotation types. */
 interface AnnotationBase {
+  /** Stable identifier for selection and edit callbacks. When provided, edit events include this ID for reliable element matching. */
+  id?: string;
   /** Human-readable label for the annotation. */
   label?: string;
   /** Fill color for the annotation element. */
@@ -593,6 +595,62 @@ export interface SeriesStyle {
   opacity?: number;
 }
 
+// ---------------------------------------------------------------------------
+// Animation
+// ---------------------------------------------------------------------------
+
+/**
+ * Named easing presets for entrance animations.
+ * Uses CSS linear() curves. Named 'ease' (not 'easing') to match Vega convention.
+ */
+export type AnimationEase = 'smooth' | 'snappy';
+
+/** Stagger configuration for sequential element reveal. */
+export interface AnimationStagger {
+  /** Delay between each element in ms. Default: 30 */
+  delay?: number;
+  /** Ordering strategy. Default: 'index' (DOM order) */
+  order?: 'index' | 'value' | 'reverse';
+}
+
+/**
+ * Animation phase config. Follows Vega's enter/update/exit model.
+ * Each phase can be true (use defaults) or a config object.
+ */
+export interface AnimationPhaseConfig {
+  /** Duration in ms. Default: 500 for enter. */
+  duration?: number;
+  /** Easing preset. Default: 'smooth'. */
+  ease?: AnimationEase;
+  /** Stagger config. true = defaults, false = no stagger. Default: true for enter. */
+  stagger?: AnimationStagger | boolean;
+}
+
+/**
+ * Full animation config object. Structured as enter/update/exit phases
+ * following Vega's encoding set model.
+ *
+ * v1 implements enter only. update and exit reserved for v2.
+ */
+export interface AnimationConfig {
+  /** Entrance animation when chart first renders. */
+  enter?: AnimationPhaseConfig | boolean;
+  /** Transition animation when data updates. Reserved for v2. */
+  update?: AnimationPhaseConfig | boolean;
+  /** Exit animation when marks are removed. Reserved for v2. */
+  exit?: AnimationPhaseConfig | boolean;
+  /** Delay before annotations animate in (ms after marks). Default: 200. */
+  annotationDelay?: number;
+}
+
+/**
+ * Animation spec property.
+ * - true: enable entrance animation with sensible defaults
+ * - false/omitted: no animation (current behavior)
+ * - AnimationConfig: full control via enter/update/exit phases
+ */
+export type AnimationSpec = boolean | AnimationConfig;
+
 /**
  * Breakpoint-conditional overrides for chart specs.
  *
@@ -609,6 +667,8 @@ export interface ChartSpecOverride {
   legend?: LegendConfig;
   /** Override annotations at this breakpoint. */
   annotations?: Annotation[];
+  /** Override animation at this breakpoint. */
+  animation?: AnimationSpec;
 }
 
 /**
@@ -655,6 +715,13 @@ export interface ChartSpec {
    * are shallow-merged into the spec before layout computation.
    */
   overrides?: Partial<Record<Breakpoint, ChartSpecOverride>>;
+  /**
+   * Animation configuration.
+   * - true: enable entrance animation with sensible defaults
+   * - false/omitted: no animation (current behavior)
+   * - AnimationConfig: full control via enter/update/exit phases
+   */
+  animation?: AnimationSpec;
 }
 
 /**
@@ -688,6 +755,8 @@ export interface TableSpec {
   compact?: boolean;
   /** Whether the table adapts to container width. Defaults to true. */
   responsive?: boolean;
+  /** Animation configuration for entrance animations. */
+  animation?: AnimationSpec;
 }
 
 /** Graph node: must have an id, plus arbitrary data fields. */
@@ -800,6 +869,8 @@ export interface LayerSpec {
   resolve?: ResolveConfig;
   /** Hidden series names. */
   hiddenSeries?: string[];
+  /** Animation configuration. */
+  animation?: AnimationSpec;
 }
 
 /**