@opendata-ai/openchart-engine 6.5.1 → 6.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.5.1",
+  "version": "6.6.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,10 +45,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.5.1",
+    "@opendata-ai/openchart-core": "6.6.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",
+    "d3-sankey": "^0.12.3",
     "d3-scale": "^4.0.0",
     "d3-shape": "^3.2.0"
   },
@@ -56,6 +57,7 @@
     "@types/d3-array": "^3.2.1",
     "@types/d3-format": "^3.0.4",
     "@types/d3-interpolate": "^3.0.4",
+    "@types/d3-sankey": "^0.12.5",
     "@types/d3-scale": "^4.0.8",
     "@types/d3-shape": "^3.1.6"
   }

package/src/__tests__/dimensions.test.ts

@@ -1,4 +1,4 @@
-import type { LegendLayout } from '@opendata-ai/openchart-core';
+import type { LayoutStrategy, LegendLayout } from '@opendata-ai/openchart-core';
 import { adaptTheme, resolveTheme } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../compiler/types';
@@ -219,4 +219,50 @@ describe('computeDimensions', () => {
     // Small angles (< 10 degrees) should not trigger rotated label logic
     expect(dimsSmall.margins.bottom).toBe(dimsNone.margins.bottom);
   });
+
+  it('does not reserve annotation margin when strategy is tooltip-only', () => {
+    const specWithAnnotations: NormalizedChartSpec = {
+      ...baseSpec,
+      annotations: [{ type: 'text', x: '2021-01-01', y: 20, text: 'Right-edge annotation' }],
+    };
+
+    const inlineStrategy: LayoutStrategy = {
+      labelMode: 'all',
+      legendPosition: 'right',
+      annotationPosition: 'inline',
+      axisLabelDensity: 'full',
+    };
+    const tooltipOnlyStrategy: LayoutStrategy = {
+      labelMode: 'none',
+      legendPosition: 'top',
+      annotationPosition: 'tooltip-only',
+      axisLabelDensity: 'minimal',
+    };
+
+    const dimsInline = computeDimensions(
+      specWithAnnotations,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+      inlineStrategy,
+    );
+    const dimsTooltipOnly = computeDimensions(
+      specWithAnnotations,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+      tooltipOnlyStrategy,
+    );
+    const dimsNoAnnotations = computeDimensions(
+      baseSpec,
+      { width: 600, height: 400 },
+      emptyLegend,
+      lightTheme,
+    );
+
+    // Inline strategy should reserve extra right margin for the annotation
+    expect(dimsInline.margins.right).toBeGreaterThan(dimsNoAnnotations.margins.right);
+    // Tooltip-only should NOT reserve extra margin (annotations are hidden)
+    expect(dimsTooltipOnly.margins.right).toBe(dimsNoAnnotations.margins.right);
+  });
 });

package/src/annotations/__tests__/compute.test.ts

@@ -945,6 +945,34 @@ describe('computeAnnotations', () => {
       const moved = nudgedLabel.x !== originalLabel.x || nudgedLabel.y !== originalLabel.y;
       expect(moved).toBe(true);
     });
+
+    it('preserves connector style when nudged away from obstacle', () => {
+      // connector: true means "straight line" - obstacle avoidance should not change it
+      const spec = makeSpec([
+        { type: 'text', x: '2020-01-01', y: 20, text: 'Explicit connector', connector: true },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      const withoutObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy);
+      const originalLabel = withoutObstacles[0].label!;
+      expect(originalLabel.connector).toBeDefined();
+      expect(originalLabel.connector!.style).toBe('straight');
+
+      // Place obstacle directly on the annotation to force a nudge
+      const obstacle: Rect = {
+        x: originalLabel.x - 5,
+        y: originalLabel.y - 5,
+        width: 80,
+        height: 30,
+      };
+
+      const withObstacles = computeAnnotations(spec, scales, chartArea, fullStrategy, false, [
+        obstacle,
+      ]);
+      const nudgedLabel = withObstacles[0].label!;
+      expect(nudgedLabel.connector).toBeDefined();
+      expect(nudgedLabel.connector!.style).toBe('straight');
+    });
   });
 
   // -----------------------------------------------------------------

