@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/charts/scatter/compute.ts

@@ -0,0 +1,192 @@
+/**
+ * Scatter / bubble chart mark computation.
+ *
+ * Takes a normalized chart spec with resolved scales and produces
+ * PointMark[] for rendering scatter plots. Axes can be any field type.
+ * Optional size encoding produces area-proportional bubbles via sqrt
+ * scaling, and color encoding groups points by category.
+ */
+
+import type {
+  Encoding,
+  FieldType,
+  GradientDef,
+  LayoutStrategy,
+  MarkAria,
+  PointMark,
+  Rect,
+} from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
+import { buildSizeScale, SIZE_SCALE_DEFAULTS } from '../../compile/size-scale';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, getSequentialColor } from '../utils';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_POINT_RADIUS = 5;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve a data value to a pixel position based on channel type and scale. */
+function resolvePosition(
+  value: unknown,
+  channelType: FieldType,
+  scale:
+    | ScaleLinear<number, number>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>,
+): number | undefined {
+  switch (channelType) {
+    case 'nominal':
+    case 'ordinal': {
+      const s = String(value);
+      if ('bandwidth' in scale && typeof scale.bandwidth === 'function') {
+        const bw = (scale as ScaleBand<string>).bandwidth();
+        const pos = (scale as ScaleBand<string>)(s);
+        if (pos === undefined) return undefined;
+        // ScalePoint has bandwidth() === 0; ScaleBand has > 0.
+        return bw > 0 ? pos + bw / 2 : pos;
+      }
+      return (scale as ScalePoint<string>)(s);
+    }
+    case 'temporal': {
+      const px = (scale as ScaleTime<number, number>)(new Date(value as string | number));
+      return Number.isNaN(px) ? undefined : px;
+    }
+    default: {
+      const num = Number(value);
+      if (!Number.isFinite(num)) return undefined;
+      return (scale as ScaleLinear<number, number>)(num);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute scatter/bubble marks from a normalized chart spec.
+ *
+ * Axes accept any field type: quantitative (linear), temporal (time),
+ * nominal/ordinal (band or point scale). 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>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>;
+  const yScale = scales.y.scale as
+    | ScaleLinear<number, number>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>;
+  const xType = xChannel.type;
+  const yType = yChannel.type;
+
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const isSequentialColor = colorEnc?.type === 'quantitative';
+  const colorField = colorEnc?.field;
+  const sizeEnc = encoding.size && 'field' in encoding.size ? encoding.size : undefined;
+  const sizeField = sizeEnc?.field;
+
+  // Bubbles: sqrt so perceived magnitude tracks disc *area*. Author overrides
+  // (`encoding.size.scale.{domain,range}`) and the degenerate-domain fallback
+  // live in the shared builder, which the size legend also calls so the key and
+  // the marks can never resolve different scales.
+  const resolvedSize = buildSizeScale(sizeEnc, spec.data, SIZE_SCALE_DEFAULTS.point);
+  const sizeScale = resolvedSize?.scale;
+
+  const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
+  const keyField = keyEnc?.field;
+  const marks: PointMark[] = [];
+
+  for (const row of spec.data) {
+    const rawX = row[xChannel.field];
+    const rawY = row[yChannel.field];
+
+    const cx = resolvePosition(rawX, xType, xScale);
+    const cy = resolvePosition(rawY, yType, yScale);
+
+    if (cx === undefined || cy === undefined) continue;
+
+    const category = colorField && !isSequentialColor ? String(row[colorField] ?? '') : undefined;
+    let color: string | GradientDef;
+    if (isSequentialColor && colorField) {
+      const val = Number(row[colorField]);
+      color = Number.isFinite(val)
+        ? getSequentialColor(scales, val)
+        : getColor(scales, '__default__');
+    } else {
+      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}=${rawX}`, `${yChannel.field}=${rawY}`];
+    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,
+    });
+  }
+
+  // Stamp keys: encoding.key field when set, else seriesKey|x composite
+  const rawKeys = marks.map((m) => {
+    if (keyField) return serializeKeyValue(m.data[keyField]);
+    const cat = colorField ? String(m.data[colorField] ?? '') : '';
+    const xVal = serializeKeyValue(m.data[xChannel.field]);
+    return cat ? `${cat}|${xVal}` : xVal;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
+  return marks;
+}

package/src/charts/scatter/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Scatter / bubble chart module.
+ *
+ * Exports the scatter chart renderer and computation functions.
+ */
+
+import type { Mark } from '@opendata-ai/openchart-core';
+import type { ChartRenderer } from '../registry';
+import { computeScatterMarks } from './compute';
+import { computeTrendLine } from './trendline';
+
+// ---------------------------------------------------------------------------
+// Scatter chart renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Scatter chart renderer.
+ *
+ * Produces point marks for each data point, optionally with size encoding
+ * for bubbles and a trend line overlay.
+ */
+export const scatterRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
+  const pointMarks = computeScatterMarks(spec, scales, chartArea, strategy);
+  const marks: Mark[] = [...pointMarks];
+
+  // Regression trend line renders by default but is opt-out via
+  // `mark: { type: 'point', trendline: false }`. Rendering it unconditionally
+  // competed with author-drawn reference lines (e.g. a manual x=y diagonal),
+  // so a chart could show two diagonals.
+  if (spec.markDef?.trendline !== false) {
+    const trendLine = computeTrendLine(pointMarks);
+    if (trendLine) {
+      // Trend line goes behind points
+      marks.unshift(trendLine);
+    }
+  }
+
+  return marks;
+};
+
+// ---------------------------------------------------------------------------
+// Public exports
+// ---------------------------------------------------------------------------
+
+export { computeScatterMarks } from './compute';
+export { computeTrendLine } from './trendline';

package/src/charts/scatter/trendline.ts

@@ -0,0 +1,100 @@
+/**
+ * Trend line computation for scatter plots.
+ *
+ * Computes a simple linear regression (least squares) over the
+ * point marks and returns a LineMark representing the best-fit line.
+ */
+
+import type { LineMark, MarkAria, PointMark } from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TRENDLINE_COLOR = '#666666';
+const TRENDLINE_STROKE_WIDTH = 1.5;
+const TRENDLINE_DASH = '6 4';
+
+// ---------------------------------------------------------------------------
+// Linear regression
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute slope and intercept for a simple linear regression.
+ * Returns null if there aren't enough points or variance is zero.
+ */
+function linearRegression(
+  points: { x: number; y: number }[],
+): { slope: number; intercept: number } | null {
+  const n = points.length;
+  if (n < 2) return null;
+
+  let sumX = 0;
+  let sumY = 0;
+  let sumXY = 0;
+  let sumXX = 0;
+
+  for (const p of points) {
+    sumX += p.x;
+    sumY += p.y;
+    sumXY += p.x * p.y;
+    sumXX += p.x * p.x;
+  }
+
+  const denominator = n * sumXX - sumX * sumX;
+  if (denominator === 0) return null;
+
+  const slope = (n * sumXY - sumX * sumY) / denominator;
+  const intercept = (sumY - slope * sumX) / n;
+
+  return { slope, intercept };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a trend line (linear regression) over scatter point marks.
+ *
+ * Returns a single LineMark spanning the x-range of the data points,
+ * rendered as a dashed line. Returns null if regression can't be computed.
+ */
+export function computeTrendLine(marks: PointMark[]): LineMark | null {
+  if (marks.length < 2) return null;
+
+  const points = marks.map((m) => ({ x: m.cx, y: m.cy }));
+  const result = linearRegression(points);
+  if (!result) return null;
+
+  const { slope, intercept } = result;
+
+  // Find x range from marks
+  let minX = Infinity;
+  let maxX = -Infinity;
+  for (const m of marks) {
+    if (m.cx < minX) minX = m.cx;
+    if (m.cx > maxX) maxX = m.cx;
+  }
+
+  // Compute y values at the endpoints
+  const y1 = slope * minX + intercept;
+  const y2 = slope * maxX + intercept;
+
+  const aria: MarkAria = {
+    label: `Trend line: linear regression`,
+  };
+
+  return {
+    type: 'line',
+    points: [
+      { x: minX, y: y1 },
+      { x: maxX, y: y2 },
+    ],
+    stroke: TRENDLINE_COLOR,
+    strokeWidth: TRENDLINE_STROKE_WIDTH,
+    strokeDasharray: TRENDLINE_DASH,
+    data: [],
+    aria,
+  };
+}

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

@@ -0,0 +1,307 @@
+import type { ChartSpec, LayerSpec, PointMark, TextMarkLayout } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart, compileLayer } from '../../../compile';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+/**
+ * Ten US states, GDP (trillions) vs population (millions). The low end clusters
+ * tightly, which is what made the scale-domain bug so visible: the further a
+ * point sat from the shared upper bound, the further its label drifted.
+ */
+const states = [
+  { label: 'CA', gdp: 3.9, pop: 39.0 },
+  { label: 'TX', gdp: 2.6, pop: 30.5 },
+  { label: 'NY', gdp: 2.1, pop: 19.6 },
+  { label: 'FL', gdp: 1.6, pop: 22.6 },
+  { label: 'IL', gdp: 1.1, pop: 12.5 },
+  { label: 'PA', gdp: 1.0, pop: 12.9 },
+  { label: 'OH', gdp: 0.9, pop: 11.8 },
+  { label: 'GA', gdp: 0.8, pop: 11.0 },
+  { label: 'NJ', gdp: 0.8, pop: 9.3 },
+  { label: 'WA', gdp: 0.8, pop: 7.8 },
+];
+
+/** A points layer plus a text layer, both encoding the *same* x/y fields. */
+function labeledScatter(textMark: ChartSpec['mark'] = { type: 'text' }): LayerSpec {
+  return {
+    layer: [
+      {
+        mark: { type: 'point' },
+        data: [...states],
+        encoding: {
+          x: { field: 'gdp', type: 'quantitative' },
+          y: { field: 'pop', type: 'quantitative' },
+        },
+      },
+      {
+        mark: textMark,
+        data: [...states],
+        encoding: {
+          x: { field: 'gdp', type: 'quantitative' },
+          y: { field: 'pop', type: 'quantitative' },
+          text: { field: 'label', type: 'nominal' },
+        },
+      },
+    ],
+  };
+}
+
+function textMarksOf(spec: ChartSpec): TextMarkLayout[] {
+  const layout = compileChart(spec, { width: 900, height: 500 });
+  return layout.marks.filter((m): m is TextMarkLayout => m.type === 'textMark');
+}
+
+/** Standalone text chart over the states, with an overridable mark def. */
+function textChart(mark: ChartSpec['mark'] = { type: 'text' }): ChartSpec {
+  return {
+    mark,
+    data: [...states],
+    encoding: {
+      x: { field: 'gdp', type: 'quantitative' },
+      y: { field: 'pop', type: 'quantitative' },
+      text: { field: 'label', type: 'nominal' },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Scale alignment
+// ---------------------------------------------------------------------------
+
+describe('text marks in a layer', () => {
+  /**
+   * Regression: text is a position-encoding mark, so it must resolve its domain
+   * the same way `point`/`beeswarm`/`range` do (tight, not zero-anchored). When
+   * it didn't, a text layer and a point layer over identical fields resolved
+   * *different* domains across the same pixel range, and every label drifted off
+   * the dot it was labeling — by up to 160px at the low end of the domain.
+   */
+  it('positions each label exactly on the point it labels', () => {
+    const layout = compileLayer(labeledScatter(), { width: 900, height: 500 });
+
+    const points = layout.marks.filter((m): m is PointMark => m.type === 'point');
+    const texts = layout.marks.filter((m): m is TextMarkLayout => m.type === 'textMark');
+
+    expect(points).toHaveLength(states.length);
+    expect(texts).toHaveLength(states.length);
+
+    for (const text of texts) {
+      const point = points.find((p) => p.data?.label === text.text);
+      expect(point, `no point for label ${text.text}`).toBeDefined();
+
+      expect(text.x).toBeCloseTo((point as PointMark).cx, 5);
+      expect(text.y).toBeCloseTo((point as PointMark).cy, 5);
+    }
+  });
+
+  it('offsets labels off their points by exactly dy, keeping x aligned', () => {
+    const layout = compileLayer(labeledScatter({ type: 'text', dy: -10 }), {
+      width: 900,
+      height: 500,
+    });
+
+    const points = layout.marks.filter((m): m is PointMark => m.type === 'point');
+    const texts = layout.marks.filter((m): m is TextMarkLayout => m.type === 'textMark');
+
+    for (const text of texts) {
+      const point = points.find((p) => p.data?.label === text.text) as PointMark;
+      expect(text.x).toBeCloseTo(point.cx, 5);
+      expect(text.y).toBeCloseTo(point.cy - 10, 5);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Offsets
+// ---------------------------------------------------------------------------
+
+describe('dx / dy', () => {
+  it('bakes the offset into x/y and retains the pre-offset anchor', () => {
+    const plain = textMarksOf(textChart());
+    const offset = textMarksOf(textChart({ type: 'text', dx: 6, dy: -10 }));
+
+    for (let i = 0; i < plain.length; i++) {
+      expect(offset[i].x).toBeCloseTo(plain[i].x + 6, 5);
+      expect(offset[i].y).toBeCloseTo(plain[i].y - 10, 5);
+      // The anchor is what a leader line would point back to.
+      expect(offset[i].anchorX).toBeCloseTo(plain[i].x, 5);
+      expect(offset[i].anchorY).toBeCloseTo(plain[i].y, 5);
+    }
+  });
+
+  it('leaves the anchor unset when the mark is not offset', () => {
+    for (const mark of textMarksOf(textChart())) {
+      expect(mark.anchorX).toBeUndefined();
+      expect(mark.anchorY).toBeUndefined();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Alignment / baseline
+// ---------------------------------------------------------------------------
+
+describe('align and baseline', () => {
+  it('centers on the data point by default', () => {
+    for (const mark of textMarksOf(textChart())) {
+      expect(mark.textAnchor).toBe('middle');
+      expect(mark.dominantBaseline).toBe('central');
+    }
+  });
+
+  it('maps align/baseline onto SVG anchor and baseline', () => {
+    const marks = textMarksOf(textChart({ type: 'text', align: 'left', baseline: 'top' }));
+    for (const mark of marks) {
+      expect(mark.textAnchor).toBe('start');
+      expect(mark.dominantBaseline).toBe('hanging');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Size channel
+// ---------------------------------------------------------------------------
+
+describe('size channel', () => {
+  const sized = (): ChartSpec => ({
+    mark: { type: 'text' },
+    data: [...states],
+    encoding: {
+      x: { field: 'gdp', type: 'quantitative' },
+      y: { field: 'pop', type: 'quantitative' },
+      text: { field: 'label', type: 'nominal' },
+      size: { field: 'gdp', type: 'quantitative' },
+    },
+  });
+
+  it('maps the size field linearly onto the default font range', () => {
+    const marks = textMarksOf(sized());
+    const byLabel = new Map(marks.map((m) => [m.text, m]));
+
+    // gdp spans 0.8 (WA) to 3.9 (CA) -> the default 11..32px range.
+    expect(byLabel.get('WA')?.fontSize).toBeCloseTo(11, 5);
+    expect(byLabel.get('CA')?.fontSize).toBeCloseTo(32, 5);
+
+    // Linear, not sqrt: interior values interpolate proportionally. A sqrt scale
+    // would land NY well above this.
+    const ny = byLabel.get('NY') as TextMarkLayout; // gdp 2.1
+    const expectedNy = 11 + (32 - 11) * ((2.1 - 0.8) / (3.9 - 0.8));
+    expect(ny.fontSize).toBeCloseTo(expectedNy, 5);
+  });
+
+  it('honors an explicit scale range', () => {
+    const spec = sized();
+    (spec.encoding.size as { scale?: unknown }).scale = { range: [10, 20] };
+
+    const marks = textMarksOf(spec);
+    const byLabel = new Map(marks.map((m) => [m.text, m]));
+    expect(byLabel.get('WA')?.fontSize).toBeCloseTo(10, 5);
+    expect(byLabel.get('CA')?.fontSize).toBeCloseTo(20, 5);
+  });
+
+  it('falls back to mark.fontSize when there is no size encoding', () => {
+    for (const mark of textMarksOf(textChart({ type: 'text', fontSize: 14 }))) {
+      expect(mark.fontSize).toBe(14);
+    }
+  });
+
+  it('defaults to 12px with no size encoding and no fontSize', () => {
+    for (const mark of textMarksOf(textChart())) {
+      expect(mark.fontSize).toBe(12);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Subset label layers
+// ---------------------------------------------------------------------------
+
+describe('a label layer over a subset of the points', () => {
+  /**
+   * Direct labeling usually names only the notable points, so the text layer
+   * carries fewer rows than the point layer. The two must still resolve the same
+   * domain — a subset must not re-fit the scale to its own narrower extent.
+   */
+  it('keeps subset labels aligned with the full point layer', () => {
+    const labeled = new Set(['CA', 'TX', 'NY', 'FL', 'IL', 'WA']);
+    const spec: LayerSpec = {
+      layer: [
+        {
+          mark: { type: 'point' },
+          data: [...states],
+          encoding: {
+            x: { field: 'gdp', type: 'quantitative' },
+            y: { field: 'pop', type: 'quantitative' },
+          },
+        },
+        {
+          mark: { type: 'text', dy: -14 },
+          data: states.filter((d) => labeled.has(d.label)),
+          encoding: {
+            x: { field: 'gdp', type: 'quantitative' },
+            y: { field: 'pop', type: 'quantitative' },
+            text: { field: 'label', type: 'nominal' },
+          },
+        },
+      ],
+    };
+
+    const layout = compileLayer(spec, { width: 900, height: 500 });
+    const points = layout.marks.filter((m): m is PointMark => m.type === 'point');
+    const texts = layout.marks.filter((m): m is TextMarkLayout => m.type === 'textMark');
+
+    expect(points).toHaveLength(states.length);
+    expect(texts).toHaveLength(labeled.size);
+
+    for (const text of texts) {
+      const point = points.find((p) => p.data?.label === text.text) as PointMark;
+      expect(text.x).toBeCloseTo(point.cx, 5);
+      expect(text.y).toBeCloseTo(point.cy - 14, 5);
+    }
+  });
+});
+
+describe('a subset whose extent is narrower than the point layer', () => {
+  /**
+   * Dropping the min-x row from the label layer narrows *its* data extent. If
+   * each leaf resolves its own domain, the label layer re-fits [1.1, 3.9] while
+   * the points keep [0.8, 3.9], and every label slides left off its dot.
+   */
+  it('still aligns when the label subset omits the extreme point', () => {
+    const labeled = new Set(['CA', 'TX', 'NY', 'FL', 'IL']); // no WA (the min gdp)
+    const spec: LayerSpec = {
+      layer: [
+        {
+          mark: { type: 'point' },
+          data: [...states],
+          encoding: {
+            x: { field: 'gdp', type: 'quantitative' },
+            y: { field: 'pop', type: 'quantitative' },
+          },
+        },
+        {
+          mark: { type: 'text' },
+          data: states.filter((d) => labeled.has(d.label)),
+          encoding: {
+            x: { field: 'gdp', type: 'quantitative' },
+            y: { field: 'pop', type: 'quantitative' },
+            text: { field: 'label', type: 'nominal' },
+          },
+        },
+      ],
+    };
+
+    const layout = compileLayer(spec, { width: 900, height: 500 });
+    const points = layout.marks.filter((m): m is PointMark => m.type === 'point');
+    const texts = layout.marks.filter((m): m is TextMarkLayout => m.type === 'textMark');
+
+    for (const text of texts) {
+      const point = points.find((p) => p.data?.label === text.text) as PointMark;
+      expect(text.x, `label ${text.text} drifted in x`).toBeCloseTo(point.cx, 5);
+      expect(text.y, `label ${text.text} drifted in y`).toBeCloseTo(point.cy, 5);
+    }
+  });
+});