@opendata-ai/openchart-engine 8.8.0 → 8.9.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _opendata_ai_openchart_core 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, GeoMapProjection, GeoMapEncoding, LegendConfig, GeoMapPointsLayer, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, TableDensity, SortState, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, GraphAnimationSpec, GraphInteractionConfig, ScaleType, EncodingChannel, FieldFormatContext, Rect, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform } 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, GeoMapProjection, GeoMapEncoding, LegendConfig, GeoMapPointsLayer, SankeyEncoding, SankeyNodeAlign, SankeyLinkColor, TileMapEncoding, TileMapPalette, MarkType, MarkDef, Encoding, ChromeText, Annotation, LabelConfig, Display, ColumnConfig, TableDensity, SortState, GraphSpec, GraphEncoding, GraphLayoutConfig, NodeOverride, GraphAnimationSpec, GraphInteractionConfig, ScaleType, EncodingChannel, FieldFormatContext, ResolvedLabel, Rect, ResolvedAnnotation, LayoutStrategy, VizSpec, Mark, BinTransform, CalculateTransform, ConditionalValueDef, FilterPredicate, TimeUnitTransform, Transform, ElementRef, TextAnnotation, ChartSpec, DesignDiagnostic, FieldMetadata, DatasetBinding, ReaderSelection, ObservationIdentity, SpecPatch, CompositionRecommendation, DesignQuestion } 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';
 
