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

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

@@ -1,310 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { ResolvedLabel, TextStyle } from '../../types/layout';
-import {
-  computeLabelBounds,
-  detectCollision,
-  EXTENDED_OFFSET_STRATEGIES,
-  type LabelCandidate,
-  OFFSET_STRATEGIES,
-  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([]);
-  });
-
-  it('accepts custom strategies without breaking default behavior', () => {
-    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,
-      },
-    ];
-
-    // Explicit default strategies should behave the same as no parameter
-    const defaultResults = resolveCollisions(labels);
-    const explicitResults = resolveCollisions(labels, OFFSET_STRATEGIES);
-    expect(explicitResults).toEqual(defaultResults);
-  });
-
-  it('resolves more dense labels with extended strategies than default', () => {
-    // 10 labels at the exact same position, simulating many converging line endpoints.
-    // The default 7 strategies can place at most 7; extended strategies should place more.
-    const labels: LabelCandidate[] = Array.from({ length: 10 }, (_, i) => ({
-      text: `Series ${i}`,
-      anchorX: 400,
-      anchorY: 200,
-      width: 60,
-      height: 14,
-      priority: 'data' as const,
-      style: defaultStyle,
-    }));
-
-    const defaultResults = resolveCollisions(labels);
-    const extendedResults = resolveCollisions(labels, EXTENDED_OFFSET_STRATEGIES);
-
-    const defaultVisible = defaultResults.filter((r) => r.visible).length;
-    const extendedVisible = extendedResults.filter((r) => r.visible).length;
-
-    // Default has 7 strategies, so at most 7 can be placed
-    expect(defaultVisible).toBeLessThanOrEqual(OFFSET_STRATEGIES.length);
-    // Extended strategies should place more labels than default
-    expect(extendedVisible).toBeGreaterThan(defaultVisible);
-  });
-
-  it('EXTENDED_OFFSET_STRATEGIES includes all base strategies', () => {
-    for (const strategy of OFFSET_STRATEGIES) {
-      expect(EXTENDED_OFFSET_STRATEGIES).toContainEqual(strategy);
-    }
-    expect(EXTENDED_OFFSET_STRATEGIES.length).toBeGreaterThan(OFFSET_STRATEGIES.length);
-  });
-});
-
-describe('computeLabelBounds', () => {
-  it('covers the glyph box for an alphabetic-baseline label (y is the baseline)', () => {
-    // Column value labels emit y on the alphabetic baseline (top + 0.8*fontSize).
-    // The bounds must cover the glyphs above the baseline, not sit below them.
-    const fontSize = 10;
-    const glyphTop = 100; // where the text visually starts
-    const label: ResolvedLabel = {
-      text: '42',
-      x: 50,
-      // Emission shifts the top-space y down to the baseline.
-      y: glyphTop + fontSize * 0.8,
-      style: { ...defaultStyle, fontSize, textAnchor: 'middle' },
-      visible: true,
-    };
-    const bounds = computeLabelBounds(label);
-    // Top edge returns to the glyph top, not the baseline.
-    expect(bounds.y).toBeCloseTo(glyphTop, 5);
-    // The glyph box (from its top for `height`) contains the baseline.
-    expect(bounds.y).toBeLessThan(label.y);
-    expect(bounds.y + bounds.height).toBeGreaterThan(label.y);
-  });
-
-  it("treats y as the vertical center for dominant-baseline 'central'", () => {
-    const fontSize = 10;
-    const label: ResolvedLabel = {
-      text: '42',
-      x: 50,
-      y: 100,
-      style: { ...defaultStyle, fontSize, dominantBaseline: 'central' },
-      visible: true,
-    };
-    const bounds = computeLabelBounds(label);
-    expect(bounds.y).toBeCloseTo(100 - bounds.height / 2, 5);
-  });
-
-  it("treats y as the top edge for dominant-baseline 'hanging'", () => {
-    const label: ResolvedLabel = {
-      text: '42',
-      x: 50,
-      y: 100,
-      style: { ...defaultStyle, dominantBaseline: 'hanging' },
-      visible: true,
-    };
-    expect(computeLabelBounds(label).y).toBe(100);
-  });
-});

package/src/labels/collision.ts

