@ponchia/ui 0.4.0 → 0.5.0

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);

package/css/annotations.css

@@ -0,0 +1,292 @@
+/* ==========================================================================
+   annotations — opt-in SVG callouts for analytical figures.
+
+   Bronto-native take on the subject / connector / note grammar: SVG-first,
+   no runtime dependency, no authoring handles. Import only beside charts,
+   reports, or generated figures that need explicit callouts.
+   ========================================================================== */
+
+.ui-annotation {
+  --annotation-color: var(--accent);
+  --annotation-line: var(--line-strong);
+  --annotation-note-bg: var(--panel);
+  --annotation-subject-fill: color-mix(in srgb, var(--annotation-color) 8%, transparent);
+  --annotation-stroke-width: 1.5;
+
+  color: var(--annotation-color);
+  font-family: var(--mono);
+  font-size: var(--text-xs);
+  overflow: visible;
+}
+
+.ui-annotation--muted {
+  --annotation-color: var(--text-dim);
+  --annotation-line: var(--line);
+}
+
+.ui-annotation--accent {
+  --annotation-color: var(--accent);
+  --annotation-line: var(--line-strong);
+}
+
+.ui-annotation--success {
+  --annotation-color: var(--success);
+}
+
+.ui-annotation--warning {
+  --annotation-color: var(--warning);
+}
+
+.ui-annotation--danger {
+  --annotation-color: var(--danger);
+}
+
+.ui-annotation--info {
+  --annotation-color: var(--info);
+}
+
+.ui-annotation__subject,
+.ui-annotation__connector,
+.ui-annotation__connector-end,
+.ui-annotation__note-line,
+.ui-annotation__badge {
+  vector-effect: non-scaling-stroke;
+}
+
+.ui-annotation__subject {
+  fill: var(--annotation-subject-fill);
+  stroke: var(--annotation-color);
+  stroke-linejoin: miter;
+  stroke-width: var(--annotation-stroke-width);
+}
+
+.ui-annotation__connector,
+.ui-annotation__note-line {
+  fill: none;
+  stroke: var(--annotation-line);
+  stroke-linecap: square;
+  stroke-linejoin: miter;
+  stroke-opacity: 0.86;
+  stroke-width: var(--annotation-stroke-width);
+}
+
+.ui-annotation__connector-end {
+  fill: var(--annotation-line);
+  stroke: none;
+}
+
+.ui-annotation__note {
+  color: var(--text-soft);
+  fill: currentColor;
+}
+
+.ui-annotation__note > rect {
+  fill: var(--annotation-note-bg);
+  stroke: var(--line);
+  stroke-width: 1;
+  vector-effect: non-scaling-stroke;
+}
+
+.ui-annotation__title {
+  fill: var(--text);
+  font-size: var(--text-xs);
+  font-weight: 700;
+  letter-spacing: 0;
+  paint-order: stroke fill;
+  stroke: var(--annotation-note-bg);
+  stroke-linejoin: round;
+  stroke-width: 3;
+  text-transform: uppercase;
+}
+
+.ui-annotation__label {
+  fill: var(--text-soft);
+  font-size: var(--text-xs);
+  letter-spacing: 0;
+  paint-order: stroke fill;
+  stroke: var(--annotation-note-bg);
+  stroke-linejoin: round;
+  stroke-width: 3;
+}
+
+.ui-annotation__badge {
+  fill: var(--annotation-note-bg);
+  stroke: var(--annotation-color);
+  stroke-width: var(--annotation-stroke-width);
+}
+
+.ui-annotation--label .ui-annotation__subject,
+.ui-annotation--badge .ui-annotation__connector,
+.ui-annotation--badge .ui-annotation__note-line {
+  display: none;
+}
+
+.ui-annotation--callout .ui-annotation__note-line,
+.ui-annotation--elbow .ui-annotation__note-line,
+.ui-annotation--curve .ui-annotation__note-line {
+  stroke: var(--annotation-color);
+}
+
+.ui-annotation--elbow .ui-annotation__connector {
+  stroke-linejoin: bevel;
+}
+
+.ui-annotation--curve .ui-annotation__connector {
+  stroke-linecap: round;
+}
+
+.ui-annotation--circle .ui-annotation__subject {
+  stroke-dasharray: 0.01 4;
+  stroke-linecap: round;
+}
+
+.ui-annotation--rect .ui-annotation__subject {
+  stroke-dasharray: 5 3;
+}
+
+.ui-annotation--threshold .ui-annotation__subject {
+  fill: none;
+  stroke: var(--annotation-color);
+  stroke-dasharray: 6 4;
+}
+
+.ui-annotation--badge .ui-annotation__subject {
+  fill: var(--annotation-color);
+}
+
+.ui-annotation--badge .ui-annotation__badge {
+  fill: var(--annotation-color);
+}
+
+.ui-annotation--badge .ui-annotation__title,
+.ui-annotation--badge .ui-annotation__label {
+  fill: var(--button-text);
+  stroke: none;
+}
+
+.ui-annotation--bracket .ui-annotation__subject,
+.ui-annotation--compare .ui-annotation__subject,
+.ui-annotation--axis .ui-annotation__subject,
+.ui-annotation--timeline .ui-annotation__subject {
+  fill: none;
+  stroke: var(--annotation-color);
+  stroke-linecap: square;
+}
+
+.ui-annotation--band .ui-annotation__subject {
+  fill: var(--annotation-subject-fill);
+  stroke: var(--annotation-color);
+  stroke-dasharray: 5 3;
+}
+
+.ui-annotation--slope .ui-annotation__subject {
+  fill: none;
+  stroke: var(--annotation-color);
+  stroke-linecap: round;
+}
+
+.ui-annotation--cluster .ui-annotation__subject {
+  fill: var(--annotation-subject-fill);
+  stroke: var(--annotation-color);
+  stroke-dasharray: 0.01 5;
+  stroke-linecap: round;
+}
+
+.ui-annotation--evidence .ui-annotation__badge {
+  fill: var(--annotation-note-bg);
+  stroke: var(--annotation-color);
+}
+
+.ui-annotation--evidence .ui-annotation__title {
+  fill: var(--annotation-color);
+  stroke: none;
+}
+
+.ui-annotation--focus {
+  --annotation-stroke-width: 2;
+  --annotation-subject-fill: color-mix(in srgb, var(--annotation-color) 14%, transparent);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .ui-annotation--draw .ui-annotation__connector,
+  .ui-annotation--draw .ui-annotation__note-line {
+    animation: uiAnnotationDraw var(--duration-slow, 600ms) var(--ease-out, ease-out) both;
+    animation-delay: var(--annotation-delay, 0ms);
+    stroke-dasharray: var(--annotation-dash, 360);
+    stroke-dashoffset: var(--annotation-dash, 360);
+  }
+
+  .ui-annotation--draw .ui-annotation__subject,
+  .ui-annotation--draw .ui-annotation__badge {
+    animation: uiAnnotationSubjectReveal var(--duration-slow, 600ms) var(--ease-out, ease-out) both;
+    animation-delay: var(--annotation-delay, 0ms);
+  }
+
+  .ui-annotation--reveal .ui-annotation__note {
+    animation: uiAnnotationReveal var(--duration-slow, 600ms) var(--ease-out, ease-out) both;
+    animation-delay: var(--annotation-delay, 0ms);
+  }
+
+  .ui-annotation--pulse .ui-annotation__subject,
+  .ui-annotation--pulse .ui-annotation__badge {
+    animation: uiAnnotationPulse 1.6s var(--ease-out, ease-out) infinite;
+    animation-delay: var(--annotation-delay, 0ms);
+    transform-box: fill-box;
+    transform-origin: center;
+  }
+}
+
+@keyframes uiAnnotationDraw {
+  to {
+    stroke-dashoffset: 0;
+  }
+}
+
+@keyframes uiAnnotationSubjectReveal {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes uiAnnotationReveal {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes uiAnnotationPulse {
+  50% {
+    opacity: 0.62;
+    transform: scale(1.06);
+  }
+}
+
+@media print {
+  .ui-annotation__subject,
+  .ui-annotation__connector,
+  .ui-annotation__note,
+  .ui-annotation__note-line,
+  .ui-annotation__badge {
+    animation: none !important;
+    opacity: 1;
+    stroke-dashoffset: 0;
+    transform: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .ui-annotation {
+    --annotation-color: CanvasText;
+    --annotation-line: CanvasText;
+    --annotation-note-bg: Canvas;
+    --annotation-subject-fill: Canvas;
+  }
+}

package/css/command.css

@@ -0,0 +1,97 @@
+/* ==========================================================================
+   command — opt-in command-palette shell (the command-first tier).
+
+   A filter input over a listbox of commands, grouped, with shortcut hints. The
+   CSS shell only; `initCommand` (behaviors) does the filtering + roving focus +
+   selection event. Bronto navigates a DOM-authored list; the HOST owns the
+   action registry, routing, and execution. Open it yourself (e.g. inside a
+   native <dialog> via initDialog) — there is no global Cmd/Ctrl+K. Pairs with
+   the `.ui-shortcut` hint. Not imported by core.css.
+   ========================================================================== */
+
+.ui-command {
+  background: var(--panel-strong);
+  border: 1px solid var(--line-strong);
+  border-radius: var(--radius-md);
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  max-block-size: min(28rem, 70vh);
+  overflow: hidden;
+}
+
+.ui-command__input {
+  background: transparent;
+  border: 0;
+  border-block-end: 1px solid var(--line);
+  color: var(--text);
+  font-family: inherit;
+  font-size: var(--text-base);
+  inline-size: 100%;
+  padding: 0.85rem 1rem;
+}
+
+.ui-command__input::placeholder {
+  color: var(--text-dim);
+}
+
+.ui-command__list {
+  list-style: none;
+  margin: 0;
+  overflow-y: auto;
+  padding: var(--space-2xs);
+}
+
+.ui-command__group {
+  color: var(--text-dim);
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  letter-spacing: var(--tracking-wide);
+  padding: 0.5rem 0.6rem 0.25rem;
+  text-transform: uppercase;
+}
+
+.ui-command__item {
+  align-items: center;
+  border-radius: var(--radius-sm);
+  color: var(--text-soft);
+  cursor: pointer;
+  display: flex;
+  gap: 0.6rem;
+  padding: 0.5rem 0.6rem;
+}
+
+/* `display: flex` would otherwise beat the UA `[hidden]` rule, so a
+   filtered-out item stays visible — re-assert none for hidden items/groups. */
+.ui-command__item[hidden],
+.ui-command__group[hidden] {
+  display: none;
+}
+
+.ui-command__item.is-active {
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  color: var(--text);
+}
+
+.ui-command__shortcut {
+  color: var(--text-dim);
+  margin-inline-start: auto;
+}
+
+.ui-command__meta {
+  color: var(--text-dim);
+  font-family: var(--mono);
+  font-size: var(--text-2xs);
+  margin-inline-start: auto;
+}
+
+.ui-command__empty {
+  color: var(--text-dim);
+  padding: 0.85rem 1rem;
+}
+
+@media (forced-colors: active) {
+  .ui-command__item.is-active {
+    background: Highlight;
+    color: HighlightText;
+  }
+}

package/css/connectors.css

@@ -0,0 +1,93 @@
+/* ==========================================================================
+   connectors — opt-in leader lines between two DOM elements.
+
+   An overlay SVG (`.ui-connector`) sits inside a positioned container and draws
+   a line from one element to another — connect a note to a card, a card to a
+   chart point, two related regions. Bronto styles and (optionally, via
+   `initConnectors`) draws/tracks the line; the geometry helpers in
+   `@ponchia/ui/connectors` compute the path. Not imported by core.css.
+
+   Monochrome by default; the rationed accent and status tones are opt-in.
+   ========================================================================== */
+
+.ui-connector {
+  --connector-color: var(--line-strong);
+
+  color: var(--connector-color);
+  inset: 0;
+  overflow: visible;
+  pointer-events: none;
+  position: absolute;
+}
+
+.ui-connector__path {
+  fill: none;
+  stroke: var(--connector-color);
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  stroke-width: var(--connector-width, 1.5);
+  vector-effect: non-scaling-stroke;
+}
+
+.ui-connector__end {
+  fill: var(--connector-color);
+  stroke: none;
+}
+
+.ui-connector--dashed .ui-connector__path {
+  stroke-dasharray: 4 3;
+}
+
+.ui-connector--accent {
+  --connector-color: var(--accent);
+}
+
+.ui-connector--muted {
+  --connector-color: var(--line);
+}
+
+.ui-connector--success {
+  --connector-color: var(--success);
+}
+
+.ui-connector--warning {
+  --connector-color: var(--warning);
+}
+
+.ui-connector--danger {
+  --connector-color: var(--danger);
+}
+
+.ui-connector--info {
+  --connector-color: var(--info);
+}
+
+/* Draw-on: the path strokes in once. Requires pathLength="1" on the path
+   (initConnectors sets it); reduced motion shows the finished line. */
+@media (prefers-reduced-motion: no-preference) {
+  .ui-connector--draw .ui-connector__path {
+    animation: ui-connector-draw 0.6s ease both;
+    stroke-dasharray: 1;
+  }
+}
+
+@keyframes ui-connector-draw {
+  from {
+    stroke-dashoffset: 1;
+  }
+
+  to {
+    stroke-dashoffset: 0;
+  }
+}
+
+/* Forced colours: keep the line visible as a system colour. */
+@media (forced-colors: active) {
+  .ui-connector__path {
+    stroke: CanvasText;
+  }
+
+  .ui-connector__end {
+    fill: CanvasText;
+  }
+}