@opendata-ai/openchart-engine 8.0.0-rc.9 → 8.1.0

package/dist/index.d.ts

@@ -1,8 +1,84 @@
 import * as _opendata_ai_openchart_core from '@opendata-ai/openchart-core';
-import { LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, ResolvedAnimationPhase, AnimationSpec, ResolvedAnimation, Point, DataRow, BarListEncoding, ThemeConfig, DarkMode, MapGeo, MapEncoding, LegendConfig, MapPointsLayer, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, FieldFormatContext, 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, MapLayout, MapSpec, SankeyLayout, SankeySpec, TableLayout, TableSpec, TileMapLayout, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
+import { AnimationEase, LegendLayout, ResolvedChrome, TooltipContent, A11yMetadata, ResolvedTheme, LegendEntry, CompileOptions, ChartLayout, LayerSpec, CompileTableOptions, TableLayout, ResolvedAnimationPhase, AnimationSpec, ResolvedAnimation, Point, DataRow, BarListEncoding, ThemeConfig, DarkMode, GeoMapGeo, GeoMapEncoding, LegendConfig, GeoMapPointsLayer, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, GraphAnimationSpec, GraphInteractionConfig, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, ScaleType, EncodingChannel, FieldFormatContext, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } from '@opendata-ai/openchart-core';
+export { BarListLayout, BarListSpec, ChartLayout, ChartSpec, CompileOptions, CompileTableOptions, GeoMapLayout, GeoMapSpec, 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';
 
+/**
+ * Graph animation resolver.
+ *
+ * Modeled on `compiler/animation.ts` but DEFAULT-ON (the deliberate chart/graph
+ * divergence): graphs already move on load, so choreography is the default and
+ * must be opted out of, not into.
+ *
+ * - `undefined` (omitted) -> full defaults
+ * - `false` -> undefined (no choreography; note `layout.warmup` still applies,
+ *   resolved independently into SimulationConfig)
+ * - object -> per-phase resolution; a per-phase `false` -> that phase is `null`
+ *
+ * `reheatAlpha` for the update impulse and the entrance `cameraFit` toggle are
+ * internal vanilla constants, not spec surface. Warmup is NOT part of this block
+ * (it lives in `layout`); `fitOnLoad` is a mount option.
+ */
+
+/** Fully resolved graph animation config consumed by the vanilla adapter. */
+interface ResolvedGraphAnimation {
+    /** Entrance reveal, or null if disabled. `cameraFit` flies the camera to the fit on load. */
+    enter: {
+        duration: number;
+        ease: AnimationEase;
+        stagger: boolean;
+        cameraFit: boolean;
+    } | null;
+    /** Data-update enter-fade for newly added marks, or null. */
+    update: {
+        duration: number;
+        ease: AnimationEase;
+    } | null;
+    /** Ghost fade-out for removed marks, or null. */
+    exit: {
+        duration: number;
+        ease: AnimationEase;
+    } | null;
+    /** Camera flight easing, or null. `'auto'` derives duration from zoom distance. */
+    camera: {
+        duration: number | 'auto';
+        ease: AnimationEase;
+    } | null;
+    /** Hover emphasis crossfade, or null. */
+    hover: {
+        duration: number;
+        ease: AnimationEase;
+    } | null;
+}
+
+/**
+ * Graph interaction resolver.
+ *
+ * Resolves `GraphInteractionConfig` into a flat, defaulted shape the vanilla
+ * adapter consumes. Category sets for `'category'` hover mode and
+ * `highlight({ category })` derive from the compilation's sort-resolved domains
+ * (not raw node data), so `getLegend()` and `highlight()` always agree.
+ */
+
+/** Hover emphasis behavior. */
+type GraphHoverMode = 'neighbors' | 'category' | 'node' | 'none';
+/** Fully resolved graph interaction config. */
+interface ResolvedGraphInteraction {
+    /** Hover emphasis mode. Default `'neighbors'`. */
+    hoverMode: GraphHoverMode;
+    /** Node dim tier during hover/focus. Default 0.15. */
+    dimOpacity: number;
+    /** Whether selecting a node flies the camera to it. Default false. */
+    selectFlyTo: boolean;
+    /** Cursor repulsion config, or null if disabled. */
+    cursorRepulsion: {
+        radius: number;
+        strength: number;
+    } | null;
+    /** Whether springy node drag is enabled. Default false. */
+    springyDrag: boolean;
+}
+
 /**
  * Graph compilation types.
  *
@@ -30,6 +106,8 @@ interface CompiledGraphNode {
     labelPriority: number;
     /** Community/cluster assignment from the clustering field. */
     community: string | undefined;
+    /** Opacity from the nodeOpacity encoding (default 1). Renderer multiplies into fill/stroke alpha. */
+    opacity: number;
     /** Original node data (all fields from the spec node). */
     data: Record<string, unknown>;
 }
@@ -71,6 +149,14 @@ interface SimulationConfig {
     linkStrength?: number;
     /** Whether to apply center force (default true). */
     centerForce?: boolean;
+    /** Deterministic layout seed (hashes into initial node positions). */
+    seed?: number;
+    /** Headless settle ticks run before first paint. 0/undefined disables warmup. */
+    warmupTicks?: number;
+    /** Wall-clock budget (ms) that caps warmup at scale. Default 250. */
+    warmupBudgetMs?: number;
+    /** Initial alpha for the simulation (update reheat / entrance). Default d3's 1. */
+    initialAlpha?: number;
 }
 /**
  * The complete engine output for graph specs.
@@ -103,6 +189,25 @@ interface GraphCompilation {
     simulationConfig: SimulationConfig;
     /** Whether to show the brand watermark. */
     watermark: boolean;
+    /** Resolved motion config, or undefined when `animation: false`. */
+    animation?: ResolvedGraphAnimation;
+    /** Resolved interaction config (always present, defaulted). */
+    interaction: ResolvedGraphInteraction;
+    /** The nodeColor field backing the legend/category emphasis, or null. */
+    legendField: string | null;
+    /** Categories to emphasize on load, captured from nodeColor.highlight. */
+    initialHighlight?: {
+        field: string;
+        values: string[];
+    };
+    /**
+     * Ids exempt from highlight/filter dimming (currently just `spec.seedNode`).
+     * Empty when no seed is set. Array-shaped so a future `pinnedNodes` needs no
+     * type change.
+     */
+    seedNodeIds: string[];
+    /** Edge legend entries (nominal edgeColor with >1 category), or undefined. */
+    edgeLegend?: LegendEntry[];
 }
 
 /**
@@ -173,18 +278,18 @@ declare function compileSankey(spec: unknown, options: CompileOptions): _opendat
  */
 declare function compileTileMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.TileMapLayout;
 /**
- * Compile a map spec into a MapLayout.
+ * Compile a map spec into a GeoMapLayout.
  *
  * Takes a raw map spec, validates, normalizes, resolves theme and chrome,
  * projects geo features, joins data, builds feature marks with color fills,
- * and returns a MapLayout ready for rendering.
+ * and returns a GeoMapLayout ready for rendering.
  *
  * @param spec - Raw map spec (validated and normalized internally).
  * @param options - Compile options (width, height, theme, darkMode).
- * @returns MapLayout with computed positions and visual properties.
+ * @returns GeoMapLayout with computed positions and visual properties.
  * @throws Error if spec is invalid or not a map type.
  */
