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

package/src/annotations/thinning.ts

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

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