@ponchia/ui 0.5.0 → 0.6.3

package/annotations/index.js

@@ -1,53 +1,229 @@
 // 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).
+  roundNumber,
+  finite,
+  dimension,
+  fmt,
+  point,
+  clamp,
+  rectPath,
 } from '../connectors/index.js';
 
-const PRECISION = 1000;
-
-function finite(name, value, fallback) {
-  const v = value ?? fallback;
-  if (!Number.isFinite(v)) throw new TypeError(`${name} must be a finite number`);
-  return v;
-}
-
-function dimension(name, value, fallback) {
-  const v = finite(name, value, fallback);
-  if (v < 0) throw new RangeError(`${name} must be greater than or equal to 0`);
-  return v;
-}
-
-function fmt(value) {
-  const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
-  return String(Object.is(rounded, -0) ? 0 : rounded);
-}
-
-function roundedNumber(value) {
-  const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
-  return Object.is(rounded, -0) ? 0 : rounded;
-}
-
-function point(x, y) {
-  return `${fmt(x)},${fmt(y)}`;
-}
-
-function clamp(value, min, max) {
-  if (max < min) return min;
-  return Math.min(max, Math.max(min, value));
-}
-
+// A circle subject is just a filled dot at (x, y) — delegate to the kernel's
+// dotMark so the arc geometry/precision can't diverge. (code-quality audit Q5.)
 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`;
+  return dotMark({ x, y }, radius);
 }
 
 function samePoint(a, b) {
@@ -106,10 +282,18 @@ function linePath(start, end) {
   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,
@@ -172,6 +356,10 @@ function noteRect(x, y, width, height, placement) {
   };
 }
 
+/**
+ * @param {NotePlacementOptions} options
+ * @returns {NotePlacement}
+ */
 export function notePlacement({
   x = 0,
   y = 0,
@@ -181,6 +369,7 @@ export function notePlacement({
   padding = 8,
   gap = 32,
   preferred = 'right',
+  inset = 0,
 } = {}) {
   const anchorX = finite('x', x);
   const anchorY = finite('y', y);
@@ -188,22 +377,25 @@ export function notePlacement({
   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);
-  const minX = bx + p;
-  const minY = by + p;
-  const maxX = bx + bw - p;
-  const maxY = by + bh - p;
+  // `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),
+        dx: roundNumber(placement.dx),
+        dy: roundNumber(placement.dy),
         align: placement.align,
         valign: placement.valign,
         transform: noteTransform({ ...placement, width: w, height: h }),
