@ponchia/ui 0.5.0 → 0.6.0

package/annotations/index.js

@@ -1,47 +1,229 @@
 // Shared SVG geometry primitives live in the connectors kernel; annotations
 // (figure callouts) build on them so a line/curve/arrow/dot is drawn one way.
+
+/**
+ * @ponchia/ui — SVG annotation geometry helpers.
+ *
+ * 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 }} AnnotationPoint
+ * @typedef {{ dx: number, dy: number }} AnnotationOffset
+ * @typedef {'callout' | 'elbow' | 'curve'} AnnotationConnectorType
+ * @typedef {'start' | 'middle' | 'end'} AnnotationAlign
+ * @typedef {'top' | 'middle' | 'bottom'} AnnotationValign
+ * @typedef {'horizontal' | 'vertical'} AxisOrientation
+ * @typedef {'up' | 'down' | 'left' | 'right'} TimelineDirection
+ *
+ * @typedef {object} CircleSubject
+ * @property {'circle'} type
+ * @property {number} radius
+ * @property {number} [radiusPadding]
+ *
+ * @typedef {object} RectSubject
+ * @property {'rect'} type
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [padding]
+ *
+ * @typedef {CircleSubject | RectSubject} ConnectorSubject
+ *
+ * @typedef {AnnotationOffset & { subject?: ConnectorSubject, mid?: number }} ConnectorOptions
+ *
+ * @typedef {object} CircleSubjectOptions
+ * @property {number} radius
+ *
+ * @typedef {object} RectSubjectOptions
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [padding]
+ *
+ * @typedef {object} ThresholdOptions
+ * @property {number} [x1]
+ * @property {number} [y1]
+ * @property {number} x2
+ * @property {number} y2
+ *
+ * @typedef {object} AxisThresholdOptions
+ * @property {AxisOrientation} [orientation]
+ * @property {number} [value]
+ * @property {number} [start]
+ * @property {number} end
+ *
+ * @typedef {object} BracketSubjectOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [depth]
+ *
+ * @typedef {object} BandSubjectOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ * @property {number} [padding]
+ *
+ * @typedef {object} SlopeSubjectOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ *
+ * @typedef {object} ComparisonBraceOptions
+ * @property {number} x1
+ * @property {number} y1
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [depth]
+ *
+ * @typedef {object} OutlierClusterOptions
+ * @property {AnnotationPoint[]} points
+ * @property {number} [radius]
+ *
+ * @typedef {object} TimelineEventOptions
+ * @property {number} [size]
+ * @property {TimelineDirection} [direction]
+ *
+ * @typedef {object} EvidenceMarkerOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {number} [padding]
+ *
+ * @typedef {AnnotationPoint & { radius?: number }} ConnectorEndDotOptions
+ *
+ * @typedef {object} ConnectorEndArrowOptions
+ * @property {number} [x1]
+ * @property {number} [y1]
+ * @property {number} x2
+ * @property {number} y2
+ * @property {number} [size]
+ * @property {number} [spread] Half-angle of the arrowhead in radians (default
+ *   0.32 ≈ a crisp 37° included angle). Larger = blunter.
+ *
+ * @typedef {object} NoteTransformOptions
+ * @property {number} [dx]
+ * @property {number} [dy]
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {AnnotationAlign} [align]
+ * @property {AnnotationValign} [valign]
+ * @property {number} [width]
+ * @property {number} [height]
+ *
+ * @typedef {object} AnnotationBounds
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ *
+ * @typedef {object} NotePlacementOptions
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} width
+ * @property {number} height
+ * @property {AnnotationBounds} bounds
+ * @property {number} [padding]
+ * @property {number} [gap]
+ * @property {'right' | 'left' | 'top' | 'bottom'} [preferred]
+ * @property {number} [inset] Extra margin (user units) the note must keep from
+ *   the bounds edge, on top of `padding`. Reserve the note's title stroke-halo
+ *   (~3) or a leader stub so a placement that "fits" doesn't clip. Default 0.
+ *
+ * @typedef {object} NotePlacement
+ * @property {number} dx
+ * @property {number} dy
+ * @property {AnnotationAlign} align
+ * @property {AnnotationValign} valign
+ * @property {string} transform
+ *
+ * @typedef {(
+ *   | CircleSubject
+ *   | RectSubject
+ *   | ({ type: 'threshold' } & ThresholdOptions)
+ *   | ({ type: 'bracket' } & BracketSubjectOptions)
+ *   | ({ type: 'band' } & BandSubjectOptions)
+ *   | ({ type: 'slope' } & SlopeSubjectOptions)
+ *   | ({ type: 'compare' } & ComparisonBraceOptions)
+ *   | ({ type: 'cluster' } & OutlierClusterOptions)
+ *   | ({ type: 'axis' } & AxisThresholdOptions)
+ *   | ({ type: 'timeline' } & TimelineEventOptions)
+ *   | ({ type: 'evidence' } & EvidenceMarkerOptions)
+ * )} AnnotationPartsSubject
+ *
+ * @typedef {object} AnnotationPartsOptions
+ * @property {AnnotationConnectorType} [type]
+ * @property {number} [x]
+ * @property {number} [y]
+ * @property {number} [dx]
+ * @property {number} [dy]
+ * @property {AnnotationPartsSubject} [subject]
+ *
+ * @typedef {object} AnnotationParts
+ * @property {string} transform
+ * @property {string} subject
+ * @property {string} connector
+ * @property {string} note
+ *
+ * @typedef {object} DeclutterLabelItem
+ * @property {number} pos Desired centre coordinate along the axis.
+ * @property {number} size The label's extent along the axis.
+ *
+ * @typedef {object} DeclutterLabelsOptions
+ * @property {number} [gap] Minimum gap kept between adjacent labels. Default 0.
+ * @property {number} [min] Lower bound of the axis. Default -Infinity.
+ * @property {number} [max] Upper bound of the axis. Default Infinity.
+ *
+ * @typedef {object} DirectLabelItem
+ * @property {AnnotationPoint} anchor The true data point the label refers to (figure coordinates).
+ * @property {number} size The label's extent along the layout axis.
+ * @property {string | number} [key] Optional identifier, echoed back on the matching output (input order).
+ *
+ * @typedef {object} DirectLabelsOptions
+ * @property {'x' | 'y'} [axis] Axis the labels declutter along. 'y' = a vertical column. Default 'y'.
+ * @property {number} [cross] Fixed coordinate on the other axis where the label column/row sits. Default 0.
+ * @property {number} [gap] Minimum gap kept between adjacent labels. Default 0.
+ * @property {number} [min] Lower bound of the layout axis. Default -Infinity.
+ * @property {number} [max] Upper bound of the layout axis. Default Infinity.
+ * @property {'straight' | 'elbow' | 'curve'} [shape] Leader-line shape. Default 'straight'.
+ *
+ * @typedef {object} DirectLabel
+ * @property {number} x Placed label point — the leader's label-side end.
+ * @property {number} y
+ * @property {AnnotationPoint} anchor The echoed input anchor.
+ * @property {string | number} [key] The echoed input key, if any.
+ * @property {string} d SVG path for the leader (anchor → label point); '' if they coincide.
+ */
+
 import {
   straightPath,
   curvePath,
   connectorPath,
+  elbowPath,
   arrowHead,
   dotMark,
   angleBetween,
+  // Shared scalar/geometry kernel — single source of truth (was copy-pasted,
+  // and the local clamp had silently diverged from the connectors one).
+  PRECISION,
+  finite,
+  dimension,
+  fmt,
+  point,
+  clamp,
 } from '../connectors/index.js';
 
