@opendata-ai/openchart-core 6.4.1 → 6.5.1

package/dist/index.d.ts

@@ -638,6 +638,53 @@ interface SeriesStyle {
     /** Opacity override (0-1). */
     opacity?: number;
 }
+/**
+ * Named easing presets for entrance animations.
+ * Uses CSS linear() curves. Named 'ease' (not 'easing') to match Vega convention.
+ */
+type AnimationEase = 'smooth' | 'snappy';
+/** Stagger configuration for sequential element reveal. */
+interface AnimationStagger {
+    /** Delay between each element in ms. Default: 80 */
+    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.
+ */
+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.
+ */
+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
+ */
+type AnimationSpec = boolean | AnimationConfig;
 /**
  * Breakpoint-conditional overrides for chart specs.
  *
@@ -654,6 +701,8 @@ interface ChartSpecOverride {
     legend?: LegendConfig;
     /** Override annotations at this breakpoint. */
     annotations?: Annotation[];
+    /** Override animation at this breakpoint. */
+    animation?: AnimationSpec;
 }
 /**
  * Chart specification: the primary input for standard chart types.
@@ -699,6 +748,13 @@ 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;
 }
 /**
  * Table specification: input for data table visualizations.
@@ -733,6 +789,8 @@ 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. */
 interface GraphNode {
@@ -834,6 +892,8 @@ interface LayerSpec {
     resolve?: ResolveConfig;
     /** Hidden series names. */
     hiddenSeries?: string[];
+    /** Animation configuration. */
+    animation?: AnimationSpec;
 }
 /**
  * Top-level visualization spec: union discriminated by structural shape.
@@ -1518,6 +1578,8 @@ interface LineMark {
     label?: ResolvedLabel;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Area mark: a filled region bounded by a top line and a baseline.
@@ -1557,6 +1619,8 @@ interface AreaMark {
     }>;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Rect mark: a rectangle.
@@ -1586,6 +1650,14 @@ 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;
 }
 /**
  * Arc mark: a pie/donut slice.
@@ -1619,6 +1691,8 @@ interface ArcMark {
     label?: ResolvedLabel;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Point mark: a circle or dot.
@@ -1646,6 +1720,8 @@ interface PointMark {
     label?: ResolvedLabel;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Text mark: data-positioned text label.
@@ -1677,6 +1753,8 @@ interface TextMarkLayout {
     label?: ResolvedLabel;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Rule mark: a line segment between two points.
@@ -1704,6 +1782,8 @@ interface RuleMarkLayout {
     data: Record<string, unknown>;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /**
  * Tick mark: a short line segment at a data coordinate.
@@ -1729,6 +1809,8 @@ interface TickMarkLayout {
     data: Record<string, unknown>;
     /** Accessibility attributes. */
     aria: MarkAria;
+    /** Index for stagger animation ordering. */
+    animationIndex?: number;
 }
 /** Discriminated union of all mark types. */
 type Mark = LineMark | AreaMark | RectMark | ArcMark | PointMark | TextMarkLayout | RuleMarkLayout | TickMarkLayout;
@@ -1846,6 +1928,21 @@ interface A11yMetadata {
     /** Whether the visualization is keyboard-navigable. */
     keyboardNavigable: boolean;
 }
