@opendata-ai/openchart-engine 1.2.0

package/src/charts/registry.ts

@@ -0,0 +1,64 @@
+/**
+ * Chart renderer registry.
+ *
+ * Each chart type (line, bar, column, scatter, pie, donut, dot) registers
+ * a renderer that produces marks from normalized specs and resolved scales.
+ * The registry pattern decouples chart-type logic from the compile pipeline.
+ */
+
+import type { LayoutStrategy, Mark, Rect, ResolvedTheme } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+import type { ResolvedScales } from '../layout/scales';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A chart renderer function.
+ *
+ * Takes a normalized spec, resolved scales, chart area, layout strategy,
+ * and the resolved theme for theme-aware styling (e.g. label colors).
+ * Returns an array of marks to render.
+ */
+export type ChartRenderer = (
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  strategy: LayoutStrategy,
+  theme: ResolvedTheme,
+) => Mark[];
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+const renderers = new Map<string, ChartRenderer>();
+
+/**
+ * Register a chart renderer for a specific chart type.
+ *
+ * @param type - Chart type string (e.g. "line", "bar").
+ * @param renderer - The renderer function.
+ */
+export function registerChartRenderer(type: string, renderer: ChartRenderer): void {
+  renderers.set(type, renderer);
+}
+
+/**
+ * Get the registered chart renderer for a type.
+ *
+ * @param type - Chart type string.
+ * @returns The renderer, or undefined if no renderer is registered.
+ */
+export function getChartRenderer(type: string): ChartRenderer | undefined {
+  return renderers.get(type);
+}
+
+/**
+ * Clear all registered renderers. Useful for testing.
+ */
+export function clearRenderers(): void {
+  renderers.clear();
+}

package/src/charts/scatter/__tests__/compute.test.ts

