@opendata-ai/openchart-engine 7.8.0 → 7.9.1

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, AnimationSpec, ResolvedAnimation, DataRow, BarListEncoding, ThemeConfig, DarkMode, TileMapEncoding, TileMapPalette, LegendConfig, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, ResolvedAnimationPhase, AnimationSpec, ResolvedAnimation, Point, DataRow, BarListEncoding, ThemeConfig, DarkMode, TileMapEncoding, TileMapPalette, LegendConfig, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
 export { BarListLayout, BarListSpec, ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GraphLayout, GraphSpec, LayerSpec, SankeyLayout, SankeySpec, TableLayout, TableSpec, TileMapLayout, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
 import { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
@@ -189,11 +189,24 @@ declare function compileBarList(spec: unknown, options: CompileOptions): _openda
  * 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.
  */
 
+/** Default values for entrance animation. */
+declare const ENTER_DEFAULTS: ResolvedAnimationPhase;
+/** Default values for update (data transition) animation. */
+declare const UPDATE_DEFAULTS: ResolvedAnimationPhase;
+/** Default values for exit animation. */
+declare const EXIT_DEFAULTS: ResolvedAnimationPhase;
 /**
  * Resolve an AnimationSpec into a fully resolved config with all defaults filled.
  * Returns undefined if animation is disabled (false or omitted).
@@ -204,6 +217,52 @@ declare function resolveAnimation(spec: AnimationSpec | undefined): ResolvedAnim
  */
 declare function clampStaggerDelay(delay: number, elementCount: number): number;
 
+/**
+ * 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.
+ */
+/**
+ * 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
+ */
+declare function serializeKeyValue(v: unknown): string;
+/**
+ * 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.
+ */
+declare function dedupeKeys(keys: string[]): string[];
+
+/**
+ * Curve interpolation mapping and path builders.
+ *
+ * Maps Vega-Lite-style interpolation strings to d3-shape curve factories.
+ * Used by both line and area chart computations.
+ *
+ * Also exports pure path-builder helpers (`buildLinePath`, `buildAreaPath`)
+ * so downstream consumers (e.g. transition interpolators) can reconstruct
+ * SVG paths from point arrays without pulling in chart-specific code.
+ */
+
+/**
+ * Build an SVG path string from an array of points using d3 line generator.
+ * Accepts an optional interpolation string (defaults to 'monotone').
+ */
+declare function buildLinePath(points: Point[], interpolate?: string): string;
+/**
+ * Build an SVG path string for a filled area from top and bottom point arrays.
+ * Accepts an optional interpolation string (defaults to 'monotone').
+ */
+declare function buildAreaPath(topPoints: Point[], bottomPoints: Point[], interpolate?: string): string;
+
 /**
  * Internal normalized barlist spec type used by the compilation pipeline.
  */
@@ -733,4 +792,4 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
 
-export { type AnnotationContext, type AnnotationMeasureTextFn, type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, type GraphCompilation, type NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type ObstacleKind, type PlacementObstacle, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clampStaggerDelay, clearRenderers, compile, compileBarList, compileChart, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, evaluatePredicate, getChartRenderer, heuristicMeasure, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };
+export { type AnnotationContext, type AnnotationMeasureTextFn, type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, ENTER_DEFAULTS, EXIT_DEFAULTS, type GraphCompilation, type NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type ObstacleKind, type PlacementObstacle, type SimulationConfig, UPDATE_DEFAULTS, type ValidationError, type ValidationErrorCode, type ValidationResult, buildAreaPath, buildLinePath, clampStaggerDelay, clearRenderers, compile, compileBarList, compileChart, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, dedupeKeys, evaluatePredicate, getChartRenderer, heuristicMeasure, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, serializeKeyValue, validateSpec };