@opendata-ai/openchart-engine 1.2.0 → 2.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @opendata-ai/openchart-engine
+
+Headless compiler for OpenChart. Takes a spec (plain JSON), validates it, and produces a fully resolved layout with computed positions, scales, marks, and accessibility metadata. No DOM dependency.
+
+## Install
+
+```bash
+npm install @opendata-ai/openchart-engine
+```
+
+You typically don't install this directly. The framework packages (`openchart-react`, `openchart-vue`, `openchart-svelte`) and the vanilla adapter include it as a dependency.
+
+## Core API
+
+### compile()
+
+The main entry point. Accepts any `VizSpec` and returns the compiled layout:
+
+```typescript
+import { compile } from '@opendata-ai/openchart-engine';
+
+const result = compile(spec, {
+  width: 600,
+  height: 400,
+  darkMode: false,
+});
+// result is a ChartLayout, TableLayout, or GraphCompilation
+```
+
+### compileChart()
+
+Compiles a `ChartSpec` into a `ChartLayout` with positioned marks, axes, gridlines, legends, and annotations:
+
+```typescript
+import { compileChart } from '@opendata-ai/openchart-engine';
+
+const layout = compileChart(chartSpec, { width: 600, height: 400 });
+// layout.marks: positioned line paths, bar rects, arc segments, etc.
+// layout.axes: tick positions, labels, format strings
+// layout.legend: entries, position, dimensions
+// layout.annotations: pixel-positioned annotation elements
+// layout.theme: fully resolved theme with all defaults filled
+```
+
+### compileTable()
+
+Compiles a `TableSpec` into a `TableLayout` with resolved columns, formatted cells, and visual enhancements:
+
+```typescript
+import { compileTable } from '@opendata-ai/openchart-engine';
+
+const layout = compileTable(tableSpec, { darkMode: false });
+```
+
+### compileGraph()
+
+Compiles a `GraphSpec` into a `GraphCompilation` with resolved node/edge visuals and simulation config. Note: the engine doesn't compute node positions. That happens at runtime via a force simulation in the vanilla adapter.
+
+```typescript
+import { compileGraph } from '@opendata-ai/openchart-engine';
+
+const compilation = compileGraph(graphSpec, { width: 600, height: 400 });
+// compilation.nodes: visual properties (size, color, label) resolved
+// compilation.edges: visual properties (width, color) resolved
+// compilation.simulationConfig: force parameters for the layout engine
+```
+
+### validateSpec()
+
+Runtime validation of any spec. Returns structured errors with paths and suggestions:
+
+```typescript
+import { validateSpec } from '@opendata-ai/openchart-engine';
+
+const result = validateSpec(spec);
+if (!result.valid) {
+  for (const error of result.errors) {
+    console.log(`${error.path}: ${error.message}`);
+    console.log(`  Suggestion: ${error.suggestion}`);
+  }
+}
+```
+
+### normalizeSpec()
+
+Fills in defaults and resolves shorthand without validation. Useful when you know the spec is valid and want the normalized form:
+
+```typescript
+import { normalizeSpec } from '@opendata-ai/openchart-engine';
+
+const normalized = normalizeSpec(spec);
+// All optional fields resolved to their defaults
+```
+
+## Chart renderer registry
+
+Chart types are registered via a plugin pattern. The engine ships with all 8 types pre-registered (line, area, bar, column, pie, donut, dot, scatter). For advanced use, you can register custom renderers:
+
+```typescript
+import { registerChartRenderer, getChartRenderer, clearRenderers } from '@opendata-ai/openchart-engine';
+
+registerChartRenderer('custom', myCustomRenderer);
+```
+
+## Re-exports
+
+For convenience, this package re-exports all types from `@opendata-ai/openchart-core`, so you can import types from either package.
+
+## Related docs
+
+- [Architecture](../../docs/architecture.md) for how the compilation pipeline works
+- [Spec reference](../../docs/spec-reference.md) for field-by-field type details

package/dist/index.js

@@ -12,6 +12,7 @@ import {
 import { estimateTextWidth } from "@opendata-ai/openchart-core";
 var DEFAULT_ANNOTATION_FONT_SIZE = 12;
 var DEFAULT_ANNOTATION_FONT_WEIGHT = 400;
+var DEFAULT_LINE_HEIGHT = 1.3;
 var DEFAULT_RANGE_FILL = "#f0c040";
 var DEFAULT_RANGE_OPACITY = 0.15;
 var DEFAULT_REFLINE_DASH = "4 3";
@@ -53,10 +54,23 @@ function makeAnnotationLabelStyle(fontSize, fontWeight, fill, isDark) {
     fontSize: fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE,
     fontWeight: fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT,
     fill: fill ?? defaultFill,
-    lineHeight: 1.3,
+    lineHeight: DEFAULT_LINE_HEIGHT,
     textAnchor: "start"
   };
 }