@@ -0,0 +1,304 @@
+import type { LayoutStrategy, PointMark, Rect } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../../../compiler/types';
+import { computeScales } from '../../../layout/scales';
+import { computeScatterMarks } from '../compute';
+import { computeTrendLine } from '../trendline';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const chartArea: Rect = { x: 50, y: 20, width: 500, height: 300 };
+
+const fullStrategy: LayoutStrategy = {
+  labelMode: 'all',
+  legendPosition: 'right',
+  annotationPosition: 'inline',
+  axisLabelDensity: 'full',
+};
+
+function makeBasicScatterSpec(): 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: '' },
+  };
+}
+
+function makeBubbleSpec(): NormalizedChartSpec {
+  return {
+    type: 'scatter',
+    data: [
+      { gdp: 10, life: 60, population: 1000 },
+      { gdp: 30, life: 70, population: 5000 },
+      { gdp: 50, life: 75, population: 300 },
+      { gdp: 70, life: 80, population: 8000 },
+    ],
+    encoding: {
+      x: { field: 'gdp', type: 'quantitative' },
+      y: { field: 'life', type: 'quantitative' },
+      size: { field: 'population', type: 'quantitative' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeColoredScatterSpec(): NormalizedChartSpec {
+  return {
+    type: 'scatter',
+    data: [
+      { x: 10, y: 20, group: 'A' },
+      { x: 30, y: 50, group: 'A' },
+      { x: 50, y: 40, group: 'B' },
+      { x: 70, y: 80, group: 'B' },
+      { x: 90, y: 60, group: 'C' },
+    ],
+    encoding: {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+      color: { field: 'group', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computeScatterMarks tests
+// ---------------------------------------------------------------------------
+
+describe('computeScatterMarks', () => {
+  describe('basic scatter', () => {
+    it('produces one PointMark per data row', () => {
+      const spec = makeBasicScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(5);
+      expect(marks.every((m) => m.type === 'point')).toBe(true);
+    });
+
+    it('point positions are within chart area bounds', () => {
+      const spec = makeBasicScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.cx).toBeGreaterThanOrEqual(chartArea.x);
+        expect(mark.cx).toBeLessThanOrEqual(chartArea.x + chartArea.width);
+        expect(mark.cy).toBeGreaterThanOrEqual(chartArea.y);
+        expect(mark.cy).toBeLessThanOrEqual(chartArea.y + chartArea.height);
+      }
+    });
+
+    it('points have default radius when no size encoding', () => {
+      const spec = makeBasicScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.r).toBe(5);
+      }
+    });
+
+    it('points have partial fill opacity for overlap visibility', () => {
+      const spec = makeBasicScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.fillOpacity).toBeGreaterThan(0);
+        expect(mark.fillOpacity).toBeLessThan(1);
+      }
+    });
+
+    it('each point has an aria label with field values', () => {
+      const spec = makeBasicScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks[0].aria.label).toContain('x=10');
+      expect(marks[0].aria.label).toContain('y=20');
+    });
+  });
+
+  describe('bubble variant (size encoding)', () => {
+    it('points have varying radii based on size field', () => {
+      const spec = makeBubbleSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      const radii = marks.map((m) => m.r);
+      const uniqueRadii = new Set(radii);
+      expect(uniqueRadii.size).toBeGreaterThan(1);
+    });
+
+    it('larger size values produce larger radii', () => {
+      const spec = makeBubbleSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      // population: 8000 should have largest radius
+      const largest = marks.find((m) => m.data.population === 8000)!;
+      const smallest = marks.find((m) => m.data.population === 300)!;
+      expect(largest.r).toBeGreaterThan(smallest.r);
+    });
+
+    it('aria label includes size field', () => {
+      const spec = makeBubbleSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks[0].aria.label).toContain('population=');
+    });
+  });
+
+  describe('color encoding', () => {
+    it('points in different groups have different colors', () => {
+      const spec = makeColoredScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      const groupA = marks.find((m) => m.data.group === 'A')!;
+      const groupB = marks.find((m) => m.data.group === 'B')!;
+      expect(groupA.fill).not.toBe(groupB.fill);
+    });
+
+    it('points in the same group share a color', () => {
+      const spec = makeColoredScatterSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      const groupAMarks = marks.filter((m) => m.data.group === 'A');
+      expect(groupAMarks[0].fill).toBe(groupAMarks[1].fill);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns empty array when no x encoding', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'scatter',
+        data: [{ y: 10 }],
+        encoding: {
+          y: { field: 'y', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(0);
+    });
+
+    it('skips rows with non-finite values', () => {
+      const spec: NormalizedChartSpec = {
+        type: 'scatter',
+        data: [
+          { x: 10, y: 20 },
+          { x: NaN, y: 30 },
+          { x: 50, y: 40 },
+        ],
+        encoding: {
+          x: { field: 'x', type: 'quantitative' },
+          y: { field: 'y', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+      expect(marks).toHaveLength(2);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeTrendLine tests
+// ---------------------------------------------------------------------------
+
+describe('computeTrendLine', () => {
+  it('produces a LineMark with two points', () => {
+    const spec = makeBasicScatterSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const points = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+    const trendLine = computeTrendLine(points);
+
+    expect(trendLine).not.toBeNull();
+    expect(trendLine!.type).toBe('line');
+    expect(trendLine!.points).toHaveLength(2);
+  });
+
+  it('trend line spans the full x-range of points', () => {
+    const spec = makeBasicScatterSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const points = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+    const trendLine = computeTrendLine(points);
+
+    const minCx = Math.min(...points.map((p) => p.cx));
+    const maxCx = Math.max(...points.map((p) => p.cx));
+
+    expect(trendLine!.points[0].x).toBeCloseTo(minCx, 1);
+    expect(trendLine!.points[1].x).toBeCloseTo(maxCx, 1);
+  });
+
+  it('trend line is dashed', () => {
+    const spec = makeBasicScatterSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const points = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+    const trendLine = computeTrendLine(points);
+
+    expect(trendLine!.strokeDasharray).toBeTruthy();
+  });
+
+  it('returns null for fewer than 2 points', () => {
+    const singlePoint: PointMark[] = [
+      {
+        type: 'point',
+        cx: 100,
+        cy: 100,
+        r: 5,
+        fill: '#000',
+        stroke: '#fff',
+        strokeWidth: 1,
+        data: {},
+        aria: { label: 'test' },
+      },
+    ];
+
+    expect(computeTrendLine(singlePoint)).toBeNull();
+    expect(computeTrendLine([])).toBeNull();
+  });
+});

package/src/charts/scatter/__tests__/trendline.test.ts

@@ -0,0 +1,191 @@
+import type { PointMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { computeTrendLine } from '../trendline';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create a PointMark with the given center coordinates. */
+function makePoint(cx: number, cy: number): PointMark {
+  return {
+    type: 'point',
+    cx,
+    cy,
+    r: 5,
+    fill: '#333',
+    stroke: '#fff',
+    strokeWidth: 1,
+    data: {},
+    aria: { label: `point at (${cx}, ${cy})` },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('computeTrendLine', () => {
+  describe('linear regression computation', () => {
+    it('returns a LineMark with two endpoint coordinates', () => {
+      const points = [makePoint(100, 200), makePoint(200, 150), makePoint(300, 100)];
+      const result = computeTrendLine(points);
+
+      expect(result).not.toBeNull();
+      expect(result!.type).toBe('line');
+      expect(result!.points).toHaveLength(2);
+    });
+
+    it('computes correct regression for a perfect positive slope', () => {
+      // y = 2x + 10: when x=0,y=10; x=100,y=210; x=200,y=410
+      // Note: these are pixel coordinates, not data coordinates
+      const points = [makePoint(0, 10), makePoint(100, 210), makePoint(200, 410)];
+      const result = computeTrendLine(points)!;
+
+      // Line spans from x=0 to x=200
+      expect(result.points[0].x).toBeCloseTo(0, 1);
+      expect(result.points[1].x).toBeCloseTo(200, 1);
+
+      // y at x=0 should be 10, y at x=200 should be 410
+      expect(result.points[0].y).toBeCloseTo(10, 1);
+      expect(result.points[1].y).toBeCloseTo(410, 1);
+    });
+
+    it('computes correct regression for a perfect negative slope', () => {
+      // y = -x + 300: when x=0,y=300; x=100,y=200; x=200,y=100
+      const points = [makePoint(0, 300), makePoint(100, 200), makePoint(200, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.points[0].x).toBeCloseTo(0, 1);
+      expect(result.points[0].y).toBeCloseTo(300, 1);
+      expect(result.points[1].x).toBeCloseTo(200, 1);
+      expect(result.points[1].y).toBeCloseTo(100, 1);
+    });
+
+    it('computes a flat line for horizontal data', () => {
+      // All y values are the same
+      const points = [makePoint(50, 150), makePoint(150, 150), makePoint(250, 150)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.points[0].y).toBeCloseTo(150, 1);
+      expect(result.points[1].y).toBeCloseTo(150, 1);
+    });
+
+    it('spans from minimum to maximum x of input points', () => {
+      const points = [makePoint(80, 100), makePoint(250, 200), makePoint(120, 130)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.points[0].x).toBeCloseTo(80, 1);
+      expect(result.points[1].x).toBeCloseTo(250, 1);
+    });
+
+    it('fits a noisy dataset with approximate best-fit line', () => {
+      // Roughly y = 0.5x + 50, with noise
+      const points = [
+        makePoint(0, 48),
+        makePoint(50, 76),
+        makePoint(100, 98),
+        makePoint(150, 122),
+        makePoint(200, 152),
+      ];
+      const result = computeTrendLine(points)!;
+
+      // The slope should be approximately 0.5
+      const slope =
+        (result.points[1].y - result.points[0].y) / (result.points[1].x - result.points[0].x);
+      expect(slope).toBeCloseTo(0.5, 0);
+
+      // Intercept at x=0 should be approximately 50
+      expect(result.points[0].y).toBeCloseTo(50, -1); // within 10
+    });
+  });
+
+  describe('visual properties', () => {
+    it('renders with a dashed stroke pattern', () => {
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.strokeDasharray).toBe('6 4');
+    });
+
+    it('has a subdued stroke color', () => {
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.stroke).toBe('#666666');
+    });
+
+    it('has a thin stroke width', () => {
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.strokeWidth).toBe(1.5);
+    });
+
+    it('has an aria label describing the trend', () => {
+      const points = [makePoint(100, 200), makePoint(300, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.aria.label).toContain('Trend line');
+      expect(result.aria.label).toContain('linear regression');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns null for an empty array', () => {
+      expect(computeTrendLine([])).toBeNull();
+    });
+
+    it('returns null for a single point', () => {
+      expect(computeTrendLine([makePoint(100, 200)])).toBeNull();
+    });
+
+    it('handles exactly two points (deterministic line)', () => {
+      const points = [makePoint(100, 300), makePoint(400, 150)];
+      const result = computeTrendLine(points)!;
+
+      // With two points, the regression line passes through both
+      expect(result.points[0].x).toBeCloseTo(100, 1);
+      expect(result.points[0].y).toBeCloseTo(300, 1);
+      expect(result.points[1].x).toBeCloseTo(400, 1);
+      expect(result.points[1].y).toBeCloseTo(150, 1);
+    });
+
+    it('returns null for vertical data (all same x)', () => {
+      // All points have the same x coordinate: denominator in regression is 0
+      const points = [makePoint(100, 50), makePoint(100, 150), makePoint(100, 250)];
+      const result = computeTrendLine(points);
+
+      expect(result).toBeNull();
+    });
+
+    it('handles points at the same location gracefully', () => {
+      // All points are identical: zero variance in both x and y
+      const points = [makePoint(100, 100), makePoint(100, 100)];
+      const result = computeTrendLine(points);
+
+      // Denominator is zero, so regression returns null
+      expect(result).toBeNull();
+    });
+
+    it('handles large coordinate values without overflow', () => {
+      const points = [makePoint(10000, 50000), makePoint(20000, 60000), makePoint(30000, 70000)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.points[0].x).toBeCloseTo(10000, 0);
+      expect(result.points[1].x).toBeCloseTo(30000, 0);
+      // Perfect slope = 1
+      const slope =
+        (result.points[1].y - result.points[0].y) / (result.points[1].x - result.points[0].x);
+      expect(slope).toBeCloseTo(1, 5);
+    });
+
+    it('handles negative coordinates', () => {
+      const points = [makePoint(-200, -100), makePoint(0, 0), makePoint(200, 100)];
+      const result = computeTrendLine(points)!;
+
+      expect(result.points[0].x).toBeCloseTo(-200, 1);
+      expect(result.points[1].x).toBeCloseTo(200, 1);
+    });
+  });
+});

package/src/charts/scatter/compute.ts

@@ -0,0 +1,124 @@
+/**
+ * Scatter / bubble chart mark computation.
+ *
+ * Takes a normalized chart spec with resolved scales and produces
+ * PointMark[] for rendering scatter plots. Both axes are quantitative.
+ * Optional size encoding produces area-proportional bubbles via sqrt
+ * scaling, and color encoding groups points by category.
+ */
+
+import type {
+  Encoding,
+  LayoutStrategy,
+  MarkAria,
+  PointMark,
+  Rect,
+} from '@opendata-ai/openchart-core';
+import { max, min } from 'd3-array';
+import type { ScaleLinear } from 'd3-scale';
+import { scaleSqrt } from 'd3-scale';
+
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_POINT_RADIUS = 5;
+const MIN_BUBBLE_RADIUS = 3;
+const MAX_BUBBLE_RADIUS = 30;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute scatter/bubble marks from a normalized chart spec.
+ *
+ * Both x and y are quantitative (linear scales). Optional size encoding
+ * maps a data field to point radius using sqrt scale (area-proportional).
+ * Optional color encoding groups points by category with distinct colors.
+ */
+export function computeScatterMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  _chartArea: Rect,
+  _strategy: LayoutStrategy,
+): PointMark[] {
+  const encoding = spec.encoding as Encoding;
+  const xChannel = encoding.x;
+  const yChannel = encoding.y;
+
+  if (!xChannel || !yChannel || !scales.x || !scales.y) {
+    return [];
+  }
+
+  const xScale = scales.x.scale as ScaleLinear<number, number>;
+  const yScale = scales.y.scale as ScaleLinear<number, number>;
+
+  const colorField = encoding.color?.field;
+  const sizeField = encoding.size?.field;
+
+  // Build a size scale for bubble variant
+  let sizeScale: ((v: number) => number) | undefined;
+  if (sizeField) {
+    const sizeValues = spec.data.map((d) => Number(d[sizeField])).filter((v) => Number.isFinite(v));
+
+    const sizeMin = min(sizeValues) ?? 0;
+    const sizeMax = max(sizeValues) ?? 1;
+
+    sizeScale = scaleSqrt()
+      .domain([sizeMin, sizeMax])
+      .range([MIN_BUBBLE_RADIUS, MAX_BUBBLE_RADIUS]);
+  }
+
+  const marks: PointMark[] = [];
+
+  for (const row of spec.data) {
+    const xVal = Number(row[xChannel.field]);
+    const yVal = Number(row[yChannel.field]);
+
+    if (!Number.isFinite(xVal) || !Number.isFinite(yVal)) continue;
+
+    const cx = xScale(xVal);
+    const cy = yScale(yVal);
+
+    const category = colorField ? String(row[colorField] ?? '') : undefined;
+    const color = getColor(scales, category ?? '__default__');
+
+    let radius = DEFAULT_POINT_RADIUS;
+    if (sizeScale && sizeField) {
+      const sizeVal = Number(row[sizeField]);
+      if (Number.isFinite(sizeVal)) {
+        radius = sizeScale(sizeVal);
+      }
+    }
+
+    const labelParts = [`${xChannel.field}=${xVal}`, `${yChannel.field}=${yVal}`];
+    if (category) labelParts.push(`${colorField}=${category}`);
+    if (sizeField && row[sizeField] != null) {
+      labelParts.push(`${sizeField}=${row[sizeField]}`);
+    }
+
+    const aria: MarkAria = {
+      label: `Data point: ${labelParts.join(', ')}`,
+    };
+
+    marks.push({
+      type: 'point',
+      cx,
+      cy,
+      r: radius,
+      fill: color,
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      fillOpacity: 0.7,
+      data: row as Record<string, unknown>,
+      aria,
+    });
+  }
+
+  return marks;
+}