@opendata-ai/openchart-engine 8.0.0-rc.8 → 8.0.0

package/src/charts/scatter/compute.ts

@@ -1,192 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,307 +0,0 @@
-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);
-    }
-  });
-});