-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 roundedNumber(value) {
   const rounded = Math.round((Object.is(value, -0) ? 0 : value) * PRECISION) / PRECISION;
   return Object.is(rounded, -0) ? 0 : rounded;
 }
 
-function point(x, y) {
-  return `${fmt(x)},${fmt(y)}`;
-}
-
-function clamp(value, min, max) {
-  if (max < min) return min;
-  return Math.min(max, Math.max(min, value));
-}
-
 function circlePathAt(x, y, radius) {
   const r = dimension('radius', radius);
   if (r === 0) return '';
@@ -106,10 +288,18 @@ function linePath(start, end) {
   return `M${point(start.x, start.y)}L${point(end.x, end.y)}`;
 }
 
+/**
+ * @param {Partial<AnnotationPoint>} [point]
+ * @returns {string}
+ */
 export function annotationTransform({ x = 0, y = 0 } = {}) {
   return `translate(${fmt(finite('x', x))}, ${fmt(finite('y', y))})`;
 }
 
+/**
+ * @param {NoteTransformOptions} [options]
+ * @returns {string}
+ */
 export function noteTransform({
   dx,
   dy,
@@ -172,6 +362,10 @@ function noteRect(x, y, width, height, placement) {
   };
 }
 
+/**
+ * @param {NotePlacementOptions} options
+ * @returns {NotePlacement}
+ */
 export function notePlacement({
   x = 0,
   y = 0,
@@ -181,6 +375,7 @@ export function notePlacement({
   padding = 8,
   gap = 32,
   preferred = 'right',
+  inset = 0,
 } = {}) {
   const anchorX = finite('x', x);
   const anchorY = finite('y', y);
@@ -188,14 +383,17 @@ export function notePlacement({
   const h = dimension('height', height);
   const p = dimension('padding', padding);
   const g = dimension('gap', gap);
+  const ins = dimension('inset', inset, 0);
   const bx = finite('bounds.x', bounds?.x, 0);
   const by = finite('bounds.y', bounds?.y, 0);
   const bw = dimension('bounds.width', bounds?.width);
   const bh = dimension('bounds.height', bounds?.height);
-  const minX = bx + p;
-  const minY = by + p;
-  const maxX = bx + bw - p;
-  const maxY = by + bh - p;
+  // `inset` reserves an extra margin (e.g. the title stroke-halo) inside the
+  // padded bounds, so a placement that "just fits" doesn't clip the halo/leader.
+  const minX = bx + p + ins;
+  const minY = by + p + ins;
+  const maxX = bx + bw - p - ins;
+  const maxY = by + bh - p - ins;
 
   for (const side of placementOrder(preferred)) {
     const placement = candidatePlacement(side, g);
@@ -226,10 +424,18 @@ export function notePlacement({
   };
 }
 
+/**
+ * @param {CircleSubjectOptions} options
+ * @returns {string}
+ */
 export function circleSubjectPath({ radius } = {}) {
   return circlePathAt(0, 0, radius);
 }
 
+/**
+ * @param {RectSubjectOptions} options
+ * @returns {string}
+ */
 export function rectSubjectPath({ width, height, x, y, padding = 0 } = {}) {
   const w = dimension('width', width);
   const h = dimension('height', height);
@@ -242,12 +448,20 @@ export function rectSubjectPath({ width, height, x, y, padding = 0 } = {}) {
   return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
 }
 
+/**
+ * @param {ThresholdOptions} options
+ * @returns {string}
+ */
 export function thresholdPath({ x1 = 0, y1 = 0, x2, y2 } = {}) {
   const start = { x: finite('x1', x1), y: finite('y1', y1) };
   const end = { x: finite('x2', x2), y: finite('y2', y2) };
   return linePath(start, end);
 }
 
+/**
+ * @param {AxisThresholdOptions} options
+ * @returns {string}
+ */
 export function axisThresholdPath({ orientation = 'horizontal', value = 0, start = 0, end } = {}) {
   const v = finite('value', value);
   const s = finite('start', start);
@@ -257,6 +471,10 @@ export function axisThresholdPath({ orientation = 'horizontal', value = 0, start
   throw new TypeError('orientation must be "horizontal" or "vertical"');
 }
 
+/**
+ * @param {BracketSubjectOptions} options
+ * @returns {string}
+ */
 export function bracketSubjectPath({ x1, y1, x2, y2, depth = 12 } = {}) {
   const start = { x: finite('x1', x1), y: finite('y1', y1) };
   const end = { x: finite('x2', x2), y: finite('y2', y2) };
@@ -268,14 +486,26 @@ export function bracketSubjectPath({ x1, y1, x2, y2, depth = 12 } = {}) {
   return `M${point(start.x, start.y)}H${fmt(start.x + d)}V${fmt(end.y)}H${fmt(end.x)}`;
 }
 
+/**
+ * @param {BandSubjectOptions} options
+ * @returns {string}
+ */
 export function bandSubjectPath({ x = 0, y = 0, width, height, padding = 0 } = {}) {
   return rectSubjectPath({ x, y, width, height, padding });
 }
 
+/**
+ * @param {SlopeSubjectOptions} options
+ * @returns {string}
+ */
 export function slopeSubjectPath({ x1, y1, x2, y2 } = {}) {
   return thresholdPath({ x1, y1, x2, y2 });
 }
 
+/**
+ * @param {ComparisonBraceOptions} options
+ * @returns {string}
+ */
 export function comparisonBracePath({ x1, y1, x2, y2, depth = 14 } = {}) {
   const start = { x: finite('x1', x1), y: finite('y1', y1) };
   const end = { x: finite('x2', x2), y: finite('y2', y2) };
@@ -313,6 +543,10 @@ export function comparisonBracePath({ x1, y1, x2, y2, depth = 14 } = {}) {
   )} ${point(x, end.y)}`;
 }
 
+/**
+ * @param {OutlierClusterOptions} options
+ * @returns {string}
+ */
 export function outlierClusterPath({ points, radius = 6 } = {}) {
   if (!Array.isArray(points)) throw new TypeError('points must be an array');
   return points
@@ -323,6 +557,10 @@ export function outlierClusterPath({ points, radius = 6 } = {}) {
     .join('');
 }
 
+/**
+ * @param {TimelineEventOptions} [options]
+ * @returns {string}
+ */
 export function timelineEventPath({ size = 10, direction = 'down' } = {}) {
   const s = dimension('size', size);
   if (s === 0) return '';
@@ -333,6 +571,10 @@ export function timelineEventPath({ size = 10, direction = 'down' } = {}) {
   throw new TypeError('direction must be "up", "down", "left" or "right"');
 }
 
+/**
+ * @param {EvidenceMarkerOptions} [options]
+ * @returns {string}
+ */
 export function evidenceMarkerPath({ x = 0, y = 0, width = 36, height = 36, padding = 0 } = {}) {
   const w = dimension('width', width);
   const h = dimension('height', height);
@@ -347,18 +589,30 @@ export function evidenceMarkerPath({ x = 0, y = 0, width = 36, height = 36, padd
   return `M${point(left, top)}H${fmt(right)}V${fmt(bottom)}H${fmt(left)}Z`;
 }
 
+/**
+ * @param {ConnectorEndDotOptions} options
+ * @returns {string}
+ */
 export function connectorEndDot({ x, y, radius = 3 } = {}) {
   return dotMark({ x: finite('x', x), y: finite('y', y) }, radius);
 }
 
-export function connectorEndArrow({ x1 = 0, y1 = 0, x2, y2, size = 7 } = {}) {
+/**
+ * @param {ConnectorEndArrowOptions} options
+ * @returns {string}
+ */
+export function connectorEndArrow({ x1 = 0, y1 = 0, x2, y2, size = 8, spread = 0.32 } = {}) {
   const start = { x: finite('x1', x1), y: finite('y1', y1) };
   const end = { x: finite('x2', x2), y: finite('y2', y2) };
   const s = dimension('size', size);
   if (s === 0 || (end.x === start.x && end.y === start.y)) return '';
-  return arrowHead(end, angleBetween(start, end), s);
+  return arrowHead(end, angleBetween(start, end), s, spread);
 }
 
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
 export function connectorLine(opts = {}) {
   const { dx, dy } = validateOffset(opts);
   if (dx === 0 && dy === 0) return '';
@@ -370,25 +624,29 @@ export function connectorLine(opts = {}) {
   return straightPath(start, end);
 }
 
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
 export function connectorElbow(opts = {}) {
   const { dx, dy } = validateOffset(opts);
   if (dx === 0 && dy === 0) return '';
   const start = connectorStart(dx, dy, opts.subject);
   if (!start) return '';
   const end = { x: dx, y: dy };
-  const vx = end.x - start.x;
-  const vy = end.y - start.y;
-  if (vx === 0 || vy === 0) return linePath(start, end);
-
-  const elbow =
-    Math.abs(vx) >= Math.abs(vy)
-      ? { x: start.x + Math.sign(vx) * Math.abs(vy), y: end.y }
-      : { x: end.x, y: start.y + Math.sign(vy) * Math.abs(vx) };
-
-  if (samePoint(start, elbow) || samePoint(elbow, end)) return linePath(start, end);
-  return `M${point(start.x, start.y)}L${point(elbow.x, elbow.y)}L${point(end.x, end.y)}`;
+  if (samePoint(start, end)) return '';
+  // A true right-angle dogleg (H/V/H), turning on the dominant axis at `mid`
+  // (0..1, default 0.5). Delegated to the connectors geometry kernel so an
+  // annotation leader and a node connector draw the same elbow. (The former
+  // inline form turned by min(|dx|,|dy|), i.e. a 45° chamfer that read as a
+  // diagonal stub, not an elbow — which the `stroke-linejoin` bevel assumes.)
+  return elbowPath(start, end, { mid: opts.mid });
 }
 
+/**
+ * @param {ConnectorOptions} opts
+ * @returns {string}
+ */
 export function connectorCurve(opts = {}) {
   const { dx, dy } = validateOffset(opts);
   if (dx === 0 && dy === 0) return '';
@@ -400,6 +658,10 @@ export function connectorCurve(opts = {}) {
   return curvePath(start, end, { curvature: 0.35 });
 }
 
+/**
+ * @param {AnnotationPartsOptions} [opts]
+ * @returns {AnnotationParts}
+ */
 export function annotationParts(opts = {}) {
   const type = opts.type ?? 'callout';
   const transform = annotationTransform({ x: opts.x ?? 0, y: opts.y ?? 0 });
@@ -442,6 +704,10 @@ export function annotationParts(opts = {}) {
  * `items`: `[{ pos, size }]` — `pos` is the desired centre coordinate along the
  * axis, `size` the label's extent along it. Returns the adjusted centre per
  * input item, in the original order.
+ *
+ * @param {DeclutterLabelItem[]} items
+ * @param {DeclutterLabelsOptions} [opts]
+ * @returns {number[]}
  */
 export function declutterLabels(items, opts = {}) {
   if (!Array.isArray(items)) throw new TypeError('items must be an array');
@@ -488,6 +754,10 @@ export function declutterLabels(items, opts = {}) {
  * in input order, the placed label point `{x, y}`, the echoed `anchor` and
  * `key`, and the leader path `d` (anchor → label; `''` if they coincide) ready
  * for a `<path class="ui-annotation__connector">`.
+ *
+ * @param {DirectLabelItem[]} items
+ * @param {DirectLabelsOptions} [opts]
+ * @returns {DirectLabel[]}
  */
 export function directLabels(items, opts = {}) {
   if (!Array.isArray(items)) throw new TypeError('items must be an array');

package/behaviors/carousel.js

@@ -1,4 +1,11 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  scrollIntoViewSafe,
+  collectHosts,
+} from './internal.js';
 
 /**
  * Image carousel / gallery, built on CSS scroll-snap so touch + trackpad
@@ -25,10 +32,9 @@ import { hasDom, noop, bindOnce } from './internal.js';
  */
 export function initCarousel({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const boxes = [];
-  if (host !== document && host.matches?.('[data-bronto-carousel]')) boxes.push(host);
-  boxes.push(...(host.querySelectorAll?.('[data-bronto-carousel]') ?? []));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const boxes = collectHosts(host, '[data-bronto-carousel]');
   const cleanups = [];
 
   for (const box of boxes) {
@@ -103,16 +109,7 @@ export function initCarousel({ root } = {}) {
     const emit = () =>
       box.dispatchEvent(new CustomEvent('bronto:change', { detail: { index }, bubbles: true }));
 
-    // jsdom (and any layout-less env) has no scrollIntoView; it's a pure
-    // affordance, so never let it break index/aria sync — same guard as
-    // initCombobox.
-    const reveal = (el) => {
-      try {
-        el?.scrollIntoView({ block: 'nearest', inline: 'center' });
-      } catch {
-        /* no layout — ignore */
-      }
-    };
+    const reveal = (el) => scrollIntoViewSafe(el, { block: 'nearest', inline: 'center' });
 
     const goTo = (i, { emitChange = true } = {}) => {
       const next = loop ? (i + n) % n : Math.max(0, Math.min(n - 1, i));
@@ -176,13 +173,17 @@ export function initCarousel({ root } = {}) {
         },
         { root: viewport, threshold: 0.6 },
       );
-      slides.forEach((s) => io.observe(s));
     }
 
     render();
     const bound = bindOnce(box, 'carousel', () => {
       viewport.addEventListener('keydown', onKey);
       box.addEventListener('click', onClick);
+      // Observe inside the add callback so observe/disconnect pair with the
+      // binding lifecycle: a re-init tears down the prior binding (which
+      // disconnects the old observer) before this starts, so two observers
+      // never watch the same slides — even for one tick.
+      slides.forEach((s) => io?.observe(s));
       return () => {
         viewport.removeEventListener('keydown', onKey);
         box.removeEventListener('click', onClick);

package/behaviors/combobox.js

@@ -1,4 +1,13 @@
-import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  nextFieldUid,
+  scrollIntoViewSafe,
+  wrapIndex,
+  collectHosts,
+} from './internal.js';
 
 /**
  * Editable combobox with a filtered listbox popup, implementing the
@@ -6,6 +15,11 @@ import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
  * and consumers most often build badly). Dependency-free, no
  * positioning library — the list is CSS-anchored under the input.
  *
+ * The input MUST have an accessible name — a `<label>`, `aria-label`, or
+ * `aria-labelledby` (a placeholder does not count). A nameless `role="combobox"`
+ * is a silent screen-reader failure, so the behavior warns at dev time when it
+ * finds one, and mirrors the input's name onto the listbox.
+ *
  * Markup: `[data-bronto-combobox]` wrapping an `<input role="combobox">`
  * (`.ui-combobox__input`) and a `<ul role="listbox">`
  * (`.ui-combobox__list`) of `<li role="option">` (`.ui-combobox__option`,
@@ -16,13 +30,16 @@ import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
  * pointer select, and outside-click close; it emits a `bronto:change`
  * CustomEvent ({ detail: { value } }) on selection. SSR-safe,
  * idempotent per instance; returns a cleanup function.
+ *
+ * Options are read from the DOM at init; if you replace the listbox contents
+ * (e.g. async/remote results) without re-initialising, filtering and keyboard
+ * nav act on the stale nodes — re-run initCombobox after mutating the options.
  */
 export function initCombobox({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const boxes = [];
-  if (host !== document && host.matches?.('[data-bronto-combobox]')) boxes.push(host);
-  boxes.push(...(host.querySelectorAll?.('[data-bronto-combobox]') ?? []));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const boxes = collectHosts(host, '[data-bronto-combobox]');
   const cleanups = [];
 
   for (const box of boxes) {
@@ -38,6 +55,29 @@ export function initCombobox({ root } = {}) {
       o.setAttribute('role', 'option');
     });
     list.setAttribute('role', 'listbox');
+    // Give the listbox its own accessible name (a bare role=listbox is unnamed
+    // to a screen reader) by mirroring the input's name. (a11y review C30.)
+    if (!list.hasAttribute('aria-label') && !list.hasAttribute('aria-labelledby')) {
+      const name =
+        input.getAttribute('aria-label') ||
+        input.labels?.[0]?.textContent?.trim() ||
+        input.getAttribute('placeholder');
+      if (name) list.setAttribute('aria-label', name);
+    }
+    // A `role="combobox"` with no accessible name is a silent AT failure. A
+    // placeholder is not a robust name (it can vanish and is ignored by some
+    // AT), so warn unless there is a real label/aria-label/aria-labelledby/title
+    // (C7). We can't invent a good name, hence a dev-time warning, not a guess.
+    const inputNamed =
+      input.hasAttribute('aria-label') ||
+      input.hasAttribute('aria-labelledby') ||
+      !!input.labels?.length ||
+      input.hasAttribute('title');
+    if (!inputNamed && typeof console !== 'undefined') {
+      console.warn(
+        '[bronto] initCombobox(): the combobox input has no accessible name — add a <label>, aria-label, or aria-labelledby (a placeholder is not enough).',
+      );
+    }
     input.setAttribute('role', 'combobox');
     input.setAttribute('aria-controls', listId);
     input.setAttribute('aria-autocomplete', 'list');
@@ -53,13 +93,7 @@ export function initCombobox({ root } = {}) {
       if (opt) {
         opt.classList.add('is-active');
         input.setAttribute('aria-activedescendant', opt.id);
-        // jsdom's scrollIntoView throws "Not implemented"; it is a
-        // pure affordance, so never let it break keyboard nav.
-        try {
-          opt.scrollIntoView({ block: 'nearest' });
-        } catch {
-          /* non-DOM/headless environment — ignore */
-        }
+        scrollIntoViewSafe(opt);
       } else {
         input.removeAttribute('aria-activedescendant');
       }
@@ -112,10 +146,7 @@ export function initCombobox({ root } = {}) {
       const vis = visible();
       if (!vis.length) return;
       open();
-      const curIdx = vis.indexOf(options[active]);
-      let next = curIdx + delta;
-      if (next < 0) next = vis.length - 1;
-      if (next >= vis.length) next = 0;
+      const next = wrapIndex(vis.indexOf(options[active]), delta, vis.length);
       active = options.indexOf(vis[next]);
       setActive(options[active]);
     };