-declare function compileMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.MapLayout;
+declare function compileGeoMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.GeoMapLayout;
 /**
  * Compile a barlist spec into a BarListLayout.
  *
@@ -199,6 +304,31 @@ declare function compileMap(spec: unknown, options: CompileOptions): _opendata_a
  */
 declare function compileBarList(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.BarListLayout;
 
+/**
+ * Graph compilation pipeline.
+ *
+ * Takes a raw graph spec (unknown shape), validates, normalizes, resolves
+ * encoding channels to visual properties, assigns communities, builds
+ * legend/tooltips/a11y, and returns a GraphCompilation.
+ *
+ * The pipeline mirrors compileChart's structure:
+ *   validate -> normalize -> resolve theme -> resolve visuals ->
+ *   community assignment -> legend -> tooltips -> a11y -> return
+ *
+ * Key difference from charts: the output does NOT include x/y positions.
+ * The force simulation in the adapter handles layout at runtime.
+ */
+
+/**
+ * Build a tooltip for a single edge, on demand.
+ *
+ * Construction is LAZY (called for the one hovered edge), not an eager O(E)
+ * descriptor map — edges outnumber nodes 5–10× and an eager map on every
+ * compile (including updateVisuals) would be pure bloat. Shows source → target
+ * and all non-structural data fields.
+ */
+declare function buildEdgeTooltip(edge: CompiledGraphEdge): TooltipContent;
+
 /**
  * Animation resolver: normalizes AnimationSpec into fully resolved config.
  *
@@ -289,11 +419,11 @@ interface NormalizedBarListSpec {
     valueFormat?: string;
 }
 
-interface NormalizedMapSpec {
+interface NormalizedGeoMapSpec {
     type: 'map';
-    geo: Required<MapGeo>;
+    geo: Required<GeoMapGeo>;
     data: Record<string, unknown>[];
-    encoding: MapEncoding;
+    encoding: GeoMapEncoding;
     chrome: NormalizedChrome;
     legend?: LegendConfig;
     theme: ThemeConfig;
@@ -301,7 +431,7 @@ interface NormalizedMapSpec {
     watermark: boolean;
     animation?: AnimationSpec;
     valueFormat?: string;
-    points?: MapPointsLayer;
+    points?: GeoMapPointsLayer;
 }
 
 /**
@@ -376,6 +506,13 @@ interface NormalizedChartSpec {
     data: DataRow[];
     encoding: Encoding;
     chrome: NormalizedChrome;
+    /**
+     * How chrome height interacts with the height budget. `'grow'` treats the
+     * container height as the plot budget and grows the SVG by the chrome height;
+     * `'subtract'` (default) shrinks the plot to fit chrome. Carried through from
+     * the spec so the layout pipeline can honor it.
+     */
+    chromeLayout?: 'subtract' | 'grow';
     /** Optional KPI metric cells, passed through unchanged. */
     metrics?: _opendata_ai_openchart_core.Metric[];
     /**
@@ -449,14 +586,25 @@ interface NormalizedGraphSpec {
     encoding: GraphEncoding;
     layout: GraphLayoutConfig;
     nodeOverrides?: Record<string, NodeOverride>;
+    /** Seed node, always in object form (the string shorthand is expanded). */
+    seedNode?: {
+        id: string;
+        style?: NodeOverride;
+    };
     chrome: NormalizedChrome;
     annotations: Annotation[];
     theme: ThemeConfig;
     darkMode: DarkMode;
     watermark: boolean;
+    animation?: GraphAnimationSpec;
+    interaction?: GraphInteractionConfig;
+    legend?: boolean | {
+        interactive?: boolean;
+        counts?: boolean;
+    };
 }
 /** Discriminated union of all normalized spec types. */
