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

package/src/annotations/thinning.ts

@@ -0,0 +1,190 @@
+/**
+ * Annotation auto-thinning: demotes text annotations that can't fit without
+ * overlap to numbered dot markers with footnote text below the chart.
+ *
+ * Single deterministic pass: run collision resolution once at the full chart
+ * area, then greedily place by priority. A candidate is demoted when it either
+ * overlaps an already-placed label or escapes the plot area. No iterative
+ * layout convergence.
+ */
+
+import type {
+  Annotation,
+  AnnotationFootnote,
+  Rect,
+  ResolvedAnnotation,
+  TextAnnotation,
+} from '@opendata-ai/openchart-core';
+import { detectCollision } from '@opendata-ai/openchart-core';
+import { type AnnotationMeasureTextFn, estimateLabelBounds } from './geometry';
+
+export interface ThinningResult {
+  annotations: ResolvedAnnotation[];
+  footnotes: AnnotationFootnote[];
+}
+
+/**
+ * Max share of the plot area inline annotation labels may collectively claim
+ * before further candidates demote to footnotes. Measured coverage for a
+ * 6-callout line chart runs ~5% at 860px and ~16% at 300px, so 10% leaves wide
+ * charts fully inline and demotes the crowded tail on narrow ones.
+ */
+const COVERAGE_BUDGET = 0.1;
+
+/** Gap enforced between inline labels; labels closer than this count as colliding. */
+const COLLISION_PADDING = 4;
+
+/**
+ * Apply auto-thinning to resolved annotations. Text annotations that still
+ * overlap after collision resolution are demoted to footnote markers.
+ *
+ * Priority ordering: annotations with lower `priority` values are kept in
+ * place first. When priority is equal (or omitted), spec order wins (earlier
+ * annotations are kept). Non-text annotations are never thinned.
+ *
+ * Explicit `responsive: false` on an annotation exempts it from thinning
+ * (it is always placed first and never demoted).
+ *
+ * @param annotations - Resolved annotations (text + range + refline, in spec order
+ *   minus any that were skipped by `computeAnnotations`).
+ * @param specs - The full spec annotations array, index-aligned with `annotations`.
+ *   Non-text specs are ignored; text specs provide `priority` and `responsive`.
+ * @param plotArea - The plot rect. Sizes the coverage budget: labels are charged
+ *   against the plot they crowd, so the same label costs a larger share of a
+ *   smaller plot. Omit to skip the budget test.
+ * @param containerBounds - The rect a label must fit inside to stay inline. This
+ *   is the whole chart, NOT the plot: annotations render outside the clip path and
+ *   legitimately sit in the margins (above a peak, below a trough), which is what
+ *   collision avoidance already assumes. Fencing them to the plot would demote
+ *   ordinary callouts. Only labels escaping the chart entirely are demoted.
+ *   Omit to skip the containment test.
+ */
+export function thinAnnotations(
+  annotations: ResolvedAnnotation[],
+  specs: Annotation[],
+  measure: AnnotationMeasureTextFn,
+  plotArea?: Rect,
+  containerBounds?: Rect,
+): ThinningResult {
+  if (annotations.length <= 1) {
+    return { annotations, footnotes: [] };
+  }
+
+  // Build index pairs: (resolved, spec, original index).
+  // Only text specs carry priority/responsive; non-text specs are ignored.
+  //
+  // `annotations` is a filtered view of `specs` -- an annotation that resolves to
+  // nothing (position outside the domain) is dropped -- so index into `specs` by
+  // the stamped `specIndex`, never by position in `annotations`. Falling back to
+  // `i` keeps a hand-built layout (no specIndex) working as it did before.
+  const entries = annotations.map((a, i) => {
+    const specIndex = a.specIndex ?? i;
+    const spec = specs[specIndex];
+    return {
+      resolved: a,
+      spec: spec?.type === 'text' ? (spec as TextAnnotation) : undefined,
+      index: i,
+    };
+  });
+
+  // Separate pinned (responsive: false) from candidates
+  const pinned: typeof entries = [];
+  const candidates: typeof entries = [];
+  for (const entry of entries) {
+    if (entry.resolved.type !== 'text' || !entry.resolved.label) {
+      pinned.push(entry);
+    } else if (entry.spec?.responsive === false) {
+      pinned.push(entry);
+    } else {
+      candidates.push(entry);
+    }
+  }
+
+  // Sort candidates by priority (lower first), then by spec order
+  candidates.sort((a, b) => {
+    const pa = a.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    const pb = b.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    if (pa !== pb) return pa - pb;
+    return a.index - b.index;
+  });
+
+  // Place pinned annotations first (they're always kept)
+  const placedBounds: Rect[] = [];
+  for (const entry of pinned) {
+    if (entry.resolved.type === 'text' && entry.resolved.label) {
+      const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label, measure);
+      placedBounds.push(bounds);
+    }
+  }
+
+  // Greedily place candidates; demote overlapping ones to footnotes.
+  //
+  // Overlap and containment alone under-thin at narrow widths: collision
+  // resolution spreads labels apart and clamping pulls them back inside, so
+  // they neither collide nor escape the plot — they just crowd it. Layer a
+  // coverage budget on top: inline labels may claim at most COVERAGE_BUDGET of
+  // the plot area, and candidates that push past it demote. Coverage rises as
+  // the plot shrinks (a fixed label costs a larger share of a smaller plot),
+  // so this only bites at small sizes and leaves roomy charts untouched.
+  //
+  // Pinned labels are exempt: they are guaranteed placement, so charging them
+  // against the budget could exhaust it before any candidate is seen and evict
+  // labels that would otherwise fit. They still block via `placedBounds`.
+  const footnotes: AnnotationFootnote[] = [];
+  const plotAreaSize = plotArea ? plotArea.width * plotArea.height : 0;
+  const coverageBudget = plotAreaSize * COVERAGE_BUDGET;
+  // Containment is checked against the chart, not the plot — see the param docs.
+  // Callers that pass no container fall back to the plot rect.
+  const containment = containerBounds ?? plotArea;
+  let usedArea = 0;
+
+  for (const entry of candidates) {
+    const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label!, measure);
+
+    if (bounds.width <= 0 || bounds.height <= 0) {
+      placedBounds.push(bounds);
+      continue;
+    }
+
+    const padded = {
+      x: bounds.x - COLLISION_PADDING,
+      y: bounds.y - COLLISION_PADDING,
+      width: bounds.width + COLLISION_PADDING * 2,
+      height: bounds.height + COLLISION_PADDING * 2,
+    };
+    const overlaps = placedBounds.some(
+      (pb) => pb.width > 0 && pb.height > 0 && detectCollision(padded, pb),
+    );
+
+    const candidateArea = bounds.width * bounds.height;
+    const overBudget = plotAreaSize > 0 && usedArea + candidateArea > coverageBudget;
+
+    if (overlaps || !fitsWithin(bounds, containment) || overBudget) {
+      const footnoteIndex = footnotes.length + 1;
+      footnotes.push({
+        index: footnoteIndex,
+        text: entry.resolved.label!.text,
+      });
+      entry.resolved.footnoteIndex = footnoteIndex;
+    } else {
+      placedBounds.push(bounds);
+      usedArea += candidateArea;
+    }
+  }
+
+  return { annotations, footnotes };
+}
+
+/**
+ * Whether a label's bounds sit entirely inside the plot. No plot area means no
+ * containment constraint, so everything fits.
+ */
+function fitsWithin(bounds: Rect, plotArea: Rect | undefined): boolean {
+  if (!plotArea || plotArea.width <= 0 || plotArea.height <= 0) return true;
+  return (
+    bounds.x >= plotArea.x &&
+    bounds.y >= plotArea.y &&
+    bounds.x + bounds.width <= plotArea.x + plotArea.width &&
+    bounds.y + bounds.height <= plotArea.y + plotArea.height
+  );
+}

