@opendata-ai/openchart-engine 7.11.0 → 8.0.0-rc.10

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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, 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 { 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 { ScaleLinear, ScaleTime, ScaleLogarithmic, ScalePower, ScaleSymLog, ScaleBand, ScalePoint, ScaleOrdinal, ScaleQuantile, ScaleQuantize, ScaleThreshold } from 'd3-scale';
 
 /**
@@ -113,11 +113,12 @@ interface GraphCompilation {
  * ChartLayout with positions, colors, and marks ready for rendering.
  *
  * @param spec - Raw chart spec (validated and normalized internally).
- * @param options - Compile options (width, height, theme, darkMode).
+ * @param optionsInput - Compile options (width, height, theme, darkMode).
+ *   Top-level spec width/height, when present, override the option values.
  * @returns ChartLayout with all computed positions.
  * @throws Error if spec is invalid or not a chart type.
  */
-declare function compileChart(spec: unknown, options: CompileOptions): ChartLayout;
+declare function compileChart(spec: unknown, optionsInput: CompileOptions): ChartLayout;
 declare function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLayout;
 /**
  * Compile a table spec into a TableLayout.
@@ -171,6 +172,19 @@ declare function compileSankey(spec: unknown, options: CompileOptions): _opendat
  * @throws Error if spec is invalid or not a tilemap type.
  */
 declare function compileTileMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.TileMapLayout;
+/**
+ * Compile a map spec into a MapLayout.
+ *
+ * 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.
+ *
+ * @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.
+ * @throws Error if spec is invalid or not a map type.
+ */
+declare function compileMap(spec: unknown, options: CompileOptions): _opendata_ai_openchart_core.MapLayout;
 /**
  * Compile a barlist spec into a BarListLayout.
  *
@@ -232,13 +246,6 @@ declare function clampStaggerDelay(delay: number, elementCount: number): number;
  * - 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[];
 
 /**
@@ -282,6 +289,21 @@ interface NormalizedBarListSpec {
     valueFormat?: string;
 }
 
+interface NormalizedMapSpec {
+    type: 'map';
+    geo: Required<MapGeo>;
+    data: Record<string, unknown>[];
+    encoding: MapEncoding;
+    chrome: NormalizedChrome;
+    legend?: LegendConfig;
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    watermark: boolean;
+    animation?: AnimationSpec;
+    valueFormat?: string;
+    points?: MapPointsLayer;
+}
+
 /**
  * Internal normalized tilemap spec type used by the compilation pipeline.
  *
@@ -356,6 +378,13 @@ interface NormalizedChartSpec {
     chrome: NormalizedChrome;
     /** Optional KPI metric cells, passed through unchanged. */
     metrics?: _opendata_ai_openchart_core.Metric[];
+    /**
+     * Searchable series highlight config. Present only when `seriesSearch` is
+     * enabled AND the spec has a categorical color encoding to search over.
+     */
+    seriesSearch?: _opendata_ai_openchart_core.SeriesSearchConfig;
+    /** Resolved "you draw it" config with defaults filled in. Present only when `youDrawIt` is enabled. */
+    youDrawIt?: _opendata_ai_openchart_core.YouDrawItConfig;
     annotations: Annotation[];
     /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets and color stay optional. */
     labels: Required<Pick<LabelConfig, 'density' | 'format' | 'prefix'>> & Pick<LabelConfig, 'offsets' | 'color' | 'fontSize' | 'suffix'>;
@@ -374,6 +403,8 @@ interface NormalizedChartSpec {
     hiddenSeries: string[];
     /** Per-series visual style overrides. */
     seriesStyles: Record<string, _opendata_ai_openchart_core.SeriesStyle>;
+    /** Author accessibility overrides (alt-text description, aria-hidden opt-out). */
+    a11y?: _opendata_ai_openchart_core.A11yConfig;
     /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
     display: Display;
     /** Resolve configuration for independent/shared scales in faceted charts. */
@@ -425,7 +456,7 @@ interface NormalizedGraphSpec {
     watermark: boolean;
 }
 /** Discriminated union of all normalized spec types. */
-type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec | NormalizedBarListSpec;
+type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec | NormalizedMapSpec | 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. */
@@ -509,6 +540,8 @@ interface ResolvedScale {
     type: ResolvedScaleType;
     /** The encoding channel this scale was derived from. */
     channel: EncodingChannel;
+    /** Per-field formatting context (extent, allIntegers) from the ORIGINAL data. */
+    formatContext?: FieldFormatContext;
 }
 /** All resolved scales for a chart. */
 interface ResolvedScales {
@@ -520,16 +553,66 @@ interface ResolvedScales {
     defaultColor?: string | _opendata_ai_openchart_core.GradientDef;
 }
 
+/** Default font size for annotation labels. */
+declare const DEFAULT_ANNOTATION_FONT_SIZE = 13;
+/** Default line height multiplier for annotation text. */
+declare const DEFAULT_LINE_HEIGHT = 1.3;
+/**
+ * Arrowhead length along the tangent. The renderer pulls the connector's line end
+ * back by exactly this much so the stroke stops at the open V instead of poking
+ * through its tip — a hand-copied duplicate on the vanilla side would silently
+ * drift the next time this changes.
+ */
+declare const ARROWHEAD_LENGTH = 7;
+
 /**
  * Geometry utilities for annotation text bounds, connector origins, and offsets.
  */
 
+/**
+ * Measure one run of text at a given size and weight.
+ *
+ * Deliberately takes no `fontFamily`: neither implementation could use one.
+ * `heuristicMeasure` below is family-blind, and the real canvas measurer gets its
+ * family from the `createMeasureText(fontFamily)` closure, not per call -- so a
+ * family passed here would be silently dropped while implying the opposite.
+ * `style.fontFamily` on a *resolved label* is a different thing: that one is real
+ * and gets rendered.
+ */
 type AnnotationMeasureTextFn = (text: string, font: {
     fontSize: number;
     fontWeight: number;
-    fontFamily?: string;
 }) => number;
 declare const heuristicMeasure: AnnotationMeasureTextFn;
+/** Arrowhead triangle points: tip + two base corners. */
+interface ArrowheadPoints {
+    tip: {
+        x: number;
+        y: number;
+    };
+    baseLeft: {
+        x: number;
+        y: number;
+    };
+    baseRight: {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Compute arrowhead triangle geometry at a connector endpoint.
+ * Returns the tip (at the endpoint) and two base corners perpendicular to the
+ * tangent direction.
+ *
+ * @param tipX - X coordinate of the arrowhead tip
+ * @param tipY - Y coordinate of the arrowhead tip
+ * @param tangentX - X component of the tangent direction (toward the tip)
+ * @param tangentY - Y component of the tangent direction (toward the tip)
+ * @param length - Arrow length along the tangent (default ARROWHEAD_LENGTH)
+ * @param halfWidth - Arrow half-width perpendicular to tangent (default ARROWHEAD_HALF_WIDTH)
+ */
+declare function computeArrowheadPoints(tipX: number, tipY: number, tangentX: number, tangentY: number, length?: number, halfWidth?: number): ArrowheadPoints;
 
 /**
  * Annotation placement engine: typed obstacles, candidate generation,
@@ -565,11 +648,36 @@ interface AnnotationContext {
         height: number;
     };
     measure: AnnotationMeasureTextFn;
+    /** Theme font stack, so annotation text is measured and rendered in the same face. */
+    fontFamily?: string;
     debugPlacement?: boolean;
     /** When true, annotations that overlap are demoted to footnote markers instead of being hidden. */
     autoThin?: boolean;
 }
 
+/**
+ * Inline rich text for annotation labels: `**bold**` spans inside an otherwise
+ * regular-weight sentence. This is the NYT/Datawrapper voice — emphasis lands on
+ * the key phrase, not on the whole block.
+ */
+/** One run of annotation text at a single weight. */
+interface RichSpan {
+    text: string;
+    bold: boolean;
+}
+/** Weight bold spans are measured and rendered at. */
+declare const BOLD_SPAN_FONT_WEIGHT = 700;
+/**
+ * Parse `**bold**` markers in a single line of annotation text.
+ *
+ * Only matched pairs turn bold; an unmatched `**` renders literally, so specs
+ * that legitimately contain asterisks are never mangled. Empty `****` also
+ * renders literally (there's nothing to emphasize).
+ *
+ * The line is expected to be a single line — callers split on `\n` first.
+ */
+declare function parseAnnotationSpans(line: string): RichSpan[];
+
 /**
  * Normalize a validated VizSpec, filling in all defaults.
  *
@@ -658,6 +766,8 @@ declare function getChartRenderer(type: string): ChartRenderer | undefined;
  */
 declare function clearRenderers(): void;
 
+declare function facetMinHeight(panelCount: number, columns: number): number;
+
 /**
  * Legend row-wrap geometry.
  *
@@ -811,4 +921,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, 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, legendGap, normalizeSpec, registerChartRenderer, resolveAnimation, resolveConditionalValue, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, serializeKeyValue, validateSpec };
+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 };