@opendata-ai/openchart-engine 8.0.0 → 8.1.0

package/dist/index.d.ts

@@ -200,6 +200,12 @@ interface GraphCompilation {
         field: string;
         values: string[];
     };
+    /**
+     * Ids exempt from highlight/filter dimming (currently just `spec.seedNode`).
+     * Empty when no seed is set. Array-shaped so a future `pinnedNodes` needs no
+     * type change.
+     */
+    seedNodeIds: string[];
     /** Edge legend entries (nominal edgeColor with >1 category), or undefined. */
     edgeLegend?: LegendEntry[];
 }
@@ -580,6 +586,11 @@ interface NormalizedGraphSpec {
     encoding: GraphEncoding;
     layout: GraphLayoutConfig;
     nodeOverrides?: Record<string, NodeOverride>;
+    /** Seed node, always in object form (the string shorthand is expanded). */
+    seedNode?: {
+        id: string;
+        style?: NodeOverride;
+    };
     chrome: NormalizedChrome;
     annotations: Annotation[];
     theme: ThemeConfig;
@@ -861,6 +872,21 @@ declare function validateSpec(spec: unknown): ValidationResult;
  */
 declare function compile(spec: unknown): CompileResult;
 
+/**
+ * Resolve which backend paints a chart's point marks: SVG (one `<circle>` per
+ * datum) or a canvas mark layer (batched paint calls).
+ *
+ * High-cardinality scatter plots are the only case where the trade is worth
+ * it, so canvas is refused for every other mark type and for the layout shapes
+ * the canvas layer cannot express (facets, layers, sparklines). Refusals are
+ * advisory: an explicit `'canvas'` request always warns, and an `'auto'`
+ * refusal warns only once the chart is dense enough for the SVG fallback to
+ * actually hurt (AUTO_CANVAS_REFUSAL_WARN_THRESHOLD).
+ */
+
+/** Point count above which `'auto'` prefers canvas over SVG. */
+declare const AUTO_CANVAS_THRESHOLD = 1000;
+
 /**
  * Chart renderer registry.
  *
@@ -1058,4 +1084,4 @@ declare function runTimeUnit(data: DataRow[], transform: TimeUnitTransform): Dat
  */
 declare function runTransforms(data: DataRow[], transforms: Transform[]): DataRow[];
 
-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 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, 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, 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, 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

@@ -10595,11 +10595,16 @@ function normalizeSankeySpec(spec, _warnings) {
     watermark: spec.watermark ?? true
   };
 }