package/src/annotations/compute.ts

@@ -675,14 +675,6 @@ function nudgeAnnotationFromObstacles(
       labelCenterY <= chartArea.y + chartArea.height + fontSize * 3;
 
     if (inBounds) {
-      // When nudged vertically (directly above/below the data), use a caret
-      // instead of a connector line for a cleaner editorial look.
-      if (candidateLabel.connector && dx === 0 && dy !== 0) {
-        candidateLabel.connector = {
-          ...candidateLabel.connector,
-          style: 'caret',
-        };
-      }
       annotation.label = candidateLabel;
       return true;
     }

package/src/compile.ts

@@ -92,6 +92,7 @@ import { computeDimensions } from './layout/dimensions';
 import { computeGridlines } from './layout/gridlines';
 import { computeScales, type ResolvedScales } from './layout/scales';
 import { computeLegend } from './legend/compute';
+import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
 import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
@@ -212,6 +213,12 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   if ('type' in normalized && (normalized as unknown as Record<string, unknown>).type === 'graph') {
     throw new Error('compileChart received a graph spec. Use compileGraph instead.');
   }
+  if (
+    'type' in normalized &&
+    (normalized as unknown as Record<string, unknown>).type === 'sankey'
+  ) {
+    throw new Error('compileChart received a sankey spec. Use compileSankey instead.');
+  }
 
   let chartSpec = normalized as NormalizedChartSpec;
 
@@ -712,3 +719,26 @@ export function compileTable(spec: unknown, options: CompileTableOptions): Table
 export function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation {
   return compileGraphImpl(spec, options);
 }
+
+// ---------------------------------------------------------------------------
+// Sankey compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a sankey spec into a SankeyLayout.
+ *
+ * Takes a raw sankey spec, validates, normalizes, resolves theme and chrome,
+ * runs the d3-sankey layout algorithm, builds node/link marks with colors and
+ * labels, and returns a SankeyLayout ready for rendering.
+ *
+ * @param spec - Raw sankey spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns SankeyLayout with computed positions and visual properties.
+ * @throws Error if spec is invalid or not a sankey type.
+ */
+export function compileSankey(
+  spec: unknown,
+  options: CompileOptions,
+): import('@opendata-ai/openchart-core').SankeyLayout {
+  return compileSankeyImpl(spec, options);
+}

package/src/compiler/normalize.ts

@@ -18,6 +18,7 @@ import type {
   FieldType,
   GraphSpec,
   LayerSpec,
+  SankeySpec,
   TableSpec,
   VizSpec,
 } from '@opendata-ai/openchart-core';
@@ -25,11 +26,12 @@ import {
   isChartSpec,
   isGraphSpec,
   isLayerSpec,
+  isSankeySpec,
   isTableSpec,
   resolveMarkDef,
   resolveMarkType,
 } from '@opendata-ai/openchart-core';
-
+import type { NormalizedSankeySpec } from '../sankey/types';
 import type {
   NormalizedChartSpec,
   NormalizedChrome,
@@ -233,6 +235,24 @@ function normalizeTableSpec(spec: TableSpec, _warnings: string[]): NormalizedTab
   };
 }
 