+function computeTextBounds(labelX, labelY, text, fontSize, fontWeight) {
+  const lines = text.split("\n");
+  const isMultiLine = lines.length > 1;
+  const maxWidth = Math.max(...lines.map((line3) => estimateTextWidth(line3, fontSize, fontWeight)));
+  const totalHeight = lines.length * fontSize * DEFAULT_LINE_HEIGHT;
+  const x = isMultiLine ? labelX - maxWidth / 2 : labelX;
+  return {
+    x,
+    y: labelY - fontSize,
+    width: maxWidth,
+    height: totalHeight
+  };
+}
 function computeAnchorOffset(anchor, _px, py, chartArea) {
   if (!anchor || anchor === "auto") {
     const isUpperHalf = py < chartArea.y + chartArea.height / 2;
@@ -80,6 +94,25 @@ function applyOffset(base, offset) {
     dy: base.dy + (offset.dy ?? 0)
   };
 }
+function computeConnectorOrigin(labelX, labelY, text, fontSize, fontWeight, targetX, targetY, connectorStyle) {
+  const box = computeTextBounds(labelX, labelY, text, fontSize, fontWeight);
+  const boxCenterX = box.x + box.width / 2;
+  const boxCenterY = box.y + box.height / 2;
+  if (connectorStyle === "curve") {
+    return {
+      x: box.x + box.width,
+      y: boxCenterY
+    };
+  }
+  const halfW = box.width / 2 || 1;
+  const halfH = box.height / 2 || 1;
+  const ndx = (targetX - boxCenterX) / halfW;
+  const ndy = (targetY - boxCenterY) / halfH;
+  if (Math.abs(ndy) >= Math.abs(ndx)) {
+    return ndy < 0 ? { x: boxCenterX, y: box.y } : { x: boxCenterX, y: box.y + box.height };
+  }
+  return ndx < 0 ? { x: box.x, y: boxCenterY } : { x: box.x + box.width, y: boxCenterY };
+}
 function resolveTextAnnotation(annotation, scales, chartArea, isDark) {
   const px = resolvePosition(annotation.x, scales.x);
   const py = resolvePosition(annotation.y, scales.y);
@@ -99,17 +132,16 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark) {
   const connectorStyle = annotation.connector === "curve" ? "curve" : "straight";
   const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = annotation.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lines = annotation.text.split("\n");
-  const lineHeight = 1.3;
-  let connectorFromX;
-  if (connectorStyle === "curve") {
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight);
-  } else if (lines.length > 1) {
-    connectorFromX = labelX;
-  } else {
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight) / 2;
-  }
-  const connectorFromY = labelY + (lines.length - 1) * fontSize * lineHeight + fontSize * 0.3;
+  const { x: connectorFromX, y: connectorFromY } = computeConnectorOrigin(
+    labelX,
+    labelY,
+    annotation.text,
+    fontSize,
+    fontWeight,
+    px,
+    py,
+    connectorStyle
+  );
   const baseFrom = { x: connectorFromX, y: connectorFromY };
   const baseTo = { x: px, y: py };
   const adjustedFrom = {
@@ -245,20 +277,9 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark) {
   };
 }
 function estimateLabelBounds(label) {
-  const lines = label.text.split("\n");
   const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lineHeight = label.style.lineHeight ?? 1.3;
-  const maxWidth = Math.max(...lines.map((line3) => estimateTextWidth(line3, fontSize, fontWeight)));
-  const totalHeight = lines.length * fontSize * lineHeight;
-  const isMultiLine = lines.length > 1;
-  const anchorX = isMultiLine ? label.x - maxWidth / 2 : label.x;
-  return {
-    x: anchorX,
-    y: label.y - fontSize,
-    width: maxWidth,
-    height: totalHeight
-  };
+  return computeTextBounds(label.x, label.y, label.text, fontSize, fontWeight);
 }
 function rectsOverlap(a, b) {
   return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
@@ -296,17 +317,30 @@ function nudgeAnnotationFromObstacles(annotation, originalAnnotation, scales, ch
   }
   candidates.sort((a, b) => a.distance - b.distance);
   for (const { dx, dy } of candidates) {
+    const newLabelX = annotation.label.x + dx;
+    const newLabelY = annotation.label.y + dy;
+    let newConnector = annotation.label.connector;
+    if (newConnector) {
+      const annFontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+      const annFontWeight = annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+      const connStyle = newConnector.style === "curve" ? "curve" : "straight";
+      const newFrom = computeConnectorOrigin(
+        newLabelX,
+        newLabelY,
+        annotation.label.text,
+        annFontSize,
+        annFontWeight,
+        px,
+        py,
+        connStyle
+      );
+      newConnector = { ...newConnector, from: newFrom };
+    }
     const candidateLabel = {
       ...annotation.label,
-      x: annotation.label.x + dx,
-      y: annotation.label.y + dy,
-      connector: annotation.label.connector ? {
-        ...annotation.label.connector,
-        from: {
-          x: annotation.label.connector.from.x + dx,
-          y: annotation.label.connector.from.y + dy
-        }
-      } : void 0
+      x: newLabelX,
+      y: newLabelY,
+      connector: newConnector
     };
     const candidateBounds = estimateLabelBounds(candidateLabel);
     const stillCollides = obstacles.some(
@@ -395,6 +429,30 @@ function groupByField(data, field) {
   }
   return groups;
 }
+function sortByField(data, field) {
+  if (data.length <= 1) return [...data];
+  return [...data].sort((a, b) => {
+    const aVal = a[field];
+    const bVal = b[field];
+    if (aVal == null && bVal == null) return 0;
+    if (aVal == null) return 1;
+    if (bVal == null) return -1;
+    if (typeof aVal === "number" && typeof bVal === "number") {
+      return aVal - bVal;
+    }
+    if (aVal instanceof Date && bVal instanceof Date) {
+      return aVal.getTime() - bVal.getTime();
+    }
+    const aStr = String(aVal);
+    const bStr = String(bVal);
+    const aNum = Number(aStr);
+    const bNum = Number(bStr);
+    if (Number.isFinite(aNum) && Number.isFinite(bNum)) {
+      return aNum - bNum;
+    }
+    return aStr.localeCompare(bStr);
+  });
+}
 function getColor(scales, key, _index, fallback = DEFAULT_COLOR) {
   if (scales.color && key !== "__default__") {
     const colorScale = scales.color.scale;
@@ -1051,8 +1109,9 @@ function computeSingleArea(spec, scales, _chartArea) {
   const marks = [];
   for (const [seriesKey, rows] of groups) {
     const color = getColor(scales, seriesKey);
+    const sortedRows = sortByField(rows, xChannel.field);
     const validPoints = [];
-    for (const row of rows) {
+    for (const row of sortedRows) {
       const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
       const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
       if (xVal === null || yVal === null) continue;
@@ -1097,11 +1156,12 @@ function computeStackedArea(spec, scales, chartArea) {
   if (!xChannel || !yChannel || !scales.x || !scales.y || !colorField) {
     return computeSingleArea(spec, scales, chartArea);
   }
+  const sortedData = sortByField(spec.data, xChannel.field);
   const seriesKeys = /* @__PURE__ */ new Set();
   const xValueSet = /* @__PURE__ */ new Set();
   const rowsByXSeries = /* @__PURE__ */ new Map();
   const rowsByX = /* @__PURE__ */ new Map();
-  for (const row of spec.data) {
+  for (const row of sortedData) {
     const xStr = String(row[xChannel.field]);
     const series = String(row[colorField]);
     seriesKeys.add(series);
@@ -1201,10 +1261,11 @@ function computeLineMarks(spec, scales, _chartArea, _strategy) {
   const marks = [];
   for (const [seriesKey, rows] of groups) {
     const color = getColor(scales, seriesKey);
+    const sortedRows = sortByField(rows, xChannel.field);
     const pointsWithData = [];
     const segments = [];
     let currentSegment = [];
-    for (const row of rows) {
+    for (const row of sortedRows) {
       const xVal = scaleValue(scales.x.scale, scales.x.type, row[xChannel.field]);
       const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
       if (xVal === null || yVal === null) {
@@ -2728,9 +2789,10 @@ function continuousTicks(resolvedScale, density) {
 function categoricalTicks(resolvedScale, density) {
   const scale = resolvedScale.scale;
   const domain = scale.domain();
-  const maxTicks = TICK_COUNTS[density];
+  const explicitTickCount = resolvedScale.channel.axis?.tickCount;
+  const maxTicks = explicitTickCount ?? TICK_COUNTS[density];
   let selectedValues = domain;
-  if (resolvedScale.type !== "band" && domain.length > maxTicks) {
+  if ((resolvedScale.type !== "band" || explicitTickCount) && domain.length > maxTicks) {
     const step = Math.ceil(domain.length / maxTicks);
     selectedValues = domain.filter((_, i) => i % step === 0);
   }
@@ -3108,7 +3170,7 @@ function computeScales(spec, chartArea, data) {
   }
   if (encoding.y) {
     let yData = data;
-    if (spec.type === "column" && encoding.color && encoding.y.type === "quantitative") {
+    if ((spec.type === "column" || spec.type === "area") && encoding.color && encoding.y.type === "quantitative") {
       const xField = encoding.x?.field;
       const yField = encoding.y.field;
       if (xField) {