@@ -215,8 +407,8 @@ export function notePlacement({
   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);
+  const dx = roundNumber(left - anchorX);
+  const dy = roundNumber(top - anchorY);
   return {
     dx,
     dy,
@@ -226,10 +418,18 @@ export function notePlacement({
   };
 }
 
+/**
+ * @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);
@@ -239,15 +439,23 @@ export function rectSubjectPath({ width, height, x, y, padding = 0 } = {}) {
   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`;
+  return rectPath(left, top, right, bottom);
 }
 
+/**
+ * @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);
@@ -257,6 +465,10 @@ export function axisThresholdPath({ orientation = 'horizontal', value = 0, start
   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) };
@@ -268,14 +480,26 @@ export function bracketSubjectPath({ x1, y1, x2, y2, depth = 12 } = {}) {
   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) };
@@ -313,6 +537,10 @@ export function comparisonBracePath({ x1, y1, x2, y2, depth = 14 } = {}) {
   )} ${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
@@ -323,6 +551,10 @@ export function outlierClusterPath({ points, radius = 6 } = {}) {
     .join('');
 }
 
+/**
+ * @param {TimelineEventOptions} [options]
+ * @returns {string}
+ */
 export function timelineEventPath({ size = 10, direction = 'down' } = {}) {
   const s = dimension('size', size);
   if (s === 0) return '';
@@ -333,6 +565,10 @@ export function timelineEventPath({ size = 10, direction = 'down' } = {}) {
   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);
@@ -344,21 +580,33 @@ export function evidenceMarkerPath({ x = 0, y = 0, width = 36, height = 36, padd
   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`;
+  return rectPath(left, top, right, bottom);
 }
 
+/**
+ * @param {ConnectorEndDotOptions} options
+ * @returns {string}
+ */
 export function connectorEndDot({ x, y, radius = 3 } = {}) {
   return dotMark({ x: finite('x', x), y: finite('y', y) }, radius);
 }
 
-export function connectorEndArrow({ x1 = 0, y1 = 0, x2, y2, size = 7 } = {}) {
+/**
+ * @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);
+  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 '';
@@ -370,25 +618,29 @@ export function connectorLine(opts = {}) {
   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 };
-  const vx = end.x - start.x;
-  const vy = end.y - start.y;
-  if (vx === 0 || vy === 0) return linePath(start, end);
-
-  const elbow =
-    Math.abs(vx) >= Math.abs(vy)
-      ? { x: start.x + Math.sign(vx) * Math.abs(vy), y: end.y }
-      : { x: end.x, y: start.y + Math.sign(vy) * Math.abs(vx) };
-
-  if (samePoint(start, elbow) || samePoint(elbow, end)) return linePath(start, end);
-  return `M${point(start.x, start.y)}L${point(elbow.x, elbow.y)}L${point(end.x, end.y)}`;
+  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 '';
@@ -400,6 +652,26 @@ export function connectorCurve(opts = {}) {
   return curvePath(start, end, { curvature: 0.35 });
 }
 
+// subject.type → its path builder. A flat dispatch table (replaces an 11-arm
+// if/else) keyed by the SubjectType union; an unknown type throws below. (Q10.)
+const SUBJECT_BUILDERS = {
+  circle: circleSubjectPath,
+  rect: rectSubjectPath,
+  threshold: thresholdPath,
+  bracket: bracketSubjectPath,
+  band: bandSubjectPath,
+  slope: slopeSubjectPath,
+  compare: comparisonBracePath,
+  cluster: outlierClusterPath,
+  axis: axisThresholdPath,
+  timeline: timelineEventPath,
+  evidence: evidenceMarkerPath,
+};
+
+/**
+ * @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 });
@@ -416,18 +688,11 @@ export function annotationParts(opts = {}) {
   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');
+  if (opts.subject != null) {
+    const build = SUBJECT_BUILDERS[opts.subject.type];
+    if (!build) throw new TypeError('unsupported subject.type');
+    subject = build(opts.subject);
+  }
 
   return { transform, subject, connector, note };
 }
@@ -442,6 +707,10 @@ export function annotationParts(opts = {}) {
  * `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');
@@ -470,7 +739,7 @@ export function declutterLabels(items, opts = {}) {
   }
 
   const out = new Array(nodes.length);
-  for (const n of nodes) out[n.index] = roundedNumber(n.pos);
+  for (const n of nodes) out[n.index] = roundNumber(n.pos);
   return out;
 }
 
@@ -488,6 +757,10 @@ export function declutterLabels(items, opts = {}) {
  * 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');
@@ -512,9 +785,9 @@ export function directLabels(items, opts = {}) {
       ? ''
       : 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) },
+      x: roundNumber(labelPoint.x),
+      y: roundNumber(labelPoint.y),
+      anchor: { x: roundNumber(a.anchor.x), y: roundNumber(a.anchor.y) },
       key: a.key,
       d,
     };

package/behaviors/carousel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
+ * swipe (and momentum) are the browser's, not hand-rolled. This wires the
+ * parts scroll-snap can't do alone: prev/next buttons, keyboard nav, a
+ * thumbnail strip, the position counter, and ARIA — keeping a JS index in
+ * sync with the scroll position both ways.
+ *
+ * Markup: `[data-bronto-carousel]` containing a `.ui-carousel__viewport`
+ * of `.ui-carousel__slide` children; optionally
+ * `[data-bronto-carousel-prev]` / `[data-bronto-carousel-next]` controls,
+ * a `.ui-carousel__thumbs` list of `.ui-carousel__thumb` buttons, and a
+ * `.ui-carousel__status` counter slot. Add `data-bronto-carousel-loop` to
+ * wrap at the ends, `data-bronto-carousel-label` to name the region.
+ *
+ * A full-screen **lightbox** is the same markup inside a native
+ * `<dialog class="ui-lightbox">` opened by {@link initDialog}: the
+ * `<dialog>` provides the top layer, focus-trap, Escape and focus-return,
+ * so this behavior never touches focus management.
+ *
+ * Emits `bronto:change` ({ detail: { index } }) on every index change
+ * (button, key, thumbnail, or swipe). SSR-safe, idempotent per carousel;
+ * returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initCarousel({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=carousel.d.ts.map

package/behaviors/carousel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["carousel.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAuK3C"}