+function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedSankeySpec {
+  return {
+    type: 'sankey',
+    data: spec.data,
+    encoding: spec.encoding,
+    nodeWidth: spec.nodeWidth ?? 12,
+    nodePadding: spec.nodePadding ?? 16,
+    nodeAlign: spec.nodeAlign ?? 'justify',
+    iterations: spec.iterations ?? 6,
+    linkStyle: spec.linkStyle ?? 'gradient',
+    chrome: normalizeChrome(spec.chrome),
+    legend: spec.legend,
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    animation: spec.animation,
+  };
+}
+
 function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGraphSpec {
   // Default layout with chargeStrength and linkDistance
   const defaultLayout = {
@@ -292,9 +312,12 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
   if (isGraphSpec(spec)) {
     return normalizeGraphSpec(spec, warnings);
   }
+  if (isSankeySpec(spec)) {
+    return normalizeSankeySpec(spec, warnings);
+  }
   // Should never happen after validation
   throw new Error(
-    `Unknown spec shape. Expected mark (chart), layer, type: 'table', or type: 'graph'.`,
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', or type: 'sankey'.`,
   );
 }
 

package/src/compiler/types.ts

@@ -28,6 +28,7 @@ import type {
   ScaleConfig,
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
+import type { NormalizedSankeySpec } from '../sankey/types';
 
 // ---------------------------------------------------------------------------
 // NormalizedChrome: all fields are ChromeText objects (not plain strings)
@@ -114,7 +115,11 @@ export interface NormalizedGraphSpec {
 }
 
 /** Discriminated union of all normalized spec types. */
-export type NormalizedSpec = NormalizedChartSpec | NormalizedTableSpec | NormalizedGraphSpec;
+export type NormalizedSpec =
+  | NormalizedChartSpec
+  | NormalizedTableSpec
+  | NormalizedGraphSpec
+  | NormalizedSankeySpec;
 
 // ---------------------------------------------------------------------------
 // Validation types

package/src/compiler/validate.ts

@@ -544,6 +544,107 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
   }
 }
 
