@opendata-ai/openchart-core 2.0.0

package/src/labels/__tests__/collision.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import type { TextStyle } from '../../types/layout';
+import type { LabelCandidate } from '../collision';
+import { detectCollision, resolveCollisions } from '../collision';
+
+const defaultStyle: TextStyle = {
+  fontFamily: 'Inter',
+  fontSize: 12,
+  fontWeight: 400,
+  fill: '#333',
+  lineHeight: 1.3,
+};
+
+describe('detectCollision', () => {
+  it('detects overlapping rectangles', () => {
+    expect(
+      detectCollision(
+        { x: 0, y: 0, width: 100, height: 50 },
+        { x: 50, y: 25, width: 100, height: 50 },
+      ),
+    ).toBe(true);
+  });
+
+  it('returns false for non-overlapping rectangles', () => {
+    expect(
+      detectCollision(
+        { x: 0, y: 0, width: 50, height: 50 },
+        { x: 100, y: 100, width: 50, height: 50 },
+      ),
+    ).toBe(false);
+  });
+
+  it('returns false for adjacent rectangles (no overlap)', () => {
+    expect(
+      detectCollision(
+        { x: 0, y: 0, width: 50, height: 50 },
+        { x: 50, y: 0, width: 50, height: 50 },
+      ),
+    ).toBe(false);
+  });
+
+  it('detects containment (one inside the other)', () => {
+    expect(
+      detectCollision(
+        { x: 0, y: 0, width: 100, height: 100 },
+        { x: 25, y: 25, width: 50, height: 50 },
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('resolveCollisions', () => {
+  it('places non-overlapping labels at their anchors', () => {
+    const labels: LabelCandidate[] = [
+      {
+        text: 'A',
+        anchorX: 0,
+        anchorY: 0,
+        width: 20,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+      {
+        text: 'B',
+        anchorX: 100,
+        anchorY: 100,
+        width: 20,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+    ];
+
+    const results = resolveCollisions(labels);
+    expect(results).toHaveLength(2);
+    expect(results[0].visible).toBe(true);
+    expect(results[1].visible).toBe(true);
+    expect(results[0].x).toBe(0);
+    expect(results[0].y).toBe(0);
+    expect(results[1].x).toBe(100);
+    expect(results[1].y).toBe(100);
+  });
+
+  it('resolves overlapping labels by offsetting', () => {
+    const labels: LabelCandidate[] = [
+      {
+        text: 'A',
+        anchorX: 50,
+        anchorY: 50,
+        width: 40,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+      {
+        text: 'B',
+        anchorX: 55,
+        anchorY: 52,
+        width: 40,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+    ];
+
+    const results = resolveCollisions(labels);
+    expect(results).toHaveLength(2);
+    // First label should be at anchor
+    expect(results[0].x).toBe(50);
+    // Second label should be offset
+    expect(results[1].x !== 55 || results[1].y !== 52).toBe(true);
+  });
+
+  it('prioritizes data labels over annotation labels', () => {
+    const labels: LabelCandidate[] = [
+      {
+        text: 'Annotation',
+        anchorX: 50,
+        anchorY: 50,
+        width: 60,
+        height: 14,
+        priority: 'annotation',
+        style: defaultStyle,
+      },
+      {
+        text: 'Data',
+        anchorX: 50,
+        anchorY: 50,
+        width: 40,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+    ];
+
+    const results = resolveCollisions(labels);
+    // Data label (higher priority) should get its preferred position
+    const dataResult = results.find((r) => r.text === 'Data');
+    expect(dataResult!.x).toBe(50);
+    expect(dataResult!.y).toBe(50);
+    expect(dataResult!.visible).toBe(true);
+  });
+
+  it('demotes labels to tooltip-only when no position works', () => {
+    // Create many overlapping labels in a tiny area
+    const labels: LabelCandidate[] = Array.from({ length: 20 }, (_, i) => ({
+      text: `Label ${i}`,
+      anchorX: 50,
+      anchorY: 50,
+      width: 80,
+      height: 14,
+      priority: 'data' as const,
+      style: defaultStyle,
+    }));
+
+    const results = resolveCollisions(labels);
+    // Some should be demoted to tooltip-only
+    const hidden = results.filter((r) => !r.visible);
+    expect(hidden.length).toBeGreaterThan(0);
+  });
+
+  it('adds connector when label is offset from anchor', () => {
+    const labels: LabelCandidate[] = [
+      {
+        text: 'A',
+        anchorX: 50,
+        anchorY: 50,
+        width: 40,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+      {
+        text: 'B',
+        anchorX: 55,
+        anchorY: 52,
+        width: 40,
+        height: 14,
+        priority: 'data',
+        style: defaultStyle,
+      },
+    ];
+
+    const results = resolveCollisions(labels);
+    const offsetLabel = results.find((r) => r.connector !== undefined);
+    if (offsetLabel) {
+      expect(offsetLabel.connector!.to.x).toBe(
+        labels.find((l) => l.text === offsetLabel.text)!.anchorX,
+      );
+    }
+  });
+
+  it('handles empty input', () => {
+    expect(resolveCollisions([])).toEqual([]);
+  });
+});

package/src/labels/collision.ts

@@ -0,0 +1,154 @@
+/**
+ * Label collision detection and resolution.
+ *
+ * Greedy algorithm: sort by priority, place in order, try offset
+ * positions for conflicts, demote to tooltip-only if no position works.
+ * Targeting ~60% of Infrographic quality for Phase 0.
+ */
+
+import type { Rect, ResolvedLabel, TextStyle } from '../types/layout';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Priority levels for label placement. Data labels win over annotations which win over axes. */
+export type LabelPriority = 'data' | 'annotation' | 'axis';
+
+/** Priority sort order (lower = higher priority). */
+const PRIORITY_ORDER: Record<LabelPriority, number> = {
+  data: 0,
+  annotation: 1,
+  axis: 2,
+};
+
+/**
+ * A label candidate for collision resolution.
+ * The collision engine decides its final position and visibility.
+ */
+export interface LabelCandidate {
+  /** The label text. */
+  text: string;
+  /** Preferred anchor position (before collision resolution). */
+  anchorX: number;
+  /** Preferred anchor position (before collision resolution). */
+  anchorY: number;
+  /** Estimated width of the label text. */
+  width: number;
+  /** Estimated height of the label text. */
+  height: number;
+  /** Label priority for collision resolution. */
+  priority: LabelPriority;
+  /** Text style to apply. */
+  style: TextStyle;
+}
+
+// ---------------------------------------------------------------------------
+// Collision detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect AABB (axis-aligned bounding box) overlap between two rectangles.
+ */
+export function detectCollision(a: Rect, b: Rect): boolean {
+  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+// ---------------------------------------------------------------------------
+// Offset strategies
+// ---------------------------------------------------------------------------
+
+/** Offsets to try when a label collides with an existing placement. */
+const OFFSET_STRATEGIES = [
+  { dx: 0, dy: 0 }, // original position
+  { dx: 0, dy: -1.2 }, // above (factor of height)
+  { dx: 0, dy: 1.2 }, // below
+  { dx: 1.1, dy: 0 }, // right
+  { dx: -1.1, dy: 0 }, // left
+  { dx: 1.1, dy: -1.2 }, // upper-right
+  { dx: -1.1, dy: -1.2 }, // upper-left
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve label collisions using a greedy placement algorithm.
+ *
+ * Sorts labels by priority (data > annotation > axis), then places
+ * each label at its preferred position. If it collides with an already-placed
+ * label, tries offset positions. If no position works, the label is
+ * demoted to tooltip-only (visible: false).
+ *
+ * @param labels - Array of label candidates to position.
+ * @returns Array of resolved labels with computed positions and visibility.
+ */
+export function resolveCollisions(labels: LabelCandidate[]): ResolvedLabel[] {
+  // Sort by priority (highest first)
+  const sorted = [...labels].sort(
+    (a, b) => PRIORITY_ORDER[a.priority] - PRIORITY_ORDER[b.priority],
+  );
+
+  const placed: Rect[] = [];
+  const results: ResolvedLabel[] = [];
+
+  for (const label of sorted) {
+    let bestRect: Rect | null = null;
+    let bestX = label.anchorX;
+    let bestY = label.anchorY;
+
+    // Try each offset strategy
+    for (const offset of OFFSET_STRATEGIES) {
+      const candidateX = label.anchorX + offset.dx * label.width;
+      const candidateY = label.anchorY + offset.dy * label.height;
+      const candidateRect: Rect = {
+        x: candidateX,
+        y: candidateY,
+        width: label.width,
+        height: label.height,
+      };
+
+      const hasCollision = placed.some((p) => detectCollision(candidateRect, p));
+
+      if (!hasCollision) {
+        bestRect = candidateRect;
+        bestX = candidateX;
+        bestY = candidateY;
+        break;
+      }
+    }
+
+    if (bestRect) {
+      placed.push(bestRect);
+      const needsConnector = bestX !== label.anchorX || bestY !== label.anchorY;
+
+      results.push({
+        text: label.text,
+        x: bestX,
+        y: bestY,
+        style: label.style,
+        visible: true,
+        connector: needsConnector
+          ? {
+              from: { x: bestX, y: bestY },
+              to: { x: label.anchorX, y: label.anchorY },
+              stroke: label.style.fill,
+              style: 'straight' as const,
+            }
+          : undefined,
+      });
+    } else {
+      // No position works, demote to tooltip-only
+      results.push({
+        text: label.text,
+        x: label.anchorX,
+        y: label.anchorY,
+        style: label.style,
+        visible: false,
+      });
+    }
+  }
+
+  return results;
+}

package/src/labels/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Labels module barrel export.
+ */
+
+export type { LabelCandidate, LabelPriority } from './collision';
+export { detectCollision, resolveCollisions } from './collision';

package/src/layout/__tests__/chrome.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { resolveTheme } from '../../theme/resolve';
+import type { Chrome } from '../../types/spec';
+import { computeChrome } from '../chrome';
+
+const theme = resolveTheme();
+
+describe('computeChrome', () => {
+  it('returns zero heights when chrome is undefined', () => {
+    const result = computeChrome(undefined, theme, 600);
+    expect(result.topHeight).toBe(0);
+    expect(result.bottomHeight).toBe(0);
+    expect(result.title).toBeUndefined();
+    expect(result.subtitle).toBeUndefined();
+  });
+
+  it('returns zero heights when chrome is empty', () => {
+    const result = computeChrome({}, theme, 600);
+    expect(result.topHeight).toBe(0);
+    expect(result.bottomHeight).toBe(0);
+  });
+
+  it('positions title correctly', () => {
+    const chrome: Chrome = { title: 'GDP Growth Rate' };
+    const result = computeChrome(chrome, theme, 600);
+
+    expect(result.title).toBeDefined();
+    expect(result.title!.text).toBe('GDP Growth Rate');
+    expect(result.title!.x).toBe(theme.spacing.padding);
+    expect(result.title!.y).toBe(theme.spacing.padding);
+    expect(result.title!.style.fontSize).toBe(theme.chrome.title.fontSize);
+    expect(result.title!.style.fontWeight).toBe(theme.chrome.title.fontWeight);
+    expect(result.topHeight).toBeGreaterThan(0);
+  });
+
+  it('positions subtitle below title', () => {
+    const chrome: Chrome = { title: 'Title', subtitle: 'Subtitle text' };
+    const result = computeChrome(chrome, theme, 600);
+
+    expect(result.title).toBeDefined();
+    expect(result.subtitle).toBeDefined();
+    expect(result.subtitle!.y).toBeGreaterThan(result.title!.y);
+  });
+
+  it('computes top height from title + subtitle + gaps', () => {
+    const chrome: Chrome = { title: 'Title', subtitle: 'Subtitle' };
+    const result = computeChrome(chrome, theme, 600);
+
+    // Top height should account for title, gap, subtitle, and chromeToChart
+    expect(result.topHeight).toBeGreaterThan(30);
+  });
+
+  it('positions source in bottom chrome', () => {
+    const chrome: Chrome = { source: 'Source: World Bank' };
+    const result = computeChrome(chrome, theme, 600);
+
+    expect(result.source).toBeDefined();
+    expect(result.source!.text).toBe('Source: World Bank');
+    expect(result.bottomHeight).toBeGreaterThan(0);
+  });
+
+  it('handles ChromeText objects with style overrides', () => {
+    const chrome: Chrome = {
+      title: {
+        text: 'Custom Title',
+        style: { fontSize: 24, fontWeight: 700, color: '#ff0000' },
+      },
+    };
+    const result = computeChrome(chrome, theme, 600);
+
+    expect(result.title!.style.fontSize).toBe(24);
+    expect(result.title!.style.fontWeight).toBe(700);
+    expect(result.title!.style.fill).toBe('#ff0000');
+  });
+
+  it('sets maxWidth based on width minus padding', () => {
+    const chrome: Chrome = { title: 'Title' };
+    const result = computeChrome(chrome, theme, 600);
+
+    const expectedMaxWidth = 600 - theme.spacing.padding * 2;
+    expect(result.title!.maxWidth).toBe(expectedMaxWidth);
+  });
+
+  it('handles full chrome with all elements', () => {
+    const chrome: Chrome = {
+      title: 'Title',
+      subtitle: 'Subtitle',
+      source: 'Source',
+      byline: 'By Author',
+      footer: 'Footer note',
+    };
+    const result = computeChrome(chrome, theme, 600);
+
+    expect(result.title).toBeDefined();
+    expect(result.subtitle).toBeDefined();
+    expect(result.source).toBeDefined();
+    expect(result.byline).toBeDefined();
+    expect(result.footer).toBeDefined();
+    expect(result.topHeight).toBeGreaterThan(0);
+    expect(result.bottomHeight).toBeGreaterThan(0);
+  });
+
+  it('uses measureText function when provided', () => {
+    const measureText = (text: string, fontSize: number) => ({
+      width: text.length * fontSize * 0.6,
+      height: fontSize * 1.2,
+    });
+
+    const chrome: Chrome = { title: 'Title' };
+    const result = computeChrome(chrome, theme, 600, measureText);
+    expect(result.title).toBeDefined();
+    // Just verify it runs without error; exact values depend on measure fn
+  });
+});

package/src/layout/__tests__/text-measure.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { estimateTextHeight, estimateTextWidth } from '../text-measure';
+
+describe('estimateTextWidth', () => {
+  it('returns 0 for empty string', () => {
+    expect(estimateTextWidth('', 14)).toBe(0);
+  });
+
+  it('scales linearly with text length', () => {
+    const w5 = estimateTextWidth('hello', 14);
+    const w10 = estimateTextWidth('helloworld', 14);
+    expect(w10).toBeCloseTo(w5 * 2, 1);
+  });
+
+  it('scales with font size', () => {
+    const w14 = estimateTextWidth('test', 14);
+    const w28 = estimateTextWidth('test', 28);
+    expect(w28).toBeCloseTo(w14 * 2, 1);
+  });
+
+  it('heavier weights produce wider estimates', () => {
+    const normal = estimateTextWidth('test', 14, 400);
+    const bold = estimateTextWidth('test', 14, 700);
+    expect(bold).toBeGreaterThan(normal);
+  });
+
+  it('produces reasonable values for common cases', () => {
+    // "GDP Growth Rate" at 18px should be roughly 120-180px wide
+    const width = estimateTextWidth('GDP Growth Rate', 18);
+    expect(width).toBeGreaterThan(100);
+    expect(width).toBeLessThan(250);
+  });
+});
+
+describe('estimateTextHeight', () => {
+  it('single line at 14px with 1.3 lineHeight is 18.2', () => {
+    expect(estimateTextHeight(14, 1, 1.3)).toBeCloseTo(18.2, 1);
+  });
+
+  it('two lines are double the height', () => {
+    const h1 = estimateTextHeight(14, 1);
+    const h2 = estimateTextHeight(14, 2);
+    expect(h2).toBeCloseTo(h1 * 2, 1);
+  });
+
+  it('defaults to 1 line and 1.3 lineHeight', () => {
+    expect(estimateTextHeight(10)).toBeCloseTo(13, 1);
+  });
+});