@opendata-ai/openchart-engine 1.2.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@opendata-ai/openchart-engine",
+  "version": "1.2.0",
+  "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
+  "license": "Apache-2.0",
+  "author": "Riley Hilliard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tryopendata/openchart.git",
+    "directory": "packages/engine"
+  },
+  "homepage": "https://github.com/tryopendata/openchart#readme",
+  "bugs": "https://github.com/tryopendata/openchart/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "chart",
+    "visualization",
+    "compiler",
+    "layout",
+    "scales",
+    "d3"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opendata-ai/openchart-core": "2.0.0",
+    "d3-array": "^3.2.0",
+    "d3-format": "^3.1.2",
+    "d3-interpolate": "^3.0.0",
+    "d3-scale": "^4.0.0",
+    "d3-shape": "^3.2.0"
+  },
+  "devDependencies": {
+    "@types/d3-array": "^3.2.1",
+    "@types/d3-format": "^3.0.4",
+    "@types/d3-interpolate": "^3.0.4",
+    "@types/d3-scale": "^4.0.8",
+    "@types/d3-shape": "^3.1.6"
+  }
+}

package/src/__test-fixtures__/specs.ts

@@ -0,0 +1,124 @@
+/**
+ * Shared test fixtures for engine tests.
+ *
+ * Factory functions for NormalizedChartSpec and shared layout objects.
+ * Each factory returns a fresh object to prevent cross-test contamination.
+ */
+
+import type { LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import type { NormalizedChartSpec } from '../compiler/types';
+
+// ---------------------------------------------------------------------------
+// Shared layout objects
+// ---------------------------------------------------------------------------
+
+/** Standard chart area used across engine tests. */
+export function makeChartArea(): Rect {
+  return { x: 50, y: 20, width: 500, height: 300 };
+}
+
+/** Full-width layout strategy (labels visible, legend on right). */
+export function makeFullStrategy(): LayoutStrategy {
+  return {
+    labelMode: 'all',
+    legendPosition: 'right',
+    annotationPosition: 'inline',
+    axisLabelDensity: 'full',
+  };
+}
+
+/** Compact layout strategy (no labels, legend on top). */
+export function makeCompactStrategy(): LayoutStrategy {
+  return {
+    labelMode: 'none',
+    legendPosition: 'top',
+    annotationPosition: 'tooltip-only',
+    axisLabelDensity: 'minimal',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Line chart spec factories
+// ---------------------------------------------------------------------------
+
+/** Single-series line chart with temporal x-axis. */
+export function makeLineSpec(): NormalizedChartSpec {
+  return {
+    type: 'line',
+    data: [
+      { date: '2020-01-01', value: 10, country: 'US' },
+      { date: '2021-01-01', value: 40, country: 'US' },
+      { date: '2020-01-01', value: 15, country: 'UK' },
+      { date: '2021-01-01', value: 35, country: 'UK' },
+    ],
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'country', type: 'nominal' },
+    },
+    chrome: {
+      title: { text: 'GDP Growth' },
+      subtitle: { text: 'US vs UK over time' },
+      source: { text: 'World Bank' },
+    },
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Bar chart spec factories
+// ---------------------------------------------------------------------------
+
+/** Basic bar chart (horizontal) with nominal y and quantitative x. */
+export function makeBarSpec(): NormalizedChartSpec {
+  return {
+    type: 'bar',
+    data: [
+      { name: 'A', value: 10 },
+      { name: 'B', value: 30 },
+      { name: 'C', value: 20 },
+    ],
+    encoding: {
+      x: { field: 'value', type: 'quantitative' },
+      y: { field: 'name', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scatter chart spec factories
+// ---------------------------------------------------------------------------
+
+/** Basic scatter chart with quantitative x and y. */
+export function makeScatterSpec(): NormalizedChartSpec {
+  return {
+    type: 'scatter',
+    data: [
+      { x: 10, y: 20 },
+      { x: 30, y: 50 },
+      { x: 50, y: 40 },
+      { x: 70, y: 80 },
+      { x: 90, y: 60 },
+    ],
+    encoding: {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}

package/src/__tests__/axes.test.ts

@@ -0,0 +1,114 @@
+import type { LayoutStrategy } from '@opendata-ai/openchart-core';
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../compiler/types';
+import { computeAxes } from '../layout/axes';
+import { computeScales } from '../layout/scales';
+
+const lineSpec: NormalizedChartSpec = {
+  type: 'line',
+  data: [
+    { date: '2020-01-01', value: 100 },
+    { date: '2021-01-01', value: 500 },
+    { date: '2022-01-01', value: 300 },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' },
+    y: { field: 'value', type: 'quantitative' },
+  },
+  chrome: {},
+  annotations: [],
+  responsive: true,
+  theme: {},
+  darkMode: 'off',
+  labels: { density: 'auto', format: '' },
+};
+
+const chartArea = { x: 50, y: 50, width: 500, height: 300 };
+const theme = resolveTheme();
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+const minimalStrategy: LayoutStrategy = {
+  labelMode: 'none',
+  legendPosition: 'top',
+  annotationPosition: 'tooltip-only',
+  axisLabelDensity: 'minimal',
+};
+
+describe('computeAxes', () => {
+  it('produces x and y axes for a line chart', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x).toBeDefined();
+    expect(axes.y).toBeDefined();
+  });
+
+  it('generates ticks for both axes', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x!.ticks.length).toBeGreaterThan(0);
+    expect(axes.y!.ticks.length).toBeGreaterThan(0);
+  });
+
+  it('tick positions are within chart area', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    for (const tick of axes.x!.ticks) {
+      expect(tick.position).toBeGreaterThanOrEqual(chartArea.x - 1);
+      expect(tick.position).toBeLessThanOrEqual(chartArea.x + chartArea.width + 1);
+    }
+
+    for (const tick of axes.y!.ticks) {
+      expect(tick.position).toBeGreaterThanOrEqual(chartArea.y - 1);
+      expect(tick.position).toBeLessThanOrEqual(chartArea.y + chartArea.height + 1);
+    }
+  });
+
+  it('tick labels are formatted strings', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    for (const tick of axes.y!.ticks) {
+      expect(typeof tick.label).toBe('string');
+      expect(tick.label.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('produces fewer ticks with minimal density', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axesFull = computeAxes(scales, chartArea, fullStrategy, theme);
+    const axesMinimal = computeAxes(scales, chartArea, minimalStrategy, theme);
+
+    // Minimal should have fewer or equal ticks
+    expect(axesMinimal.y!.ticks.length).toBeLessThanOrEqual(axesFull.y!.ticks.length);
+  });
+
+  it('y-axis has gridlines by default', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.y!.gridlines.length).toBeGreaterThan(0);
+  });
+
+  it('axes have correct start/end positions', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    // X axis sits at the bottom of the chart area
+    expect(axes.x!.start.y).toBe(chartArea.y + chartArea.height);
+    expect(axes.x!.end.y).toBe(chartArea.y + chartArea.height);
+
+    // Y axis sits at the left of the chart area
+    expect(axes.y!.start.x).toBe(chartArea.x);
+    expect(axes.y!.end.x).toBe(chartArea.x);
+  });
+});

package/src/__tests__/compile-chart.test.ts

@@ -0,0 +1,337 @@
+import { describe, expect, it } from 'vitest';
+import { compileChart, compileGraph, compileTable } from '../compile';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const lineSpec = {
+  type: 'line' as const,
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 40, country: 'US' },
+    { date: '2020-01-01', value: 15, country: 'UK' },
+    { date: '2021-01-01', value: 35, country: 'UK' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' as const },
+    y: { field: 'value', type: 'quantitative' as const },
+    color: { field: 'country', type: 'nominal' as const },
+  },
+  chrome: {
+    title: 'GDP Growth',
+    subtitle: 'US vs UK over time',
+    source: 'World Bank',
+  },
+};
+
+const barSpec = {
+  type: 'bar' as const,
+  data: [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 30 },
+    { name: 'C', value: 20 },
+  ],
+  encoding: {
+    x: { field: 'value', type: 'quantitative' as const },
+    y: { field: 'name', type: 'nominal' as const },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('compileChart', () => {
+  it('returns a ChartLayout with all required fields populated', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+
+    // Chart area has real dimensions within the total viewport
+    expect(layout.area.width).toBeGreaterThan(0);
+    expect(layout.area.height).toBeGreaterThan(0);
+    expect(layout.area.x).toBeGreaterThanOrEqual(0);
+    expect(layout.area.y).toBeGreaterThanOrEqual(0);
+
+    // Chrome is resolved with positions
+    expect(layout.chrome.topHeight).toBeGreaterThan(0);
+    expect(layout.chrome.title?.text).toBe('GDP Growth');
+
+    // Axes have ticks
+    expect(layout.axes.x?.ticks.length).toBeGreaterThan(0);
+    expect(layout.axes.y?.ticks.length).toBeGreaterThan(0);
+
+    // Marks were produced by the registered renderer
+    expect(layout.marks.length).toBeGreaterThan(0);
+
+    // Annotations array exists (empty for this spec since none were specified)
+    expect(layout.annotations).toEqual([]);
+
+    // Legend has entries for the two series
+    expect(layout.legend.entries.length).toBe(2);
+
+    // Tooltip descriptors is a Map (may or may not have entries depending on marks)
+    expect(layout.tooltipDescriptors).toBeInstanceOf(Map);
+
+    // Accessibility metadata is populated
+    expect(layout.a11y.altText.length).toBeGreaterThan(0);
+    expect(layout.a11y.role).toBe('img');
+
+    // Theme is resolved with actual color values
+    expect(layout.theme.colors.background).toBeTruthy();
+    expect(layout.theme.colors.categorical.length).toBeGreaterThan(0);
+
+    // Dimensions match the input
+    expect(layout.dimensions).toEqual({ width: 600, height: 400 });
+  });
+
+  it('has correct total dimensions', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.dimensions.width).toBe(600);
+    expect(layout.dimensions.height).toBe(400);
+  });
+
+  it('chart area fits within total dimensions', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.area.x).toBeGreaterThan(0);
+    expect(layout.area.y).toBeGreaterThan(0);
+    expect(layout.area.x + layout.area.width).toBeLessThan(600);
+    expect(layout.area.y + layout.area.height).toBeLessThan(400);
+  });
+
+  it('chrome title and subtitle are resolved with correct text and positions', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.chrome.topHeight).toBeGreaterThan(0);
+
+    // Title
+    expect(layout.chrome.title!.text).toBe('GDP Growth');
+    expect(layout.chrome.title!.x).toBeGreaterThanOrEqual(0);
+    expect(layout.chrome.title!.y).toBeGreaterThan(0);
+    expect(layout.chrome.title!.maxWidth).toBeGreaterThan(0);
+    expect(layout.chrome.title!.style.fontSize).toBeGreaterThan(0);
+
+    // Subtitle
+    expect(layout.chrome.subtitle!.text).toBe('US vs UK over time');
+    expect(layout.chrome.subtitle!.y).toBeGreaterThan(layout.chrome.title!.y);
+  });
+
+  it('bottom chrome source is resolved with text and position', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.chrome.bottomHeight).toBeGreaterThan(0);
+    expect(layout.chrome.source!.text).toBe('World Bank');
+    expect(layout.chrome.source!.x).toBeGreaterThanOrEqual(0);
+    expect(layout.chrome.source!.y).toBeGreaterThan(0);
+    expect(layout.chrome.source!.style.fontSize).toBeGreaterThan(0);
+  });
+
+  it('has axes with ticks and valid positions for a line chart', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+
+    // X axis
+    const xTicks = layout.axes.x!.ticks;
+    expect(xTicks.length).toBeGreaterThan(0);
+    for (const tick of xTicks) {
+      expect(tick.position).toBeGreaterThanOrEqual(0);
+      expect(tick.label).toBeTruthy();
+    }
+
+    // Y axis
+    const yTicks = layout.axes.y!.ticks;
+    expect(yTicks.length).toBeGreaterThan(0);
+    for (const tick of yTicks) {
+      expect(tick.position).toBeGreaterThanOrEqual(0);
+      expect(tick.label).toBeTruthy();
+    }
+
+    // Axes have start and end points
+    expect(layout.axes.x!.start.x).toBeLessThan(layout.axes.x!.end.x);
+    expect(layout.axes.y!.start.y).not.toBe(layout.axes.y!.end.y);
+  });
+
+  it('has a legend when color encoding is present', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.legend.entries.length).toBeGreaterThan(0);
+    expect(layout.legend.entries.some((e) => e.label === 'US')).toBe(true);
+    expect(layout.legend.entries.some((e) => e.label === 'UK')).toBe(true);
+  });
+
+  it('legend entries have colors and shapes', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    for (const entry of layout.legend.entries) {
+      expect(entry.color).toBeTruthy();
+      expect(['circle', 'square', 'line']).toContain(entry.shape);
+    }
+  });
+
+  it('legend position is "right" at full width', () => {
+    const layout = compileChart(lineSpec, { width: 800, height: 400 });
+    expect(layout.legend.position).toBe('right');
+  });
+
+  it('legend position is "top" at compact width', () => {
+    const layout = compileChart(lineSpec, { width: 320, height: 400 });
+    expect(layout.legend.position).toBe('top');
+  });
+
+  it('produces line and point marks with the registered renderer', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.marks.length).toBeGreaterThan(0);
+
+    const lineMarks = layout.marks.filter((m) => m.type === 'line');
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(lineMarks.length).toBeGreaterThan(0);
+    expect(pointMarks.length).toBeGreaterThan(0);
+
+    // Line marks should have points with valid coordinates
+    for (const mark of lineMarks) {
+      if (mark.type === 'line') {
+        expect(mark.points.length).toBeGreaterThan(0);
+        expect(mark.stroke).toBeTruthy();
+        expect(mark.strokeWidth).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it('includes accessibility metadata with meaningful content', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.a11y.altText).toContain('Line chart');
+    expect(layout.a11y.altText).toContain('GDP Growth');
+    expect(layout.a11y.role).toBe('img');
+    expect(layout.a11y.dataTableFallback.length).toBeGreaterThan(0);
+    // With marks present, keyboard navigation should be enabled
+    expect(layout.a11y.keyboardNavigable).toBe(true);
+  });
+
+  it('produces different strategies at different widths', () => {
+    const narrow = compileChart(lineSpec, { width: 320, height: 400 });
+    const wide = compileChart(lineSpec, { width: 800, height: 400 });
+
+    // At 320px the legend should be on top, at 800px on the right
+    expect(narrow.legend.position).toBe('top');
+    expect(wide.legend.position).toBe('right');
+  });
+
+  it('dark mode adapts the theme colors', () => {
+    const light = compileChart(lineSpec, { width: 600, height: 400 });
+    const dark = compileChart(lineSpec, { width: 600, height: 400, darkMode: true });
+
+    expect(light.theme.isDark).toBe(false);
+    expect(dark.theme.isDark).toBe(true);
+    expect(dark.theme.colors.background).not.toBe(light.theme.colors.background);
+    // Dark mode text should be light, light mode text should be dark
+    expect(dark.theme.colors.text).not.toBe(light.theme.colors.text);
+  });
+
+  it('compiles a bar chart with rect marks and both axes', () => {
+    const layout = compileChart(barSpec, { width: 600, height: 400 });
+
+    // Bar charts produce rect marks
+    expect(layout.marks.length).toBe(3);
+    for (const mark of layout.marks) {
+      expect(mark.type).toBe('rect');
+      if (mark.type === 'rect') {
+        expect(mark.width).toBeGreaterThan(0);
+        expect(mark.height).toBeGreaterThan(0);
+        expect(mark.fill).toBeTruthy();
+      }
+    }
+
+    // Both axes should be present with ticks
+    expect(layout.axes.x!.ticks.length).toBeGreaterThan(0);
+    expect(layout.axes.y!.ticks.length).toBe(3); // A, B, C
+  });
+
+  it('bar chart y-axis labels match the nominal field values', () => {
+    const layout = compileChart(barSpec, { width: 600, height: 400 });
+    const yLabels = layout.axes.y!.ticks.map((t) => t.label);
+    expect(yLabels).toContain('A');
+    expect(yLabels).toContain('B');
+    expect(yLabels).toContain('C');
+  });
+
+  it('throws on invalid spec', () => {
+    expect(() => compileChart({ type: 'bogus' }, { width: 600, height: 400 })).toThrow();
+  });
+
+  it('throws if a table spec is passed', () => {
+    expect(() =>
+      compileChart(
+        { type: 'table', data: [{ a: 1 }], columns: [{ key: 'a' }] },
+        { width: 600, height: 400 },
+      ),
+    ).toThrow('compileTable');
+  });
+});
+
+describe('compileTable', () => {
+  it('returns a valid TableLayout with resolved columns and rows', () => {
+    const layout = compileTable(
+      {
+        type: 'table',
+        data: [{ name: 'Alice', age: 30 }],
+        columns: [{ key: 'name' }, { key: 'age' }],
+        chrome: { title: 'People' },
+      },
+      { width: 600, height: 400 },
+    );
+
+    // Chrome title is resolved
+    expect(layout.chrome.title!.text).toBe('People');
+    expect(layout.chrome.topHeight).toBeGreaterThan(0);
+
+    // Columns are resolved with labels and widths
+    expect(layout.columns).toHaveLength(2);
+    expect(layout.columns[0].key).toBe('name');
+    expect(layout.columns[0].label).toBeTruthy();
+    expect(layout.columns[0].width).toBeGreaterThan(0);
+    expect(layout.columns[1].key).toBe('age');
+
+    // Rows contain formatted cell values
+    expect(layout.rows).toHaveLength(1);
+    expect(layout.rows[0].cells).toHaveLength(2);
+    expect(layout.rows[0].cells[0].formattedValue).toBe('Alice');
+    expect(layout.rows[0].cells[1].formattedValue).toBe('30');
+
+    // Accessibility caption includes the title
+    expect(layout.a11y.caption).toContain('People');
+
+    // Theme is resolved
+    expect(layout.theme.isDark).toBe(false);
+    expect(layout.theme.colors.background).toBeTruthy();
+  });
+
+  it('throws if a chart spec is passed', () => {
+    expect(() => compileTable(lineSpec, { width: 600, height: 400 })).toThrow('compileChart');
+  });
+});
+
+describe('compileGraph', () => {
+  it('returns a valid GraphCompilation for a graph spec', () => {
+    const result = compileGraph(
+      {
+        type: 'graph',
+        nodes: [{ id: 'a' }],
+        edges: [],
+      },
+      { width: 600, height: 400 },
+    );
+    expect(result.nodes).toHaveLength(1);
+    expect(result.edges).toHaveLength(0);
+    expect(result.dimensions).toEqual({ width: 600, height: 400 });
+  });
+
+  it('throws for non-graph specs', () => {
+    expect(() =>
+      compileGraph(
+        {
+          type: 'scatter',
+          data: [{ x: 1, y: 2 }],
+          encoding: {
+            x: { field: 'x', type: 'quantitative' },
+            y: { field: 'y', type: 'quantitative' },
+          },
+        },
+        { width: 600, height: 400 },
+      ),
+    ).toThrow('compileGraph received a scatter spec');
+  });
+});