+// ---------------------------------------------------------------------------
+// Sankey validation
+// ---------------------------------------------------------------------------
+
+function validateSankeySpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  // Validate data
+  if (!Array.isArray(spec.data)) {
+    errors.push({
+      message: 'Spec error: sankey spec requires a "data" array',
+      path: 'data',
+      code: 'INVALID_TYPE',
+      suggestion:
+        'Provide data as an array of objects, e.g. data: [{ source: "A", target: "B", value: 10 }]',
+    });
+    return;
+  }
+
+  if (spec.data.length === 0) {
+    errors.push({
+      message: 'Spec error: "data" must be a non-empty array',
+      path: 'data',
+      code: 'EMPTY_DATA',
+      suggestion: 'Add at least one data row, e.g. data: [{ source: "A", target: "B", value: 10 }]',
+    });
+    return;
+  }
+
+  const firstRow = spec.data[0] as unknown;
+  if (typeof firstRow !== 'object' || firstRow === null || Array.isArray(firstRow)) {
+    errors.push({
+      message: 'Spec error: each item in "data" must be a plain object',
+      path: 'data[0]',
+      code: 'INVALID_TYPE',
+      suggestion:
+        'Each data item should be an object, e.g. { source: "A", target: "B", value: 10 }',
+    });
+    return;
+  }
+
+  // Validate encoding
+  if (!spec.encoding || typeof spec.encoding !== 'object') {
+    errors.push({
+      message:
+        'Spec error: sankey spec requires an "encoding" object with source, target, and value channels',
+      path: 'encoding',
+      code: 'MISSING_FIELD',
+      suggestion:
+        'Add an encoding object, e.g. encoding: { source: { field: "source", type: "nominal" }, target: { field: "target", type: "nominal" }, value: { field: "value", type: "quantitative" } }',
+    });
+    return;
+  }
+
+  const encoding = spec.encoding as Record<string, unknown>;
+  const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
+  const availableColumns = [...dataColumns].join(', ');
+
+  // Required channels
+  for (const channel of ['source', 'target', 'value'] as const) {
+    const ch = encoding[channel] as Record<string, unknown> | undefined;
+    if (!ch || typeof ch !== 'object') {
+      errors.push({
+        message: `Spec error: sankey encoding requires "${channel}" channel`,
+        path: `encoding.${channel}`,
+        code: 'MISSING_FIELD',
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+      });
+      continue;
+    }
+
+    if (!ch.field || typeof ch.field !== 'string') {
+      errors.push({
+        message: `Spec error: encoding.${channel} must have a "field" string`,
+        path: `encoding.${channel}.field`,
+        code: 'MISSING_FIELD',
+        suggestion: `Add a field name from your data columns: ${availableColumns}`,
+      });
+      continue;
+    }
+
+    if (!dataColumns.has(ch.field as string)) {
+      errors.push({
+        message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
+        path: `encoding.${channel}.field`,
+        code: 'DATA_FIELD_MISSING',
+        suggestion: `Use one of the available data columns: ${availableColumns}`,
+      });
+    }
+  }
+
+  // Validate darkMode if provided
+  if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
+    errors.push({
+      message: 'Spec error: darkMode must be "auto", "force", or "off"',
+      path: 'darkMode',
+      code: 'INVALID_VALUE',
+      suggestion:
+        'Use one of: "auto" (system preference), "force" (always dark), or "off" (always light)',
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer validation
 // ---------------------------------------------------------------------------
@@ -678,19 +779,20 @@ export function validateSpec(spec: unknown): ValidationResult {
   const hasMark = 'mark' in obj;
   const isTable = obj.type === 'table';
   const isGraph = obj.type === 'graph';
-  const isLayer = hasLayer && !isTable && !isGraph;
-  const isChart = hasMark && !hasLayer && !isTable && !isGraph;
+  const isSankey = obj.type === 'sankey';
+  const isLayer = hasLayer && !isTable && !isGraph && !isSankey;
+  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey;
 
-  if (!isChart && !isTable && !isGraph && !isLayer) {
+  if (!isChart && !isTable && !isGraph && !isSankey && !isLayer) {
     return {
       valid: false,
       errors: [
         {
           message:
-            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs',
+            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey',
           path: 'mark',
           code: 'MISSING_FIELD',
-          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs (type: "table" or type: "graph"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
+          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey (type: "table", type: "graph", or type: "sankey"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
         },
       ],
       normalized: null,
@@ -733,6 +835,8 @@ export function validateSpec(spec: unknown): ValidationResult {
     validateTableSpec(obj, errors);
   } else if (isGraph) {
     validateGraphSpec(obj, errors);
+  } else if (isSankey) {
+    validateSankeySpec(obj, errors);
   }
 
   if (errors.length > 0) {

package/src/index.ts

@@ -12,7 +12,7 @@
 // Main compile API
 // ---------------------------------------------------------------------------
 
-export { compileChart, compileGraph, compileLayer, compileTable } from './compile';
+export { compileChart, compileGraph, compileLayer, compileSankey, compileTable } from './compile';
 
 // ---------------------------------------------------------------------------
 // Animation resolution
@@ -31,6 +31,12 @@ export type {
   SimulationConfig,
 } from './graphs/types';
 
+// ---------------------------------------------------------------------------
+// Sankey compilation types
+// ---------------------------------------------------------------------------
+
+export type { NormalizedSankeySpec } from './sankey/types';
+
 // ---------------------------------------------------------------------------
 // Compiler pipeline (spec validation, normalization, generic compile)
 // ---------------------------------------------------------------------------
@@ -90,6 +96,8 @@ export type {
   GraphLayout,
   GraphSpec,
   LayerSpec,
+  SankeyLayout,
+  SankeySpec,
   TableLayout,
   TableSpec,
   VizSpec,

package/src/layout/dimensions.ts

@@ -191,7 +191,12 @@ export function computeDimensions(
   // Reserve right margin for text annotations near the chart's right edge.
   // Without this, annotation text at the last data point clips outside the SVG.
   // Account for anchor direction and offset.dx to avoid over-reserving space.
-  if (spec.annotations.length > 0 && encoding.x) {
+  // Skip when annotations are hidden (tooltip-only at compact breakpoints).
+  if (
+    strategy?.annotationPosition !== 'tooltip-only' &&
+    spec.annotations.length > 0 &&
+    encoding.x
+  ) {
     const xField = encoding.x.field;
     // Find the maximum x value in the data
     let maxX: string | number | undefined;