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

package/src/charts/bar/labels.ts

@@ -1,311 +0,0 @@
-/**
- * Bar chart label computation.
- *
- * Produces value labels for horizontal bars, positioned inside the bar
- * if the bar is wide enough, or outside (to the right) otherwise.
- *
- * Respects the spec's label density setting:
- * - 'all': consider every bar's label (no density pre-filter), but still run
- *   collision resolution so colliding losers are hidden rather than drawn on
- *   top of each other. Composes with the stacked-segment pre-hide pass below.
- * - 'auto': existing behavior (density pre-filter + collision detection)
- * - 'endpoints': first and last bars only
- * - 'none': return empty array
- */
-
-import type {
-  LabelCandidate,
-  LabelDensity,
-  NumberFormatter,
-  RectMark,
-  ResolvedLabel,
-} from '@opendata-ai/openchart-core';
-import {
-  estimateTextWidth,
-  getRepresentativeColor,
-  pickLabelColor,
-  resolveCollisions,
-} from '@opendata-ai/openchart-core';
-import { filterByDensity } from '../_shared/density-filter';
-import { formatLabelValue } from '../_shared/format-label-value';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Suffix multipliers mirroring core's abbreviateNumber output (K/M/B/T). */
-const SUFFIX_MULTIPLIERS: Record<string, number> = {
-  K: 1_000,
-  M: 1_000_000,
-  B: 1_000_000_000,
-  T: 1_000_000_000_000,
-};
-
-/**
- * Parse a numeric string that may include comma separators and/or a
- * K/M/B/T abbreviation suffix (as produced by `abbreviateNumber`).
- * Returns NaN when the string cannot be parsed.
- */
-function parseDisplayNumber(raw: string): number {
-  // Normalize Unicode minus (U+2212, produced by d3-format) to ASCII hyphen-minus
-  const trimmed = raw.trim().replace(/\u2212/g, '-');
-  if (!trimmed) return NaN;
-
-  // Check for trailing abbreviation suffix (case-insensitive)
-  const last = trimmed[trimmed.length - 1].toUpperCase();
-  const multiplier = SUFFIX_MULTIPLIERS[last];
-  if (multiplier) {
-    const numPart = trimmed.slice(0, -1).replace(/,/g, '');
-    const n = Number(numPart);
-    return Number.isNaN(n) ? NaN : n * multiplier;
-  }
-
-  // Strip literal % suffix (e.g., from "+.0f%" d3-format strings)
-  if (last === '%') {
-    return Number(trimmed.slice(0, -1).replace(/,/g, ''));
-  }
-
-  // No suffix — strip commas and parse
-  return Number(trimmed.replace(/,/g, ''));
-}
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const LABEL_FONT_SIZE = 11;
-const LABEL_FONT_WEIGHT = 600;
-const LABEL_PADDING = 6;
-const MIN_WIDTH_FOR_INSIDE_LABEL = 40;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compute value labels for bar marks.
- *
- * For each bar, the value from the data is formatted and placed either
- * inside the bar (right-aligned) if the bar is wide enough, or just
- * outside the bar's right edge.
- */
-export function computeBarLabels(
-  marks: RectMark[],
-  _chartArea: { x: number; y: number; width: number; height: number },
-  density: LabelDensity = 'auto',
-  labelFormatter?: NumberFormatter | null,
-  labelPrefix?: string,
-  valueField?: string,
-  labelColor?: string,
-  darkMode = false,
-  fontSize?: number,
-  labelSuffix?: string,
-): ResolvedLabel[] {
-  const FONT_SIZE = fontSize ?? LABEL_FONT_SIZE;
-  const targetMarks = filterByDensity(marks, density);
-
-  const candidates: LabelCandidate[] = [];
-  // Track whether each candidate fits within its stacked segment.
-  // Non-stacked bars are always considered fitting (undefined = fits).
-  const fitsInSegment: boolean[] = [];
-  // The display anchor x (start/end/middle reference point) for each candidate.
-  // Candidates carry the box's LEFT edge for collision math; on emit we map any
-  // horizontal nudge back onto this display anchor so textAnchor stays honored.
-  const displayAnchorX: number[] = [];
-
-  const formatter = labelFormatter ?? null;
-
-  for (const mark of targetMarks) {
-    // Get the original numeric value from the data row when possible,
-    // falling back to parsing the aria label (which may lose precision
-    // due to abbreviation rounding, e.g. 1955 → "2K" → 2000).
-    let valuePart: string;
-    const rawNum = valueField != null ? Number(mark.data[valueField]) : NaN;
-
-    if (formatter && Number.isFinite(rawNum)) {
-      valuePart = formatter(rawNum);
-    } else if (Number.isFinite(rawNum)) {
-      valuePart = formatLabelValue(rawNum);
-    } else {
-      // Fallback: extract from aria label
-      const ariaLabel = mark.aria.label;
-      if (!ariaLabel) continue;
-      const lastColon = ariaLabel.lastIndexOf(':');
-      const rawValue = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
-      if (!rawValue) continue;
-      if (formatter) {
-        const num = parseDisplayNumber(rawValue);
-        valuePart = !Number.isNaN(num) ? formatter(num) : rawValue;
-      } else {
-        valuePart = rawValue;
-      }
-    }
-    if (labelPrefix) valuePart = labelPrefix + valuePart;
-    if (labelSuffix) valuePart = valuePart + labelSuffix;
-
-    const textWidth = estimateTextWidth(valuePart, FONT_SIZE, LABEL_FONT_WEIGHT);
-    const textHeight = FONT_SIZE * 1.2;
-
-    // Detect stacked bars: cornerRadius 0 indicates stacked segment
-    const isStacked = mark.stackGroup !== undefined;
-
-    // Determine if label goes inside or outside the bar
-    const isInside = mark.width >= MIN_WIDTH_FOR_INSIDE_LABEL;
-    const isNegative = Number.isFinite(rawNum) ? rawNum < 0 : false;
-    const bgColor = getRepresentativeColor(mark.fill);
-
-    let anchorX: number;
-    let fill: string;
-    let textAnchor: 'start' | 'end' | 'middle';
-
-    if (isStacked && isInside) {
-      // Stacked: centered within segment
-      anchorX = mark.x + mark.width / 2;
-      fill = pickLabelColor(bgColor, darkMode);
-      textAnchor = 'middle';
-    } else if (isInside) {
-      if (isNegative) {
-        // Negative bar: left-aligned within bar (bar extends leftward)
-        anchorX = mark.x + LABEL_PADDING;
-        fill = pickLabelColor(bgColor, darkMode);
-        textAnchor = 'start';
-      } else {
-        // Positive bar: right-aligned within bar
-        anchorX = mark.x + mark.width - LABEL_PADDING;
-        fill = pickLabelColor(bgColor, darkMode);
-        textAnchor = 'end';
-      }
-    } else {
-      if (isNegative) {
-        // Outside negative bar: just past the bar's left edge
-        anchorX = mark.x - LABEL_PADDING;
-        fill = labelColor ?? getRepresentativeColor(mark.fill);
-        textAnchor = 'end';
-      } else {
-        // Outside positive bar: just past the bar's right edge
-        anchorX = mark.x + mark.width + LABEL_PADDING;
-        fill = labelColor ?? getRepresentativeColor(mark.fill);
-        textAnchor = 'start';
-      }
-    }
-
-    // Collision math works in top-left-edge space so the AABB
-    // (rect = { x: anchorX, y: anchorY, width, height }) matches the label's
-    // real footprint. The renderer anchors text by textAnchor (start/end/
-    // middle) and centers it vertically (dominant-baseline: central), so we
-    // convert the display anchor to the box's top-left corner here and shift
-    // back on emit. Feeding the display anchor directly desynced the collision
-    // box from the drawn text (by width for end/middle, by textHeight/2
-    // vertically), letting adjacent bar labels pass the overlap check while
-    // visibly colliding.
-    const centerY = mark.y + mark.height / 2;
-    const anchorY = centerY - textHeight / 2;
-    const leftEdgeX =
-      textAnchor === 'end'
-        ? anchorX - textWidth
-        : textAnchor === 'middle'
-          ? anchorX - textWidth / 2
-          : anchorX;
-
-    // Check if label text fits within the stacked segment
-    const fits = !(isStacked && textWidth > mark.width - 2 * LABEL_PADDING);
-
-    displayAnchorX.push(anchorX);
-    fitsInSegment.push(fits);
-    candidates.push({
-      text: valuePart,
-      anchorX: leftEdgeX,
-      anchorY,
-      width: textWidth,
-      height: textHeight,
-      priority: 'data',
-      style: {
-        fontFamily: 'system-ui, -apple-system, sans-serif',
-        fontSize: FONT_SIZE,
-        fontWeight: LABEL_FONT_WEIGHT,
-        fill,
-        lineHeight: 1.2,
-        textAnchor,
-        dominantBaseline: 'central',
-        fontVariant: 'tabular-nums',
-      },
-    });
-  }
-
-  if (candidates.length === 0) return [];
-
-  // Every density that reaches here ('all' and 'auto') pre-hides candidates
-  // that don't fit their stacked segment, then runs collision resolution.
-  // 'all' just skips the density pre-filter above so every mark is a
-  // candidate; colliding losers are still hidden by resolveCollisions.
-  const fittingCandidates: LabelCandidate[] = [];
-  const unfittingIndices = new Set<number>();
-  for (let i = 0; i < candidates.length; i++) {
-    if (fitsInSegment[i] === false) {
-      unfittingIndices.add(i);
-    } else {
-      // Carry the original candidate index so we can zip the resolved output
-      // back to it regardless of any reordering resolveCollisions performs.
-      fittingCandidates.push({ ...candidates[i], index: i });
-    }
-  }
-
-  // resolveCollisions may reorder its output (it sorts by priority), so key the
-  // result by the source index we carried rather than by position.
-  const resolvedByOrig = new Map<number, ResolvedLabel>();
-  for (const r of resolveCollisions(fittingCandidates)) {
-    if (r.index !== undefined) resolvedByOrig.set(r.index, r);
-  }
-
-  // Shift resolved y back from top-edge space to the vertical center that the
-  // central-baseline renderer expects (see anchorY derivation above).
-  const halfHeight = FONT_SIZE * 1.2 * 0.5;
-
-  // Re-insert hidden labels for candidates that didn't fit, preserving order
-  const results: ResolvedLabel[] = [];
-  for (let i = 0; i < candidates.length; i++) {
-    if (unfittingIndices.has(i)) {
-      results.push({
-        text: candidates[i].text,
-        x: displayAnchorX[i],
-        y: candidates[i].anchorY + halfHeight,
-        style: candidates[i].style,
-        visible: false,
-      });
-    } else {
-      const r = resolvedByOrig.get(i);
-      if (!r) continue;
-      // Collision math ran in left-edge/top space; renderers draw at the display
-      // anchor with central baseline. The inverse mapping shifts every point by
-      // dx (left-edge -> display anchor) on x and +halfHeight on y. Apply it to
-      // the label AND both connector endpoints, or the leader line for an
-      // end/middle-anchored label points to the box's top-left corner (up to
-      // textWidth + halfHeight away from the text it's calling out).
-      const dx = displayAnchorX[i] - candidates[i].anchorX;
-      // Drop the internal zip index so it doesn't leak into the label output.
-      const { index: _index, ...rest } = r;
-      results.push({
-        ...rest,
-        x: r.x + dx,
-        y: r.y + halfHeight,
-        connector: r.connector
-          ? {
-              ...r.connector,
-              from: {
-                ...r.connector.from,
-                x: r.connector.from.x + dx,
-                y: r.connector.from.y + halfHeight,
-              },
-              to: {
-                ...r.connector.to,
-                x: r.connector.to.x + dx,
-                y: r.connector.to.y + halfHeight,
-              },
-            }
-          : undefined,
-      });
-    }
-  }
-
-  return results;
-}

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

