@ponchia/ui 0.5.0 → 0.6.0

package/connectors/index.js

@@ -10,36 +10,78 @@
  *
  *   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) {
+export 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) {
+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 +102,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 +115,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 +128,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 +151,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 +172,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 +184,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 +222,12 @@ export function dotMark(p, radius = 3) {
   )} 0 1 1 ${point(px, py - r)}Z`;
 }
 
-/** Pick facing edges from the rects' relative centres. */
+/**
+ * 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 +240,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 +256,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.

package/css/app.css

@@ -6,7 +6,7 @@
 .ui-app-shell {
   display: grid;
   grid-template-columns: var(--app-rail, 14rem) minmax(0, 1fr);
-  min-block-size: 100vh;
+  min-block-size: 100dvh;
 }
 
 .ui-app-shell--full {
@@ -24,7 +24,7 @@
   padding: var(--space-md);
   position: sticky;
   inset-block-start: 0;
-  block-size: 100vh;
+  block-size: 100svh;
   overflow-y: auto;
 }
 
@@ -34,6 +34,7 @@
   display: flex;
   font-family: var(--display);
   font-size: 1.05rem;
+  font-weight: var(--display-weight);
   gap: 0.5rem;
   letter-spacing: var(--tracking-wide);
   padding: 0.35rem 0.5rem;
@@ -87,18 +88,33 @@
   inline-size: 0.34rem;
 }
 
-.ui-app-nav a:hover {
-  background: var(--bg-accent);
-  color: var(--text);
+@media (hover: hover) {
+  .ui-app-nav a:hover {
+    background: var(--bg-accent);
+    color: var(--text);
+  }
 }
 
-.ui-app-nav a.is-active {
+/* Current page honours BOTH the `.is-active` class and `aria-current` — the
+   sibling `.ui-sitenav` signals current-page with `aria-current="page"`, so the
+   app-shell nav now accepts the same programmatic cue (author it for AT, not
+   just the visual class — C19). */
+.ui-app-nav a.is-active,
+.ui-app-nav a[aria-current]:not([aria-current='false']) {
   background: var(--accent-soft);
   border-inline-start-color: var(--accent);
   color: var(--accent-text);
 }
 
-.ui-app-nav a.is-active::before {
+@media (pointer: coarse) {
+  .ui-app-nav a {
+    min-block-size: 2.9rem;
+    padding-inline: 0.9rem;
+  }
+}
+
+.ui-app-nav a.is-active::before,
+.ui-app-nav a[aria-current]:not([aria-current='false'])::before {
   opacity: 1;
 }
 
@@ -153,6 +169,7 @@
   color: var(--text);
   font-family: var(--display);
   font-size: 1.1rem;
+  font-weight: var(--display-weight);
   letter-spacing: var(--tracking-wide);
   margin: 0;
   text-transform: uppercase;
@@ -207,6 +224,7 @@
   color: var(--text);
   font-family: var(--display);
   font-size: 0.95rem;
+  font-weight: var(--display-weight);
   letter-spacing: var(--tracking-wide);
   margin: 0;
   text-transform: uppercase;
@@ -230,11 +248,7 @@
    permanent admin-shell alias (grouped on the canonical rules there —
    identical output). Nothing app-specific left to define here. */
 
-/* --- Mobile rail collapse --- */
-
-.ui-app-rail__toggle {
-  display: none;
-}
+/* --- Mobile rail: collapses to a horizontal scrolling strip --- */
 
 @media (max-width: 880px) {
   .ui-app-shell {
@@ -254,6 +268,15 @@
     display: none;
   }
 
+  /* The rail is flex-row here, so the base `margin-block-start: auto` (which
+     pushed account to the bottom in the column layout) is inert and account can
+     scroll off. Push it to the inline end instead so sign-out stays reachable.
+     (layout review C21.) */
+  .ui-app-rail__account {
+    margin-block-start: 0;
+    margin-inline-start: auto;
+  }
+
   .ui-app-nav {
     grid-auto-flow: column;
     gap: 0.15rem;
@@ -269,11 +292,18 @@
     white-space: nowrap;
   }
 
-  .ui-app-nav a.is-active {
+  .ui-app-nav a.is-active,
+  .ui-app-nav a[aria-current]:not([aria-current='false']) {
     border-inline-start: 0;
     border-block-end-color: var(--accent);
   }
 
+  /* No --app-rail-height token exists, so drop the redundant second sticky;
+     only the horizontal rail stays pinned. */
+  .ui-app-topbar {
+    position: static;
+  }
+
   .ui-app-content {
     padding: var(--space-md);
   }

package/css/base.css

@@ -12,7 +12,10 @@ html {
   background: var(--bg);
   color: var(--text);
   font-family: var(--sans);
-  font-size: 15px;
+
+  /* = 15px at the 16px default, but rem honours a user's browser font-size
+     preference (which a px root would ignore). */
+  font-size: 0.9375rem;
   line-height: 1.55;
   scroll-behavior: smooth;
   text-rendering: optimizeLegibility;
@@ -24,12 +27,16 @@ body {
   background: var(--bg);
   color: var(--text);
   margin: 0;
-  min-block-size: 100vh;
+  min-block-size: 100dvh;
   position: relative;
 }
 
+:root {
+  --scroll-offset: 6rem;
+}
+
 main [id] {
-  scroll-margin-top: 6rem;
+  scroll-margin-block-start: var(--scroll-offset);
 }
 
 ::selection {
@@ -176,6 +183,7 @@ textarea:focus-visible,
 
 .ui-display {
   font-family: var(--display);
+  font-weight: var(--display-weight);
   text-transform: uppercase;
 }
 
@@ -219,13 +227,10 @@ textarea:focus-visible,
     outline-offset: -2px;
   }
 
-  /* The active tab signals selection only via accent colour/border, both
-     flattened by the forced palette — re-assert it with a system colour
-     so the selected tab stays distinguishable (a11y review L3). */
-  .ui-tab.is-active {
-    border-block-end-color: Highlight;
-    color: Highlight;
-  }
+  /* NB: the active-tab forced-colors re-assert lives in disclosure.css, right
+     after the `.ui-tab.is-active` default — placing it here (an earlier bundle
+     leaf) let the later default win even in forced-colors mode, since @media
+     adds no specificity. (a11y review C10.) */
 
   /* Keyboard focus must never depend on a colour that gets overridden. */
   a:focus-visible,

package/css/connectors.css

@@ -91,3 +91,20 @@
     fill: CanvasText;
   }
 }
+
+/* Print: keep the relationship lines and arrowheads in their meaning-carrying
+   colour, and settle any draw-on to a solid line (the draw needs JS to set
+   pathLength, which never runs for a static PDF). */
+@media print {
+  .ui-connector__path,
+  .ui-connector__end {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+
+  .ui-connector--draw .ui-connector__path {
+    animation: none;
+    stroke-dasharray: none;
+    stroke-dashoffset: 0;
+  }
+}

package/css/content.css

@@ -13,6 +13,11 @@
   font-size: var(--text-base);
   line-height: 1.7;
 
+  /* Machine-generated Markdown carries long unbreakable tokens (URLs, hashes,
+     code) that otherwise force horizontal page scroll on the prose surface
+     itself. Break them. (css-robustness review C9; the table cell already does.) */
+  overflow-wrap: break-word;
+
   /* Readable measure; the container can still be wider for tables/media. */
   --prose-measure: 72ch;
 }
@@ -75,7 +80,7 @@
 
 /* Anchored headings clear a sticky chrome and expose a dot on hover. */
 .ui-prose :is(h1, h2, h3, h4, h5, h6)[id] {
-  scroll-margin-block-start: 6rem;
+  scroll-margin-block-start: var(--scroll-offset);
 }
 
 /* --- Text-level --- */
@@ -300,6 +305,7 @@
   display: grid;
   font-family: var(--display);
   font-size: var(--text-xl);
+  font-weight: var(--display-weight);
   gap: var(--space-sm);
   line-height: 1.2;
   margin-block: var(--space-xl);

package/css/dataviz.css

@@ -30,7 +30,11 @@
   --chart-div-6: oklch(66% 0.13 55deg);
   --chart-div-7: oklch(56% 0.15 45deg);
 
-  /* Dot-matrix pattern fills — pair with the matching colour (WCAG 1.4.1). */
+  /* Dot-matrix pattern fills — pair with the matching colour (WCAG 1.4.1).
+     Series 1 (the accent) is intentionally `none`: absence-of-pattern IS its
+     redundant channel. The colour palette is CVD-safe on its own (gated by
+     check:charts), so a colour+pattern chart stays distinguishable; a
+     pattern-ONLY chart must still give series 1 a fill or a labelled legend. */
   --chart-pattern-size: 8px;
   --chart-pattern-ink: rgb(0 0 0 / 0.34);
   --chart-pattern-1: none;

package/css/disclosure.css

@@ -44,11 +44,29 @@
     border-color var(--duration-fast) var(--ease-standard);
 }
 
+/* Coarse-pointer tap-target floor (~2.9rem ≈ 44px), matching inputs/sitenav —
+   tabs are easy to mis-tap on touch (WCAG 2.5.8 — C24). */
+@media (pointer: coarse) {
+  .ui-tab {
+    min-block-size: 2.9rem;
+  }
+}
+
 .ui-tab.is-active {
   border-block-end-color: var(--accent);
   color: var(--accent-text);
 }
 
+/* Forced-colors re-assert MUST sit after the default above (same specificity,
+   @media adds none) or the accent default wins and the selected tab loses its
+   only cue. Moved here from base.css, an earlier bundle leaf. (a11y review C10.) */
+@media (forced-colors: active) {
+  .ui-tab.is-active {
+    border-block-end-color: Highlight;
+    color: Highlight;
+  }
+}
+
 .ui-tab:focus-visible {
   /* An inset box, deliberately distinct from the .is-active bottom-border
      so focus ≠ selection for low-vision keyboard users: the global
@@ -199,7 +217,7 @@
 
 .ui-segmented__option:has(input:focus-visible) {
   outline: 2px solid var(--focus-ring);
-  outline-offset: 2px;
+  outline-offset: -2px;
 }
 
 @media (hover: hover) {
@@ -240,7 +258,7 @@
   inline-size: 0.22rem;
 }
 
-.ui-breadcrumb__item[aria-current] {
+.ui-breadcrumb__item[aria-current]:not([aria-current='false']) {
   color: var(--text);
 }
 
@@ -290,18 +308,32 @@
   color: var(--accent-text);
 }
 
-.ui-pagination__item[aria-disabled='true'] {
+/* Disabled covers BOTH the native `<button disabled>` the demo ships and the
+   `aria-disabled="true"` ARIA path; `pointer-events: none` makes the
+   aria-disabled item genuinely inert (it was clickable before — C5). */
+.ui-pagination__item[aria-disabled='true'],
+.ui-pagination__item:disabled {
   cursor: not-allowed;
   opacity: 0.4;
+  pointer-events: none;
 }
 
 @media (hover: hover) {
-  .ui-pagination__item:not(.is-active, [aria-disabled='true']):hover {
+  .ui-pagination__item:not(.is-active, [aria-disabled='true'], :disabled):hover {
     border-color: var(--line-strong);
     color: var(--text);
   }
 }
 
+/* Coarse-pointer tap-target floor, matching inputs/sitenav (~2.9rem ≈ 44px) —
+   pagination controls are easy to mis-tap on touch (WCAG 2.5.8 — C24). */
+@media (pointer: coarse) {
+  .ui-pagination__item {
+    min-block-size: 2.9rem;
+    min-inline-size: 2.9rem;
+  }
+}
+
 /* --- Avatar — sharp, monospace initials or image --- */
 
 .ui-avatar {
@@ -429,8 +461,8 @@
 .ui-carousel__prev::before,
 .ui-carousel__next::before {
   block-size: 0.5rem;
-  border-block-start: 1.5px solid currentColor;
-  border-inline-end: 1.5px solid currentColor;
+  border-block-start: 1.5px solid currentcolor;
+  border-inline-end: 1.5px solid currentcolor;
   content: '';
   inline-size: 0.5rem;
 }

package/css/dots.css

@@ -281,6 +281,13 @@
   transform: rotate(315deg) translateY(calc(var(--ds-box) / -2 + var(--ds-dot) / 2));
 }
 
+/* The comet expects exactly 8 `<i>`; a 9th+ child has no rotation rule and
+   would pile up dead-centre. Hide the overflow so extra children fail safe
+   rather than rendering a stray static dot (C26). */
+.ui-dotspinner i:nth-child(n + 9) {
+  display: none;
+}
+
 .ui-dotspinner--sm {
   --ds-box: 1.05rem;
   --ds-dot: 0.18rem;
@@ -370,3 +377,53 @@
     clip-path: none;
   }
 }
+
+/* Forced-colors (Windows HCM): semantic status dots and hot/accent matrix
+   cells encode meaning purely via background-color, which collapses to one
+   system colour under HCM (WCAG 1.4.1). Opt out of forced-color remapping and
+   apply four visually-distinct system colours so the signals stay
+   differentiable. */
+@media (forced-colors: active) {
+  .ui-dot--success {
+    forced-color-adjust: none;
+    background: LinkText;
+  }
+
+  .ui-dot--warning {
+    forced-color-adjust: none;
+    background: Mark;
+  }
+
+  .ui-dot--danger {
+    forced-color-adjust: none;
+    background: Highlight;
+  }
+
+  .ui-dot--info {
+    forced-color-adjust: none;
+    background: ButtonText;
+  }
+
+  .ui-dotmatrix__cell--hot {
+    forced-color-adjust: none;
+    background: Highlight;
+  }
+
+  .ui-dotmatrix__cell--accent {
+    forced-color-adjust: none;
+    background: LinkText;
+  }
+}
+
+/* Print: the dot surfaces carry data (heatmap cells, the segmented meter, the
+   status dot, the masked glyph), so their painted fills must survive the print
+   "economy" default that drops backgrounds. */
+@media print {
+  .ui-dotmatrix__cell,
+  .ui-dotbar i,
+  .ui-dot,
+  .ui-icon {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+}