@ponchia/ui 0.4.1 → 0.6.0

package/annotations/index.js

@@ -0,0 +1,792 @@
+// Shared SVG geometry primitives live in the connectors kernel; annotations
+// (figure callouts) build on them so a line/curve/arrow/dot is drawn one way.
+
+/**
+ * @ponchia/ui — SVG annotation geometry helpers.
+ *
+ * The public types below are JSDoc `@typedef`s; the shipped `index.d.ts` is
+ * generated from them (and these signatures) by `tsc --emitDeclarationOnly`.
+ *
+ * @typedef {{ x: number, y: number }} AnnotationPoint
+ * @typedef {{ dx: number, dy: number }} AnnotationOffset
+ * @typedef {'callout' | 'elbow' | 'curve'} AnnotationConnectorType
+ * @typedef {'start' | 'middle' | 'end'} AnnotationAlign
+ * @typedef {'top' | 'middle' | 'bottom'} AnnotationValign
+ * @typedef {'horizontal' | 'vertical'} AxisOrientation
+ * @typedef {'up' | 'down' | 'left' | 'right'} TimelineDirection
+ *
+ * @typedef {object} CircleSubject
+ * @property {'circle'} type
+ * @property {number} radius
+ * @property {number} [radiusPadding]
+ *
+ * @typedef {object} RectSubject
+ * @property {'rect'} type
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [padding]
+ *
+ * @typedef {CircleSubject | RectSubject} ConnectorSubject
+ *
+ * @typedef {AnnotationOffset & { subject?: ConnectorSubject, mid?: number }} ConnectorOptions
+ *
+ * @typedef {object} CircleSubjectOptions
+ * @property {number} radius
+ *
+ * @typedef {object} RectSubjectOptions
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [padding]
+ *
+ * @typedef {object} ThresholdOptions
+ * @property {number} [x1]
+ * @property {number} [y1]
+ * @property {number} x2
+ * @property {number} y2
+ *
+ * @typedef {object} AxisThresholdOptions
+ * @property {AxisOrientation} [orientation]
+ * @property {number} [value]
+ * @property {number} [start]
+ * @property {number} end
+ *
+ * @typedef {object} BracketSubjectOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [depth]
+ *
+ * @typedef {object} BandSubjectOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [padding]
+ *
+ * @typedef {object} SlopeSubjectOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ *
+ * @typedef {object} ComparisonBraceOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [depth]
+ *
+ * @typedef {object} OutlierClusterOptions
+ * @property {AnnotationPoint[]} points
+ * @property {number} [radius]
+ *
+ * @typedef {object} TimelineEventOptions
+ * @property {number} [size]
+ * @property {TimelineDirection} [direction]
+ *
+ * @typedef {object} EvidenceMarkerOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {number} [padding]
+ *
+ * @typedef {AnnotationPoint & { radius?: number }} ConnectorEndDotOptions
+ *
+ * @typedef {object} ConnectorEndArrowOptions
+ * @property {number} [x1]
+ * @property {number} [y1]
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [size]
+ * @property {number} [spread] Half-angle of the arrowhead in radians (default
+ *   0.32 ≈ a crisp 37° included angle). Larger = blunter.
+ *
+ * @typedef {object} NoteTransformOptions
+ * @property {number} [dx]
+ * @property {number} [dy]
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {AnnotationAlign} [align]
+ * @property {AnnotationValign} [valign]
+ * @property {number} [width]
+ * @property {number} [height]
+ *
+ * @typedef {object} AnnotationBounds
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ *
+ * @typedef {object} NotePlacementOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ * @property {AnnotationBounds} bounds
+ * @property {number} [padding]
+ * @property {number} [gap]
+ * @property {'right' | 'left' | 'top' | 'bottom'} [preferred]
+ * @property {number} [inset] Extra margin (user units) the note must keep from
+ *   the bounds edge, on top of `padding`. Reserve the note's title stroke-halo
+ *   (~3) or a leader stub so a placement that "fits" doesn't clip. Default 0.
+ *
+ * @typedef {object} NotePlacement
+ * @property {number} dx
+ * @property {number} dy
+ * @property {AnnotationAlign} align
+ * @property {AnnotationValign} valign
+ * @property {string} transform
+ *
+ * @typedef {(
+ *   | CircleSubject
+ *   | RectSubject
+ *   | ({ type: 'threshold' } & ThresholdOptions)
+ *   | ({ type: 'bracket' } & BracketSubjectOptions)
+ *   | ({ type: 'band' } & BandSubjectOptions)
+ *   | ({ type: 'slope' } & SlopeSubjectOptions)
+ *   | ({ type: 'compare' } & ComparisonBraceOptions)
+ *   | ({ type: 'cluster' } & OutlierClusterOptions)
+ *   | ({ type: 'axis' } & AxisThresholdOptions)
+ *   | ({ type: 'timeline' } & TimelineEventOptions)
+ *   | ({ type: 'evidence' } & EvidenceMarkerOptions)
+ * )} AnnotationPartsSubject
+ *
+ * @typedef {object} AnnotationPartsOptions
+ * @property {AnnotationConnectorType} [type]
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [dx]
+ * @property {number} [dy]
+ * @property {AnnotationPartsSubject} [subject]
+ *
+ * @typedef {object} AnnotationParts
+ * @property {string} transform
+ * @property {string} subject
+ * @property {string} connector
+ * @property {string} note
+ *
+ * @typedef {object} DeclutterLabelItem
+ * @property {number} pos Desired centre coordinate along the axis.
+ * @property {number} size The label's extent along the axis.
+ *
+ * @typedef {object} DeclutterLabelsOptions
+ * @property {number} [gap] Minimum gap kept between adjacent labels. Default 0.
+ * @property {number} [min] Lower bound of the axis. Default -Infinity.
+ * @property {number} [max] Upper bound of the axis. Default Infinity.
+ *
+ * @typedef {object} DirectLabelItem
+ * @property {AnnotationPoint} anchor The true data point the label refers to (figure coordinates).
+ * @property {number} size The label's extent along the layout axis.
+ * @property {string | number} [key] Optional identifier, echoed back on the matching output (input order).
+ *
+ * @typedef {object} DirectLabelsOptions
+ * @property {'x' | 'y'} [axis] Axis the labels declutter along. 'y' = a vertical column. Default 'y'.
+ * @property {number} [cross] Fixed coordinate on the other axis where the label column/row sits. Default 0.
+ * @property {number} [gap] Minimum gap kept between adjacent labels. Default 0.
+ * @property {number} [min] Lower bound of the layout axis. Default -Infinity.
+ * @property {number} [max] Upper bound of the layout axis. Default Infinity.
+ * @property {'straight' | 'elbow' | 'curve'} [shape] Leader-line shape. Default 'straight'.
+ *
+ * @typedef {object} DirectLabel
+ * @property {number} x Placed label point — the leader's label-side end.
+ * @property {number} y
+ * @property {AnnotationPoint} anchor The echoed input anchor.
+ * @property {string | number} [key] The echoed input key, if any.
+ * @property {string} d SVG path for the leader (anchor → label point); '' if they coincide.
+ */
+
+import {
+  straightPath,
+  curvePath,
+  connectorPath,
+  elbowPath,
+  arrowHead,
+  dotMark,
+  angleBetween,
+  // Shared scalar/geometry kernel — single source of truth (was copy-pasted,
+  // and the local clamp had silently diverged from the connectors one).
+  PRECISION,
+  finite,
+  dimension,
+  fmt,
+  point,
+  clamp,
+} from '../connectors/index.js';
+
+function roundedNumber(value) {
+  const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function circlePathAt(x, y, radius) {
+  const r = dimension('radius', radius);
+  if (r === 0) return '';
+  return `M${point(x, y - r)}A${fmt(r)},${fmt(r)} 0 1 1 ${point(x, y + r)}A${fmt(r)},${fmt(
+    r,
+  )} 0 1 1 ${point(x, y - r)}Z`;
+}
+
+function samePoint(a, b) {
+  return fmt(a.x) === fmt(b.x) && fmt(a.y) === fmt(b.y);
+}
+
+function validateOffset(opts) {
+  return {
+    dx: finite('dx', opts?.dx),
+    dy: finite('dy', opts?.dy),
+  };
+}
+
+function trimForCircle(dx, dy, subject) {
+  const len = Math.hypot(dx, dy);
+  const radius = dimension('subject.radius', subject.radius);
+  const padding = dimension('subject.radiusPadding', subject.radiusPadding, 0);
+  const trim = radius + padding;
+  if (trim <= 0) return { x: 0, y: 0 };
+  if (trim >= len) return null;
+  return { x: (dx / len) * trim, y: (dy / len) * trim };
+}
+
+function trimForRect(dx, dy, subject) {
+  const width = dimension('subject.width', subject.width);
+  const height = dimension('subject.height', subject.height);
+  const padding = dimension('subject.padding', subject.padding, 0);
+  const x = finite('subject.x', subject.x, -width / 2);
+  const y = finite('subject.y', subject.y, -height / 2);
+  const minX = x - padding;
+  const minY = y - padding;
+  const maxX = x + width + padding;
+  const maxY = y + height + padding;
+  const candidates = [];
+
+  if (dx > 0) candidates.push(maxX / dx);
+  if (dx < 0) candidates.push(minX / dx);
+  if (dy > 0) candidates.push(maxY / dy);
+  if (dy < 0) candidates.push(minY / dy);
+
+  const t = Math.min(...candidates.filter((v) => Number.isFinite(v) && v > 0));
+  if (!Number.isFinite(t) || t <= 0) return { x: 0, y: 0 };
+  if (t >= 1) return null;
+  return { x: dx * t, y: dy * t };
+}
+
+function connectorStart(dx, dy, subject) {
+  if (!subject) return { x: 0, y: 0 };
+  if (subject.type === 'circle') return trimForCircle(dx, dy, subject);
+  if (subject.type === 'rect') return trimForRect(dx, dy, subject);
+  throw new TypeError('subject.type must be "circle" or "rect"');
+}
+
+function linePath(start, end) {
+  if (samePoint(start, end)) return '';
+  return `M${point(start.x, start.y)}L${point(end.x, end.y)}`;
+}
+
+/**
+ * @param {Partial<AnnotationPoint>} [point]
+ * @returns {string}
+ */
+export function annotationTransform({ x = 0, y = 0 } = {}) {
+  return `translate(${fmt(finite('x', x))}, ${fmt(finite('y', y))})`;
+}
+
+/**
+ * @param {NoteTransformOptions} [options]
+ * @returns {string}
+ */
+export function noteTransform({
+  dx,
+  dy,
+  x,
+  y,
+  align = 'start',
+  valign = 'top',
+  width = 0,
+  height = 0,
+} = {}) {
+  let nx = finite('dx', dx, x ?? 0);
+  let ny = finite('dy', dy, y ?? 0);
+  const w = dimension('width', width);
+  const h = dimension('height', height);
+
+  if (align === 'middle') nx -= w / 2;
+  else if (align === 'end') nx -= w;
+  else if (align !== 'start') throw new TypeError('align must be "start", "middle" or "end"');
+
+  if (valign === 'middle') ny -= h / 2;
+  else if (valign === 'bottom') ny -= h;
+  else if (valign !== 'top') throw new TypeError('valign must be "top", "middle" or "bottom"');
+
+  return `translate(${fmt(nx)}, ${fmt(ny)})`;
+}
+
+function candidatePlacement(side, gap) {
+  if (side === 'right') return { dx: gap, dy: 0, align: 'start', valign: 'middle' };
+  if (side === 'left') return { dx: -gap, dy: 0, align: 'end', valign: 'middle' };
+  if (side === 'top') return { dx: 0, dy: -gap, align: 'middle', valign: 'bottom' };
+  if (side === 'bottom') return { dx: 0, dy: gap, align: 'middle', valign: 'top' };
+  throw new TypeError('preferred must be "right", "left", "top" or "bottom"');
+}
+
+function placementOrder(preferred) {
+  if (preferred === 'right') return ['right', 'top', 'bottom', 'left'];
+  if (preferred === 'left') return ['left', 'top', 'bottom', 'right'];
+  if (preferred === 'top') return ['top', 'right', 'left', 'bottom'];
+  if (preferred === 'bottom') return ['bottom', 'right', 'left', 'top'];
+  throw new TypeError('preferred must be "right", "left", "top" or "bottom"');
+}
+
+function noteRect(x, y, width, height, placement) {
+  const anchorX = x + placement.dx;
+  const anchorY = y + placement.dy;
+  let left = anchorX;
+  let top = anchorY;
+
+  if (placement.align === 'middle') left -= width / 2;
+  else if (placement.align === 'end') left -= width;
+
+  if (placement.valign === 'middle') top -= height / 2;
+  else if (placement.valign === 'bottom') top -= height;
+
+  return {
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+  };
+}
+
+/**
+ * @param {NotePlacementOptions} options
+ * @returns {NotePlacement}
+ */
+export function notePlacement({
+  x = 0,
+  y = 0,
+  width,
+  height,
+  bounds,
+  padding = 8,
+  gap = 32,
+  preferred = 'right',
+  inset = 0,
+} = {}) {
+  const anchorX = finite('x', x);
+  const anchorY = finite('y', y);
+  const w = dimension('width', width);
+  const h = dimension('height', height);
+  const p = dimension('padding', padding);
+  const g = dimension('gap', gap);
+  const ins = dimension('inset', inset, 0);
+  const bx = finite('bounds.x', bounds?.x, 0);
+  const by = finite('bounds.y', bounds?.y, 0);
+  const bw = dimension('bounds.width', bounds?.width);
+  const bh = dimension('bounds.height', bounds?.height);
+  // `inset` reserves an extra margin (e.g. the title stroke-halo) inside the
+  // padded bounds, so a placement that "just fits" doesn't clip the halo/leader.
+  const minX = bx + p + ins;
+  const minY = by + p + ins;
+  const maxX = bx + bw - p - ins;
+  const maxY = by + bh - p - ins;
+
+  for (const side of placementOrder(preferred)) {
+    const placement = candidatePlacement(side, g);
+    const rect = noteRect(anchorX, anchorY, w, h, placement);
+    if (rect.left >= minX && rect.top >= minY && rect.right <= maxX && rect.bottom <= maxY) {
+      return {
+        dx: roundedNumber(placement.dx),
+        dy: roundedNumber(placement.dy),
+        align: placement.align,
+        valign: placement.valign,
+        transform: noteTransform({ ...placement, width: w, height: h }),
+      };
+    }
+  }
+
+  const fallback = candidatePlacement(preferred, g);
+  const rect = noteRect(anchorX, anchorY, w, h, fallback);
+  const left = clamp(rect.left, minX, maxX - w);
+  const top = clamp(rect.top, minY, maxY - h);
+  const dx = roundedNumber(left - anchorX);
+  const dy = roundedNumber(top - anchorY);
+  return {
+    dx,
+    dy,
+    align: 'start',
+    valign: 'top',
+    transform: noteTransform({ dx, dy }),
+  };
+}
+
+/**
+ * @param {CircleSubjectOptions} options
+ * @returns {string}
+ */
+export function circleSubjectPath({ radius } = {}) {
+  return circlePathAt(0, 0, radius);
+}
+
+/**
+ * @param {RectSubjectOptions} options
+ * @returns {string}
+ */
+export function rectSubjectPath({ width, height, x, y, padding = 0 } = {}) {
+  const w = dimension('width', width);
+  const h = dimension('height', height);
+  const p = dimension('padding', padding);
+  if (w === 0 || h === 0) return '';
+  const left = finite('x', x, -w / 2) - p;
+  const top = finite('y', y, -h / 2) - p;
+  const right = left + w + p * 2;
+  const bottom = top + h + p * 2;
+  return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
+}
+
+/**
+ * @param {ThresholdOptions} options
+ * @returns {string}
+ */
+export function thresholdPath({ x1 = 0, y1 = 0, x2, y2 } = {}) {
+  const start = { x: finite('x1', x1), y: finite('y1', y1) };
+  const end = { x: finite('x2', x2), y: finite('y2', y2) };
+  return linePath(start, end);
+}
+
+/**
+ * @param {AxisThresholdOptions} options
+ * @returns {string}
+ */
+export function axisThresholdPath({ orientation = 'horizontal', value = 0, start = 0, end } = {}) {
+  const v = finite('value', value);
+  const s = finite('start', start);
+  const e = finite('end', end);
+  if (orientation === 'horizontal') return thresholdPath({ x1: s, y1: v, x2: e, y2: v });
+  if (orientation === 'vertical') return thresholdPath({ x1: v, y1: s, x2: v, y2: e });
+  throw new TypeError('orientation must be "horizontal" or "vertical"');
+}
+
+/**
+ * @param {BracketSubjectOptions} options
+ * @returns {string}
+ */
+export function bracketSubjectPath({ x1, y1, x2, y2, depth = 12 } = {}) {
+  const start = { x: finite('x1', x1), y: finite('y1', y1) };
+  const end = { x: finite('x2', x2), y: finite('y2', y2) };
+  const d = finite('depth', depth);
+  if (samePoint(start, end) || d === 0) return linePath(start, end);
+  if (Math.abs(end.x - start.x) >= Math.abs(end.y - start.y)) {
+    return `M${point(start.x, start.y)}V${fmt(start.y + d)}H${fmt(end.x)}V${fmt(end.y)}`;
+  }
+  return `M${point(start.x, start.y)}H${fmt(start.x + d)}V${fmt(end.y)}H${fmt(end.x)}`;
+}
+
+/**
+ * @param {BandSubjectOptions} options
+ * @returns {string}
+ */
+export function bandSubjectPath({ x = 0, y = 0, width, height, padding = 0 } = {}) {
+  return rectSubjectPath({ x, y, width, height, padding });
+}
+
+/**
+ * @param {SlopeSubjectOptions} options
+ * @returns {string}
+ */
+export function slopeSubjectPath({ x1, y1, x2, y2 } = {}) {
+  return thresholdPath({ x1, y1, x2, y2 });
+}
+
+/**
+ * @param {ComparisonBraceOptions} options
+ * @returns {string}
+ */
+export function comparisonBracePath({ x1, y1, x2, y2, depth = 14 } = {}) {
+  const start = { x: finite('x1', x1), y: finite('y1', y1) };
+  const end = { x: finite('x2', x2), y: finite('y2', y2) };
+  const d = finite('depth', depth);
+  if (samePoint(start, end) || d === 0) return linePath(start, end);
+
+  if (Math.abs(end.x - start.x) >= Math.abs(end.y - start.y)) {
+    const y = start.y;
+    const mid = (start.x + end.x) / 2;
+    const q = (end.x - start.x) / 4;
+    return `M${point(start.x, y)}C${point(start.x + q, y)} ${point(start.x + q, y + d)} ${point(
+      mid,
+      y + d,
+    )}C${point(mid, y + d)} ${point(mid, y + d * 2)} ${point(mid, y + d * 2)}C${point(
+      mid,
+      y + d,
+    )} ${point(end.x - q, y + d)} ${point(end.x - q, y)}C${point(end.x - q, y)} ${point(
+      end.x - q,
+      y,
+    )} ${point(end.x, y)}`;
+  }
+
+  const x = start.x;
+  const mid = (start.y + end.y) / 2;
+  const q = (end.y - start.y) / 4;
+  return `M${point(x, start.y)}C${point(x, start.y + q)} ${point(x + d, start.y + q)} ${point(
+    x + d,
+    mid,
+  )}C${point(x + d, mid)} ${point(x + d * 2, mid)} ${point(x + d * 2, mid)}C${point(
+    x + d,
+    mid,
+  )} ${point(x + d, end.y - q)} ${point(x, end.y - q)}C${point(x, end.y - q)} ${point(
+    x,
+    end.y - q,
+  )} ${point(x, end.y)}`;
+}
+
+/**
+ * @param {OutlierClusterOptions} options
+ * @returns {string}
+ */
+export function outlierClusterPath({ points, radius = 6 } = {}) {
+  if (!Array.isArray(points)) throw new TypeError('points must be an array');
+  return points
+    .map((p, i) =>
+      circlePathAt(finite(`points[${i}].x`, p?.x), finite(`points[${i}].y`, p?.y), radius),
+    )
+    .filter(Boolean)
+    .join('');
+}
+
+/**
+ * @param {TimelineEventOptions} [options]
+ * @returns {string}
+ */
+export function timelineEventPath({ size = 10, direction = 'down' } = {}) {
+  const s = dimension('size', size);
+  if (s === 0) return '';
+  if (direction === 'down') return `M0,0L${point(s / 2, s)}H${fmt(-s / 2)}Z`;
+  if (direction === 'up') return `M0,0L${point(s / 2, -s)}H${fmt(-s / 2)}Z`;
+  if (direction === 'right') return `M0,0L${point(s, s / 2)}V${fmt(-s / 2)}Z`;
+  if (direction === 'left') return `M0,0L${point(-s, s / 2)}V${fmt(-s / 2)}Z`;
+  throw new TypeError('direction must be "up", "down", "left" or "right"');
+}
+
+/**
+ * @param {EvidenceMarkerOptions} [options]
+ * @returns {string}
+ */
+export function evidenceMarkerPath({ x = 0, y = 0, width = 36, height = 36, padding = 0 } = {}) {
+  const w = dimension('width', width);
+  const h = dimension('height', height);
+  const p = dimension('padding', padding);
+  if (w === 0 || h === 0) return '';
+  const cx = finite('x', x);
+  const cy = finite('y', y);
+  const left = cx - w / 2 - p;
+  const top = cy - h / 2 - p;
+  const right = left + w + p * 2;
+  const bottom = top + h + p * 2;
+  return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
+}
+
+/**
+ * @param {ConnectorEndDotOptions} options
+ * @returns {string}
+ */
+export function connectorEndDot({ x, y, radius = 3 } = {}) {
+  return dotMark({ x: finite('x', x), y: finite('y', y) }, radius);
+}
+
+/**
+ * @param {ConnectorEndArrowOptions} options
+ * @returns {string}
+ */
+export function connectorEndArrow({ x1 = 0, y1 = 0, x2, y2, size = 8, spread = 0.32 } = {}) {
+  const start = { x: finite('x1', x1), y: finite('y1', y1) };
+  const end = { x: finite('x2', x2), y: finite('y2', y2) };
+  const s = dimension('size', size);
+  if (s === 0 || (end.x === start.x && end.y === start.y)) return '';
+  return arrowHead(end, angleBetween(start, end), s, spread);
+}
+
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorLine(opts = {}) {
+  const { dx, dy } = validateOffset(opts);
+  if (dx === 0 && dy === 0) return '';
+  const start = connectorStart(dx, dy, opts.subject);
+  if (!start) return '';
+  const end = { x: dx, y: dy };
+  // Guard a trim that rounds onto the note anchor (straightPath has no guard).
+  if (samePoint(start, end)) return '';
+  return straightPath(start, end);
+}
+
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorElbow(opts = {}) {
+  const { dx, dy } = validateOffset(opts);
+  if (dx === 0 && dy === 0) return '';
+  const start = connectorStart(dx, dy, opts.subject);
+  if (!start) return '';
+  const end = { x: dx, y: dy };
+  if (samePoint(start, end)) return '';
+  // A true right-angle dogleg (H/V/H), turning on the dominant axis at `mid`
+  // (0..1, default 0.5). Delegated to the connectors geometry kernel so an
+  // annotation leader and a node connector draw the same elbow. (The former
+  // inline form turned by min(|dx|,|dy|), i.e. a 45° chamfer that read as a
+  // diagonal stub, not an elbow — which the `stroke-linejoin` bevel assumes.)
+  return elbowPath(start, end, { mid: opts.mid });
+}
+
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
+export function connectorCurve(opts = {}) {
+  const { dx, dy } = validateOffset(opts);
+  if (dx === 0 && dy === 0) return '';
+  const start = connectorStart(dx, dy, opts.subject);
+  if (!start) return '';
+  const end = { x: dx, y: dy };
+  if (samePoint(start, end)) return '';
+  // Annotation callouts use a gentler curve than the connectors default.
+  return curvePath(start, end, { curvature: 0.35 });
+}
+
+/**
+ * @param {AnnotationPartsOptions} [opts]
+ * @returns {AnnotationParts}
+ */
+export function annotationParts(opts = {}) {
+  const type = opts.type ?? 'callout';
+  const transform = annotationTransform({ x: opts.x ?? 0, y: opts.y ?? 0 });
+  const dx = finite('dx', opts.dx, 0);
+  const dy = finite('dy', opts.dy, 0);
+  const connectorSubject =
+    opts.subject?.type === 'circle' || opts.subject?.type === 'rect' ? opts.subject : undefined;
+  const connector =
+    type === 'curve'
+      ? connectorCurve({ dx, dy, subject: connectorSubject })
+      : type === 'elbow'
+        ? connectorElbow({ dx, dy, subject: connectorSubject })
+        : connectorLine({ dx, dy, subject: connectorSubject });
+  const note = noteTransform({ dx, dy });
+  let subject = '';
+
+  if (opts.subject?.type === 'circle') subject = circleSubjectPath(opts.subject);
+  else if (opts.subject?.type === 'rect') subject = rectSubjectPath(opts.subject);
+  else if (opts.subject?.type === 'threshold') subject = thresholdPath(opts.subject);
+  else if (opts.subject?.type === 'bracket') subject = bracketSubjectPath(opts.subject);
+  else if (opts.subject?.type === 'band') subject = bandSubjectPath(opts.subject);
+  else if (opts.subject?.type === 'slope') subject = slopeSubjectPath(opts.subject);
+  else if (opts.subject?.type === 'compare') subject = comparisonBracePath(opts.subject);
+  else if (opts.subject?.type === 'cluster') subject = outlierClusterPath(opts.subject);
+  else if (opts.subject?.type === 'axis') subject = axisThresholdPath(opts.subject);
+  else if (opts.subject?.type === 'timeline') subject = timelineEventPath(opts.subject);
+  else if (opts.subject?.type === 'evidence') subject = evidenceMarkerPath(opts.subject);
+  else if (opts.subject != null) throw new TypeError('unsupported subject.type');
+
+  return { transform, subject, connector, note };
+}
+
+/**
+ * Declutter labels along ONE axis: nudge overlapping labels apart so each keeps
+ * `gap` from its neighbours, sweeping up from `min`; if the run overflows `max`
+ * it slides up to fit. Deterministic and order-preserving — NOT a general 2-D
+ * collision solver (with more labels than the range holds, the overflow past
+ * `min` is the caller's to resolve: fewer labels, a longer axis, or rotation).
+ *
+ * `items`: `[{ pos, size }]` — `pos` is the desired centre coordinate along the
+ * axis, `size` the label's extent along it. Returns the adjusted centre per
+ * input item, in the original order.
+ *
+ * @param {DeclutterLabelItem[]} items
+ * @param {DeclutterLabelsOptions} [opts]
+ * @returns {number[]}
+ */
+export function declutterLabels(items, opts = {}) {
+  if (!Array.isArray(items)) throw new TypeError('items must be an array');
+  const gap = dimension('gap', opts.gap, 0);
+  const min = opts.min == null ? -Infinity : finite('min', opts.min);
+  const max = opts.max == null ? Infinity : finite('max', opts.max);
+  if (max < min) throw new RangeError('max must be greater than or equal to min');
+
+  const nodes = items.map((it, index) => ({
+    index,
+    half: dimension('size', it?.size) / 2,
+    pos: finite('pos', it?.pos),
+  }));
+  const order = [...nodes].sort((a, b) => a.pos - b.pos);
+
+  let floor = min;
+  for (const n of order) {
+    const center = Math.max(n.pos, floor + n.half);
+    n.pos = center;
+    floor = center + n.half + gap;
+  }
+  if (max !== Infinity && order.length) {
+    const last = order[order.length - 1];
+    const overflow = last.pos + last.half - max;
+    if (overflow > 0) for (const n of order) n.pos -= overflow;
+  }
+
+  const out = new Array(nodes.length);
+  for (const n of nodes) out[n.index] = roundedNumber(n.pos);
+  return out;
+}
+
+/**
+ * Direct labeling: declutter labels along one axis and draw a leader line from
+ * each true anchor to its placed label. This is the 1-D core of Labella,
+ * completed with leaders via the shared connector kernel — deterministic and
+ * pure. It owns no scales (map data → figure coords first), no DOM, no
+ * nearest-anchor matching, and no 2-D placement; those stay the host's job.
+ *
+ * Each `items[i]` is `{ anchor: {x, y}, size, key? }`: `anchor` is the true
+ * data point in figure coordinates, `size` is the label's extent along the
+ * layout `axis`. Labels declutter along `axis` ('y' = a vertical column,
+ * default) and sit at the fixed `cross` coordinate on the other axis. Returns,
+ * in input order, the placed label point `{x, y}`, the echoed `anchor` and
+ * `key`, and the leader path `d` (anchor → label; `''` if they coincide) ready
+ * for a `<path class="ui-annotation__connector">`.
+ *
+ * @param {DirectLabelItem[]} items
+ * @param {DirectLabelsOptions} [opts]
+ * @returns {DirectLabel[]}
+ */
+export function directLabels(items, opts = {}) {
+  if (!Array.isArray(items)) throw new TypeError('items must be an array');
+  const axis = opts.axis === 'x' ? 'x' : 'y';
+  const cross = finite('cross', opts.cross, 0);
+  const shape = opts.shape === 'elbow' || opts.shape === 'curve' ? opts.shape : 'straight';
+
+  const anchors = items.map((it) => ({
+    anchor: { x: finite('anchor.x', it?.anchor?.x), y: finite('anchor.y', it?.anchor?.y) },
+    size: dimension('size', it?.size),
+    key: it?.key,
+  }));
+
+  const placed = declutterLabels(
+    anchors.map((a) => ({ pos: a.anchor[axis], size: a.size })),
+    { gap: opts.gap, min: opts.min, max: opts.max },
+  );
+
+  return anchors.map((a, i) => {
+    const labelPoint = axis === 'y' ? { x: cross, y: placed[i] } : { x: placed[i], y: cross };
+    const d = samePoint(a.anchor, labelPoint)
+      ? ''
+      : connectorPath({ from: a.anchor, to: labelPoint, shape });
+    return {
+      x: roundedNumber(labelPoint.x),
+      y: roundedNumber(labelPoint.y),
+      anchor: { x: roundedNumber(a.anchor.x), y: roundedNumber(a.anchor.y) },
+      key: a.key,
+      d,
+    };
+  });
+}