@@ -1,280 +0,0 @@
-import type { PointMark } from '@opendata-ai/openchart-core';
-import { describe, expect, it } from 'vitest';
-import { compileChart } from '../../../compile';
-import { compile } from '../../../compiler';
-
-// ---------------------------------------------------------------------------
-// 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;
-  };
-}
-
-const REGIONS = ['Northeast', 'Midwest', 'South', 'West'];
-
-/** Deterministic observation rows: income value, region lane, population size. */
-function makeRows(count: number, seed = 1): Array<Record<string, unknown>> {
-  const rand = seededRandom(seed);
-  return Array.from({ length: count }, (_, i) => ({
-    income: Math.round(((rand() + rand()) / 2) * 120 + 20),
-    region: REGIONS[i % REGIONS.length],
-    pop: Math.round(rand() * 900 + 10),
-  }));
-}
-
-function singleLaneSpec(count = 300) {
-  return {
-    mark: 'beeswarm' as const,
-    data: makeRows(count),
-    encoding: {
-      x: { field: 'income', type: 'quantitative' as const },
-    },
-  };
-}
-
-function groupedSpec(count = 200) {
-  return {
-    mark: 'beeswarm' as const,
-    data: makeRows(count),
-    encoding: {
-      x: { field: 'income', type: 'quantitative' as const },
-      y: { field: 'region', type: 'nominal' as const },
-      color: { field: 'region', type: 'nominal' as const },
-    },
-  };
-}
-
-const OPTIONS = { width: 800, height: 500 };
-
-function pointMarks(layout: ReturnType<typeof compileChart>): PointMark[] {
-  return layout.marks.filter((m): m is PointMark => m.type === 'point');
-}
-
-/** Assert every pair of circles keeps at least (r1 + r2) separation. */
-function expectNoOverlap(marks: PointMark[]): void {
-  const epsilon = 1e-6;
-  for (let i = 0; i < marks.length; i++) {
-    for (let j = i + 1; j < marks.length; j++) {
-      const dx = marks[i].cx - marks[j].cx;
-      const dy = marks[i].cy - marks[j].cy;
-      const dist = Math.sqrt(dx * dx + dy * dy);
-      expect(dist).toBeGreaterThanOrEqual(marks[i].r + marks[j].r - epsilon);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
-describe('beeswarm compile', () => {
-  it('renders a 300-point single-lane swarm with zero overlapping circles', () => {
-    const layout = compileChart(singleLaneSpec(300), OPTIONS);
-    const marks = pointMarks(layout);
-    expect(marks).toHaveLength(300);
-    expectNoOverlap(marks);
-  });
-
-  it('compiles the same spec twice to identical positions (determinism)', () => {
-    const spec = singleLaneSpec(300);
-    const first = pointMarks(compileChart(spec, OPTIONS)).map((m) => [m.cx, m.cy, m.r]);
-    const second = pointMarks(compileChart(spec, OPTIONS)).map((m) => [m.cx, m.cy, m.r]);
-    expect(second).toEqual(first);
-  });
-
-  it('drops rows whose value is null or the field is missing', () => {
-    // The validator rejects a quantitative field that carries non-numeric or
-    // non-finite values (strings, NaN, Infinity), but tolerates null/undefined
-    // (`val != null` skips them). Those null/missing rows must then be dropped
-    // by the compute pass rather than producing NaN-positioned dots.
-    const spec = {
-      mark: 'beeswarm' as const,
-      data: [
-        { income: 40 },
-        { income: null },
-        { notIncome: 5 }, // field missing entirely -> undefined
-        { income: 90 },
-      ],
-      encoding: {
-        x: { field: 'income', type: 'quantitative' as const },
-      },
-    };
-    const marks = pointMarks(compileChart(spec, OPTIONS));
-    // Only the two rows with finite values (40 and 90) survive.
-    expect(marks).toHaveLength(2);
-    for (const mark of marks) {
-      expect(Number.isFinite(mark.cx)).toBe(true);
-      expect(Number.isFinite(mark.cy)).toBe(true);
-    }
-  });
-
-  it('renders only the value axis for a single-lane swarm', () => {
-    const layout = compileChart(singleLaneSpec(60), OPTIONS);
-    expect(layout.axes.x?.ticks.length).toBeGreaterThan(0);
-    expect(layout.axes.y).toBeUndefined();
-  });
-
-  it('centers a single-lane horizontal swarm on the middle of the chart area', () => {
-    const layout = compileChart(singleLaneSpec(1), OPTIONS);
-    const [mark] = pointMarks(layout);
-    expect(mark.cy).toBeCloseTo(layout.area.y + layout.area.height / 2, 6);
-  });
-
-  it('renders 4 grouped lanes as non-overlapping swarms with lane labels', () => {
-    const layout = compileChart(groupedSpec(200), OPTIONS);
-    const marks = pointMarks(layout);
-    expect(marks).toHaveLength(200);
-    expectNoOverlap(marks);
-
-    // One swarm per lane: 4 distinct lane groups in the data
-    const lanes = new Set(marks.map((m) => String(m.data.region)));
-    expect(lanes).toEqual(new Set(REGIONS));
-
-    // Lane labels render on the band axis
-    const tickLabels = (layout.axes.y?.ticks ?? []).map((t) => t.label);
-    for (const region of REGIONS) {
-      expect(tickLabels).toContain(region);
-    }
-
-    // Each lane's dots cluster around its own band center: lanes must not
-    // share a mean cross-axis position.
-    const meansByLane = REGIONS.map((region) => {
-      const laneMarks = marks.filter((m) => m.data.region === region);
-      return laneMarks.reduce((sum, m) => sum + m.cy, 0) / laneMarks.length;
-    });
-    const uniqueMeans = new Set(meansByLane.map((m) => Math.round(m / 10)));
-    expect(uniqueMeans.size).toBe(REGIONS.length);
-  });
-
-  it('renders a vertical swarm when y is quantitative', () => {
-    const data = [
-      { income: 20, region: 'West' },
-      { income: 140, region: 'West' },
-    ];
-    const layout = compileChart(
-      {
-        mark: 'beeswarm' as const,
-        data,
-        encoding: {
-          y: { field: 'income', type: 'quantitative' as const },
-          x: { field: 'region', type: 'nominal' as const },
-        },
-      },
-      OPTIONS,
-    );
-    const marks = pointMarks(layout);
-    expect(marks).toHaveLength(2);
-    // SVG y grows downward: the larger value sits higher (smaller cy)
-    const low = marks.find((m) => m.data.income === 20)!;
-    const high = marks.find((m) => m.data.income === 140)!;
-    expect(high.cy).toBeLessThan(low.cy);
-  });
-
-  it('sizes dots from the size encoding and keeps them collision-free', () => {
-    const spec = {
-      ...groupedSpec(120),
-      encoding: {
-        ...groupedSpec(120).encoding,
-        size: { field: 'pop', type: 'quantitative' as const },
-      },
-    };
-    const layout = compileChart(spec, OPTIONS);
-    const marks = pointMarks(layout);
-    const radii = new Set(marks.map((m) => m.r));
-    expect(radii.size).toBeGreaterThan(1);
-    for (const mark of marks) {
-      expect(mark.r).toBeGreaterThanOrEqual(2);
-      expect(mark.r).toBeLessThanOrEqual(10);
-    }
-    expectNoOverlap(marks);
-  });
-
-  it('stamps stable unique keys on every dot', () => {
-    const layout = compileChart(singleLaneSpec(100), OPTIONS);
-    const keys = pointMarks(layout).map((m) => m.key);
-    expect(keys.every((k) => typeof k === 'string' && k.length > 0)).toBe(true);
-    expect(new Set(keys).size).toBe(keys.length);
-  });
-
-  it('produces tooltips and a11y coverage for every dot', () => {
-    const layout = compileChart(groupedSpec(40), OPTIONS);
-    const marks = pointMarks(layout);
-    expect(layout.tooltipDescriptors.size).toBe(marks.length);
-    expect(layout.a11y.keyboardNavigable).toBe(true);
-    expect(layout.a11y.altText).toContain('Beeswarm chart');
-    expect(layout.a11y.altText).toContain('distribution of income by region');
-    for (const mark of marks) {
-      expect(mark.aria.label).toContain('income=');
-    }
-  });
-});
-
-describe('beeswarm validation', () => {
-  it('rejects a spec with two quantitative axes', () => {
-    expect(() =>
-      compileChart(
-        {
-          mark: 'beeswarm',
-          data: [{ a: 1, b: 2 }],
-          encoding: {
-            x: { field: 'a', type: 'quantitative' },
-            y: { field: 'b', type: 'quantitative' },
-          },
-        },
-        OPTIONS,
-      ),
-    ).toThrow(/only one quantitative axis/);
-  });
-
-  it('rejects a spec with no positional channel', () => {
-    expect(() =>
-      compileChart({ mark: 'beeswarm', data: [{ a: 1 }], encoding: {} }, OPTIONS),
-    ).toThrow(/quantitative encoding\.x or encoding\.y/);
-  });
-
-  it('rejects a spec where no declared axis is quantitative', () => {
-    expect(() =>
-      compileChart(
-        {
-          mark: 'beeswarm',
-          data: [{ a: 'x', b: 'y' }],
-          encoding: {
-            x: { field: 'a', type: 'nominal' },
-            y: { field: 'b', type: 'nominal' },
-          },
-        },
-        OPTIONS,
-      ),
-    ).toThrow(/requires one quantitative axis/);
-  });
-});
-
-describe('beeswarm overplotting guard', () => {
-  it('warns past the ~2000-point budget and suggests alternatives', () => {
-    const { warnings } = compile(singleLaneSpec(2001));
-    const warning = warnings.find((w) => w.includes('beeswarm'));
-    expect(warning).toBeDefined();
-    expect(warning).toContain('2001 data points');
-    expect(warning).toContain("mark: 'tick'");
-    expect(warning).toContain('histogram');
-  });
-
-  it('stays quiet at or under the budget', () => {
-    const { warnings } = compile(singleLaneSpec(2000));
-    expect(warnings.filter((w) => w.includes('beeswarm'))).toEqual([]);
-  });
-
-  it('never escalates the budget to an error: the chart still compiles', () => {
-    const layout = compileChart(singleLaneSpec(2001), OPTIONS);
-    expect(pointMarks(layout)).toHaveLength(2001);
-  });
-});