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

package/src/charts/bar/labels.ts

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

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