+/** Resolved entrance animation config with all defaults applied. */
+interface ResolvedAnimation {
+    /** Whether entrance animation is enabled. */
+    enabled: boolean;
+    /** Duration in ms. */
+    duration: number;
+    /** Easing preset name. */
+    ease: 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 complete engine output for chart visualizations.
  *
@@ -1881,6 +1978,8 @@ interface ChartLayout {
         width: number;
         height: number;
     };
+    /** Resolved animation config. Present only when animation is enabled. */
+    animation?: ResolvedAnimation;
 }
 /** A resolved column definition with computed properties. */
 interface ResolvedColumn {
@@ -2039,6 +2138,8 @@ interface TableLayout {
     };
     /** The resolved theme. */
     theme: ResolvedTheme;
+    /** Resolved animation config. Present only when animation is enabled. */
+    animation?: ResolvedAnimation;
 }
 /** A resolved graph node with computed position and visual properties. */
 interface GraphNodeLayout {
@@ -2685,4 +2786,4 @@ declare function scatterChart(data: DataRow[], x: FieldRef, y: FieldRef, options
  */
 declare function dataTable(data: DataRow[], options?: TableBuilderOptions): TableSpec;
 
-export { type A11yMetadata, type AggregateOp, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };
+export { type A11yMetadata, type AggregateOp, type AnimationConfig, type AnimationEase, type AnimationPhaseConfig, type AnimationSpec, type AnimationStagger, type Annotation, type AnnotationAnchor, type AnnotationOffset, type AnnotationPosition, type ArcMark, type AreaMark, type AxisConfig, type AxisLabelDensity, type AxisLayout, type AxisTick, BRAND_FONT_SIZE, BRAND_MIN_WIDTH, BRAND_RESERVE_WIDTH, type BarColumnConfig, type BarTableCell, type BinParams, type BinTransform, type Breakpoint, CATEGORICAL_PALETTE, CHART_ENCODING_RULES, CHART_TYPES, type CalculateExpression, type CalculateTransform, type CategoricalPalette, type CategoryColorsConfig, type CategoryTableCell, type CellStyle, type ChannelRule, type ChartBuilderOptions, type ChartEventHandlers, type ChartLayout, type ChartSpec, type ChartSpecOverride, type ChartSpecWithoutData, type ChartType, type Chrome, type ChromeDefaults, type ChromeKey, type ChromeMode, type ChromeText, type ChromeTextStyle, type ColorBlindnessType, type ColumnConfig, type CompileOptions, type CompileTableOptions, type Condition, type ConditionalValueDef, DEFAULT_THEME, DIVERGING_PALETTES, type DarkMode, type DataRow, type DateGranularity, type DivergingPalette, EXTENDED_OFFSET_STRATEGIES, type ElementEdit, type ElementRef, type Encoding, type EncodingChannel, type EncodingRule, type FieldPredicate, type FieldRef, type FieldType, type FilterPredicate, type FilterTransform, type FlagTableCell, GRAPH_ENCODING_RULES, type GraphChannelRule, type GraphEdge, type GraphEdgeLayout, type GraphEncoding, type GraphEncodingChannel, type GraphLayout, type GraphLayoutConfig, type GraphNode, type GraphNodeLayout, type GraphSpec, type GraphSpecWithoutData, type Gridline, type HeatmapColumnConfig, type HeatmapTableCell, type HeightClass, type ImageColumnConfig, type ImageTableCell, type LabelCandidate, type LabelConfig, type LabelDensity, type LabelMode, type LabelPriority, type LayerSpec, type LayoutStrategy, type LegendConfig, type LegendEntry, type LegendLayout, type LegendPosition, type LineMark, type LogicalAnd, type LogicalNot, type LogicalOr, MARK_DISPLAY_NAMES, MARK_ENCODING_RULES, MARK_TYPES, type Margins, type Mark, type MarkAria, type MarkDef, type MarkEvent, type MarkType, type MeasureTextFn, type NodeOverride, OFFSET_STRATEGIES, type OffsetStrategy, type PaginationState, type Point, type PointMark, type RangeAnnotation, type Rect, type RectMark, type RefLineAnnotation, type ResolveConfig, type ResolveMode, type ResolvedAnimation, type ResolvedAnnotation, type ResolvedChrome, type ResolvedChromeElement, type ResolvedColumn, type ResolvedLabel, type ResolvedTheme, type RuleMarkLayout, SEQUENTIAL_PALETTES, type ScaleConfig, type ScaleType, type SequentialPalette, type SeriesStyle, type SortState, type SparklineColumnConfig, type SparklineData, type SparklineTableCell, type StoredVizSpec, type TableBuilderOptions, type TableCell, type TableCellBase, type TableLayout, type TableRow, type TableSpec, type TableSpecWithoutData, type TextAnnotation, type TextMarkLayout, type TextStyle, type TextTableCell, type Theme, type ThemeChromeDefaults, type ThemeColors, type ThemeConfig, type ThemeFontSizes, type ThemeFontWeights, type ThemeFonts, type ThemeSpacing, type TickMarkLayout, type TimeUnit, type TimeUnitTransform, type TooltipContent, type TooltipField, type Transform, type VizSpec, abbreviateNumber, adaptColorForDarkMode, adaptTheme, areaChart, barChart, buildD3Formatter, buildTemporalFormatter, checkPaletteDistinguishability, columnChart, computeChrome, computeLabelBounds, contrastRatio, dataTable, detectCollision, donutChart, dotChart, elementRef, estimateTextWidth, findAccessibleColor, formatDate, formatNumber, generateAltText, generateAriaLabels, generateDataTable, getBreakpoint, getHeightClass, getLayoutStrategy, inferFieldType, isChartSpec, isConditionalDef, isEncodingChannel, isGraphSpec, isLayerSpec, isRangeAnnotation, isRefLineAnnotation, isTableSpec, isTextAnnotation, lineChart, meetsAA, pieChart, resolveCollisions, resolveMarkDef, resolveMarkType, resolveTheme, scatterChart, simulateColorBlindness };