@ponchia/ui 0.5.0 → 0.6.3

package/connectors/index.d.ts

@@ -1,71 +1,203 @@
+export function finite(name: any, value: any, fallback: any): any;
+export function dimension(name: any, value: any, fallback: any): any;
+export function roundNumber(value: any): number;
+export function fmt(value: any): string;
+export function point(x: any, y: any): string;
+export function clamp(value: any, min: any, max: any): any;
 /**
- * @ponchia/ui/connectors — dependency-free SVG geometry for leader lines.
- * Pure functions: points/rects in, SVG path strings (or coordinates) out.
+ * A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`.
+ * @param {Rect} rect
+ * @param {Side} [side]
+ * @returns {Point}
  */
-
-export interface Point {
-  x: number;
-  y: number;
-}
-
-export interface Rect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-
-export type Side = 'top' | 'right' | 'bottom' | 'left' | 'center';
-export type ConnectorShape = 'straight' | 'elbow' | 'curve';
-
-export interface ConnectorPathOptions {
-  from: Point;
-  to: Point;
-  shape?: ConnectorShape;
-  /** Curve control-point reach along the dominant axis (curve shape). Default 0.5. */
-  curvature?: number;
-  /** Turn position 0..1 along the span (elbow shape). Default 0.5. */
-  mid?: number;
-}
-
-export interface ConnectRectsOptions {
-  fromRect: Rect;
-  toRect: Rect;
-  /** Anchor edges. Omit both to auto-pick facing edges from the rects. */
-  fromSide?: Side;
-  toSide?: Side;
-  shape?: ConnectorShape;
-  curvature?: number;
-  mid?: number;
-}
-
-export interface ConnectRectsResult {
-  /** SVG path data. */
-  d: string;
-  from: Point;
-  to: Point;
-  /**
-   * The path's **end-tangent** at `to` in radians (`endTangentAngle(from, to,
-   * shape)`) — the direction the path arrives, so rotating an arrowhead at `to`
-   * by this points it along the path. Equals the straight `from`→`to` angle for
-   * `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
-   */
-  angle: number;
-}
-
-export declare function anchorPoint(rect: Rect, side?: Side): Point;
-export declare function angleBetween(from: Point, to: Point): number;
-export declare function straightPath(from: Point, to: Point): string;
-export declare function elbowPath(from: Point, to: Point, opts?: { mid?: number }): string;
-export declare function curvePath(from: Point, to: Point, opts?: { curvature?: number }): string;
-export declare function connectorPath(opts: ConnectorPathOptions): string;
-export declare function arrowHead(p: Point, angle: number, size?: number): string;
-export declare function dotMark(p: Point, radius?: number): string;
-export declare function autoSides(
-  fromRect: Rect,
-  toRect: Rect,
-): { from: Side; to: Side };
-/** Angle (radians) at which a `shape` path arrives at `to` — the chord for
- *  `straight`, axis-aligned for `elbow`/`curve`. Use it to rotate an end marker. */
-export declare function endTangentAngle(from: Point, to: Point, shape?: ConnectorShape): number;
-export declare function connectRects(opts: ConnectRectsOptions): ConnectRectsResult;
+export function anchorPoint(rect: Rect, side?: Side): Point;
+/**
+ * Angle (radians) from `from` to `to`.
+ * @param {Point} from
+ * @param {Point} to
+ * @returns {number}
+ */
+export function angleBetween(from: Point, to: Point): number;
+/**
+ * Straight line from `from` to `to`.
+ * @param {Point} from
+ * @param {Point} to
+ * @returns {string}
+ */
+export function straightPath(from: Point, to: Point): string;
+/**
+ * Right-angle dogleg. Turns on the dominant axis at `mid` (0..1) of the span.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {{ mid?: number }} [opts]
+ * @returns {string}
+ */
+export function elbowPath(from: Point, to: Point, opts?: {
+    mid?: number;
+}): string;
+/**
+ * Cubic curve; control points extend along the dominant axis by `curvature`.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {{ curvature?: number }} [opts]
+ * @returns {string}
+ */
+export function curvePath(from: Point, to: Point, opts?: {
+    curvature?: number;
+}): string;
+/**
+ * Build a path between two points by `shape` (`straight` | `elbow` | `curve`).
+ * @param {ConnectorPathOptions} [opts]
+ * @returns {string}
+ */
+export function connectorPath(opts?: ConnectorPathOptions): string;
+/**
+ * A filled triangle arrowhead at `p`, pointing along `angle` (radians).
+ * @param {Point} p
+ * @param {number} angle
+ * @param {number} [size]
+ * @param {number} [spread] Half-angle of the head in radians (default 0.45).
+ *   Smaller is crisper/sharper; must be in (0, π/2).
+ * @returns {string}
+ */
+export function arrowHead(p: Point, angle: number, size?: number, spread?: number): string;
+/**
+ * A filled dot at `p`.
+ * @param {Point} p
+ * @param {number} [radius]
+ * @returns {string}
+ */
+export function dotMark(p: Point, radius?: number): string;
+/**
+ * An axis-aligned rectangle path from its corners (callers derive the corners
+ * from a centre or a top-left as they need). Shared by the annotation
+ * rect/band and evidence-marker subjects. (code-quality audit Q5.)
+ * @param {number} left
+ * @param {number} top
+ * @param {number} right
+ * @param {number} bottom
+ * @returns {string}
+ */
+export function rectPath(left: number, top: number, right: number, bottom: number): string;
+/**
+ * Pick facing edges from the rects' relative centres.
+ * @param {Rect} fromRect
+ * @param {Rect} toRect
+ * @returns {{ from: Side, to: Side }}
+ */
+export function autoSides(fromRect: Rect, toRect: Rect): {
+    from: Side;
+    to: Side;
+};
+/**
+ * Angle (radians) at which a `shape` path *arrives* at `to` — straight is the
+ * chord; elbow/curve arrive axis-aligned along the dominant axis. Rotate an
+ * end marker by this so it points along the path, not the chord.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {ConnectorShape} [shape]
+ * @returns {number}
+ */
+export function endTangentAngle(from: Point, to: Point, shape?: ConnectorShape): number;
+/**
+ * Connect two rects. Resolves anchor points (explicit `fromSide`/`toSide`, else
+ * auto), builds the path, and returns `{ d, from, to, angle }` so the caller can
+ * place an arrowhead/dot at `to` rotated by `angle`.
+ * @param {ConnectRectsOptions} [opts]
+ * @returns {ConnectRectsResult}
+ */
+export function connectRects(opts?: ConnectRectsOptions): ConnectRectsResult;
+/**
+ * @ponchia/ui/connectors — dependency-free SVG geometry for connecting two
+ * elements (or two points) with a leader line.
+ *
+ * Pure functions only: they take points/rects and return SVG path strings (or
+ * resolved coordinates). They own no DOM, no scales, and no live tracking —
+ * that optional glue lives in `@ponchia/ui/behaviors` (`initConnectors`). This
+ * is the page-coordinate, element-to-element cousin of the figure-coordinate
+ * `@ponchia/ui/annotations` helpers.
+ *
+ *   import { connectRects } from '@ponchia/ui/connectors';
+ *   const { d } = connectRects({ fromRect: a, toRect: b, shape: 'elbow' });
+ *
+ * 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 }} Point
+ * @typedef {{ x: number, y: number, width: number, height: number }} Rect
+ * @typedef {'top' | 'right' | 'bottom' | 'left' | 'center'} Side
+ * @typedef {'straight' | 'elbow' | 'curve'} ConnectorShape
+ *
+ * @typedef {object} ConnectorPathOptions
+ * @property {Point} from
+ * @property {Point} to
+ * @property {ConnectorShape} [shape]
+ * @property {number} [curvature] Curve control-point reach along the dominant axis (curve shape). Default 0.5.
+ * @property {number} [mid] Turn position 0..1 along the span (elbow shape). Default 0.5.
+ *
+ * @typedef {object} ConnectRectsOptions
+ * @property {Rect} fromRect
+ * @property {Rect} toRect
+ * @property {Side} [fromSide] Anchor edges. Omit both to auto-pick facing edges from the rects.
+ * @property {Side} [toSide]
+ * @property {ConnectorShape} [shape]
+ * @property {number} [curvature]
+ * @property {number} [mid]
+ *
+ * @typedef {object} ConnectRectsResult
+ * @property {string} d SVG path data.
+ * @property {Point} from
+ * @property {Point} to
+ * @property {number} angle The path's end-tangent at `to` in radians — the direction the path arrives, so rotating an arrowhead at `to` by this points it along the path. Equals the straight `from`→`to` angle for `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
+ */
+export const PRECISION: 1000;
+export type Point = {
+    x: number;
+    y: number;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type Side = "top" | "right" | "bottom" | "left" | "center";
+export type ConnectorShape = "straight" | "elbow" | "curve";
+export type ConnectorPathOptions = {
+    from: Point;
+    to: Point;
+    shape?: ConnectorShape | undefined;
+    /**
+     * Curve control-point reach along the dominant axis (curve shape). Default 0.5.
+     */
+    curvature?: number | undefined;
+    /**
+     * Turn position 0..1 along the span (elbow shape). Default 0.5.
+     */
+    mid?: number | undefined;
+};
+export type ConnectRectsOptions = {
+    fromRect: Rect;
+    toRect: Rect;
+    /**
+     * Anchor edges. Omit both to auto-pick facing edges from the rects.
+     */
+    fromSide?: Side | undefined;
+    toSide?: Side | undefined;
+    shape?: ConnectorShape | undefined;
+    curvature?: number | undefined;
+    mid?: number | undefined;
+};
+export type ConnectRectsResult = {
+    /**
+     * SVG path data.
+     */
+    d: string;
+    from: Point;
+    to: Point;
+    /**
+     * The path's end-tangent at `to` in radians — the direction the path arrives, so rotating an arrowhead at `to` by this points it along the path. Equals the straight `from`→`to` angle for `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
+     */
+    angle: number;
+};
+//# sourceMappingURL=index.d.ts.map

package/connectors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":"AAkDA,kEAIC;AAED,qEAIC;AAKD,gDAGC;AAED,wCAEC;AAED,8CAEC;AAID,2DAGC;AAED;;;;;GAKG;AACH,kCAJW,IAAI,SACJ,IAAI,GACF,KAAK,CAoBjB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;GAKG;AACH,mCAJW,KAAK,MACL,KAAK,GACH,MAAM,CAOlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACd,MAAM,CAgBlB;AAED;;;;;;GAMG;AACH,gCALW,KAAK,MACL,KAAK,SACL;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpB,MAAM,CAclB;AAED;;;;GAIG;AACH,qCAHW,oBAAoB,GAClB,MAAM,CAOlB;AAED;;;;;;;;GAQG;AACH,6BAPW,KAAK,SACL,MAAM,SACN,MAAM,WACN,MAAM,GAEJ,MAAM,CAalB;AAED;;;;;GAKG;AACH,2BAJW,KAAK,WACL,MAAM,GACJ,MAAM,CAUlB;AAED;;;;;;;;;GASG;AACH,+BANW,MAAM,OACN,MAAM,SACN,MAAM,UACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;GAKG;AACH,oCAJW,IAAI,UACJ,IAAI,GACF;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,CAWpC;AAED;;;;;;;;GAQG;AACH,sCALW,KAAK,MACL,KAAK,UACL,cAAc,GACZ,MAAM,CAQlB;AAED;;;;;;GAMG;AACH,oCAHW,mBAAmB,GACjB,kBAAkB,CAW9B;AAvSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAMH,wBAAyB,IAAI,CAAC;oBAhCjB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE;mBACxB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE;mBACvD,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ;6BAC9C,UAAU,GAAG,OAAO,GAAG,OAAO;;UAG7B,KAAK;QACL,KAAK;;;;;;;;;;;;cAML,IAAI;YACJ,IAAI;;;;;;;;;;;;;;OAQJ,MAAM;UACN,KAAK;QACL,KAAK;;;;WACL,MAAM"}

package/connectors/index.js

@@ -10,36 +10,85 @@
  *
  *   import { connectRects } from '@ponchia/ui/connectors';
  *   const { d } = connectRects({ fromRect: a, toRect: b, shape: 'elbow' });
+ *
+ * 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 }} Point
+ * @typedef {{ x: number, y: number, width: number, height: number }} Rect
+ * @typedef {'top' | 'right' | 'bottom' | 'left' | 'center'} Side
+ * @typedef {'straight' | 'elbow' | 'curve'} ConnectorShape
+ *
+ * @typedef {object} ConnectorPathOptions
+ * @property {Point} from
+ * @property {Point} to
+ * @property {ConnectorShape} [shape]
+ * @property {number} [curvature] Curve control-point reach along the dominant axis (curve shape). Default 0.5.
+ * @property {number} [mid] Turn position 0..1 along the span (elbow shape). Default 0.5.
+ *
+ * @typedef {object} ConnectRectsOptions
+ * @property {Rect} fromRect
+ * @property {Rect} toRect
+ * @property {Side} [fromSide] Anchor edges. Omit both to auto-pick facing edges from the rects.
+ * @property {Side} [toSide]
+ * @property {ConnectorShape} [shape]
+ * @property {number} [curvature]
+ * @property {number} [mid]
+ *
+ * @typedef {object} ConnectRectsResult
+ * @property {string} d SVG path data.
+ * @property {Point} from
+ * @property {Point} to
+ * @property {number} angle The path's end-tangent at `to` in radians — the direction the path arrives, so rotating an arrowhead at `to` by this points it along the path. Equals the straight `from`→`to` angle for `shape: 'straight'`; axis-aligned for `elbow`/`curve`.
  */
 
