@opendata-ai/openchart-engine 8.0.0-rc.2 → 8.0.0-rc.20

package/src/annotations/__tests__/geometry.test.ts

@@ -1,66 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { computeArrowheadPoints } from '../geometry';
-
-describe('computeArrowheadPoints', () => {
-  it('produces a downward-pointing arrow for a downward tangent', () => {
-    const head = computeArrowheadPoints(100, 200, 0, 1);
-    expect(head.tip).toEqual({ x: 100, y: 200 });
-    // Base should be above the tip (tangent points down)
-    expect(head.baseLeft.y).toBeLessThan(head.tip.y);
-    expect(head.baseRight.y).toBeLessThan(head.tip.y);
-    // Base corners symmetric around the tangent axis
-    expect(head.baseLeft.x).toBeLessThan(head.tip.x);
-    expect(head.baseRight.x).toBeGreaterThan(head.tip.x);
-  });
-
-  it('produces a rightward-pointing arrow for a rightward tangent', () => {
-    const head = computeArrowheadPoints(200, 100, 1, 0);
-    expect(head.tip).toEqual({ x: 200, y: 100 });
-    // Base should be to the left of the tip
-    expect(head.baseLeft.x).toBeLessThan(head.tip.x);
-    expect(head.baseRight.x).toBeLessThan(head.tip.x);
-  });
-
-  it('respects custom length and halfWidth', () => {
-    const defaultHead = computeArrowheadPoints(100, 200, 0, 1);
-    const bigHead = computeArrowheadPoints(100, 200, 0, 1, 16, 8);
-
-    // Bigger arrow should have base further from tip
-    const defaultBaseDist = Math.abs(defaultHead.baseLeft.y - defaultHead.tip.y);
-    const bigBaseDist = Math.abs(bigHead.baseLeft.y - bigHead.tip.y);
-    expect(bigBaseDist).toBeGreaterThan(defaultBaseDist);
-
-    // Bigger arrow should have wider base
-    const defaultWidth = Math.abs(defaultHead.baseLeft.x - defaultHead.baseRight.x);
-    const bigWidth = Math.abs(bigHead.baseLeft.x - bigHead.baseRight.x);
-    expect(bigWidth).toBeGreaterThan(defaultWidth);
-  });
-
-  it('handles diagonal tangent', () => {
-    const head = computeArrowheadPoints(100, 100, 1, 1);
-    expect(head.tip).toEqual({ x: 100, y: 100 });
-    // Base points should be behind the tip along the diagonal
-    const baseMidX = (head.baseLeft.x + head.baseRight.x) / 2;
-    const baseMidY = (head.baseLeft.y + head.baseRight.y) / 2;
-    expect(baseMidX).toBeLessThan(head.tip.x);
-    expect(baseMidY).toBeLessThan(head.tip.y);
-  });
-
-  it('uses defaults of length=7, halfWidth=3.5', () => {
-    const head = computeArrowheadPoints(100, 200, 0, 1);
-    // For a pure downward tangent, base is 7px above tip
-    expect(head.baseLeft.y).toBeCloseTo(193);
-    expect(head.baseRight.y).toBeCloseTo(193);
-    // Base corners are 3.5px to each side
-    expect(head.baseLeft.x).toBeCloseTo(96.5);
-    expect(head.baseRight.x).toBeCloseTo(103.5);
-  });
-
-  it('handles zero-length tangent gracefully', () => {
-    const head = computeArrowheadPoints(100, 100, 0, 0);
-    expect(head.tip).toEqual({ x: 100, y: 100 });
-    // Should not produce NaN
-    expect(Number.isFinite(head.baseLeft.x)).toBe(true);
-    expect(Number.isFinite(head.baseLeft.y)).toBe(true);
-  });
-});

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

@@ -1,256 +0,0 @@
-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

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