@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/annotations/placement.ts

@@ -0,0 +1,636 @@
+/**
+ * Annotation placement engine: typed obstacles, candidate generation,
+ * scored search, and two-pass deterministic placement.
+ */
+
+import { overlapArea, type Rect } from '@opendata-ai/openchart-core';
+import { ANCHOR_OFFSET, subtitleBaselineY } from './constants';
+import {
+  type AnnotationMeasureTextFn,
+  computeTextBlockBounds,
+  heuristicMeasure,
+  unionRects,
+} from './geometry';
+
+export type ObstacleKind =
+  | 'mark'
+  | 'line'
+  | 'area-fill'
+  | 'legend'
+  | 'data-label'
+  | 'endpoint-label'
+  | 'watermark'
+  | 'axis-band'
+  | 'annotation';
+
+export interface PlacementObstacle extends Rect {
+  kind: ObstacleKind;
+}
+
+/**
+ * Sample a polyline into bucket-based obstacle rects. Each bucket spans a
+ * fixed x-width and covers the min/max y of the line within that bucket,
+ * padded vertically. Interpolates segment y-values at bucket edges so steep
+ * segments produce gap-free coverage.
+ */
+function lerpY(p0: { x: number; y: number }, p1: { x: number; y: number }, x: number): number {
+  const dx = p1.x - p0.x;
+  if (Math.abs(dx) < 1e-9) return (p0.y + p1.y) / 2;
+  const t = (x - p0.x) / dx;
+  return p0.y + t * (p1.y - p0.y);
+}
+
+function fillBucketsFromSegments(
+  points: Array<{ x: number; y: number }>,
+  buckets: Array<{ minY: number; maxY: number }>,
+  xMin: number,
+  bucketWidth: number,
+): void {
+  const bucketCount = buckets.length;
+
+  function updateBucket(b: number, y: number): void {
+    if (b < 0 || b >= bucketCount) return;
+    if (y < buckets[b].minY) buckets[b].minY = y;
+    if (y > buckets[b].maxY) buckets[b].maxY = y;
+  }
+
+  for (let i = 0; i < points.length - 1; i++) {
+    const p0 = points[i];
+    const p1 = points[i + 1];
+    const segXMin = Math.min(p0.x, p1.x);
+    const segXMax = Math.max(p0.x, p1.x);
+    const bStart = Math.max(0, Math.floor((segXMin - xMin) / bucketWidth));
+    const bEnd = Math.min(bucketCount - 1, Math.floor((segXMax - xMin) / bucketWidth));
+    for (let b = bStart; b <= bEnd; b++) {
+      const bx0 = xMin + b * bucketWidth;
+      const bx1 = xMin + (b + 1) * bucketWidth;
+      updateBucket(b, lerpY(p0, p1, Math.max(bx0, segXMin)));
+      updateBucket(b, lerpY(p0, p1, Math.min(bx1, segXMax)));
+    }
+  }
+
+  for (const p of points) {
+    const b = Math.min(Math.floor((p.x - xMin) / bucketWidth), bucketCount - 1);
+    updateBucket(b, p.y);
+  }
+}
+
+export function samplePolylineObstacles(
+  points: Array<{ x: number; y: number }>,
+  kind: 'line' | 'area-fill' = 'line',
+  bucketWidth = 24,
+  pad = 3,
+): PlacementObstacle[] {
+  if (points.length === 0) return [];
+
+  if (points.length === 1) {
+    const p = points[0];
+    return [
+      {
+        x: p.x - pad,
+        y: p.y - pad,
+        width: pad * 2,
+        height: pad * 2,
+        kind,
+      },
+    ];
+  }
+
+  let xMin = Infinity;
+  let xMax = -Infinity;
+  for (const p of points) {
+    if (p.x < xMin) xMin = p.x;
+    if (p.x > xMax) xMax = p.x;
+  }
+
+  const span = xMax - xMin;
+  if (span <= 0) {
+    // All points at same x: single vertical rect
+    let yMin = Infinity;
+    let yMax = -Infinity;
+    for (const p of points) {
+      if (p.y < yMin) yMin = p.y;
+      if (p.y > yMax) yMax = p.y;
+    }
+    return [
+      {
+        x: xMin - pad,
+        y: yMin - pad,
+        width: pad * 2,
+        height: yMax - yMin + pad * 2,
+        kind,
+      },
+    ];
+  }
+
+  const bucketCount = Math.ceil(span / bucketWidth);
+  const buckets: Array<{ minY: number; maxY: number }> = [];
+  for (let i = 0; i < bucketCount; i++) {
+    buckets.push({ minY: Infinity, maxY: -Infinity });
+  }
+
+  fillBucketsFromSegments(points, buckets, xMin, bucketWidth);
+
+  const obstacles: PlacementObstacle[] = [];
+  for (let b = 0; b < bucketCount; b++) {
+    const bucket = buckets[b];
+    if (bucket.minY === Infinity) continue;
+    obstacles.push({
+      x: xMin + b * bucketWidth,
+      y: bucket.minY - pad,
+      width: bucketWidth,
+      height: bucket.maxY - bucket.minY + pad * 2,
+      kind,
+    });
+  }
+
+  return obstacles;
+}
+
+/**
+ * Sample an area mark's fill region into bucket-based obstacles. The top
+ * boundary produces 'line' obstacles (hard), and the fill between top and
+ * bottom produces 'area-fill' obstacles (soft).
+ */
+export function sampleAreaObstacles(
+  topPoints: Array<{ x: number; y: number }>,
+  bottomPoints: Array<{ x: number; y: number }>,
+  bucketWidth = 24,
+  pad = 3,
+): PlacementObstacle[] {
+  const lineObs = samplePolylineObstacles(topPoints, 'line', bucketWidth, pad);
+
+  // For the fill region, sample both top and bottom boundaries and create
+  // fill obstacles spanning from the top boundary down to the bottom boundary
+  // within each bucket.
+  if (topPoints.length < 2 || bottomPoints.length < 2) return lineObs;
+
+  let xMin = Infinity;
+  let xMax = -Infinity;
+  for (const p of topPoints) {
+    if (p.x < xMin) xMin = p.x;
+    if (p.x > xMax) xMax = p.x;
+  }
+
+  const span = xMax - xMin;
+  if (span <= 0) return lineObs;
+
+  const bucketCount = Math.ceil(span / bucketWidth);
+  const topBuckets: Array<{ minY: number; maxY: number }> = [];
+  const bottomBuckets: Array<{ minY: number; maxY: number }> = [];
+  for (let i = 0; i < bucketCount; i++) {
+    topBuckets.push({ minY: Infinity, maxY: -Infinity });
+    bottomBuckets.push({ minY: Infinity, maxY: -Infinity });
+  }
+
+  fillBucketsFromSegments(topPoints, topBuckets, xMin, bucketWidth);
+  fillBucketsFromSegments(bottomPoints, bottomBuckets, xMin, bucketWidth);
+
+  const fillObs: PlacementObstacle[] = [];
+  for (let b = 0; b < bucketCount; b++) {
+    const top = topBuckets[b];
+    const bottom = bottomBuckets[b];
+    if (top.minY === Infinity || bottom.minY === Infinity) continue;
+
+    const fillTop = Math.min(top.minY, top.maxY);
+    const fillBottom = Math.max(bottom.minY, bottom.maxY);
+    if (fillBottom <= fillTop) continue;
+
+    fillObs.push({
+      x: xMin + b * bucketWidth,
+      y: fillTop,
+      width: bucketWidth,
+      height: fillBottom - fillTop,
+      kind: 'area-fill',
+    });
+  }
+
+  return [...lineObs, ...fillObs];
+}
+
+/** Normalize a plain Rect[] to PlacementObstacle[] with a default kind. */
+export function normalizeObstacles(
+  rects: Rect[],
+  kind: ObstacleKind = 'mark',
+): PlacementObstacle[] {
+  return rects.map((r) => ({ ...r, kind }));
+}
+
+// ---------------------------------------------------------------------------
+// Scored placement search
+// ---------------------------------------------------------------------------
+
+const OBSTACLE_WEIGHTS: Record<ObstacleKind, number> = {
+  annotation: 30,
+  line: 20,
+  mark: 8,
+  'data-label': 8,
+  'endpoint-label': 8,
+  legend: 6,
+  watermark: 6,
+  'axis-band': 6,
+  'area-fill': 1.5,
+};
+
+const W_SVG = 50;
+const W_CHART = 6;
+const W_DIST = 2;
+const EPSILON = 0.001;
+const CLEAN_THRESHOLD = EPSILON * 16;
+
+interface DirectionDef {
+  ux: number;
+  uy: number;
+  textAnchor: 'start' | 'end';
+  attach:
+    | 'bottom-center'
+    | 'bottom-left'
+    | 'left-middle'
+    | 'top-left'
+    | 'top-center'
+    | 'top-right'
+    | 'right-middle'
+    | 'bottom-right';
+}
+
+const D = Math.SQRT1_2;
+
+const DIRECTIONS: DirectionDef[] = [
+  { ux: 0, uy: -1, textAnchor: 'start', attach: 'bottom-center' }, // N
+  { ux: D, uy: -D, textAnchor: 'start', attach: 'bottom-left' }, // NE
+  { ux: 1, uy: 0, textAnchor: 'start', attach: 'left-middle' }, // E
+  { ux: D, uy: D, textAnchor: 'start', attach: 'top-left' }, // SE
+  { ux: 0, uy: 1, textAnchor: 'start', attach: 'top-center' }, // S
+  { ux: -D, uy: D, textAnchor: 'end', attach: 'top-right' }, // SW
+  { ux: -1, uy: 0, textAnchor: 'end', attach: 'right-middle' }, // W
+  { ux: -D, uy: -D, textAnchor: 'end', attach: 'bottom-right' }, // NW
+];
+
+// Preferred direction orderings: away from data vertically, right over left
+const LOWER_HALF_ORDER = [1, 0, 7, 2, 3, 4, 5, 6]; // NE, N, NW, E, SE, S, SW, W
+const UPPER_HALF_ORDER = [3, 4, 5, 2, 1, 0, 7, 6]; // SE, S, SW, E, NE, N, NW, W
+
+export interface PlacementCandidate {
+  labelX: number;
+  labelY: number;
+  textAnchor: 'start' | 'end';
+  box: Rect;
+  directionIndex: number;
+  ring: 1 | 2 | 3;
+  score: number;
+  candidateIdx: number;
+}
+
+export interface CandidateScoreBreakdown {
+  direction: string;
+  ring: 1 | 2 | 3;
+  box: Rect;
+  perObstacle: Array<{ kind: ObstacleKind; overlap: number; contribution: number }>;
+  outsideSvg: number;
+  outsideChart: number;
+  distance: number;
+  tiebreak: number;
+  total: number;
+}
+
+function computeAttachmentPoint(
+  anchorX: number,
+  anchorY: number,
+  dir: DirectionDef,
+  radius: number,
+): { x: number; y: number } {
+  return {
+    x: anchorX + dir.ux * radius,
+    y: anchorY + dir.uy * radius,
+  };
+}
+
+function labelPositionFromAttachment(
+  attachPt: { x: number; y: number },
+  dir: DirectionDef,
+  boxHeight: number,
+  fontSize: number,
+  boxWidth: number,
+): { labelX: number; labelY: number } {
+  const attach = dir.attach;
+
+  // A `*-center` attach means the block straddles the point, so `labelX` (the
+  // text's start edge, since these directions render textAnchor 'start') has to
+  // back off by half the block width. Centering the BLOCK is not the same as
+  // center-aligning the TEXT: the lines inside stay left-aligned and ragged
+  // right, per the reference voice. Without this the point sits at the block's
+  // left edge and a "top" anchor reads as "up and to the right".
+  const centered = attach === 'top-center' || attach === 'bottom-center';
+  const labelX = centered ? attachPt.x - boxWidth / 2 : attachPt.x;
+
+  let labelY: number;
+  if (attach === 'left-middle' || attach === 'right-middle') {
+    labelY = attachPt.y - boxHeight / 2 + fontSize;
+  } else if (attach === 'top-left' || attach === 'top-center' || attach === 'top-right') {
+    labelY = attachPt.y + fontSize;
+  } else {
+    labelY = attachPt.y - boxHeight + fontSize;
+  }
+
+  return { labelX, labelY };
+}
+
+function areaOutside(box: Rect, container: Rect): number {
+  const insideX = Math.max(
+    0,
+    Math.min(box.x + box.width, container.x + container.width) - Math.max(box.x, container.x),
+  );
+  const insideY = Math.max(
+    0,
+    Math.min(box.y + box.height, container.y + container.height) - Math.max(box.y, container.y),
+  );
+  const insideArea = insideX * insideY;
+  const boxArea = box.width * box.height;
+  return Math.max(0, boxArea - insideArea);
+}
+
+function inflateRect(r: Rect, pad: number): Rect {
+  return {
+    x: r.x - pad,
+    y: r.y - pad,
+    width: r.width + pad * 2,
+    height: r.height + pad * 2,
+  };
+}
+
+function scoreCandidate(
+  box: Rect,
+  obstacles: Rect[],
+  svgRect: Rect,
+  chartArea: Rect,
+  anchorX: number,
+  anchorY: number,
+  chartDiagonal: number,
+  candidateIndex: number,
+  debug?: boolean,
+): { score: number; breakdown?: CandidateScoreBreakdown } {
+  const boxArea = box.width * box.height || 1;
+  const inflated = inflateRect(box, 3);
+
+  let obstacleScore = 0;
+  const perObstacle: CandidateScoreBreakdown['perObstacle'] = [];
+
+  for (const obs of obstacles) {
+    const kind = 'kind' in obs ? (obs as PlacementObstacle).kind : 'mark';
+    const overlap = overlapArea(inflated, obs);
+    if (overlap > 0) {
+      const weight = OBSTACLE_WEIGHTS[kind] ?? 8;
+      const contribution = (weight * overlap) / boxArea;
+      obstacleScore += contribution;
+      if (debug) {
+        perObstacle.push({ kind, overlap, contribution });
+      }
+    }
+  }
+
+  const outsideSvg = (W_SVG * areaOutside(box, svgRect)) / boxArea;
+  const outsideChart = (W_CHART * areaOutside(box, chartArea) * 0.3) / boxArea;
+
+  const nearestX = Math.max(box.x, Math.min(anchorX, box.x + box.width));
+  const nearestY = Math.max(box.y, Math.min(anchorY, box.y + box.height));
+  const dx = anchorX - nearestX;
+  const dy = anchorY - nearestY;
+  const dist = Math.sqrt(dx * dx + dy * dy);
+  const distance = (W_DIST * dist) / (chartDiagonal || 1);
+
+  const tiebreak = candidateIndex * EPSILON;
+  const score = obstacleScore + outsideSvg + outsideChart + distance + tiebreak;
+
+  if (debug) {
+    return {
+      score,
+      breakdown: {
+        direction: '',
+        ring: 1,
+        box,
+        perObstacle,
+        outsideSvg,
+        outsideChart,
+        distance,
+        tiebreak,
+        total: score,
+      },
+    };
+  }
+
+  return { score };
+}
+
+export interface PlacementResult {
+  labelX: number;
+  labelY: number;
+  textAnchor: 'start' | 'end';
+  bounds: Rect;
+  score: number;
+  debug?: CandidateScoreBreakdown[];
+}
+
+/**
+ * Run the scored placement search for a single auto annotation.
+ * Generates candidates around the anchor point, scores each, returns the best.
+ */
+export function findBestPlacement(
+  anchorX: number,
+  anchorY: number,
+  text: string,
+  style: { fontSize: number; fontWeight: number; lineHeight: number; fontFamily?: string },
+  subtitleText: string | undefined,
+  subtitleStyle:
+    | { fontSize: number; fontWeight: number; lineHeight: number; fontFamily?: string }
+    | undefined,
+  obstacles: Rect[],
+  chartArea: Rect,
+  svgRect: Rect,
+  measure: AnnotationMeasureTextFn = heuristicMeasure,
+  debug = false,
+): PlacementResult {
+  const isUpperHalf = anchorY < chartArea.y + chartArea.height / 2;
+  const dirOrder = isUpperHalf ? UPPER_HALF_ORDER : LOWER_HALF_ORDER;
+  const chartDiagonal = Math.sqrt(chartArea.width ** 2 + chartArea.height ** 2);
+
+  // Compute box dimensions for candidate generation
+  const sampleBounds = computeTextBlockBounds(
+    0,
+    style.fontSize,
+    text,
+    {
+      ...style,
+      textAnchor: 'start',
+    },
+    measure,
+  );
+  const boxHeight = sampleBounds.height;
+
+  // Centering a `*-center` attach needs the width of the WHOLE block, not just
+  // the primary line: a subtitle is often the wider of the two, and centering on
+  // the primary width alone would leave a lede+subtitle stack visibly off-center
+  // over its point.
+  const subtitleSampleWidth =
+    subtitleText && subtitleStyle
+      ? computeTextBlockBounds(
+          0,
+          subtitleStyle.fontSize,
+          subtitleText,
+          { ...subtitleStyle, textAnchor: 'start' },
+          measure,
+        ).width
+      : 0;
+  const boxWidth = Math.max(sampleBounds.width, subtitleSampleWidth);
+
+  // The innermost ring is the default setback for an auto-placed label, so it's
+  // the same quantity ANCHOR_OFFSET expresses for the explicit path — keep them
+  // as one constant. A 12px ring sat inside the standoff + marker-pullback
+  // overhead, so an auto-placed label's connector was always shorter than
+  // MIN_CONNECTOR_LENGTH and got suppressed: six bare callouts rendered as
+  // floating text with no leader back to the data.
+  const r1 = ANCHOR_OFFSET;
+  const r2 = r1 + boxHeight + 8;
+  const r3 = 2 * r2;
+
+  let nextCandidateIdx = 0;
+
+  function generateCandidates(radii: number[]): PlacementCandidate[] {
+    const candidates: PlacementCandidate[] = [];
+
+    for (const radius of radii) {
+      const ring = radius === r1 ? 1 : radius === r2 ? 2 : 3;
+      for (const di of dirOrder) {
+        const dir = DIRECTIONS[di];
+        const attachPt = computeAttachmentPoint(anchorX, anchorY, dir, radius);
+        const { labelX, labelY } = labelPositionFromAttachment(
+          attachPt,
+          dir,
+          boxHeight,
+          style.fontSize,
+          boxWidth,
+        );
+
+        let box = computeTextBlockBounds(
+          labelX,
+          labelY,
+          text,
+          {
+            ...style,
+            textAnchor: dir.textAnchor,
+          },
+          measure,
+        );
+
+        // Union with subtitle bounds if present
+        if (subtitleText && subtitleStyle) {
+          // This pass SCORES a candidate subtitle position; the resolver STAMPS the
+          // one that renders. They must agree, or the scored block height is a lie
+          // and the bounds other annotations avoid no longer contain the subtitle.
+          // Hence the shared formula rather than a second copy of the sum.
+          const subtitleY = subtitleBaselineY(
+            labelY,
+            style.fontSize * style.lineHeight,
+            text.split('\n').length,
+          );
+          const subBounds = computeTextBlockBounds(
+            labelX,
+            subtitleY,
+            subtitleText,
+            {
+              ...subtitleStyle,
+              textAnchor: dir.textAnchor,
+            },
+            measure,
+          );
+          box = unionRects(box, subBounds);
+        }
+
+        const idx = nextCandidateIdx++;
+        const { score } = scoreCandidate(
+          box,
+          obstacles,
+          svgRect,
+          chartArea,
+          anchorX,
+          anchorY,
+          chartDiagonal,
+          idx,
+        );
+
+        candidates.push({
+          labelX,
+          labelY,
+          textAnchor: dir.textAnchor,
+          box,
+          directionIndex: di,
+          ring: ring as 1 | 2 | 3,
+          score,
+          candidateIdx: idx,
+        });
+      }
+    }
+
+    return candidates;
+  }
+
+  // Ring 1 + Ring 2 (16 candidates)
+  let candidates = generateCandidates([r1, r2]);
+  let best = candidates.reduce((a, b) => (a.score <= b.score ? a : b));
+
+  // Ring 3 if no clean placement found
+  if (best.score > CLEAN_THRESHOLD) {
+    const ring3 = generateCandidates([r3]);
+    candidates = [...candidates, ...ring3];
+    best = candidates.reduce((a, b) => (a.score <= b.score ? a : b));
+  }
+
+  let debugBreakdowns: CandidateScoreBreakdown[] | undefined;
+  if (debug) {
+    const dirNames = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
+    debugBreakdowns = candidates.map((c) => {
+      const { breakdown } = scoreCandidate(
+        c.box,
+        obstacles,
+        svgRect,
+        chartArea,
+        anchorX,
+        anchorY,
+        chartDiagonal,
+        c.candidateIdx,
+        true,
+      );
+      return {
+        ...breakdown!,
+        direction: dirNames[c.directionIndex],
+        ring: c.ring,
+      };
+    });
+  }
+
+  return {
+    labelX: best.labelX,
+    labelY: best.labelY,
+    textAnchor: best.textAnchor,
+    bounds: best.box,
+    score: best.score,
+    debug: debugBreakdowns,
+  };
+}
+
+/** Check if an annotation should use the placement search (pure-auto, non-drop-line). */
+export function isAutoPlacement(annotation: {
+  anchor?: string;
+  offset?: { dx?: number; dy?: number };
+  connector?: string | boolean | { type?: string };
+}): boolean {
+  if (annotation.offset) return false;
+  if (annotation.anchor && annotation.anchor !== 'auto') return false;
+  if (annotation.connector === 'drop-line') return false;
+  if (
+    typeof annotation.connector === 'object' &&
+    annotation.connector !== null &&
+    annotation.connector.type === 'drop-line'
+  )
+    return false;
+  return true;
+}