@ponchia/ui 0.4.1 → 0.5.0

package/classes/index.js

@@ -268,8 +268,6 @@ export const cls = Object.freeze({
   reportAppendix: 'ui-report__appendix',
   reportFootnotes: 'ui-report__footnotes',
   chart: 'ui-chart',
-  chartLegend: 'ui-chart__legend',
-  chartSwatch: 'ui-chart__swatch',
   chartCaption: 'ui-chart__caption',
   chartPlot: 'ui-chart__plot',
   chartBar: 'ui-chart__bar',
@@ -277,6 +275,188 @@ export const cls = Object.freeze({
   chartTrack: 'ui-chart__track',
   chartFill: 'ui-chart__fill',
   chartFallback: 'ui-chart__fallback',
+  // legend (standalone data keys — css/legend.css)
+  legend: 'ui-legend',
+  legendVertical: 'ui-legend--vertical',
+  legendCompact: 'ui-legend--compact',
+  legendGradient: 'ui-legend--gradient',
+  legendDiverging: 'ui-legend--diverging',
+  legendThreshold: 'ui-legend--threshold',
+  legendWithValues: 'ui-legend--with-values',
+  legendInteractive: 'ui-legend--interactive',
+  legendTitle: 'ui-legend__title',
+  legendItem: 'ui-legend__item',
+  legendSwatch: 'ui-legend__swatch',
+  legendSwatchCircle: 'ui-legend__swatch--circle',
+  legendSwatchLine: 'ui-legend__swatch--line',
+  legendSwatch1: 'ui-legend__swatch--1',
+  legendSwatch2: 'ui-legend__swatch--2',
+  legendSwatch3: 'ui-legend__swatch--3',
+  legendSwatch4: 'ui-legend__swatch--4',
+  legendSwatch5: 'ui-legend__swatch--5',
+  legendSwatch6: 'ui-legend__swatch--6',
+  legendSwatch7: 'ui-legend__swatch--7',
+  legendSwatch8: 'ui-legend__swatch--8',
+  legendSymbol: 'ui-legend__symbol',
+  legendLabel: 'ui-legend__label',
+  legendValue: 'ui-legend__value',
+  legendCaption: 'ui-legend__caption',
+  legendTrack: 'ui-legend__track',
+  legendTicks: 'ui-legend__ticks',
+  legendTick: 'ui-legend__tick',
+  annotation: 'ui-annotation',
+  annotationSubject: 'ui-annotation__subject',
+  annotationConnector: 'ui-annotation__connector',
+  annotationConnectorEnd: 'ui-annotation__connector-end',
+  annotationNote: 'ui-annotation__note',
+  annotationNoteLine: 'ui-annotation__note-line',
+  annotationTitle: 'ui-annotation__title',
+  annotationLabel: 'ui-annotation__label',
+  annotationBadge: 'ui-annotation__badge',
+  annotationLabelVariant: 'ui-annotation--label',
+  annotationCallout: 'ui-annotation--callout',
+  annotationElbow: 'ui-annotation--elbow',
+  annotationCurve: 'ui-annotation--curve',
+  annotationCircle: 'ui-annotation--circle',
+  annotationRect: 'ui-annotation--rect',
+  annotationThreshold: 'ui-annotation--threshold',
+  annotationBadgeVariant: 'ui-annotation--badge',
+  annotationBracket: 'ui-annotation--bracket',
+  annotationBand: 'ui-annotation--band',
+  annotationSlope: 'ui-annotation--slope',
+  annotationCompare: 'ui-annotation--compare',
+  annotationCluster: 'ui-annotation--cluster',
+  annotationAxis: 'ui-annotation--axis',
+  annotationTimeline: 'ui-annotation--timeline',
+  annotationEvidence: 'ui-annotation--evidence',
+  annotationAccent: 'ui-annotation--accent',
+  annotationMuted: 'ui-annotation--muted',
+  annotationSuccess: 'ui-annotation--success',
+  annotationWarning: 'ui-annotation--warning',
+  annotationDanger: 'ui-annotation--danger',
+  annotationInfo: 'ui-annotation--info',
+  annotationDraw: 'ui-annotation--draw',
+  annotationPulse: 'ui-annotation--pulse',
+  annotationReveal: 'ui-annotation--reveal',
+  annotationFocus: 'ui-annotation--focus',
+  // marks (evidence/emphasis for running text — css/marks.css)
+  mark: 'ui-mark',
+  markAccent: 'ui-mark--accent',
+  markSuccess: 'ui-mark--success',
+  markWarning: 'ui-mark--warning',
+  markDanger: 'ui-mark--danger',
+  markInfo: 'ui-mark--info',
+  markMuted: 'ui-mark--muted',
+  markUnderline: 'ui-mark--underline',
+  markBox: 'ui-mark--box',
+  markStrike: 'ui-mark--strike',
+  markDraw: 'ui-mark--draw',
+  bracketNote: 'ui-bracket-note',
+  bracketNoteLabel: 'ui-bracket-note__label',
+  bracketNoteAccent: 'ui-bracket-note--accent',
+  bracketNoteWarning: 'ui-bracket-note--warning',
+  bracketNoteDanger: 'ui-bracket-note--danger',
+  bracketNoteInfo: 'ui-bracket-note--info',
+  // connectors (leader lines — css/connectors.css)
+  connector: 'ui-connector',
+  connectorPath: 'ui-connector__path',
+  connectorEnd: 'ui-connector__end',
+  connectorDashed: 'ui-connector--dashed',
+  connectorAccent: 'ui-connector--accent',
+  connectorMuted: 'ui-connector--muted',
+  connectorSuccess: 'ui-connector--success',
+  connectorWarning: 'ui-connector--warning',
+  connectorDanger: 'ui-connector--danger',
+  connectorInfo: 'ui-connector--info',
+  connectorDraw: 'ui-connector--draw',
+  // spotlight (guided-focus overlay — css/spotlight.css)
+  spotlight: 'ui-spotlight',
+  spotlightHole: 'ui-spotlight__hole',
+  spotlightRing: 'ui-spotlight--ring',
+  tourNote: 'ui-tour-note',
+  tourNoteStep: 'ui-tour-note__step',
+  tourNoteTitle: 'ui-tour-note__title',
+  tourNoteBody: 'ui-tour-note__body',
+  tourNoteActions: 'ui-tour-note__actions',
+  // crosshair (plot ruler + readout — css/crosshair.css)
+  crosshair: 'ui-crosshair',
+  crosshairMuted: 'ui-crosshair--muted',
+  crosshairLine: 'ui-crosshair__line',
+  crosshairLineX: 'ui-crosshair__line--x',
+  crosshairLineY: 'ui-crosshair__line--y',
+  crosshairBadge: 'ui-crosshair__badge',
+  readout: 'ui-readout',
+  // selection-state vocabulary (cross-cutting — css/selection.css)
+  sel: 'ui-sel',
+  selOn: 'ui-sel--on',
+  selOff: 'ui-sel--off',
+  selMaybe: 'ui-sel--maybe',
+  // source / citation / provenance — the trust layer (css/sources.css)
+  citation: 'ui-citation',
+  citationChip: 'ui-citation--chip',
+  sourceList: 'ui-source-list',
+  sourceListItem: 'ui-source-list__item',
+  sourceCard: 'ui-source-card',
+  sourceCardTitle: 'ui-source-card__title',
+  sourceCardOrigin: 'ui-source-card__origin',
+  sourceCardTime: 'ui-source-card__time',
+  sourceCardExcerpt: 'ui-source-card__excerpt',
+  sourceCardActions: 'ui-source-card__actions',
+  provenance: 'ui-provenance',
+  provenanceItem: 'ui-provenance__item',
+  srcVerified: 'ui-src--verified',
+  srcUnverified: 'ui-src--unverified',
+  srcGenerated: 'ui-src--generated',
+  srcReviewed: 'ui-src--reviewed',
+  srcStale: 'ui-src--stale',
+  srcConflict: 'ui-src--conflict',
+  // lifecycle / system state (css/state.css)
+  state: 'ui-state',
+  stateLabel: 'ui-state__label',
+  stateDetail: 'ui-state__detail',
+  stateBusy: 'ui-state--busy',
+  stateSaving: 'ui-state--saving',
+  stateSaved: 'ui-state--saved',
+  stateQueued: 'ui-state--queued',
+  stateOffline: 'ui-state--offline',
+  stateStale: 'ui-state--stale',
+  stateConflict: 'ui-state--conflict',
+  stateError: 'ui-state--error',
+  stateLocked: 'ui-state--locked',
+  stateReviewed: 'ui-state--reviewed',
+  stateNeedsReview: 'ui-state--needs-review',
+  syncbar: 'ui-syncbar',
+  // generated content / AI-trust surfaces (css/generated.css)
+  generated: 'ui-generated',
+  generatedLabel: 'ui-generated__label',
+  originLabel: 'ui-origin-label',
+  originLabelAi: 'ui-origin-label--ai',
+  reasoning: 'ui-reasoning',
+  reasoningBody: 'ui-reasoning__body',
+  toolLog: 'ui-tool-log',
+  toolCall: 'ui-tool-call',
+  toolCallName: 'ui-tool-call__name',
+  toolCallStatus: 'ui-tool-call__status',
+  toolCallBody: 'ui-tool-call__body',
+  // workbench — inspector / property / selection bar (css/workbench.css)
+  inspector: 'ui-inspector',
+  inspectorHeader: 'ui-inspector__header',
+  inspectorBody: 'ui-inspector__body',
+  property: 'ui-property',
+  propertyLabel: 'ui-property__label',
+  propertyValue: 'ui-property__value',
+  selectionbar: 'ui-selectionbar',
+  selectionbarCount: 'ui-selectionbar__count',
+  selectionbarActions: 'ui-selectionbar__actions',
+  // command palette shell (css/command.css + initCommand)
+  command: 'ui-command',
+  commandInput: 'ui-command__input',
+  commandList: 'ui-command__list',
+  commandGroup: 'ui-command__group',
+  commandItem: 'ui-command__item',
+  commandShortcut: 'ui-command__shortcut',
+  commandMeta: 'ui-command__meta',
+  commandEmpty: 'ui-command__empty',
   printOnly: 'ui-print-only',
   screenOnly: 'ui-screen-only',
   breakBefore: 'ui-break-before',
@@ -284,6 +464,8 @@ export const cls = Object.freeze({
   keep: 'ui-keep',
   printExact: 'ui-print-exact',
   kbd: 'ui-kbd',
+  shortcut: 'ui-shortcut',
+  shortcutSep: 'ui-shortcut__sep',
   display: 'ui-display',
   mono: 'ui-mono',
   muted: 'ui-muted',
@@ -345,6 +527,31 @@ export function cx(...parts) {
 
 const j = (...p) => p.filter(Boolean).join(' ');
 
+// Lifecycle state → canonical tone class.
+const stateTone = (state) =>
+  ({
+    saving: cls.stateSaving,
+    saved: cls.stateSaved,
+    queued: cls.stateQueued,
+    offline: cls.stateOffline,
+    stale: cls.stateStale,
+    conflict: cls.stateConflict,
+    error: cls.stateError,
+    locked: cls.stateLocked,
+    reviewed: cls.stateReviewed,
+    'needs-review': cls.stateNeedsReview,
+  })[state] || '';
+
+// Trust-state → tone class, shared by the source/citation/provenance recipes.
+const srcTone = (state) =>
+  (state === 'verified' && cls.srcVerified) ||
+  (state === 'unverified' && cls.srcUnverified) ||
+  (state === 'generated' && cls.srcGenerated) ||
+  (state === 'reviewed' && cls.srcReviewed) ||
+  (state === 'stale' && cls.srcStale) ||
+  (state === 'conflict' && cls.srcConflict) ||
+  '';
+
 export const ui = {
   button: ({ variant, icon, size } = {}) =>
     j(
@@ -440,6 +647,110 @@ export const ui = {
     j(cls.container, narrow && cls.containerNarrow, wide && cls.containerWide),
   tag: ({ accent } = {}) => j(cls.tag, accent && cls.tagAccent),
   inputIcon: ({ end } = {}) => j(cls.inputIcon, end && cls.inputIconEnd),
+  legend: ({ orient, type, diverging, compact, withValues, interactive } = {}) =>
+    j(
+      cls.legend,
+      orient === 'vertical' && cls.legendVertical,
+      type === 'gradient' && cls.legendGradient,
+      type === 'threshold' && cls.legendThreshold,
+      diverging && cls.legendDiverging,
+      compact && cls.legendCompact,
+      withValues && cls.legendWithValues,
+      interactive && cls.legendInteractive,
+    ),
+  legendItem: ({ inactive } = {}) => j(cls.legendItem, inactive && 'is-inactive'),
+  legendSwatch: ({ series, shape } = {}) =>
+    j(
+      cls.legendSwatch,
+      series === 1 && cls.legendSwatch1,
+      series === 2 && cls.legendSwatch2,
+      series === 3 && cls.legendSwatch3,
+      series === 4 && cls.legendSwatch4,
+      series === 5 && cls.legendSwatch5,
+      series === 6 && cls.legendSwatch6,
+      series === 7 && cls.legendSwatch7,
+      series === 8 && cls.legendSwatch8,
+      shape === 'circle' && cls.legendSwatchCircle,
+      shape === 'line' && cls.legendSwatchLine,
+    ),
+  annotation: ({ variant = 'callout', tone = 'accent', motion } = {}) =>
+    j(
+      cls.annotation,
+      variant === 'label' && cls.annotationLabelVariant,
+      variant === 'callout' && cls.annotationCallout,
+      variant === 'elbow' && cls.annotationElbow,
+      variant === 'curve' && cls.annotationCurve,
+      variant === 'circle' && cls.annotationCircle,
+      variant === 'rect' && cls.annotationRect,
+      variant === 'threshold' && cls.annotationThreshold,
+      variant === 'badge' && cls.annotationBadgeVariant,
+      variant === 'bracket' && cls.annotationBracket,
+      variant === 'band' && cls.annotationBand,
+      variant === 'slope' && cls.annotationSlope,
+      variant === 'compare' && cls.annotationCompare,
+      variant === 'cluster' && cls.annotationCluster,
+      variant === 'axis' && cls.annotationAxis,
+      variant === 'timeline' && cls.annotationTimeline,
+      variant === 'evidence' && cls.annotationEvidence,
+      tone === 'accent' && cls.annotationAccent,
+      tone === 'muted' && cls.annotationMuted,
+      tone === 'success' && cls.annotationSuccess,
+      tone === 'warning' && cls.annotationWarning,
+      tone === 'danger' && cls.annotationDanger,
+      tone === 'info' && cls.annotationInfo,
+      motion === 'draw' && cls.annotationDraw,
+      motion === 'pulse' && cls.annotationPulse,
+      motion === 'reveal' && cls.annotationReveal,
+      motion === 'focus' && cls.annotationFocus,
+    ),
+  mark: ({ style, tone, motion } = {}) =>
+    j(
+      cls.mark,
+      style === 'underline' && cls.markUnderline,
+      style === 'box' && cls.markBox,
+      style === 'strike' && cls.markStrike,
+      tone === 'accent' && cls.markAccent,
+      tone === 'success' && cls.markSuccess,
+      tone === 'warning' && cls.markWarning,
+      tone === 'danger' && cls.markDanger,
+      tone === 'info' && cls.markInfo,
+      tone === 'muted' && cls.markMuted,
+      motion === 'draw' && cls.markDraw,
+    ),
+  bracketNote: ({ tone } = {}) =>
+    j(
+      cls.bracketNote,
+      tone === 'accent' && cls.bracketNoteAccent,
+      tone === 'warning' && cls.bracketNoteWarning,
+      tone === 'danger' && cls.bracketNoteDanger,
+      tone === 'info' && cls.bracketNoteInfo,
+    ),
+  connector: ({ tone, dashed, motion } = {}) =>
+    j(
+      cls.connector,
+      tone === 'accent' && cls.connectorAccent,
+      tone === 'muted' && cls.connectorMuted,
+      tone === 'success' && cls.connectorSuccess,
+      tone === 'warning' && cls.connectorWarning,
+      tone === 'danger' && cls.connectorDanger,
+      tone === 'info' && cls.connectorInfo,
+      dashed && cls.connectorDashed,
+      motion === 'draw' && cls.connectorDraw,
+    ),
+  spotlight: ({ ring } = {}) => j(cls.spotlight, ring && cls.spotlightRing),
+  crosshair: ({ muted } = {}) => j(cls.crosshair, muted && cls.crosshairMuted),
+  sel: ({ state } = {}) =>
+    j(
+      cls.sel,
+      state === 'on' && cls.selOn,
+      state === 'off' && cls.selOff,
+      state === 'maybe' && cls.selMaybe,
+    ),
+  citation: ({ chip, state } = {}) => j(cls.citation, chip && cls.citationChip, srcTone(state)),
+  source: ({ state } = {}) => j(cls.sourceCard, srcTone(state)),
+  provenance: ({ state } = {}) => j(cls.provenance, srcTone(state)),
+  state: ({ state, busy } = {}) => j(cls.state, stateTone(state), busy && cls.stateBusy),
+  originLabel: ({ ai } = {}) => j(cls.originLabel, ai && cls.originLabelAi),
 };
 
 export default ui;

package/connectors/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @ponchia/ui/connectors — dependency-free SVG geometry for leader lines.
+ * Pure functions: points/rects in, SVG path strings (or coordinates) out.
+ */
+
+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;

package/connectors/index.js

@@ -0,0 +1,179 @@
+/**
+ * @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' });
+ */
+
+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 point(x, y) {
+  return `${fmt(x)},${fmt(y)}`;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`. */
+export function anchorPoint(rect, side = 'center') {
+  const x = finite('rect.x', rect?.x, 0);
+  const y = finite('rect.y', rect?.y, 0);
+  const w = dimension('rect.width', rect?.width, 0);
+  const h = dimension('rect.height', rect?.height, 0);
+  switch (side) {
+    case 'top':
+      return { x: x + w / 2, y };
+    case 'bottom':
+      return { x: x + w / 2, y: y + h };
+    case 'left':
+      return { x, y: y + h / 2 };
+    case 'right':
+      return { x: x + w, y: y + h / 2 };
+    case 'center':
+    default:
+      return { x: x + w / 2, y: y + h / 2 };
+  }
+}
+
+/** Angle (radians) from `from` to `to`. */
+export function angleBetween(from, to) {
+  return Math.atan2(
+    finite('to.y', to?.y) - finite('from.y', from?.y),
+    finite('to.x', to?.x) - finite('from.x', from?.x),
+  );
+}
+
+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),
+    finite('to.y', to?.y),
+  )}`;
+}
+
+/** Right-angle dogleg. Turns on the dominant axis at `mid` (0..1) of the span. */
+export function elbowPath(from, to, opts = {}) {
+  const fx = finite('from.x', from?.x);
+  const fy = finite('from.y', from?.y);
+  const tx = finite('to.x', to?.x);
+  const ty = finite('to.y', to?.y);
+  const mid = clamp(finite('mid', opts.mid, 0.5), 0, 1);
+  const dx = tx - fx;
+  const dy = ty - fy;
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    const mx = fx + dx * mid;
+    return `M${point(fx, fy)}H${fmt(mx)}V${fmt(ty)}H${fmt(tx)}`;
+  }
+  const my = fy + dy * mid;
+  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`. */
+export function curvePath(from, to, opts = {}) {
+  const fx = finite('from.x', from?.x);
+  const fy = finite('from.y', from?.y);
+  const tx = finite('to.x', to?.x);
+  const ty = finite('to.y', to?.y);
+  const k = finite('curvature', opts.curvature, 0.5);
+  const dx = tx - fx;
+  const dy = ty - fy;
+  const horizontal = Math.abs(dx) >= Math.abs(dy);
+  const c1 = horizontal ? { x: fx + dx * k, y: fy } : { x: fx, y: fy + dy * k };
+  const c2 = horizontal ? { x: tx - dx * k, y: ty } : { x: tx, y: ty - dy * k };
+  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`). */
+export function connectorPath(opts = {}) {
+  const { from, to, shape = 'straight' } = opts;
+  if (shape === 'elbow') return elbowPath(from, to, opts);
+  if (shape === 'curve') return curvePath(from, to, opts);
+  return straightPath(from, to);
+}
+
+/** A filled triangle arrowhead at `p`, pointing along `angle` (radians). */
+export function arrowHead(p, angle, size = 8) {
+  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 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 };
+  return `M${point(px, py)}L${point(p1.x, p1.y)}L${point(p2.x, p2.y)}Z`;
+}
+
+/** A filled dot at `p`. */
+export function dotMark(p, radius = 3) {
+  const px = finite('p.x', p?.x);
+  const py = finite('p.y', p?.y);
+  const r = dimension('radius', radius, 3);
+  if (r === 0) return '';
+  return `M${point(px, py - r)}A${fmt(r)},${fmt(r)} 0 1 1 ${point(px, py + r)}A${fmt(r)},${fmt(
+    r,
+  )} 0 1 1 ${point(px, py - r)}Z`;
+}
+
+/** Pick facing edges from the rects' relative centres. */
+export function autoSides(fromRect, toRect) {
+  const fc = anchorPoint(fromRect, 'center');
+  const tc = anchorPoint(toRect, 'center');
+  const dx = tc.x - fc.x;
+  const dy = tc.y - fc.y;
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    return dx >= 0 ? { from: 'right', to: 'left' } : { from: 'left', to: 'right' };
+  }
+  return dy >= 0 ? { from: 'bottom', to: 'top' } : { from: 'top', to: 'bottom' };
+}
+
+/**
+ * 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. */
+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);
+  const dy = finite('to.y', to?.y) - finite('from.y', from?.y);
+  if (Math.abs(dx) >= Math.abs(dy)) return dx >= 0 ? 0 : Math.PI;
+  return dy >= 0 ? Math.PI / 2 : -Math.PI / 2;
+}
+
+export function connectRects(opts = {}) {
+  const { fromRect, toRect, shape = 'straight', curvature, mid } = opts;
+  // Honor each side override independently; auto-pick whichever is unset.
+  const auto = autoSides(fromRect, toRect);
+  const sides = { from: opts.fromSide || auto.from, to: opts.toSide || auto.to };
+  const from = anchorPoint(fromRect, sides.from);
+  const to = anchorPoint(toRect, sides.to);
+  const d = connectorPath({ from, to, shape, curvature, mid });
+  return { d, from, to, angle: endTangentAngle(from, to, shape) };
+}

package/css/analytical.css

@@ -0,0 +1,21 @@
+/* ==========================================================================
+   analytical — convenience roll-up of the opt-in analytical-primitive layers.
+
+   Import this one file instead of the seven leaves when you're building
+   analytical / generated-report UI:
+
+     @import '@ponchia/ui';
+     @import '@ponchia/ui/css/analytical.css';
+
+   Add @ponchia/ui/css/dataviz.css for the chart colour palette (legend swatches
+   fall back to the accent without it) and @ponchia/ui/css/report.css for the
+   document grammar as needed — those are separate concerns, kept opt-in.
+   ========================================================================== */
+
+@import url('./annotations.css') layer(bronto);
+@import url('./legend.css') layer(bronto);
+@import url('./marks.css') layer(bronto);
+@import url('./connectors.css') layer(bronto);
+@import url('./spotlight.css') layer(bronto);
+@import url('./crosshair.css') layer(bronto);
+@import url('./selection.css') layer(bronto);