@@ -1,249 +0,0 @@
-/**
- * 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.
- */
-
-import { estimateTextWidth } from '../layout/text-measure';
-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;
-  /**
-   * Optional caller-assigned source index. resolveCollisions may reorder its
-   * output (it sorts by priority), so callers that zip the result back against
-   * a parallel array should carry an index here and read it off ResolvedLabel
-   * rather than relying on positional order.
-   */
-  index?: number;
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-}
-
-/** Compute the area of intersection between two axis-aligned rectangles. Returns 0 if disjoint. */
-export function overlapArea(a: Rect, b: Rect): number {
-  const w = Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x);
-  const h = Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y);
-  return w > 0 && h > 0 ? w * h : 0;
-}
-
-// ---------------------------------------------------------------------------
-// Offset strategies
-// ---------------------------------------------------------------------------
-
-/** An offset position to try when resolving a label collision. */
-export interface OffsetStrategy {
-  dx: number;
-  dy: number;
-}
-
-/** Offsets to try when a label collides with an existing placement. */
-export const OFFSET_STRATEGIES: readonly OffsetStrategy[] = [
-  { 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
-];
-
-/**
- * Extended offset strategies with additional vertical spread for dense
- * multi-series endpoints (e.g. 5+ line series converging at similar y-values).
- */
-export const EXTENDED_OFFSET_STRATEGIES: readonly OffsetStrategy[] = [
-  ...OFFSET_STRATEGIES,
-  { dx: 0, dy: -2.4 }, // further above
-  { dx: 0, dy: 2.4 }, // further below
-  { dx: 0, dy: -3.6 }, // even further above
-  { dx: 0, dy: 3.6 }, // even further below
-  { dx: 1.1, dy: -2.4 }, // upper-right far
-  { dx: 1.1, dy: 2.4 }, // lower-right far
-];
-
-// ---------------------------------------------------------------------------
-// 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.
- * @param strategies - Optional offset strategies to use (defaults to OFFSET_STRATEGIES).
- * @returns Array of resolved labels with computed positions and visibility.
- */
-export function resolveCollisions(
-  labels: LabelCandidate[],
-  strategies: readonly OffsetStrategy[] = OFFSET_STRATEGIES,
-): 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 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 nudgeDx = bestX - label.anchorX;
-      const nudgeDy = bestY - label.anchorY;
-      const nudgeDist = Math.sqrt(nudgeDx * nudgeDx + nudgeDy * nudgeDy);
-      // Only show a connector when the label is nudged far enough that the
-      // reader can't tell which data point it belongs to. Short nudges between
-      // adjacent series labels produce visual noise without aiding comprehension.
-      const MIN_CONNECTOR_DISTANCE = 20;
-      const needsConnector = nudgeDist >= MIN_CONNECTOR_DISTANCE;
-
-      results.push({
-        text: label.text,
-        x: bestX,
-        y: bestY,
-        style: label.style,
-        visible: true,
-        // Only carry the index through when the caller set one, so labels that
-        // don't need it keep an unchanged output shape.
-        ...(label.index !== undefined ? { index: label.index } : {}),
-        connector: needsConnector
-          ? {
-              from: { x: bestX, y: bestY },
-              to: { x: label.anchorX, y: label.anchorY },
-              stroke: label.style.fill,
-              style: 'straight' as const,
-              arrow: false,
-            }
-          : 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,
-        ...(label.index !== undefined ? { index: label.index } : {}),
-      });
-    }
-  }
-
-  return results;
-}
-
-// ---------------------------------------------------------------------------
-// Label bounds estimation
-// ---------------------------------------------------------------------------
-
-/**
- * Compute the bounding rect of a resolved label from its position and text.
- * Uses heuristic text measurement so it works without DOM access.
- *
- * label.y is the SVG text anchor point, whose meaning depends on the label's
- * dominant-baseline. The rect's top edge is derived accordingly so the box
- * covers the actual glyphs (obstacles were sitting ~0.8*fontSize below the
- * text for alphabetic-baseline labels, e.g. column value labels):
- *   - 'central': y is the vertical center, so top = y - height/2.
- *   - 'hanging'/'text-after-edge': y is the top edge already.
- *   - default (alphabetic): y is the baseline, so top = y - fontSize*0.8
- *     (matches textAscent, the top-to-baseline distance renderers apply).
- */
-export function computeLabelBounds(label: ResolvedLabel): Rect {
-  const fontSize = label.style.fontSize;
-  const fontWeight = label.style.fontWeight;
-  const width = estimateTextWidth(label.text, fontSize, fontWeight);
-  const height = fontSize * (label.style.lineHeight ?? 1.2);
-
-  // Adjust x based on text anchor
-  let x = label.x;
-  if (label.style.textAnchor === 'middle') {
-    x = label.x - width / 2;
-  } else if (label.style.textAnchor === 'end') {
-    x = label.x - width;
-  }
-
-  // Map the anchor y to the box top based on dominant-baseline.
-  const baseline = label.style.dominantBaseline;
-  let y: number;
-  if (baseline === 'central') {
-    y = label.y - height / 2;
-  } else if (baseline === 'hanging' || baseline === 'text-after-edge') {
-    y = label.y;
-  } else {
-    y = label.y - fontSize * 0.8;
-  }
-
-  return { x, y, width, height };
-}

package/src/labels/index.ts

@@ -1,13 +0,0 @@
-/**
- * Labels module barrel export.
- */
-
-export type { LabelCandidate, LabelPriority, OffsetStrategy } from './collision';
-export {
-  computeLabelBounds,
-  detectCollision,
-  EXTENDED_OFFSET_STRATEGIES,
-  OFFSET_STRATEGIES,
-  overlapArea,
-  resolveCollisions,
-} from './collision';