@opendata-ai/openchart-engine 8.0.0-rc.2 → 8.0.0-rc.20

package/src/charts/beeswarm/__tests__/dodge.test.ts

@@ -1,148 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { DEFAULT_DODGE_PADDING, dodgeOffsets } from '../dodge';
-
-// ---------------------------------------------------------------------------
-// Fixtures
-// ---------------------------------------------------------------------------
-
-/** Deterministic pseudo-random sequence (mulberry32) for repeatable fixtures. */
-function seededRandom(seed: number): () => number {
-  let a = seed;
-  return () => {
-    a |= 0;
-    a = (a + 0x6d2b79f5) | 0;
-    let t = Math.imul(a ^ (a >>> 15), 1 | a);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-/** Clustered value-axis positions in [0, 500] that force many collisions. */
-function makePositions(count: number, seed = 42): number[] {
-  const rand = seededRandom(seed);
-  return Array.from({ length: count }, () => {
-    // Sum of two draws clusters values around the middle (triangular-ish)
-    return ((rand() + rand()) / 2) * 500;
-  });
-}
-
-/** Assert every pair of circles keeps at least (r1 + r2) separation. */
-function expectNoOverlap(
-  positions: readonly number[],
-  offsets: readonly number[],
-  radii: readonly number[],
-): void {
-  const epsilon = 1e-6;
-  for (let i = 0; i < positions.length; i++) {
-    for (let j = i + 1; j < positions.length; j++) {
-      const dx = positions[i] - positions[j];
-      const dy = offsets[i] - offsets[j];
-      const dist = Math.sqrt(dx * dx + dy * dy);
-      expect(dist).toBeGreaterThanOrEqual(radii[i] + radii[j] - epsilon);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('dodgeOffsets', () => {
-  it('leaves a single dot at offset 0', () => {
-    expect(dodgeOffsets([100], [4])).toEqual([0]);
-  });
-
-  it('leaves non-colliding dots at offset 0', () => {
-    const offsets = dodgeOffsets([0, 100, 200], [4, 4, 4]);
-    expect(offsets).toEqual([0, 0, 0]);
-  });
-
-  it('produces zero overlapping circles at 300 clustered points', () => {
-    const positions = makePositions(300);
-    const radii = positions.map(() => 4);
-    const offsets = dodgeOffsets(positions, radii);
-    expectNoOverlap(positions, offsets, radii);
-  });
-
-  it('respects per-dot radii (sized dots stay collision-free)', () => {
-    const positions = makePositions(150, 7);
-    const rand = seededRandom(99);
-    const radii = positions.map(() => 2 + rand() * 8);
-    const offsets = dodgeOffsets(positions, radii);
-    expectNoOverlap(positions, offsets, radii);
-  });
-
-  it('is deterministic: same input yields identical output', () => {
-    const positions = makePositions(200, 3);
-    const radii = positions.map(() => 4);
-    const first = dodgeOffsets(positions, radii);
-    const second = dodgeOffsets(positions, radii);
-    expect(second).toEqual(first);
-  });
-
-  it('keeps the first placed dot on the lane center and breaks symmetric ties to the negative side', () => {
-    // Two dots at the same position: the first (by index) stays at 0, the
-    // second must move; both interval edges have equal magnitude, so the
-    // documented tie-break picks the negative side.
-    const offsets = dodgeOffsets([100, 100], [4, 4]);
-    expect(offsets[0]).toBe(0);
-    expect(offsets[1]).toBeLessThan(0);
-    expect(Math.abs(offsets[1])).toBeCloseTo(8 + DEFAULT_DODGE_PADDING, 6);
-  });
-
-  it('places dots at the minimal offset avoiding collisions', () => {
-    // Three dots at one position: center, one side, other side; the third
-    // dot must not leapfrog to a farther slot.
-    const offsets = dodgeOffsets([50, 50, 50], [4, 4, 4]);
-    expect(offsets[0]).toBe(0);
-    const sep = 8 + DEFAULT_DODGE_PADDING;
-    expect(Math.abs(offsets[1])).toBeCloseTo(sep, 6);
-    expect(Math.abs(offsets[2])).toBeCloseTo(sep, 6);
-    expect(Math.sign(offsets[1])).not.toBe(Math.sign(offsets[2]));
-  });
-
-  it('maps offsets back to input order, not sweep order', () => {
-    // Descending input positions: the sweep runs ascending, but each offset
-    // must land on its own input index.
-    const positions = [300, 100, 200];
-    const offsets = dodgeOffsets(positions, [4, 4, 4]);
-    expect(offsets).toEqual([0, 0, 0]);
-  });
-
-  it('dodges only within a lane', () => {
-    // Same position, different lanes: no collision, both stay centered.
-    const separate = dodgeOffsets([100, 100], [4, 4], ['a', 'b']);
-    expect(separate).toEqual([0, 0]);
-
-    // Same lane collides as usual.
-    const together = dodgeOffsets([100, 100], [4, 4], ['a', 'a']);
-    expect(together[1]).not.toBe(0);
-  });
-
-  it('keeps lanes independent and collision-free in mixed input', () => {
-    const rand = seededRandom(11);
-    const lanesPool = ['a', 'b', 'c', 'd'];
-    const positions = makePositions(200, 5);
-    const radii = positions.map(() => 4);
-    const lanes = positions.map(() => lanesPool[Math.floor(rand() * lanesPool.length)]);
-    const offsets = dodgeOffsets(positions, radii, lanes);
-
-    for (const lane of lanesPool) {
-      const idx = positions.map((_, i) => i).filter((i) => lanes[i] === lane);
-      expectNoOverlap(
-        idx.map((i) => positions[i]),
-        idx.map((i) => offsets[i]),
-        idx.map((i) => radii[i]),
-      );
-    }
-  });
-
-  it('honors a custom padding', () => {
-    const offsets = dodgeOffsets([100, 100], [4, 4], undefined, 5);
-    expect(Math.abs(offsets[1])).toBeCloseTo(13, 6);
-  });
-
-  it('returns an empty array for empty input', () => {
-    expect(dodgeOffsets([], [])).toEqual([]);
-  });
-});

package/src/charts/beeswarm/compute.ts

@@ -1,203 +0,0 @@
-/**
- * Beeswarm chart mark computation.
- *
- * One quantitative value axis positions every observation; the deterministic
- * dodge layout (see ./dodge) spreads colliding dots along the cross axis so
- * each dot stays visible. An optional nominal channel on the other axis
- * groups the dots into lanes (one swarm per category via a band scale).
- * The cross axis has no scale: offsets are pure pixel-space.
- *
- * Orientation follows the bar convention: quantitative x = horizontal swarm,
- * quantitative y = vertical swarm.
- */
-
-import type {
-  Encoding,
-  GradientDef,
-  LayoutStrategy,
-  MarkAria,
-  PointMark,
-  Rect,
-} from '@opendata-ai/openchart-core';
-import type { ScaleBand, ScaleLinear } 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';
-import { dodgeOffsets } from './dodge';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/**
- * Default dot radius (px). Smaller than the scatter default (5) because
- * beeswarms carry hundreds of dots and the dodge layout trades radius for
- * swarm height: at r=4 a 300-dot swarm stays inside a typical chart area.
- */
-const DEFAULT_DOT_RADIUS = 4;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compute beeswarm marks from a normalized chart spec.
- *
- * The quantitative channel is the value axis (x = horizontal swarm,
- * y = vertical). The opposite channel, when present, must be nominal/ordinal
- * and lanes the dots via its band scale; otherwise all dots share one lane
- * centered on the cross axis. Radii come from the optional `size` encoding
- * (sqrt scale, area-proportional) or the default dot radius; the dodge
- * layout consumes per-dot radii so sized swarms stay collision-free.
- */
-export function computeBeeswarmMarks(
-  spec: NormalizedChartSpec,
-  scales: ResolvedScales,
-  chartArea: Rect,
-  _strategy: LayoutStrategy,
-): PointMark[] {
-  const encoding = spec.encoding as Encoding;
-
-  // Orientation: prefer a quantitative x (horizontal swarm), else quantitative y.
-  const isHorizontal = encoding.x?.type === 'quantitative';
-  const valueChannel = isHorizontal ? encoding.x : encoding.y;
-  const laneChannel = isHorizontal ? encoding.y : encoding.x;
-  const valueScale = isHorizontal ? scales.x : scales.y;
-  const laneScale = isHorizontal ? scales.y : scales.x;
-
-  if (!valueChannel || valueChannel.type !== 'quantitative' || !valueScale) {
-    return [];
-  }
-
-  const positionScale = valueScale.scale as ScaleLinear<number, number>;
-
-  // Lane centers: band scale when the nominal channel is present, else the
-  // middle of the cross axis. The cross axis itself has no scale: dodge
-  // offsets are pixel-space around each lane center.
-  const bandScale =
-    laneScale && laneScale.type === 'band' ? (laneScale.scale as ScaleBand<string>) : undefined;
-  const defaultLaneCenter = isHorizontal
-    ? chartArea.y + chartArea.height / 2
-    : chartArea.x + chartArea.width / 2;
-
-  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;
-
-  // Sized dots: sqrt (area-proportional), same override surface as scatter.
-  // Shared builder so the marks and any size legend resolve one scale.
-  const resolvedSize = buildSizeScale(sizeEnc, spec.data, SIZE_SCALE_DEFAULTS.beeswarm);
-  const sizeScale = resolvedSize?.scale;
-
-  // Resolve every renderable dot first: dodge needs the full position/radius
-  // arrays before any mark can be placed.
-  interface ResolvedDot {
-    row: Record<string, unknown>;
-    value: number;
-    position: number;
-    radius: number;
-    lane: string;
-    laneCenter: number;
-  }
-  const dots: ResolvedDot[] = [];
-
-  for (const row of spec.data) {
-    const raw = row[valueChannel.field];
-    // Drop null/undefined explicitly: the validator tolerates them (it only
-    // rejects non-numeric or non-finite present values), but Number(null) is 0,
-    // which would silently place a phantom dot at value 0 instead of skipping.
-    if (raw == null) continue;
-    const value = Number(raw);
-    if (!Number.isFinite(value)) continue;
-
-    const position = positionScale(value);
-    if (!Number.isFinite(position)) continue;
-
-    let lane = '__default__';
-    let laneCenter = defaultLaneCenter;
-    if (bandScale && laneChannel) {
-      lane = String(row[laneChannel.field] ?? '');
-      const bandStart = bandScale(lane);
-      if (bandStart === undefined) continue;
-      laneCenter = bandStart + bandScale.bandwidth() / 2;
-    }
-
-    let radius = DEFAULT_DOT_RADIUS;
-    if (sizeScale && sizeField) {
-      const sizeVal = Number(row[sizeField]);
-      if (Number.isFinite(sizeVal)) {
-        radius = sizeScale(sizeVal);
-      }
-    }
-
-    dots.push({ row: row as Record<string, unknown>, value, position, radius, lane, laneCenter });
-  }
-
-  const offsets = dodgeOffsets(
-    dots.map((d) => d.position),
-    dots.map((d) => d.radius),
-    dots.map((d) => d.lane),
-  );
-
-  const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
-  const keyField = keyEnc?.field;
-  const marks: PointMark[] = [];
-
-  for (let i = 0; i < dots.length; i++) {
-    const dot = dots[i];
-    const cross = dot.laneCenter + offsets[i];
-
-    let color: string | GradientDef;
-    if (isSequentialColor && colorField) {
-      const colorVal = Number(dot.row[colorField]);
-      color = Number.isFinite(colorVal)
-        ? getSequentialColor(scales, colorVal)
-        : getColor(scales, '__default__');
-    } else if (colorField) {
-      color = getColor(scales, String(dot.row[colorField] ?? '__default__'));
-    } else {
-      color = getColor(scales, '__default__');
-    }
-
-    const labelParts = [`${valueChannel.field}=${dot.row[valueChannel.field]}`];
-    if (laneChannel && dot.lane !== '__default__') {
-      labelParts.push(`${laneChannel.field}=${dot.lane}`);
-    }
-    if (sizeField && dot.row[sizeField] != null) {
-      labelParts.push(`${sizeField}=${dot.row[sizeField]}`);
-    }
-
-    const aria: MarkAria = {
-      label: `Data point: ${labelParts.join(', ')}`,
-    };
-
-    marks.push({
-      type: 'point',
-      cx: isHorizontal ? dot.position : cross,
-      cy: isHorizontal ? cross : dot.position,
-      r: dot.radius,
-      fill: color,
-      stroke: '#ffffff',
-      strokeWidth: 1,
-      data: dot.row,
-      aria,
-    });
-  }
-
-  // Stamp keys: encoding.key field when set, else lane|value composite
-  const rawKeys = marks.map((m, i) => {
-    if (keyField) return serializeKeyValue(m.data[keyField]);
-    const valueKey = serializeKeyValue(m.data[valueChannel.field]);
-    return dots[i].lane !== '__default__' ? `${dots[i].lane}|${valueKey}` : valueKey;
-  });
-  const keys = dedupeKeys(rawKeys);
-  for (let i = 0; i < marks.length; i++) {
-    marks[i].key = keys[i];
-  }
-
-  return marks;
-}

package/src/charts/beeswarm/dodge.ts

@@ -1,155 +0,0 @@
-/**
- * Deterministic sweep-line dodge for beeswarm layouts.
- *
- * Port of Observable Plot's dodge transform (anchor "middle"): dots are
- * placed in value order, each at the smallest signed cross-axis offset that
- * avoids every previously placed circle. Pure array math with stable sorts
- * and explicit tie-breaking, so the same input always produces the same
- * output: no force simulation, no iteration tuning, no animation frames.
- */
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Default extra gap (px) enforced between circle edges. */
-export const DEFAULT_DODGE_PADDING = 1;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compute cross-axis offsets that resolve circle collisions along a value axis.
- *
- * Dots are processed in ascending value-axis order (ties broken by input
- * index, so the layout is deterministic). For each dot, every already-placed
- * dot that overlaps it horizontally contributes a blocked interval of
- * cross-axis offsets; the dot takes the smallest-magnitude offset outside all
- * blocked intervals. Candidates are 0 and the blocked-interval edges; when a
- * positive and a negative candidate have equal magnitude, the negative side
- * wins (up in a horizontal swarm, left in a vertical one).
- *
- * When `lanes` is provided, dots dodge only against dots in the same lane
- * (one independent swarm per category).
- *
- * @param positions - Value-axis pixel positions, one per dot.
- * @param radii - Per-dot radii in pixels, parallel to `positions`.
- * @param lanes - Optional lane key per dot; dots in different lanes never collide.
- * @param padding - Extra pixel gap between circle edges. Defaults to 1.
- * @returns Signed cross-axis pixel offsets (centered on 0), parallel to `positions`.
- */
-export function dodgeOffsets(
-  positions: readonly number[],
-  radii: readonly number[],
-  lanes?: readonly string[],
-  padding: number = DEFAULT_DODGE_PADDING,
-): number[] {
-  const n = positions.length;
-  const offsets = new Array<number>(n).fill(0);
-
-  // Group indices by lane (single implicit lane when none provided)
-  const groups = new Map<string, number[]>();
-  for (let i = 0; i < n; i++) {
-    const lane = lanes?.[i] ?? '__default__';
-    const group = groups.get(lane);
-    if (group) {
-      group.push(i);
-    } else {
-      groups.set(lane, [i]);
-    }
-  }
-
-  for (const group of groups.values()) {
-    dodgeLane(group, positions, radii, padding, offsets);
-  }
-
-  return offsets;
-}
-
-// ---------------------------------------------------------------------------
-// Per-lane sweep
-// ---------------------------------------------------------------------------
-
-/**
- * Place one lane's dots, writing results into the shared offsets array.
- *
- * The backward scan's early `break` (line ~101) keeps this near-linear when
- * value positions are spread out: once the horizontal gap to an earlier dot
- * exceeds any possible collision distance, no earlier dot can collide either.
- * The degenerate case is many dots sharing one identical value position — the
- * gap stays 0, the break never fires, and the scan touches every placed dot,
- * so a lane of N coincident points is O(N^2). The overplotting guard caps the
- * swarm at ~2000 points, which bounds the worst case; real data spreads out
- * enough that this stays linear in practice.
- */
-function dodgeLane(
-  indices: number[],
-  positions: readonly number[],
-  radii: readonly number[],
-  padding: number,
-  offsets: number[],
-): void {
-  // Sweep order: ascending value position, ties broken by input index so the
-  // sort (and therefore the layout) is fully deterministic.
-  const order = [...indices].sort((a, b) => positions[a] - positions[b] || a - b);
-
-  // Already-placed dots in sweep order. Because placement follows ascending
-  // positions, the backward scan below can stop as soon as the horizontal gap
-  // exceeds the largest possible collision distance.
-  const placed: number[] = [];
-  let maxPlacedRadius = 0;
-
-  for (const i of order) {
-    const p = positions[i];
-    const r = radii[i];
-
-    // Blocked cross-axis intervals from placed dots that overlap horizontally.
-    const intervals: Array<[number, number]> = [];
-    for (let k = placed.length - 1; k >= 0; k--) {
-      const j = placed[k];
-      const dx = p - positions[j];
-      if (dx > r + maxPlacedRadius + padding) break; // no earlier dot can reach
-      const sep = r + radii[j] + padding;
-      if (dx * dx >= sep * sep) continue;
-      const dy = Math.sqrt(sep * sep - dx * dx);
-      intervals.push([offsets[j] - dy, offsets[j] + dy]);
-    }
-
-    offsets[i] = minimalFreeOffset(intervals);
-    placed.push(i);
-    if (r > maxPlacedRadius) maxPlacedRadius = r;
-  }
-}
-
-/**
- * Smallest-magnitude offset outside all blocked open intervals.
- *
- * The feasible set is the complement of a union of open intervals, so the
- * minimal-|offset| point is either 0 or an interval edge. Candidates sort by
- * (|value|, value): equal magnitudes resolve to the negative side.
- */
-function minimalFreeOffset(intervals: Array<[number, number]>): number {
-  if (intervals.length === 0) return 0;
-
-  const candidates: number[] = [0];
-  for (const [lo, hi] of intervals) {
-    candidates.push(lo, hi);
-  }
-  candidates.sort((a, b) => Math.abs(a) - Math.abs(b) || a - b);
-
-  for (const candidate of candidates) {
-    let blocked = false;
-    for (const [lo, hi] of intervals) {
-      if (candidate > lo && candidate < hi) {
-        blocked = true;
-        break;
-      }
-    }
-    if (!blocked) return candidate;
-  }
-
-  // Unreachable: interval edges are never strictly inside their own interval,
-  // so at least one candidate is always free. Kept for type safety.
-  return 0;
-}

package/src/charts/beeswarm/index.ts

@@ -1,32 +0,0 @@
-/**
- * Beeswarm chart module.
- *
- * Exports the beeswarm renderer and computation functions. Beeswarms emit
- * plain PointMark[] (rendered by the existing point mark path) with no
- * per-dot value labels: a swarm carries hundreds of observations, so labels
- * would only recreate the overplotting the layout exists to solve.
- */
-
-import type { Mark } from '@opendata-ai/openchart-core';
-import type { ChartRenderer } from '../registry';
-import { computeBeeswarmMarks } from './compute';
-
-// ---------------------------------------------------------------------------
-// Beeswarm chart renderer
-// ---------------------------------------------------------------------------
-
-/**
- * Beeswarm chart renderer.
- *
- * Produces one dodged PointMark per observation.
- */
-export const beeswarmRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _theme) => {
-  return computeBeeswarmMarks(spec, scales, chartArea, strategy) as Mark[];
-};
-
-// ---------------------------------------------------------------------------
-// Public exports
-// ---------------------------------------------------------------------------
-
-export { computeBeeswarmMarks } from './compute';
-export { DEFAULT_DODGE_PADDING, dodgeOffsets } from './dodge';

package/src/charts/builtin.ts

@@ -1,75 +0,0 @@
-/**
- * Built-in chart renderer registration.
- *
- * Each chart type (line, bar, column, scatter, pie, etc.) has a renderer that
- * produces marks from a normalized spec. This module wires them into the
- * registry. Importing it is a side effect: the built-ins register as soon as
- * it's loaded.
- *
- * Tests that call `clearRenderers()` can call `registerBuiltinRenderers()` to
- * restore the default set rather than leaving the registry empty for later
- * tests in the same process.
- */
-
-import { barRenderer } from './bar';
-import { beeswarmRenderer } from './beeswarm';
-import { calendarRenderer } from './calendar';
-import { columnRenderer } from './column';
-import { dotRenderer } from './dot';
-import { areaRenderer, lineRenderer } from './line';
-import { parliamentRenderer } from './parliament';
-import { donutRenderer, pieRenderer } from './pie';
-import { rangeRenderer } from './range';
-import { rectRenderer } from './rect';
-import { type ChartRenderer, registerChartRenderer } from './registry';
-import { ruleRenderer } from './rule';
-import { scatterRenderer } from './scatter';
-import { textRenderer } from './text';
-import { tickRenderer } from './tick';
-import { waffleRenderer } from './waffle';
-
-// Mark type mapping from old chart types:
-// - 'bar' -> barRenderer (horizontal bars, old 'bar')
-// - 'bar:vertical' is handled by columnRenderer (old 'column')
-// - 'arc' -> pieRenderer (old 'pie'); donutRenderer is also registered
-// - 'point' -> scatterRenderer (old 'scatter')
-// - 'circle' -> dotRenderer (old 'dot')
-// - 'line' and 'area' unchanged
-// - 'text', 'rule', 'tick' are new Vega-Lite mark types
-//
-// For 'bar', orientation is resolved at compile time to dispatch to the right
-// renderer. We register both barRenderer and columnRenderer; the compile
-// function picks based on orientation.
-const builtinRenderers: Record<string, ChartRenderer> = {
-  line: lineRenderer,
-  area: areaRenderer,
-  bar: barRenderer, // horizontal bars
-  'bar:vertical': columnRenderer, // vertical bars (old 'column')
-  point: scatterRenderer, // old 'scatter'
-  arc: pieRenderer, // old 'pie' (donut handled via innerRadius)
-  'arc:donut': donutRenderer, // old 'donut'
-  circle: dotRenderer, // old 'dot'
-  lollipop: dotRenderer, // semantic alias for dot/circle
-  beeswarm: beeswarmRenderer, // dodged distribution dots
-  text: textRenderer,
-  rule: ruleRenderer,
-  tick: tickRenderer,
-  rect: rectRenderer, // heatmap cells (band x band); see charts/rect
-  range: rangeRenderer, // dumbbell / arrow / range bar (orientation resolved internally)
-  waffle: waffleRenderer, // unit grid for part-to-whole counts
-  calendar: calendarRenderer, // weeks x weekdays daily heatmap (no positional scales)
-  parliament: parliamentRenderer, // hemicycle seat dots (no positional scales)
-};
-
-/**
- * Register all built-in chart renderers. Called once on module load; also
- * exported so tests that clear the registry can restore the defaults.
- */
-export function registerBuiltinRenderers(): void {
-  for (const [type, renderer] of Object.entries(builtinRenderers)) {
-    registerChartRenderer(type, renderer);
-  }
-}
-
-// Side effect: register on first import.
-registerBuiltinRenderers();