-const PRECISION = 1000;
+// Shared scalar/geometry primitives. Exported so the annotations layer composes
+// on the SAME kernel instead of copy-pasting it (the copies had silently
+// diverged — see `clamp`). Low-level helpers; the documented API is the path
+// builders below.
+export const PRECISION = 1000;
 
-function finite(name, value, fallback) {
+export 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) {
+export 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) {
+// Round to PRECISION, normalising -0 → 0, and return the NUMBER (the numeric
+// core `fmt` stringifies). Shared with the annotations layer for the rounded
+// coordinates it echoes back to the host. (code-quality audit Q5.)
+export function roundNumber(value) {
   const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
-  return String(Object.is(rounded, -0) ? 0 : rounded);
+  return Object.is(rounded, -0) ? 0 : rounded;
 }
 
-function point(x, y) {
+export function fmt(value) {
+  return String(roundNumber(value));
+}
+
+export function point(x, y) {
   return `${fmt(x)},${fmt(y)}`;
 }
 
-function clamp(value, min, max) {
+// Guarded form (returns min when the range is inverted) — the reconciled body;
+// connectors only ever calls clamp(v, 0, 1) so this is output-identical here.
+export function clamp(value, min, max) {
+  if (max < min) return min;
   return Math.min(max, Math.max(min, value));
 }
 
-/** A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`. */
+/**
+ * A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`.
+ * @param {Rect} rect
+ * @param {Side} [side]
+ * @returns {Point}
+ */
 export function anchorPoint(rect, side = 'center') {
   const x = finite('rect.x', rect?.x, 0);
   const y = finite('rect.y', rect?.y, 0);
@@ -60,7 +109,12 @@ export function anchorPoint(rect, side = 'center') {
   }
 }
 
-/** Angle (radians) from `from` to `to`. */
+/**
+ * Angle (radians) from `from` to `to`.
+ * @param {Point} from
+ * @param {Point} to
+ * @returns {number}
+ */
 export function angleBetween(from, to) {
   return Math.atan2(
     finite('to.y', to?.y) - finite('from.y', from?.y),
@@ -68,6 +122,12 @@ export function angleBetween(from, to) {
   );
 }
 
+/**
+ * Straight line from `from` to `to`.
+ * @param {Point} from
+ * @param {Point} to
+ * @returns {string}
+ */
 export function straightPath(from, to) {
   return `M${point(finite('from.x', from?.x), finite('from.y', from?.y))}L${point(
     finite('to.x', to?.x),
@@ -75,7 +135,13 @@ export function straightPath(from, to) {
   )}`;
 }
 
-/** Right-angle dogleg. Turns on the dominant axis at `mid` (0..1) of the span. */
+/**
+ * Right-angle dogleg. Turns on the dominant axis at `mid` (0..1) of the span.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {{ mid?: number }} [opts]
+ * @returns {string}
+ */
 export function elbowPath(from, to, opts = {}) {
   const fx = finite('from.x', from?.x);
   const fy = finite('from.y', from?.y);
@@ -92,7 +158,13 @@ export function elbowPath(from, to, opts = {}) {
   return `M${point(fx, fy)}V${fmt(my)}H${fmt(tx)}V${fmt(ty)}`;
 }
 
-/** Cubic curve; control points extend along the dominant axis by `curvature`. */
+/**
+ * Cubic curve; control points extend along the dominant axis by `curvature`.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {{ curvature?: number }} [opts]
+ * @returns {string}
+ */
 export function curvePath(from, to, opts = {}) {
   const fx = finite('from.x', from?.x);
   const fy = finite('from.y', from?.y);
@@ -107,7 +179,11 @@ export function curvePath(from, to, opts = {}) {
   return `M${point(fx, fy)}C${point(c1.x, c1.y)} ${point(c2.x, c2.y)} ${point(tx, ty)}`;
 }
 
-/** Build a path between two points by `shape` (`straight` | `elbow` | `curve`). */
+/**
+ * Build a path between two points by `shape` (`straight` | `elbow` | `curve`).
+ * @param {ConnectorPathOptions} [opts]
+ * @returns {string}
+ */
 export function connectorPath(opts = {}) {
   const { from, to, shape = 'straight' } = opts;
   if (shape === 'elbow') return elbowPath(from, to, opts);
@@ -115,20 +191,34 @@ export function connectorPath(opts = {}) {
   return straightPath(from, to);
 }
 
-/** A filled triangle arrowhead at `p`, pointing along `angle` (radians). */
-export function arrowHead(p, angle, size = 8) {
+/**
+ * A filled triangle arrowhead at `p`, pointing along `angle` (radians).
+ * @param {Point} p
+ * @param {number} angle
+ * @param {number} [size]
+ * @param {number} [spread] Half-angle of the head in radians (default 0.45).
+ *   Smaller is crisper/sharper; must be in (0, π/2).
+ * @returns {string}
+ */
+export function arrowHead(p, angle, size = 8, spread = 0.45) {
   const px = finite('p.x', p?.x);
   const py = finite('p.y', p?.y);
   const a = finite('angle', angle, 0);
   const s = dimension('size', size, 8);
+  const sp = finite('spread', spread, 0.45);
+  if (sp <= 0 || sp >= Math.PI / 2) throw new RangeError('spread must be in (0, π/2)');
   const back = a + Math.PI;
-  const spread = 0.45;
-  const p1 = { x: px + Math.cos(back - spread) * s, y: py + Math.sin(back - spread) * s };
-  const p2 = { x: px + Math.cos(back + spread) * s, y: py + Math.sin(back + spread) * s };
+  const p1 = { x: px + Math.cos(back - sp) * s, y: py + Math.sin(back - sp) * s };
+  const p2 = { x: px + Math.cos(back + sp) * s, y: py + Math.sin(back + sp) * s };
   return `M${point(px, py)}L${point(p1.x, p1.y)}L${point(p2.x, p2.y)}Z`;
 }
 
-/** A filled dot at `p`. */
+/**
+ * A filled dot at `p`.
+ * @param {Point} p
+ * @param {number} [radius]
+ * @returns {string}
+ */
 export function dotMark(p, radius = 3) {
   const px = finite('p.x', p?.x);
   const py = finite('p.y', p?.y);
@@ -139,7 +229,26 @@ export function dotMark(p, radius = 3) {
   )} 0 1 1 ${point(px, py - r)}Z`;
 }
 
-/** Pick facing edges from the rects' relative centres. */
+/**
+ * An axis-aligned rectangle path from its corners (callers derive the corners
+ * from a centre or a top-left as they need). Shared by the annotation
+ * rect/band and evidence-marker subjects. (code-quality audit Q5.)
+ * @param {number} left
+ * @param {number} top
+ * @param {number} right
+ * @param {number} bottom
+ * @returns {string}
+ */
+export function rectPath(left, top, right, bottom) {
+  return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
+}
+
+/**
+ * Pick facing edges from the rects' relative centres.
+ * @param {Rect} fromRect
+ * @param {Rect} toRect
+ * @returns {{ from: Side, to: Side }}
+ */
 export function autoSides(fromRect, toRect) {
   const fc = anchorPoint(fromRect, 'center');
   const tc = anchorPoint(toRect, 'center');
@@ -152,13 +261,14 @@ export function autoSides(fromRect, toRect) {
 }
 
 /**
- * Connect two rects. Resolves anchor points (explicit `fromSide`/`toSide`, else
- * auto), builds the path, and returns `{ d, from, to, angle }` so the caller can
- * place an arrowhead/dot at `to` rotated by `angle`.
+ * Angle (radians) at which a `shape` path *arrives* at `to` — straight is the
+ * chord; elbow/curve arrive axis-aligned along the dominant axis. Rotate an
+ * end marker by this so it points along the path, not the chord.
+ * @param {Point} from
+ * @param {Point} to
+ * @param {ConnectorShape} [shape]
+ * @returns {number}
  */
-/** Angle (radians) at which a `shape` path *arrives* at `to` — straight is the
- *  chord; elbow/curve arrive axis-aligned along the dominant axis. Rotate an
- *  end marker by this so it points along the path, not the chord. */
 export function endTangentAngle(from, to, shape = 'straight') {
   if (shape === 'straight') return angleBetween(from, to);
   const dx = finite('to.x', to?.x) - finite('from.x', from?.x);
@@ -167,6 +277,13 @@ export function endTangentAngle(from, to, shape = 'straight') {
   return dy >= 0 ? Math.PI / 2 : -Math.PI / 2;
 }
 
+/**
+ * Connect two rects. Resolves anchor points (explicit `fromSide`/`toSide`, else
+ * auto), builds the path, and returns `{ d, from, to, angle }` so the caller can
+ * place an arrowhead/dot at `to` rotated by `angle`.
+ * @param {ConnectRectsOptions} [opts]
+ * @returns {ConnectRectsResult}
+ */
 export function connectRects(opts = {}) {
   const { fromRect, toRect, shape = 'straight', curvature, mid } = opts;
   // Honor each side override independently; auto-pick whichever is unset.