-function normalizeGraphSpec(spec) {
+function normalizeGraphSpec(spec, warnings) {
   const layout = {
     type: "force",
     ...spec.layout
   };
+  let seedNode = typeof spec.seedNode === "string" ? { id: spec.seedNode } : spec.seedNode;
+  if (seedNode && !spec.nodes.some((n) => n.id === seedNode?.id)) {
+    warnings.push(`seedNode "${seedNode.id}" does not match any node id; it will be ignored.`);
+    seedNode = void 0;
+  }
   return {
     type: "graph",
     nodes: spec.nodes,
@@ -10607,6 +10612,7 @@ function normalizeGraphSpec(spec) {
     encoding: spec.encoding ?? {},
     layout,
     nodeOverrides: spec.nodeOverrides,
+    seedNode,
     chrome: normalizeChrome(spec.chrome),
     annotations: normalizeAnnotations(spec.annotations),
     theme: spec.theme ?? {},
@@ -10722,7 +10728,7 @@ function normalizeSpec(spec, warnings = []) {
     return normalizeTableSpec(spec, warnings);
   }
   if (isGraphSpec(spec)) {
-    return normalizeGraphSpec(spec);
+    return normalizeGraphSpec(spec, warnings);
   }
   if (isSankeySpec(spec)) {
     return normalizeSankeySpec(spec, warnings);
@@ -11624,6 +11630,35 @@ function validateGraphSpec(spec, errors) {
       nodeIds.add(node.id);
     }
   }
+  if (spec.seedNode !== void 0) {
+    if (typeof spec.seedNode === "string") {
+      if (spec.seedNode === "") {
+        errors.push({
+          message: 'Spec error: "seedNode" must be a non-empty node id',
+          path: "seedNode",
+          code: "MISSING_FIELD",
+          suggestion: `Use one of the existing node ids, e.g. seedNode: "${[...nodeIds][0] ?? "a"}"`
+        });
+      }
+    } else if (typeof spec.seedNode !== "object" || spec.seedNode === null || Array.isArray(spec.seedNode)) {
+      errors.push({
+        message: `Spec error: "seedNode" must be a node id string or an object like { id, style }, got ${Array.isArray(spec.seedNode) ? "array" : typeof spec.seedNode}`,
+        path: "seedNode",
+        code: "INVALID_TYPE",
+        suggestion: `Use the id shorthand (seedNode: "${[...nodeIds][0] ?? "a"}") or the object form (seedNode: { id: "${[...nodeIds][0] ?? "a"}", style: { radius: 14 } })`
+      });
+    } else {
+      const seedId = spec.seedNode.id;
+      if (typeof seedId !== "string" || seedId === "") {
+        errors.push({
+          message: 'Spec error: "seedNode" must have a non-empty string "id" field',
+          path: "seedNode.id",
+          code: "MISSING_FIELD",
+          suggestion: `Add the seed node id, e.g. seedNode: { id: "${[...nodeIds][0] ?? "a"}" }`
+        });
+      }
+    }
+  }
   if (!Array.isArray(spec.edges)) {
     errors.push({
       message: 'Spec error: graph spec requires an "edges" array',
@@ -13513,9 +13548,9 @@ function buildBandScale(channel, data, rangeStart, rangeEnd, defaultPadding = DE
   }
   return { scale, type: "band", channel };
 }
-function buildPointScale(channel, data, rangeStart, rangeEnd) {
+function buildPointScale(channel, data, rangeStart, rangeEnd, defaultPadding = 0.5) {
   const values = channel.scale?.domain ? channel.scale.domain : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
-  const padding = channel.scale?.padding ?? channel.scale?.paddingOuter ?? 0.5;
+  const padding = channel.scale?.padding ?? channel.scale?.paddingOuter ?? defaultPadding;
   const scale = point().domain(values).range([rangeStart, rangeEnd]).padding(padding);
   if (channel.scale?.reverse) {
     const [r0, r1] = scale.range();
@@ -13592,7 +13627,7 @@ function buildPositionalScale(channel, data, rangeStart, rangeEnd, chartType, ax
       case "point":
         return buildPointScale(channel, data, rangeStart, rangeEnd);
       case "ordinal":
-        return buildBandScale(channel, data, rangeStart, rangeEnd);
+        return buildCategoricalScale(channel, data, rangeStart, rangeEnd, chartType, axis);
     }
   }
   switch (channel.type) {
@@ -13602,17 +13637,21 @@ function buildPositionalScale(channel, data, rangeStart, rangeEnd, chartType, ax
       return buildLinearScale(channel, data, rangeStart, rangeEnd);
     case "nominal":
     case "ordinal":
-      if (chartType === "rect") {
-        return buildBandScale(channel, data, rangeStart, rangeEnd, HEATMAP_BAND_PADDING);
-      }
-      if (chartType === "bar" || chartType === "beeswarm" || chartType === "range" || (chartType === "circle" || chartType === "lollipop") && axis === "y") {
-        return buildBandScale(channel, data, rangeStart, rangeEnd);
-      }
-      return buildPointScale(channel, data, rangeStart, rangeEnd);
+      return buildCategoricalScale(channel, data, rangeStart, rangeEnd, chartType, axis);
     default:
       return buildLinearScale(channel, data, rangeStart, rangeEnd);
   }
 }
+function buildCategoricalScale(channel, data, rangeStart, rangeEnd, chartType, axis) {
+  if (chartType === "rect") {
+    return buildBandScale(channel, data, rangeStart, rangeEnd, HEATMAP_BAND_PADDING);
+  }
+  if (chartType === "bar" || chartType === "beeswarm" || chartType === "range" || (chartType === "circle" || chartType === "lollipop") && axis === "y") {
+    return buildBandScale(channel, data, rangeStart, rangeEnd);
+  }
+  const isTrendMark = chartType === "line" || chartType === "area";
+  return buildPointScale(channel, data, rangeStart, rangeEnd, isTrendMark ? 0 : 0.5);
+}
 function computeScales(spec, chartArea, data) {
   const result = {};
   const encoding = spec.encoding;
@@ -14764,6 +14803,32 @@ function applyBandLabelStride(ticks2, stride) {
   const lastIdx = ticks2.length - 1;
   return ticks2.filter((_, i) => (lastIdx - i) % stride === 0);
 }
+var LABEL_EDGE_GUARD = 2;
+function clampXTickLabels(ticks2, totalWidth, tickAngle, fontSize, fontWeight, measureText) {
+  const rotated = tickAngle !== void 0 && Math.abs(tickAngle) > 10;
+  const rad = rotated ? Math.abs(tickAngle) * Math.PI / 180 : 0;
+  const across = rotated ? fontSize * 1.2 * Math.sin(rad) / 2 : 0;
+  return ticks2.map((tick) => {
+    const width = measureLabel(tick.label, fontSize, fontWeight, measureText);
+    let left2;
+    let right2;
+    if (rotated) {
+      const along = width * Math.cos(rad);
+      const trailsLeft = tickAngle < 0;
+      left2 = trailsLeft ? -(along + across) : -across;
+      right2 = trailsLeft ? across : along + across;
+    } else {
+      left2 = -width / 2;
+      right2 = width / 2;
+    }
+    let x2 = tick.position;
+    const overRight = x2 + right2 - (totalWidth - LABEL_EDGE_GUARD);
+    if (overRight > 0) x2 -= overRight;
+    const overLeft = LABEL_EDGE_GUARD - (x2 + left2);
+    if (overLeft > 0) x2 += overLeft;
+    return x2 === tick.position ? tick : { ...tick, labelPosition: x2 };
+  });
+}
 function computeAxes(scales, chartArea, strategy, theme, measureText, dataContext) {
   const result = {};
   const baseDensity = strategy.axisLabelDensity;
@@ -14976,6 +15041,14 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
   const totalWidth = dataContext?.totalWidth ?? chartArea.x + chartArea.width;
   if (result.x) {
     const isRotated = !!result.x.tickAngle && Math.abs(result.x.tickAngle) > 10;
+    result.x.ticks = clampXTickLabels(
+      result.x.ticks,
+      totalWidth,
+      result.x.tickAngle,
+      result.x.tickLabelStyle.fontSize,
+      result.x.tickLabelStyle.fontWeight,
+      measureText
+    );
     result.x.extent = computeXAxisExtentFromLabels({
       labels: result.x.ticks.map((t) => t.label),
       tickAngle: result.x.tickAngle,
@@ -19498,6 +19571,16 @@ function resolveGraphInteraction(cfg) {
 
 // src/graphs/compile-graph.ts
 var graphNumberFormatter = defaultNumberFormatter8({ allIntegers: false, surface: "chart" });
+function mergeOverrides(...layers) {
+  const merged = {};
+  for (const layer of layers) {
+    if (!layer) continue;
+    for (const [key, value2] of Object.entries(layer)) {
+      if (value2 !== void 0) merged[key] = value2;
+    }
+  }
+  return merged;
+}
 var SWATCH_SIZE2 = 12;
 var SWATCH_GAP2 = 6;
 var ENTRY_GAP2 = 16;
@@ -19658,12 +19741,23 @@ function compileGraph(spec, options) {
   if (options.darkMode) {
     theme = adaptTheme3(theme);
   }
+  const seedNodeIds = graphSpec.seedNode ? [graphSpec.seedNode.id] : [];
+  const nodeOverrides = graphSpec.seedNode ? {
+    ...graphSpec.nodeOverrides,
+    [graphSpec.seedNode.id]: mergeOverrides(
+      // Radius is deliberately absent so the seed doesn't fight a nodeSize
+      // encoding; a host wanting a bigger seed sets seedNode.style.radius.
+      { stroke: theme.colors.text, strokeWidth: 2, alwaysShowLabel: true },
+      graphSpec.seedNode.style,
+      graphSpec.nodeOverrides?.[graphSpec.seedNode.id]
+    )
+  } : graphSpec.nodeOverrides;
   const compiledNodes = resolveNodeVisuals(
     graphSpec.nodes,
     graphSpec.encoding,
     graphSpec.edges,
     theme,
-    graphSpec.nodeOverrides
+    nodeOverrides
   );
   const clusteringField = graphSpec.layout.clustering?.field;
   const hasCommunities = !!clusteringField;
@@ -19769,6 +19863,7 @@ function compileGraph(spec, options) {
     interaction,
     legendField,
     initialHighlight,
+    seedNodeIds,
     edgeLegend
   };
 }
@@ -23610,6 +23705,10 @@ function compileChart(spec, optionsInput) {
     watermark = false;
     chartSpec = { ...chartSpec, watermark: false };
   }
+  if (heightClass === "cramped" && !chartSpec.userExplicit.watermark) {
+    watermark = false;
+    chartSpec = { ...chartSpec, watermark: false };
+  }
   const mergedThemeConfig = options.theme ? { ...chartSpec.theme, ...options.theme } : chartSpec.theme;
   let theme = resolveTheme7(mergedThemeConfig);
   if (options.darkMode) {
@@ -24218,6 +24317,7 @@ function compileBarList2(spec, options) {
 }
 export {
   ARROWHEAD_LENGTH,
+  AUTO_CANVAS_THRESHOLD,
   BOLD_SPAN_FONT_WEIGHT,
   DEFAULT_ANNOTATION_FONT_SIZE,
   DEFAULT_LINE_HEIGHT,