@opendata-ai/openchart-engine 7.2.3 → 7.3.0

package/src/annotations/__tests__/placement-fuzz.test.ts

@@ -0,0 +1,256 @@
+import type { Rect } from '@opendata-ai/openchart-core';
+import { overlapArea } from '@opendata-ai/openchart-core';
+import { describe, it } from 'vitest';
+import type { PlacementObstacle, PlacementResult } from '../placement';
+import { findBestPlacement, samplePolylineObstacles } from '../placement';
+
+// ---------------------------------------------------------------------------
+// Seeded PRNG (mulberry32) - deterministic, no Date.now or Math.random
+// ---------------------------------------------------------------------------
+
+function mulberry32(seed: number) {
+  return () => {
+    let t = (seed += 0x6d2b79f5);
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Random helpers
+// ---------------------------------------------------------------------------
+
+function randRange(rng: () => number, min: number, max: number): number {
+  return min + rng() * (max - min);
+}
+
+function randInt(rng: () => number, min: number, max: number): number {
+  return Math.floor(randRange(rng, min, max + 1));
+}
+
+function randPick<T>(rng: () => number, arr: T[]): T {
+  return arr[Math.floor(rng() * arr.length)];
+}
+
+// ---------------------------------------------------------------------------
+// Case generator
+// ---------------------------------------------------------------------------
+
+type ChartType = 'line' | 'column' | 'scatter';
+
+interface FuzzCase {
+  caseIndex: number;
+  containerWidth: number;
+  containerHeight: number;
+  chartArea: Rect;
+  svgRect: Rect;
+  chartType: ChartType;
+  dataPoints: Array<{ x: number; y: number }>;
+  annotationIndices: number[];
+  obstacles: PlacementObstacle[];
+}
+
+function generateCase(rng: () => number, caseIndex: number): FuzzCase {
+  const containerWidth = randInt(rng, 320, 1200);
+  const containerHeight = randInt(rng, 240, 600);
+  const inset = 50;
+
+  const svgRect: Rect = { x: 0, y: 0, width: containerWidth, height: containerHeight };
+  const chartArea: Rect = {
+    x: inset,
+    y: inset,
+    width: containerWidth - inset * 2,
+    height: containerHeight - inset * 2,
+  };
+
+  const chartType = randPick<ChartType>(rng, ['line', 'column', 'scatter']);
+  const numPoints = randInt(rng, 5, 60);
+
+  // Generate random data points within the chart area
+  const dataPoints: Array<{ x: number; y: number }> = [];
+  for (let i = 0; i < numPoints; i++) {
+    dataPoints.push({
+      x: randRange(rng, chartArea.x, chartArea.x + chartArea.width),
+      y: randRange(rng, chartArea.y, chartArea.y + chartArea.height),
+    });
+  }
+
+  // Sort by x for line charts (polyline needs ordered points)
+  if (chartType === 'line') {
+    dataPoints.sort((a, b) => a.x - b.x);
+  }
+
+  // Generate obstacles based on chart type
+  let obstacles: PlacementObstacle[] = [];
+
+  if (chartType === 'line') {
+    obstacles = samplePolylineObstacles(dataPoints, 'line', 24, 3);
+  } else if (chartType === 'column') {
+    // Rect obstacles for column bars
+    const barWidth = Math.max(4, (chartArea.width / numPoints) * 0.6);
+    for (const pt of dataPoints) {
+      const barHeight = chartArea.y + chartArea.height - pt.y;
+      obstacles.push({
+        x: pt.x - barWidth / 2,
+        y: pt.y,
+        width: barWidth,
+        height: barHeight,
+        kind: 'mark',
+      });
+    }
+  } else {
+    // Scatter: point obstacles as small rects
+    const pointRadius = 4;
+    for (const pt of dataPoints) {
+      obstacles.push({
+        x: pt.x - pointRadius,
+        y: pt.y - pointRadius,
+        width: pointRadius * 2,
+        height: pointRadius * 2,
+        kind: 'mark',
+      });
+    }
+  }
+
+  // Pick 1-5 annotation anchor indices from the data points
+  const numAnnotations = randInt(rng, 1, 5);
+  const annotationIndices: number[] = [];
+  for (let i = 0; i < numAnnotations; i++) {
+    annotationIndices.push(randInt(rng, 0, numPoints - 1));
+  }
+
+  return {
+    caseIndex,
+    containerWidth,
+    containerHeight,
+    chartArea,
+    svgRect,
+    chartType,
+    dataPoints,
+    annotationIndices,
+    obstacles,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Test
+// ---------------------------------------------------------------------------
+
+const ANNOTATION_STYLE = { fontSize: 12, fontWeight: 600, lineHeight: 1.2 };
+
+describe('placement engine fuzz', () => {
+  it('passes 200 fuzz cases', () => {
+    const rng = mulberry32(42);
+
+    for (let i = 0; i < 200; i++) {
+      const tc = generateCase(rng, i);
+      const results: PlacementResult[] = [];
+      // Copy obstacles so we can append placed annotation bounds
+      const liveObstacles: PlacementObstacle[] = [...tc.obstacles];
+
+      for (const ptIdx of tc.annotationIndices) {
+        const anchor = tc.dataPoints[ptIdx];
+        const text = `Annotation ${ptIdx}`;
+
+        const result = findBestPlacement(
+          anchor.x,
+          anchor.y,
+          text,
+          ANNOTATION_STYLE,
+          undefined, // no subtitle
+          undefined,
+          liveObstacles,
+          tc.chartArea,
+          tc.svgRect,
+        );
+
+        results.push(result);
+
+        // Add this placed annotation as an obstacle for subsequent annotations
+        liveObstacles.push({
+          ...result.bounds,
+          kind: 'annotation',
+        });
+      }
+
+      const caseInfo = () =>
+        JSON.stringify(
+          {
+            caseIndex: tc.caseIndex,
+            containerWidth: tc.containerWidth,
+            containerHeight: tc.containerHeight,
+            chartType: tc.chartType,
+            numDataPoints: tc.dataPoints.length,
+            annotationIndices: tc.annotationIndices,
+            chartArea: tc.chartArea,
+            svgRect: tc.svgRect,
+          },
+          null,
+          2,
+        );
+
+      // Invariant 1: Pairwise non-overlap when all placements found clean spots
+      const allClean = results.every((r) => r.score < 0.1);
+      if (allClean && results.length > 1) {
+        for (let a = 0; a < results.length; a++) {
+          for (let b = a + 1; b < results.length; b++) {
+            const overlap = overlapArea(results[a].bounds, results[b].bounds);
+            if (overlap >= 0.5) {
+              throw new Error(
+                `Invariant 1 failed: pairwise overlap ${overlap.toFixed(2)}px^2 between annotation ${a} and ${b} (both scored < 0.1).\n${caseInfo()}`,
+              );
+            }
+          }
+        }
+      }
+
+      // Invariant 2: Bounds within SVG (2px margin tolerance)
+      const margin = 2;
+      for (let r = 0; r < results.length; r++) {
+        const b = results[r].bounds;
+        const inBounds =
+          b.x >= tc.svgRect.x - margin &&
+          b.y >= tc.svgRect.y - margin &&
+          b.x + b.width <= tc.svgRect.x + tc.svgRect.width + margin &&
+          b.y + b.height <= tc.svgRect.y + tc.svgRect.height + margin;
+
+        if (!inBounds) {
+          // Only fail if the placement engine scored it well (low score means
+          // it thought this was a good placement). High-score placements may
+          // be pushed out of bounds when the chart is too crowded.
+          if (results[r].score < 1) {
+            throw new Error(
+              `Invariant 2 failed: annotation ${r} bounds outside SVG rect (score=${results[r].score.toFixed(3)}).\n` +
+                `bounds: ${JSON.stringify(b)}\nsvgRect: ${JSON.stringify(tc.svgRect)}\n${caseInfo()}`,
+            );
+          }
+        }
+      }
+
+      // Invariant 3: Line avoidance - when chart type is 'line', verify
+      // low-score annotations don't overlap line obstacles near their anchor
+      if (tc.chartType === 'line') {
+        for (let r = 0; r < results.length; r++) {
+          if (results[r].score >= 0.1) continue; // only check clean placements
+
+          const anchor = tc.dataPoints[tc.annotationIndices[r]];
+          // Check line obstacles near the anchor (within 30px horizontally)
+          const nearbyLineObs = tc.obstacles.filter(
+            (obs) =>
+              obs.kind === 'line' && obs.x < anchor.x + 30 && obs.x + obs.width > anchor.x - 30,
+          );
+
+          for (const obs of nearbyLineObs) {
+            const overlap = overlapArea(results[r].bounds, obs);
+            if (overlap > 5) {
+              throw new Error(
+                `Invariant 3 failed: annotation ${r} overlaps nearby line obstacle by ${overlap.toFixed(2)}px^2 (score=${results[r].score.toFixed(3)}).\n${caseInfo()}`,
+              );
+            }
+          }
+        }
+      }
+    }
+  });
+});

package/src/annotations/__tests__/placement-invariants.test.ts

@@ -0,0 +1,345 @@
+import { overlapArea } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { findBestPlacement, type PlacementObstacle, samplePolylineObstacles } from '../placement';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const CHART_AREA = { x: 50, y: 20, width: 500, height: 300 };
+const SVG_RECT = { x: 0, y: 0, width: 600, height: 360 };
+const DEFAULT_STYLE = { fontSize: 12, fontWeight: 400, lineHeight: 1.3 };
+
+// ---------------------------------------------------------------------------
+// 1. Pairwise non-overlap
+// ---------------------------------------------------------------------------
+
+describe('pairwise non-overlap', () => {
+  it('two annotations at the same point do not overlap', () => {
+    const anchorX = 300;
+    const anchorY = 170;
+
+    const r1 = findBestPlacement(
+      anchorX,
+      anchorY,
+      'Label A',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    // Feed the first result's bounds as an obstacle for the second
+    const obstacle: PlacementObstacle = { ...r1.bounds, kind: 'annotation' };
+    const r2 = findBestPlacement(
+      anchorX,
+      anchorY,
+      'Label B',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [obstacle],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    expect(overlapArea(r1.bounds, r2.bounds)).toBe(0);
+  });
+
+  it('three annotations at the same point do not overlap each other', () => {
+    const anchorX = 250;
+    const anchorY = 160;
+    const obstacles: PlacementObstacle[] = [];
+
+    const results = [];
+    for (const label of ['Alpha', 'Beta', 'Gamma']) {
+      const r = findBestPlacement(
+        anchorX,
+        anchorY,
+        label,
+        DEFAULT_STYLE,
+        undefined,
+        undefined,
+        obstacles,
+        CHART_AREA,
+        SVG_RECT,
+      );
+      results.push(r);
+      obstacles.push({ ...r.bounds, kind: 'annotation' });
+    }
+
+    // Check all pairs
+    for (let i = 0; i < results.length; i++) {
+      for (let j = i + 1; j < results.length; j++) {
+        expect(
+          overlapArea(results[i].bounds, results[j].bounds),
+          `annotations ${i} and ${j} should not overlap`,
+        ).toBe(0);
+      }
+    }
+  });
+
+  it('two annotations at nearby points (within 20px) do not overlap', () => {
+    const r1 = findBestPlacement(
+      200,
+      150,
+      'Nearby A',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    const obstacle: PlacementObstacle = { ...r1.bounds, kind: 'annotation' };
+    const r2 = findBestPlacement(
+      215,
+      155,
+      'Nearby B',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [obstacle],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    expect(overlapArea(r1.bounds, r2.bounds)).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Bounds within SVG
+// ---------------------------------------------------------------------------
+
+describe('bounds within SVG', () => {
+  const MARGIN = 2;
+
+  function expectWithinSvg(label: string, anchorX: number, anchorY: number) {
+    const r = findBestPlacement(
+      anchorX,
+      anchorY,
+      label,
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    expect(r.bounds.x).toBeGreaterThanOrEqual(SVG_RECT.x - MARGIN);
+    expect(r.bounds.y).toBeGreaterThanOrEqual(SVG_RECT.y - MARGIN);
+    expect(r.bounds.x + r.bounds.width).toBeLessThanOrEqual(SVG_RECT.x + SVG_RECT.width + MARGIN);
+    expect(r.bounds.y + r.bounds.height).toBeLessThanOrEqual(SVG_RECT.y + SVG_RECT.height + MARGIN);
+  }
+
+  it('annotation near top-left corner stays within SVG', () => {
+    expectWithinSvg('Top Left', CHART_AREA.x + 10, CHART_AREA.y + 10);
+  });
+
+  it('annotation near bottom-right corner stays within SVG', () => {
+    expectWithinSvg(
+      'Bottom Right',
+      CHART_AREA.x + CHART_AREA.width - 10,
+      CHART_AREA.y + CHART_AREA.height - 10,
+    );
+  });
+
+  it('annotation near right edge stays within SVG', () => {
+    expectWithinSvg(
+      'Right Edge',
+      CHART_AREA.x + CHART_AREA.width - 5,
+      CHART_AREA.y + CHART_AREA.height / 2,
+    );
+  });
+
+  it('annotation at center is well within SVG', () => {
+    const cx = CHART_AREA.x + CHART_AREA.width / 2;
+    const cy = CHART_AREA.y + CHART_AREA.height / 2;
+    const r = findBestPlacement(
+      cx,
+      cy,
+      'Center',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      [],
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    // Center placement should be comfortably inside -- use a stricter margin
+    const STRICT = 10;
+    expect(r.bounds.x).toBeGreaterThanOrEqual(SVG_RECT.x + STRICT);
+    expect(r.bounds.y).toBeGreaterThanOrEqual(SVG_RECT.y + STRICT);
+    expect(r.bounds.x + r.bounds.width).toBeLessThanOrEqual(SVG_RECT.x + SVG_RECT.width - STRICT);
+    expect(r.bounds.y + r.bounds.height).toBeLessThanOrEqual(SVG_RECT.y + SVG_RECT.height - STRICT);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Line avoidance
+// ---------------------------------------------------------------------------
+
+describe('line avoidance', () => {
+  it('annotation placed on a line avoids nearby line obstacles', () => {
+    // Create a simple ascending line spanning the chart
+    const points = [];
+    for (let i = 0; i <= 10; i++) {
+      points.push({
+        x: CHART_AREA.x + (i / 10) * CHART_AREA.width,
+        y: CHART_AREA.y + CHART_AREA.height - (i / 10) * CHART_AREA.height,
+      });
+    }
+
+    const bucketWidth = 24;
+    const lineObstacles = samplePolylineObstacles(points, 'line', bucketWidth);
+
+    // Pick an anchor that sits on the line (midpoint)
+    const anchorX = CHART_AREA.x + CHART_AREA.width / 2;
+    const anchorY = CHART_AREA.y + CHART_AREA.height / 2;
+
+    const result = findBestPlacement(
+      anchorX,
+      anchorY,
+      'On the line',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      lineObstacles,
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    // Check that the result doesn't overlap line obstacles within +/-2 buckets of anchor
+    const nearbyObstacles = lineObstacles.filter((obs) => {
+      const obsMidX = obs.x + obs.width / 2;
+      return Math.abs(obsMidX - anchorX) <= bucketWidth * 2;
+    });
+
+    for (const obs of nearbyObstacles) {
+      expect(
+        overlapArea(result.bounds, obs),
+        `annotation should not overlap nearby line obstacle at x=${obs.x}`,
+      ).toBe(0);
+    }
+  });
+
+  it('annotation avoids a steep line segment', () => {
+    // Steep V-shape line where the anchor is at the valley
+    const points = [
+      { x: CHART_AREA.x + 100, y: CHART_AREA.y + 50 },
+      { x: CHART_AREA.x + 200, y: CHART_AREA.y + 250 },
+      { x: CHART_AREA.x + 300, y: CHART_AREA.y + 50 },
+    ];
+
+    const bucketWidth = 24;
+    const lineObstacles = samplePolylineObstacles(points, 'line', bucketWidth);
+
+    // Anchor at the valley
+    const anchorX = CHART_AREA.x + 200;
+    const anchorY = CHART_AREA.y + 250;
+
+    const result = findBestPlacement(
+      anchorX,
+      anchorY,
+      'Valley',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      lineObstacles,
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    const nearbyObstacles = lineObstacles.filter((obs) => {
+      const obsMidX = obs.x + obs.width / 2;
+      return Math.abs(obsMidX - anchorX) <= bucketWidth * 2;
+    });
+
+    for (const obs of nearbyObstacles) {
+      expect(
+        overlapArea(result.bounds, obs),
+        `annotation should not overlap nearby line obstacle at x=${obs.x}`,
+      ).toBe(0);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. Determinism
+// ---------------------------------------------------------------------------
+
+describe('determinism', () => {
+  it('identical inputs produce identical outputs', () => {
+    const anchorX = 300;
+    const anchorY = 170;
+    const text = 'Deterministic';
+    const obstacles: PlacementObstacle[] = [
+      { x: 280, y: 140, width: 40, height: 20, kind: 'mark' },
+    ];
+
+    const r1 = findBestPlacement(
+      anchorX,
+      anchorY,
+      text,
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      obstacles,
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    const r2 = findBestPlacement(
+      anchorX,
+      anchorY,
+      text,
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      obstacles,
+      CHART_AREA,
+      SVG_RECT,
+    );
+
+    expect(r1.labelX).toBe(r2.labelX);
+    expect(r1.labelY).toBe(r2.labelY);
+    expect(r1.textAnchor).toBe(r2.textAnchor);
+    expect(r1.bounds).toEqual(r2.bounds);
+    expect(r1.score).toBe(r2.score);
+  });
+
+  it('deterministic with multiple obstacles', () => {
+    const obstacles: PlacementObstacle[] = [
+      { x: 100, y: 100, width: 60, height: 30, kind: 'mark' },
+      { x: 200, y: 80, width: 50, height: 40, kind: 'line' },
+      { x: 150, y: 200, width: 80, height: 20, kind: 'legend' },
+    ];
+
+    const args = [
+      250,
+      150,
+      'Stable',
+      DEFAULT_STYLE,
+      undefined,
+      undefined,
+      obstacles,
+      CHART_AREA,
+      SVG_RECT,
+    ] as const;
+
+    const r1 = findBestPlacement(...args);
+    const r2 = findBestPlacement(...args);
+
+    expect(r1.labelX).toBe(r2.labelX);
+    expect(r1.labelY).toBe(r2.labelY);
+    expect(r1.textAnchor).toBe(r2.textAnchor);
+    expect(r1.bounds).toEqual(r2.bounds);
+    expect(r1.score).toBe(r2.score);
+  });
+});