@ponchia/ui 0.6.6 → 0.6.8

package/connectors/index.js

@@ -48,12 +48,26 @@
 // builders below.
 export const PRECISION = 1000;
 
+/**
+ * Resolve a numeric option with an optional fallback.
+ * @param {string} name
+ * @param {number | null | undefined} value
+ * @param {number | null | undefined} [fallback]
+ * @returns {number}
+ */
 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;
 }
 
+/**
+ * Resolve a non-negative numeric option with an optional fallback.
+ * @param {string} name
+ * @param {number | null | undefined} value
+ * @param {number | null | undefined} [fallback]
+ * @returns {number}
+ */
 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`);
@@ -63,26 +77,64 @@ export function dimension(name, value, fallback) {
 // 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.)
+/**
+ * @param {number} value
+ * @returns {number}
+ */
 export function roundNumber(value) {
   const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
   return Object.is(rounded, -0) ? 0 : rounded;
 }
 
+/**
+ * @param {number} value
+ * @returns {string}
+ */
 export function fmt(value) {
   return String(roundNumber(value));
 }
 
+/**
+ * @param {number} x
+ * @param {number} y
+ * @returns {string}
+ */
 export function point(x, y) {
   return `${fmt(x)},${fmt(y)}`;
 }
 
 // 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.
+/**
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
 export function clamp(value, min, max) {
   if (max < min) return min;
   return Math.min(max, Math.max(min, value));
 }
 
+function connectorShape(value) {
+  const shape = value ?? 'straight';
+  if (shape === 'straight' || shape === 'elbow' || shape === 'curve') return shape;
+  throw new TypeError('shape must be "straight", "elbow" or "curve"');
+}
+
+function sideValue(value) {
+  const side = value ?? 'center';
+  if (
+    side === 'top' ||
+    side === 'right' ||
+    side === 'bottom' ||
+    side === 'left' ||
+    side === 'center'
+  )
+    return side;
+  throw new TypeError('side must be "top", "right", "bottom", "left" or "center"');
+}
+
 /**
  * A point on a rect's edge (or centre). `rect` is `{ x, y, width, height }`.
  * @param {Rect} rect
@@ -90,11 +142,11 @@ export function clamp(value, min, max) {
  * @returns {Point}
  */
 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) {
+  const x = finite('rect.x', rect?.x);
+  const y = finite('rect.y', rect?.y);
+  const w = dimension('rect.width', rect?.width);
+  const h = dimension('rect.height', rect?.height);
+  switch (sideValue(side)) {
     case 'top':
       return { x: x + w / 2, y };
     case 'bottom':
@@ -185,7 +237,8 @@ export function curvePath(from, to, opts = {}) {
  * @returns {string}
  */
 export function connectorPath(opts = {}) {
-  const { from, to, shape = 'straight' } = opts;
+  const { from, to } = opts;
+  const shape = connectorShape(opts.shape);
   if (shape === 'elbow') return elbowPath(from, to, opts);
   if (shape === 'curve') return curvePath(from, to, opts);
   return straightPath(from, to);
@@ -270,7 +323,8 @@ export function autoSides(fromRect, toRect) {
  * @returns {number}
  */
 export function endTangentAngle(from, to, shape = 'straight') {
-  if (shape === 'straight') return angleBetween(from, to);
+  const resolved = connectorShape(shape);
+  if (resolved === '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;
@@ -285,10 +339,14 @@ export function endTangentAngle(from, to, shape = 'straight') {
  * @returns {ConnectRectsResult}
  */
 export function connectRects(opts = {}) {
-  const { fromRect, toRect, shape = 'straight', curvature, mid } = opts;
+  const { fromRect, toRect, curvature, mid } = opts;
+  const shape = connectorShape(opts.shape);
   // 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 sides = {
+    from: opts.fromSide == null ? auto.from : sideValue(opts.fromSide),
+    to: opts.toSide == null ? auto.to : sideValue(opts.toSide),
+  };
   const from = anchorPoint(fromRect, sides.from);
   const to = anchorPoint(toRect, sides.to);
   const d = connectorPath({ from, to, shape, curvature, mid });

package/css/analytical.css

@@ -1,7 +1,7 @@
 /* ==========================================================================
    analytical — convenience roll-up of the opt-in analytical-primitive layers.
 
-   Import this one file instead of the seven leaves when you're building
+   Import this one file instead of the nine leaves when you're building
    analytical / generated-report UI:
 
      @import '@ponchia/ui';
@@ -13,9 +13,11 @@
    ========================================================================== */
 
 @import url('./annotations.css') layer(bronto);
+@import url('./figure.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);
+@import url('./highlights.css') layer(bronto);

package/css/annotations.css

@@ -278,8 +278,20 @@
     animation: none !important;
     opacity: 1;
     stroke-dashoffset: 0;
+  }
+
+  .ui-annotation__subject,
+  .ui-annotation__connector,
+  .ui-annotation__note-line,
+  .ui-annotation__badge {
     transform: none;
   }
+
+  .ui-annotation--draw .ui-annotation__connector,
+  .ui-annotation--draw .ui-annotation__note-line {
+    stroke-dasharray: none;
+    stroke-dashoffset: 0;
+  }
 }
 
 @media (forced-colors: active) {

package/css/app.css

@@ -1,6 +1,6 @@
 /* ==========================================================================
-   app — admin shell (sidebar + topbar + panels + metrics)
-   For admin / operator dashboards.
+   app — service shell (sidebar + topbar + panels + metrics)
+   For app, service, admin, and operator dashboards.
    ========================================================================== */
 
 .ui-app-shell {
@@ -103,7 +103,7 @@
 .ui-app-nav a[aria-current]:not([aria-current='false']) {
   background: var(--accent-soft);
   border-inline-start-color: var(--accent);
-  color: var(--accent-text);
+  color: var(--text);
 }
 
 @media (pointer: coarse) {
@@ -257,7 +257,7 @@
 /* --- Metric tiles ---
    The metric primitive itself is shell-agnostic and now lives in
    primitives.css as `.ui-stat` / `.ui-statgrid`; `.ui-app-metric*` and
-   `.ui-app-metrics` remain as permanent admin-shell aliases (grouped on
+   `.ui-app-metrics` remain as permanent app-shell aliases (grouped on
    the canonical rules there — identical output). Nothing app-specific
    left to define here. */
 

package/css/clamp.css

@@ -0,0 +1,92 @@
+/* ==========================================================================
+   clamp — opt-in bounded excerpt + reveal.
+
+   For source excerpts, claim basis, caveats, and evidence text that should
+   scan as a bounded block but remain reachable. Bronto owns the visual clamp
+   and optional CSS-only reveal affordance; the host owns content, IDs, and
+   whether truncation is appropriate. Not imported by core.css.
+   ========================================================================== */
+
+.ui-clamp {
+  --clamp-lines: 4;
+
+  display: grid;
+  gap: var(--space-2xs);
+  min-inline-size: 0;
+  position: relative;
+}
+
+.ui-clamp__body {
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: var(--clamp-lines);
+  display: -webkit-box;
+  line-clamp: var(--clamp-lines);
+  mask-image: linear-gradient(to bottom, #000 72%, transparent 100%);
+  overflow: hidden;
+}
+
+.ui-clamp:has(> .ui-clamp__toggle:checked) .ui-clamp__body {
+  -webkit-line-clamp: unset;
+  display: block;
+  line-clamp: none;
+  mask-image: none;
+}
+
+.ui-clamp__toggle {
+  block-size: 1px;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  overflow: hidden;
+  position: absolute;
+  white-space: nowrap;
+}
+
+.ui-clamp__control {
+  color: var(--accent-text);
+  cursor: pointer;
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  inline-size: max-content;
+  letter-spacing: var(--tracking-wide);
+  text-decoration: underline;
+  text-decoration-color: color-mix(in srgb, var(--accent) 55%, transparent);
+  text-underline-offset: 0.2rem;
+  text-transform: uppercase;
+}
+
+.ui-clamp__toggle:focus-visible + .ui-clamp__body + .ui-clamp__control {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.ui-clamp__less {
+  display: none;
+}
+
+.ui-clamp:has(> .ui-clamp__toggle:checked) .ui-clamp__more {
+  display: none;
+}
+
+.ui-clamp:has(> .ui-clamp__toggle:checked) .ui-clamp__less {
+  display: inline;
+}
+
+@media (hover: hover) {
+  .ui-clamp__control:hover {
+    text-decoration-color: currentColor;
+  }
+}
+
+@media print {
+  .ui-clamp__body {
+    -webkit-line-clamp: unset;
+    display: block;
+    line-clamp: none;
+    mask-image: none;
+  }
+
+  .ui-clamp__toggle,
+  .ui-clamp__control {
+    display: none;
+  }
+}

package/css/crosshair.css

@@ -13,6 +13,9 @@
   --crosshair-x: 0;
   --crosshair-y: 0;
   --crosshair-color: var(--accent);
+  --crosshair-readout-gap: 0.35rem;
+  --crosshair-readout-x: var(--crosshair-readout-gap);
+  --crosshair-readout-y: var(--crosshair-readout-gap);
 
   inset: 0;
   opacity: 0;
@@ -25,6 +28,22 @@
   opacity: 1;
 }
 
+.ui-crosshair[data-readout-inline='before'] {
+  --crosshair-readout-x: calc(-100% - var(--crosshair-readout-gap));
+}
+
+.ui-crosshair[data-readout-block='above'] {
+  --crosshair-readout-y: calc(-100% - var(--crosshair-readout-gap));
+}
+
+.ui-crosshair:dir(rtl) {
+  --crosshair-readout-x: calc(100% + var(--crosshair-readout-gap));
+}
+
+.ui-crosshair:dir(rtl)[data-readout-inline='before'] {
+  --crosshair-readout-x: calc(-1 * var(--crosshair-readout-gap));
+}
+
 @media (prefers-reduced-motion: reduce) {
   .ui-crosshair {
     transition: none;
@@ -76,8 +95,9 @@
   color: var(--text);
 }
 
-/* A pinned readout chip — host fills the content; it follows the crosshair. */
-.ui-readout {
+/* A pinned readout chip — host fills the content; it follows the crosshair.
+   Scoped so report-kit/crosshair imports do not restyle standalone dot readouts. */
+.ui-crosshair .ui-readout {
   background: var(--panel);
   border: 1px solid var(--line);
   border-radius: var(--radius-sm);
@@ -87,10 +107,15 @@
   font-size: var(--text-xs);
   inset-block-start: var(--crosshair-y);
   inset-inline-start: var(--crosshair-x);
+  max-inline-size: calc(100% - var(--crosshair-readout-gap) * 2);
+  overflow: hidden;
   padding-block: 0.2rem;
   padding-inline: 0.4rem;
   pointer-events: none;
   position: absolute;
+  text-overflow: ellipsis;
+  transform: translate(var(--crosshair-readout-x), var(--crosshair-readout-y));
+  white-space: nowrap;
 }
 
 @media (forced-colors: active) {

package/css/feedback.css

@@ -335,9 +335,7 @@
   position: absolute;
   text-transform: uppercase;
   transform: translate(-50%, 4px);
-  transition:
-    opacity var(--duration-fast) var(--ease-standard),
-    transform var(--duration-fast) var(--ease-standard);
+  transition: opacity var(--duration-fast) var(--ease-standard);
   white-space: nowrap;
   z-index: var(--z-popover);
 }
@@ -348,33 +346,6 @@
   transform: translate(-50%, 0);
 }
 
-/* Progressive enhancement: where CSS anchor positioning exists, lift
-   the bubble out of the normal flow so it can't be clipped by an
-   ancestor's overflow/scroll and auto-flips at the viewport edge.
-   Unsupported browsers keep the absolutely-positioned fallback above
-   (fine for short labels; use .ui-popover + initPopover for rich or
-   edge-critical content). */
-@supports (anchor-name: --x) {
-  .ui-tooltip {
-    anchor-name: --ui-tooltip;
-  }
-
-  .ui-tooltip__bubble {
-    inset: auto;
-    margin-block-end: 0.5rem;
-    position: fixed;
-    position-anchor: --ui-tooltip;
-    position-area: block-start center;
-    position-try-fallbacks: flip-block;
-    transform: translateY(4px);
-  }
-
-  .ui-tooltip:hover .ui-tooltip__bubble,
-  .ui-tooltip:focus-within .ui-tooltip__bubble {
-    transform: translateY(0);
-  }
-}
-
 /* Popover surface — a top-layer panel positioned by initPopover (JS
    collision-aware, dependency-free). Uses the native [popover] top
    layer when available so it never clips; the class styles it either
@@ -389,6 +360,7 @@
   inline-size: max-content;
   margin: 0;
   max-inline-size: min(22rem, calc(100vw - 2rem));
+  overflow: auto;
   padding: var(--space-sm) var(--space-md);
   position: fixed;
   z-index: var(--z-popover);

package/css/figure.css

@@ -0,0 +1,102 @@
+/* ==========================================================================
+   figure — opt-in analytical/report figure stage.
+
+   A frame for chart/diagram/media evidence: caption, stable stage, optional
+   overlay, key, and fallback data. Bronto owns only the layout grammar. The
+   host still owns data, scales, chart rendering, annotation content, and the
+   fallback table. Not imported by core.css.
+   ========================================================================== */
+
+.ui-figure {
+  display: grid;
+  gap: var(--space-sm);
+  margin: 0;
+  min-inline-size: 0;
+}
+
+.ui-figure > *,
+.ui-figure__body > *,
+.ui-figure__stage > * {
+  min-inline-size: 0;
+}
+
+.ui-figure__caption {
+  color: var(--text-dim);
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  letter-spacing: 0;
+  line-height: 1.5;
+  text-transform: uppercase;
+}
+
+.ui-figure__body {
+  align-items: start;
+  display: grid;
+  gap: var(--space-sm);
+}
+
+.ui-figure__body--key-right {
+  grid-template-columns: minmax(0, 1fr) minmax(min(100%, 10rem), var(--figure-key-width, 14rem));
+}
+
+.ui-figure__stage {
+  --figure-max-inline: 42rem;
+  --figure-min-block: 0px;
+
+  display: grid;
+  inline-size: min(100%, var(--figure-max-inline));
+  margin-inline: auto;
+  min-block-size: var(--figure-min-block);
+  place-items: center;
+  position: relative;
+}
+
+.ui-figure__media {
+  display: block;
+  inline-size: 100%;
+  max-inline-size: 100%;
+}
+
+.ui-figure__stage > :is(canvas, img, picture, svg):not(.ui-figure__overlay) {
+  display: block;
+  max-inline-size: 100%;
+}
+
+.ui-figure__overlay {
+  block-size: 100%;
+  inline-size: 100%;
+  inset: 0;
+  overflow: visible;
+  pointer-events: none;
+  position: absolute;
+}
+
+.ui-figure__key,
+.ui-figure__data {
+  display: grid;
+  gap: var(--space-xs);
+}
+
+.ui-figure__data {
+  margin-block-start: var(--space-xs);
+}
+
+@media (max-width: 44rem) {
+  .ui-figure__body--key-right {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media print {
+  .ui-figure {
+    break-inside: avoid;
+  }
+
+  .ui-figure__body {
+    display: block;
+  }
+
+  .ui-figure__body > * + * {
+    margin-block-start: var(--space-sm);
+  }
+}

package/css/highlights.css

@@ -0,0 +1,50 @@
+/* ==========================================================================
+   highlights — opt-in CSS Custom Highlight API paint.
+
+   Named text ranges for cited evidence, search hits, and current match. The
+   HOST creates Range objects and registers Highlight instances in CSS.highlights
+   under the documented names. Bronto only paints the registered ranges. Not
+   imported by core.css.
+   ========================================================================== */
+
+.ui-highlights {
+  --highlight-evidence: var(--accent-soft);
+  --highlight-search: var(--warning-soft);
+  --highlight-current: color-mix(in srgb, var(--accent) 22%, transparent);
+}
+
+.ui-highlights::highlight(bronto-evidence) {
+  background-color: var(--highlight-evidence);
+  color: inherit;
+  text-decoration-color: var(--accent);
+  text-decoration-line: underline;
+  text-decoration-thickness: 0.1em;
+  text-underline-offset: 0.18em;
+}
+
+.ui-highlights::highlight(bronto-search) {
+  background-color: var(--highlight-search);
+  color: inherit;
+}
+
+.ui-highlights::highlight(bronto-current) {
+  background-color: var(--highlight-current);
+  color: var(--text);
+}
+
+@media (forced-colors: active) {
+  .ui-highlights::highlight(bronto-evidence),
+  .ui-highlights::highlight(bronto-search),
+  .ui-highlights::highlight(bronto-current) {
+    background-color: Highlight;
+    color: HighlightText;
+    text-decoration-color: HighlightText;
+  }
+}
+
+@media print {
+  .ui-highlights {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+}

package/css/interval.css

@@ -0,0 +1,90 @@
+/* ==========================================================================
+   interval — opt-in low/high uncertainty span.
+
+   A compact report primitive for "the value is somewhere in this range" —
+   confidence intervals, estimates, budget windows, and measured uncertainty.
+   Boundary: the HOST normalises `--lo`, `--hi`, and optional `--v` to 0..1 and
+   writes the accessible label. Bronto only paints geometry. Not imported by
+   core.css.
+   ========================================================================== */
+
+.ui-interval {
+  --lo: 0;
+  --hi: 1;
+
+  display: grid;
+  gap: 0.35rem;
+  inline-size: 100%;
+  min-inline-size: 0;
+}
+
+.ui-interval__track {
+  background: var(--surface-4);
+  block-size: 0.7rem;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-pill);
+  min-inline-size: 8rem;
+  position: relative;
+}
+
+.ui-interval__range {
+  background: color-mix(in srgb, var(--accent) 26%, transparent);
+  border: 1px solid color-mix(in srgb, var(--accent) 58%, var(--line));
+  border-radius: var(--radius-pill);
+  inline-size: max(2px, calc((var(--hi) - var(--lo)) * 100%));
+  inset-block: 18%;
+  inset-inline-start: calc(var(--lo) * 100%);
+  position: absolute;
+}
+
+.ui-interval__point {
+  background: var(--text);
+  border: 2px solid var(--panel);
+  border-radius: 50%;
+  block-size: 0.72rem;
+  box-shadow: 0 0 0 1px var(--line-strong);
+  inline-size: 0.72rem;
+  inset-block-start: 50%;
+  inset-inline-start: calc(var(--v, var(--lo)) * 100%);
+  position: absolute;
+  transform: translate(-50%, -50%);
+}
+
+.ui-interval__label,
+.ui-interval__bounds {
+  color: var(--text-dim);
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  letter-spacing: 0;
+}
+
+.ui-interval__label {
+  color: var(--text-soft);
+}
+
+.ui-interval__bounds {
+  display: flex;
+  gap: var(--space-sm);
+  justify-content: space-between;
+}
+
+@media (forced-colors: active) {
+  .ui-interval__track,
+  .ui-interval__range,
+  .ui-interval__point {
+    border-color: CanvasText;
+  }
+
+  .ui-interval__range,
+  .ui-interval__point {
+    background: CanvasText;
+  }
+}
+
+@media print {
+  .ui-interval__range,
+  .ui-interval__point {
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+}

package/css/navigation.css

@@ -70,6 +70,18 @@
   transform: translateX(0.6rem);
 }
 
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme='light']) .ui-themetoggle__thumb {
+    background: var(--accent);
+    transform: translateX(0.6rem);
+  }
+
+  :root[dir='rtl']:not([data-theme='light']) .ui-themetoggle__thumb,
+  :root:not([data-theme='light']) [dir='rtl'] .ui-themetoggle__thumb {
+    transform: translateX(-0.6rem);
+  }
+}
+
 [dir='rtl'][data-theme='dark'] .ui-themetoggle__thumb,
 [dir='rtl'] [data-theme='dark'] .ui-themetoggle__thumb {
   transform: translateX(-0.6rem);

package/css/primitives.css

@@ -569,9 +569,8 @@
 }
 
 .ui-chip--accent {
-  /* accent-strong, not accent: chip text is small uppercase mono and must
-     clear WCAG AA 4.5:1 — same rule as .ui-eyebrow above. */
-  color: var(--accent-text);
+  /* Tone rides the border + hover tint; text stays neutral-readable. */
+  color: var(--text-soft);
   border-color: var(--accent);
 }