@@ -584,6 +584,7 @@ interface NormalizedChartSpec {
     responsive: boolean;
     /** Whether auto-thinning of annotations at narrow widths is enabled. Resolved from `responsive.autoThin`. */
     autoThin: boolean;
+    compactAnnotationLimit?: number | null;
     theme: ThemeConfig;
     darkMode: DarkMode;
     /** Whether the OpenData watermark is enabled. */
@@ -681,6 +682,8 @@ interface ValidationError {
 }
 /** Result of spec validation. */
 interface ValidationResult {
+    /** Advisory authored-option warnings; incompatible options remain accepted in 8.x. */
+    warnings?: string[];
     /** Whether the spec is valid. */
     valid: boolean;
     /** Validation errors (empty if valid). */
@@ -813,6 +816,28 @@ interface ArrowheadPoints {
  * @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;
+/**
+ * Rebuild a connector's geometry against a (possibly moved) annotation bounds.
+ *
+ * `from` comes from the ray-box exit; `to` is recomputed by pulling back from
+ * `connector.endpoint` — never from the already-pulled-back `to`, which would
+ * shrink the line a little more on every pass.
+ *
+ * Returns `undefined` when the connector should be suppressed: the target sits
+ * inside the text block, or the resulting line is shorter than
+ * `MIN_CONNECTOR_LENGTH`.
+ */
+declare function automaticControlPoint(from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}, exit?: 'horizontal' | 'vertical', bend?: number): {
+    x: number;
+    y: number;
+};
+declare function refreshConnector(connector: NonNullable<ResolvedLabel['connector']>, bounds: Rect, markerRadius: number, keepVisible?: boolean): ResolvedLabel['connector'];
 
 /**
  * Annotation placement engine: typed obstacles, candidate generation,
@@ -824,22 +849,22 @@ 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 ReferenceReserve {
+    right: number;
+    top: number;
+    labelWidth: number;
+}
+interface ReferenceLanes {
+    rightLabels?: ResolvedAnnotation[];
+    topBottom?: number;
+}
 
 interface AnnotationContext {
     scales: ResolvedScales;
     chartArea: Rect;
+    referenceContainer?: Rect;
+    referenceLanes?: ReferenceLanes;
+    referenceReserve?: ReferenceReserve;
     strategy: LayoutStrategy;
     isDark: boolean;
     obstacles: PlacementObstacle[];
@@ -850,7 +875,9 @@ interface AnnotationContext {
     measure: AnnotationMeasureTextFn;
     /** Theme font stack, so annotation text is measured and rendered in the same face. */
     fontFamily?: string;
+    colors?: _opendata_ai_openchart_core.ThemeColors;
     debugPlacement?: boolean;
+    onWarn?: (message: string) => void;
     /** When true, annotations that overlap are demoted to footnote markers instead of being hidden. */
     autoThin?: boolean;
     /**
@@ -893,24 +920,7 @@ declare function parseAnnotationSpans(line: string): RichSpan[];
  */
 declare function normalizeSpec(spec: VizSpec, warnings?: string[]): NormalizedSpec;
 
-/**
- * Runtime spec validation.
- *
- * TypeScript catches compile-time errors for specs written in code.
- * This module catches runtime errors for specs coming from JSON, APIs,
- * or Claude-generated output where the TypeScript compiler can't help.
- *
- * Every error includes a machine-readable code and an actionable suggestion
- * so consumers (and LLMs) can fix issues programmatically.
- */
-
-/**
- * Validate a spec at runtime.
- *
- * Checks structure, required fields, encoding rules, data shape, and
- * field type compatibility. Returns structured errors with machine-readable
- * codes and actionable suggestions for each problem found.
- */
+/** Validation warnings remain advisory throughout 8.x. */
 declare function validateSpec(spec: unknown): ValidationResult;
 
 /**
@@ -928,7 +938,9 @@ declare function validateSpec(spec: unknown): ValidationResult;
  * @returns CompileResult with the normalized spec and any warnings.
  * @throws Error if the spec is invalid.
  */
-declare function compile(spec: unknown): CompileResult;
+declare function compile(spec: unknown, options?: {
+    markOptionWarnings?: boolean;
+}): CompileResult;
 
 /**
  * Resolve which backend paints a chart's point marks: SVG (one `<circle>` per
@@ -1146,4 +1158,82 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
 
-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, MAX_3D_NODES, 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, buildArcPath, 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 };
+/** Frozen, engine-owned geometry for a single annotation editing gesture. */
+
+/** Opaque gesture snapshot. Create a new context after a committed edit or resize. */
+interface AnnotationEditContext {
+    readonly kind: 'annotation-edit-context';
+}
+/** Snapshot a compiled layout without asking callers to reconstruct scales or obstacles. */
+declare function createAnnotationEditContext(layout: ChartLayout, spec: unknown): AnnotationEditContext;
+/** Convert the rendered block box to an explicit placement, preserving its alignment. */
+declare function inverseLabelPlacement(ctx: AnnotationEditContext, ref: ElementRef, renderedBox: Rect): Pick<TextAnnotation, 'anchor' | 'offset' | 'responsive'>;
+/** Move only the label block; keep its data anchor and the surrounding layout frozen. */
+declare function previewAnnotationMove(ctx: AnnotationEditContext, ref: ElementRef, delta: {
+    dx: number;
+    dy: number;
+}): ResolvedAnnotation;
+/** Change a curve without moving its label, attachment, or marker. */
+declare function previewConnectorBend(ctx: AnnotationEditContext, ref: ElementRef, bend: number): ResolvedAnnotation;
+/** Preview a connector endpoint nudge without parsing rendered path geometry. */
+declare function previewConnectorOffset(ctx: AnnotationEditContext, ref: ElementRef, end: 'from' | 'to', delta: {
+    dx: number;
+    dy: number;
+}): ResolvedAnnotation;
+
+/** Sample label and attachment independently. Leader visibility is chosen by the final layout. */
+declare function interpolateAnnotationGeometry(before: ResolvedAnnotation, after: ResolvedAnnotation, t: number): ResolvedAnnotation;
+
+/** Checks use resolved geometry and authored metadata, never headline interpretation. */
+declare function diagnoseChart(spec: ChartSpec, layout: ChartLayout): DesignDiagnostic[];
+
+/** Type-tagging avoids collisions between e.g. 1 and "1". Missing keys are invalid. */
+declare function observationKey(value: unknown): string | null;
+declare function resolveObservationIdentities(data: DataRow[], keyField?: string, seriesField?: string): ObservationIdentity[];
+/** Filtering supplies all rows plus visible keys; deletion supplies a new full dataset. */
+declare function reconcileReaderSelection(selection: ReaderSelection, rows: DataRow[], keyField?: string, seriesField?: string, visibleKeys?: ReadonlySet<string>): ReaderSelection;
+interface ObservationComparison {
+    absolute: number;
+    relative?: number;
+    unit?: string;
+}
+/** Explicit metadata is required across views; same-field callers can share it. */
+declare function compareObservations(before: number, after: number, a: FieldMetadata, b: FieldMetadata): ObservationComparison | null;
+declare function linkedEntityKeys(row: DataRow, source: DatasetBinding, target: DatasetBinding): string[];
+
+/** JSON-pointer patch application is atomic: validate all paths before returning a new document. */
+declare function applySpecPatch(spec: VizSpec, patch: SpecPatch): VizSpec;
+
+interface RecommendationRoles {
+    measure?: string;
+    category?: string;
+    time?: string;
+    secondMeasure?: string;
+    series?: string;
+}
+interface RecommendationResult {
+    recommendations: CompositionRecommendation[];
+    missingRoles: string[];
+    explanation?: string;
+}
+/** Deterministic suggestions require an explicit question and field roles. No aggregation is inferred. */
+declare function recommendCompositions(data: DataRow[], question: DesignQuestion, roles: RecommendationRoles): RecommendationResult;
+
+/** A documented authored-spec change made by migrateSpecV8. */
+interface SpecRepair {
+    path: string;
+    from: unknown;
+    to: unknown;
+    reason: string;
+}
+/**
+ * Rewrite v8 aliases without mutating the input. Safe to run repeatedly.
+ * Legacy end-of-line labels become endpoint labels; their manual offsets are
+ * reported as lost repairs because the two placement models are different.
+ */
+declare function migrateSpecV8<T>(input: T): {
+    spec: T;
+    repairs: SpecRepair[];
+};
+
+export { ARROWHEAD_LENGTH, AUTO_CANVAS_THRESHOLD, type AnnotationContext, type AnnotationEditContext, 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, MAX_3D_NODES, type NormalizedBarListSpec, type NormalizedChartSpec, type NormalizedChrome, type NormalizedGeoMapSpec, type NormalizedGraphSpec, type NormalizedSankeySpec, type NormalizedSpec, type NormalizedTableSpec, type NormalizedTileMapSpec, type ObservationComparison, type ObstacleKind, type PlacementObstacle, type RecommendationResult, type RecommendationRoles, type RichSpan, type SimulationConfig, type SpecRepair, UPDATE_DEFAULTS, type ValidationError, type ValidationErrorCode, type ValidationResult, applySpecPatch, automaticControlPoint, buildArcPath, buildAreaPath, buildEdgeTooltip, buildLinePath, clampStaggerDelay, clearRenderers, compareObservations, compile, compileBarList, compileChart, compileGeoMap, compileGraph, compileLayer, compileSankey, compileTable, compileTileMap, computeArrowheadPoints, createAnnotationEditContext, dedupeKeys, diagnoseChart, evaluatePredicate, facetMinHeight, getChartRenderer, heuristicMeasure, interpolateAnnotationGeometry, inverseLabelPlacement, isConditionalValueDef, legendGap, linkedEntityKeys, migrateSpecV8, normalizeSpec, observationKey, parseAnnotationSpans, previewAnnotationMove, previewConnectorBend, previewConnectorOffset, recommendCompositions, reconcileReaderSelection, refreshConnector, registerChartRenderer, resolveAnimation, resolveConditionalValue, resolveObservationIdentities, runBin, runCalculate, runFilter, runTimeUnit, runTransforms, serializeKeyValue, validateSpec };