@opendata-ai/openchart-engine 8.4.1 → 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;
@@ -1124,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 };

package/dist/index.js

@@ -7430,7 +7430,8 @@ function normalizeGraphSpec(spec, warnings) {
     watermark: spec.watermark ?? true,
     animation: spec.animation,
     interaction: spec.interaction,
-    legend: spec.legend
+    legend: spec.legend,
+    dimensions: spec.dimensions
   };
 }
 function normalizeTileMapSpec(spec, warnings) {
@@ -15109,6 +15110,9 @@ function resolveGraphInteraction(cfg) {
   };
 }
 
+// src/graphs/types.ts
+var MAX_3D_NODES = 2e3;
+
 // src/graphs/compile-graph.ts
 var graphNumberFormatter = defaultNumberFormatter8({ allIntegers: false, surface: "chart" });
 function mergeOverrides(...layers) {
@@ -15264,6 +15268,7 @@ function compileGraph(spec, options) {
     );
   }
   const graphSpec = normalized;
+  const numDimensions = resolveNumDimensions(graphSpec, options.onWarn);
   for (const [name, ch] of [
     ["nodeColor", graphSpec.encoding.nodeColor],
     ["edgeColor", graphSpec.encoding.edgeColor]
@@ -15405,9 +15410,39 @@ function compileGraph(spec, options) {
     legendField,
     initialHighlight,
     seedNodeIds,
-    edgeLegend
+    edgeLegend,
+    numDimensions
   };
 }
+function resolveNumDimensions(spec, onWarn) {
+  const requested = spec.dimensions;
+  if (requested !== void 0 && requested !== 2 && requested !== 3) {
+    throw new Error(
+      `Spec error: graph "dimensions" must be 2 or 3, received ${JSON.stringify(requested)}.`
+    );
+  }
+  if (requested !== 3) return 2;
+  if (spec.nodes.length > MAX_3D_NODES) {
+    onWarn?.(
+      `dimensions: 3 is unavailable for ${spec.nodes.length} nodes (the limit is ${MAX_3D_NODES}); rendering in 2D.`
+    );
+    return 2;
+  }
+  if (spec.interaction?.cursorRepulsion) {
+    onWarn?.("interaction.cursorRepulsion is not supported in 3D; it will be ignored.");
+  }
+  if (spec.interaction?.springyDrag) {
+    onWarn?.("interaction.springyDrag is not supported in 3D; it will be ignored.");
+  }
+  const hasStroke = (o) => o?.stroke !== void 0 || o?.strokeWidth !== void 0;
+  const strokeOverrides = Object.values(spec.nodeOverrides ?? {}).some(hasStroke) || hasStroke(spec.seedNode?.style);
+  if (strokeOverrides) {
+    onWarn?.(
+      "nodeOverrides/seedNode.style stroke and strokeWidth are not supported in 3D; they will be ignored."
+    );
+  }
+  return 3;
+}
 var DEFAULT_COLLISION_PADDING = 5;
 
 // src/layout/dimensions.ts
@@ -19970,6 +20005,7 @@ export {
   DEFAULT_LINE_HEIGHT,
   ENTER_DEFAULTS,
   EXIT_DEFAULTS,
+  MAX_3D_NODES,
   UPDATE_DEFAULTS,
   buildArcPath,
   buildAreaPath,