package/src/barlist/__tests__/compile-barlist.test.ts

@@ -0,0 +1,200 @@
+import type { BarListSpec, CompileOptions } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+
+import { compileBarList } from '../compile-barlist';
+
+const BASE_OPTIONS: CompileOptions = {
+  width: 600,
+  height: 400,
+};
+
+function makeSpec(overrides?: Partial<BarListSpec>): BarListSpec {
+  return {
+    type: 'barlist',
+    data: [
+      { label: 'Alpha', count: 100 },
+      { label: 'Beta', count: 75 },
+      { label: 'Gamma', count: 50 },
+      { label: 'Delta', count: 25 },
+    ],
+    encoding: {
+      label: { field: 'label', type: 'nominal' },
+      value: { field: 'count', type: 'quantitative' },
+    },
+    ...overrides,
+  };
+}
+
+describe('compileBarList', () => {
+  it('compiles a basic barlist spec with correct row count', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(4);
+  });
+
+  it('sorts rows by value descending', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Low', count: 10 },
+        { label: 'High', count: 100 },
+        { label: 'Mid', count: 50 },
+      ],
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].label.text).toBe('High');
+    expect(layout.rows[1].label.text).toBe('Mid');
+    expect(layout.rows[2].label.text).toBe('Low');
+  });
+
+  it('limits rows to maxItems', () => {
+    const spec = makeSpec({ maxItems: 2 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(2);
+    expect(layout.rows[0].label.text).toBe('Alpha');
+    expect(layout.rows[1].label.text).toBe('Beta');
+  });
+
+  it('filters out null values', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Valid', count: 50 },
+        { label: 'Null', count: null },
+        { label: 'Also valid', count: 25 },
+      ],
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(2);
+  });
+
+  it('assigns cycling colors to rows', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const colors = layout.rows.map((r) => r.bar.fill);
+    expect(colors[0]).not.toBe(colors[1]);
+    expect(colors[1]).not.toBe(colors[2]);
+  });
+
+  it('bar width is proportional to value', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const maxWidth = layout.rows[0].bar.width;
+    const halfWidth = layout.rows[2].bar.width;
+    expect(halfWidth).toBeCloseTo(maxWidth * 0.5, 0);
+  });
+
+  it('first row gets full-width bar', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const row0 = layout.rows[0];
+    expect(row0.bar.width).toBe(row0.track.width);
+  });
+
+  it('pill cornerRadius is half the bar height', () => {
+    const spec = makeSpec({ barHeight: 8, cornerRadius: 'pill' });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.cornerRadius).toBe(4);
+    expect(layout.rows[0].track.cornerRadius).toBe(4);
+  });
+
+  it('numeric cornerRadius is used directly', () => {
+    const spec = makeSpec({ cornerRadius: 3 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.cornerRadius).toBe(3);
+  });
+
+  it('default barHeight is 6', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].bar.height).toBe(6);
+  });
+
+  it('custom barHeight applies', () => {
+    const spec = makeSpec({ barHeight: 10 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.height).toBe(10);
+  });
+
+  it('builds tooltip descriptors keyed by row index', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.tooltipDescriptors.size).toBe(4);
+    const tooltip = layout.tooltipDescriptors.get('0');
+    expect(tooltip?.title).toBe('Alpha');
+    expect(tooltip?.fields[0].value).toBeDefined();
+  });
+
+  it('builds a11y metadata', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.a11y.altText).toContain('4 items');
+    expect(layout.a11y.dataTableFallback).toHaveLength(4);
+    expect(layout.a11y.role).toBe('list');
+  });
+
+  it('returns animation indices matching row order', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].animationIndex).toBe(0);
+    expect(layout.rows[1].animationIndex).toBe(1);
+    expect(layout.rows[2].animationIndex).toBe(2);
+  });
+
+  it('throws when data is empty', () => {
+    const spec = makeSpec({ data: [] });
+    expect(() => compileBarList(spec, BASE_OPTIONS)).toThrow(/empty/i);
+  });
+
+  it('formats values with valueFormat', () => {
+    const spec = makeSpec({ valueFormat: '$,.0f' });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].formattedValue).toBe('$100');
+  });
+
+  it('formats values with SI suffix format', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Big', count: 1500 },
+        { label: 'Small', count: 200 },
+      ],
+      valueFormat: '~s',
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].formattedValue).toBe('1.5k');
+  });
+
+  it('dark mode changes label colors', () => {
+    const lightLayout = compileBarList(makeSpec(), { ...BASE_OPTIONS, darkMode: false });
+    const darkLayout = compileBarList(makeSpec(), { ...BASE_OPTIONS, darkMode: true });
+    expect(lightLayout.rows[0].valueLabel.style.fill).not.toBe(
+      darkLayout.rows[0].valueLabel.style.fill,
+    );
+  });
+
+  it('rejects non-barlist specs', () => {
+    const invalidSpec = {
+      type: 'tilemap',
+      data: { CA: 100 },
+    };
+    expect(() => compileBarList(invalidSpec, BASE_OPTIONS)).toThrow('non-barlist');
+  });
+
+  it('uses color encoding for consistent category colors', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'A', count: 100, cat: 'x' },
+        { label: 'B', count: 50, cat: 'x' },
+        { label: 'C', count: 25, cat: 'y' },
+      ],
+      encoding: {
+        label: { field: 'label', type: 'nominal' },
+        value: { field: 'count', type: 'quantitative' },
+        color: { field: 'cat', type: 'nominal' },
+      },
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.fill).toBe(layout.rows[1].bar.fill);
+    expect(layout.rows[0].bar.fill).not.toBe(layout.rows[2].bar.fill);
+  });
+
+  it('preserves original data in row marks', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].data).toEqual({ label: 'Alpha', count: 100 });
+  });
+
+  it('rows have correct aria labels', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].aria.label).toContain('Alpha');
+  });
+});