-type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec | NormalizedMapSpec | NormalizedBarListSpec;
+type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec | NormalizedGeoMapSpec | NormalizedBarListSpec;
 /** Machine-readable error code for programmatic handling. */
 type ValidationErrorCode = 'MISSING_FIELD' | 'INVALID_TYPE' | 'INVALID_VALUE' | 'ENCODING_MISMATCH' | 'DATA_FIELD_MISSING' | 'EMPTY_DATA';
 /** A single validation error with context. */
@@ -724,6 +872,21 @@ declare function validateSpec(spec: unknown): ValidationResult;
  */
 declare function compile(spec: unknown): CompileResult;
 
+/**
+ * Resolve which backend paints a chart's point marks: SVG (one `<circle>` per
+ * datum) or a canvas mark layer (batched paint calls).
+ *
+ * High-cardinality scatter plots are the only case where the trade is worth
+ * it, so canvas is refused for every other mark type and for the layout shapes
+ * the canvas layer cannot express (facets, layers, sparklines). Refusals are
+ * advisory: an explicit `'canvas'` request always warns, and an `'auto'`
+ * refusal warns only once the chart is dense enough for the SVG fallback to
+ * actually hurt (AUTO_CANVAS_REFUSAL_WARN_THRESHOLD).
+ */
+
+/** Point count above which `'auto'` prefers canvas over SVG. */
+declare const AUTO_CANVAS_THRESHOLD = 1000;
+
 /**
  * Chart renderer registry.
  *
@@ -921,4 +1084,4 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
 
-export { ARROWHEAD_LENGTH, type AnnotationContext, type AnnotationMeasureTextFn, type ArrowheadPoints, BOLD_SPAN_FONT_WEIGHT, type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, DEFAULT_ANNOTATION_FONT_SIZE, DEFAULT_LINE_HEIGHT, ENTER_DEFAULTS, EXIT_DEFAULTS, type GraphCompilation, type NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedMapSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type ObstacleKind, type PlacementObstacle, type RichSpan, type SimulationConfig, UPDATE_DEFAULTS, type ValidationError, type ValidationErrorCode, type ValidationResult, buildAreaPath, buildLinePath, clampStaggerDelay, clearRenderers, compile, compileBarList, compileChart, compileGraph, compileLayer, compileMap, compileSankey, compileTable, compileTileMap, computeArrowheadPoints, dedupeKeys, evaluatePredicate, facetMinHeight, getChartRenderer, heuristicMeasure, isConditionalValueDef, legendGap, normalizeSpec, parseAnnotationSpans, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, serializeKeyValue, validateSpec };
+export { ARROWHEAD_LENGTH, AUTO_CANVAS_THRESHOLD, type AnnotationContext, type AnnotationMeasureTextFn, type ArrowheadPoints, BOLD_SPAN_FONT_WEIGHT, type ChartRenderer, type CompileResult, type CompiledGraphEdge, type CompiledGraphNode, DEFAULT_ANNOTATION_FONT_SIZE, DEFAULT_LINE_HEIGHT, ENTER_DEFAULTS, EXIT_DEFAULTS, type GraphCompilation, type NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGeoMapSpec, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type ObstacleKind, type PlacementObstacle, type RichSpan, type SimulationConfig, UPDATE_DEFAULTS, type ValidationError, type ValidationErrorCode, type ValidationResult, buildAreaPath, buildEdgeTooltip, buildLinePath, clampStaggerDelay, clearRenderers, compile, compileBarList, compileChart, compileGeoMap, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, computeArrowheadPoints, dedupeKeys, evaluatePredicate, facetMinHeight, getChartRenderer, heuristicMeasure, isConditionalValueDef, legendGap, normalizeSpec, parseAnnotationSpans, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, serializeKeyValue, validateSpec };