@opendata-ai/openchart-engine 8.4.0 → 8.5.0

package/dist/index.d.ts

@@ -208,7 +208,23 @@ interface GraphCompilation {
     seedNodeIds: string[];
     /** Edge legend entries (nominal edgeColor with >1 category), or undefined. */
     edgeLegend?: LegendEntry[];
+    /**
+     * Resolved render dimensionality. `3` only when the spec asked for it AND the
+     * node count is within {@link MAX_3D_NODES}; otherwise `2`.
+     */
+    numDimensions: 2 | 3;
 }
+/**
+ * Node ceiling for 3D rendering. The 3D simulation runs on the main thread, so
+ * a spec above this falls back to 2D with a warning rather than freezing the
+ * page.
+ *
+ * The number is measured, not guessed. On the RFC 27 gate rig (headed Chromium,
+ * ANGLE/Metal, 900x600, DPR 2) an idle 3,000-node / ~6,000-edge scene held
+ * 22-27fps against a 30fps floor, while 2,000 held 38-44fps. Every edge is a
+ * separate draw call, which is what the ceiling is really made of.
+ */
+declare const MAX_3D_NODES = 2000;
 
 /**
  * Compile a chart spec into a ChartLayout.
@@ -645,6 +661,8 @@ interface NormalizedGraphSpec {
         interactive?: boolean;
         counts?: boolean;
     };
+    /** Requested render dimensionality. Validated (and gated) in compileGraph. */
+    dimensions?: 2 | 3;
 }
 /** Discriminated union of all normalized spec types. */
 type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec | NormalizedSankeySpec | NormalizedTileMapSpec | NormalizedGeoMapSpec | NormalizedBarListSpec;
@@ -801,7 +819,7 @@ declare function computeArrowheadPoints(tipX: number, tipY: number, tangentX: nu
  * scored search, and two-pass deterministic placement.
  */
 
-type ObstacleKind = 'mark' | 'line' | 'area-fill' | 'legend' | 'data-label' | 'endpoint-label' | 'watermark' | 'axis-band' | 'annotation';
+type ObstacleKind = 'mark' | 'line' | 'area-fill' | 'legend' | 'data-label' | 'endpoint-label' | 'watermark' | 'axis-band' | 'annotation' | 'chrome';
 interface PlacementObstacle extends Rect {
     kind: ObstacleKind;
 }
@@ -835,6 +853,12 @@ interface AnnotationContext {
     debugPlacement?: boolean;
     /** When true, annotations that overlap are demoted to footnote markers instead of being hidden. */
     autoThin?: boolean;
+    /**
+     * First y an annotation label may occupy, in SVG coordinates. Callers pass
+     * the bottom of the top chrome block so hand-placed callouts stay clear of
+     * the title/subtitle. Defaults to the plain SVG clamp margin.
+     */
+    topBound?: number;
 }
 
 /**
@@ -1118,4 +1142,4 @@ 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, 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 };
+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 };