@opendata-ai/openchart-engine 7.2.4 → 7.4.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, AnimationSpec, ResolvedAnimation, DataRow, BarListEncoding, ThemeConfig, DarkMode, TileMapEncoding, TileMapPalette, LegendConfig, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, 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, 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';
 
@@ -416,6 +416,88 @@ interface NormalizedSankeySpec {
     linkOpacity?: number;
 }
 
+/** Continuous D3 scales (linear, time, log, pow, sqrt, symlog) that support .ticks() and .nice(). */
+type D3ContinuousScale = ScaleLinear<number, number> | ScaleTime<number, number> | ScaleLogarithmic<number, number> | ScalePower<number, number> | ScaleSymLog<number, number>;
+/** Discretizing D3 scales (quantile, quantize, threshold). */
+type D3DiscretizingScale = ScaleQuantile<number> | ScaleQuantize<number> | ScaleThreshold<number, number>;
+/** Categorical D3 scales (band, point, ordinal) that support .domain() as string[]. */
+type D3CategoricalScale = ScaleBand<string> | ScalePoint<string> | ScaleOrdinal<string, string>;
+/** Union of all D3 scale types used by the engine. */
+type D3Scale = D3ContinuousScale | D3CategoricalScale | D3DiscretizingScale;
+/** All resolved scale type identifiers. */
+type ResolvedScaleType = ScaleType | 'sequential';
+/**
+ * A resolved scale wrapping a d3 scale with type metadata.
+ * We need to carry the scale type around so axes and marks know
+ * how to interpret the domain/range. Consumers use the `type` discriminant
+ * to determine which D3 methods are available on the scale.
+ */
+interface ResolvedScale {
+    /** The d3 scale function. Maps domain value -> pixel position or color. */
+    scale: D3Scale;
+    /** The scale type for downstream use. */
+    type: ResolvedScaleType;
+    /** The encoding channel this scale was derived from. */
+    channel: EncodingChannel;
+}
+/** All resolved scales for a chart. */
+interface ResolvedScales {
+    x?: ResolvedScale;
+    y?: ResolvedScale;
+    color?: ResolvedScale;
+    size?: ResolvedScale;
+    /** Default color for single-series charts (first categorical palette color or markDef.fill gradient). */
+    defaultColor?: string | _opendata_ai_openchart_core.GradientDef;
+}
+
+/**
+ * Geometry utilities for annotation text bounds, connector origins, and offsets.
+ */
+
+type AnnotationMeasureTextFn = (text: string, font: {
+    fontSize: number;
+    fontWeight: number;
+    fontFamily?: string;
+}) => number;
+declare const heuristicMeasure: AnnotationMeasureTextFn;
+
+/**
+ * Annotation placement engine: typed obstacles, candidate generation,
+ * scored search, and two-pass deterministic placement.
+ */
+
+type ObstacleKind = 'mark' | 'line' | 'area-fill' | 'legend' | 'data-label' | 'endpoint-label' | 'watermark' | 'axis-band' | 'annotation';
+interface PlacementObstacle extends Rect {
+    kind: ObstacleKind;
+}
+
+/**
+ * Annotation computation: converts spec-level annotations to pixel-positioned
+ * ResolvedAnnotation objects using the resolved scales.
+ *
+ * Handles three annotation types:
+ * - text: positioned at a data coordinate with an optional callout
+ * - range: a highlighted rectangle between two data values
+ * - refline: a horizontal or vertical reference line at a data value
+ *
+ * Supports fine-grained positioning via offset, anchor, connector, and zIndex.
+ * At compact breakpoints, annotations are simplified or hidden.
+ */
+
+interface AnnotationContext {
+    scales: ResolvedScales;
+    chartArea: Rect;
+    strategy: LayoutStrategy;
+    isDark: boolean;
+    obstacles: PlacementObstacle[];
+    svg: {
+        width: number;
+        height: number;
+    };
+    measure: AnnotationMeasureTextFn;
+    debugPlacement?: boolean;
+}
+
 /**
  * Normalize a validated VizSpec, filling in all defaults.
  *
@@ -462,40 +544,6 @@ declare function validateSpec(spec: unknown): ValidationResult;
  */
 declare function compile(spec: unknown): CompileResult;
 
-/** Continuous D3 scales (linear, time, log, pow, sqrt, symlog) that support .ticks() and .nice(). */
-type D3ContinuousScale = ScaleLinear<number, number> | ScaleTime<number, number> | ScaleLogarithmic<number, number> | ScalePower<number, number> | ScaleSymLog<number, number>;
-/** Discretizing D3 scales (quantile, quantize, threshold). */
-type D3DiscretizingScale = ScaleQuantile<number> | ScaleQuantize<number> | ScaleThreshold<number, number>;
-/** Categorical D3 scales (band, point, ordinal) that support .domain() as string[]. */
-type D3CategoricalScale = ScaleBand<string> | ScalePoint<string> | ScaleOrdinal<string, string>;
-/** Union of all D3 scale types used by the engine. */
-type D3Scale = D3ContinuousScale | D3CategoricalScale | D3DiscretizingScale;
-/** All resolved scale type identifiers. */
-type ResolvedScaleType = ScaleType | 'sequential';
-/**
- * A resolved scale wrapping a d3 scale with type metadata.
- * We need to carry the scale type around so axes and marks know
- * how to interpret the domain/range. Consumers use the `type` discriminant
- * to determine which D3 methods are available on the scale.
- */
-interface ResolvedScale {
-    /** The d3 scale function. Maps domain value -> pixel position or color. */
-    scale: D3Scale;
-    /** The scale type for downstream use. */
-    type: ResolvedScaleType;
-    /** The encoding channel this scale was derived from. */
-    channel: EncodingChannel;
-}
-/** All resolved scales for a chart. */
-interface ResolvedScales {
-    x?: ResolvedScale;
-    y?: ResolvedScale;
-    color?: ResolvedScale;
-    size?: ResolvedScale;
-    /** Default color for single-series charts (first categorical palette color or markDef.fill gradient). */
-    defaultColor?: string | _opendata_ai_openchart_core.GradientDef;
-}
-
 /**
  * Chart renderer registry.
  *
@@ -508,10 +556,11 @@ interface ResolvedScales {
  * A chart renderer function.
  *
  * Takes a normalized spec, resolved scales, chart area, layout strategy,
- * and the resolved theme for theme-aware styling (e.g. label colors).
- * Returns an array of marks to render.
+ * the resolved theme for theme-aware styling (e.g. label colors), and the
+ * full container width (used by geometry gates that must key off the
+ * container, not the derived plot width). Returns an array of marks to render.
  */
-type ChartRenderer = (spec: NormalizedChartSpec, scales: ResolvedScales, chartArea: Rect, strategy: LayoutStrategy, theme: ResolvedTheme) => Mark[];
+type ChartRenderer = (spec: NormalizedChartSpec, scales: ResolvedScales, chartArea: Rect, strategy: LayoutStrategy, theme: ResolvedTheme, containerWidth: number) => Mark[];
 /**
  * Register a chart renderer for a specific chart type.
  *
@@ -671,4 +720,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 NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type SimulationConfig, type ValidationError, type ValidationErrorCode, type ValidationResult, clampStaggerDelay, clearRenderers, compile, compileBarList, compileChart, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, evaluatePredicate, getChartRenderer, isConditionalValueDef, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, validateSpec };
+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 };