@ponchia/ui 0.5.0 → 0.6.0

package/behaviors/command.js

@@ -1,4 +1,13 @@
-import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
+import {
+  hasDom,
+  resolveHost,
+  noop,
+  bindOnce,
+  nextFieldUid,
+  collectHosts,
+  scrollIntoViewSafe,
+  wrapIndex,
+} from './internal.js';
 
 /**
  * Command palette — filter + keyboard-navigate a DOM-authored command list.
@@ -17,13 +26,15 @@ import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
  * select. It emits `bronto:command:select` ({ detail: { value, label } }) on
  * choose and `bronto:command:close` on Escape. SSR-safe, idempotent per
  * instance; returns a cleanup function.
+ *
+ * Items are read from the DOM at init; re-run initCommand after replacing the
+ * command list so filtering/navigation see the current nodes.
  */
 export function initCommand({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const palettes = [];
-  if (host !== document && host.matches?.('[data-bronto-command]')) palettes.push(host);
-  palettes.push(...(host.querySelectorAll?.('[data-bronto-command]') ?? []));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const palettes = collectHosts(host, '[data-bronto-command]');
   const cleanups = [];
 
   for (const box of palettes) {
@@ -58,11 +69,7 @@ export function initCommand({ root } = {}) {
       if (item) {
         active = items.indexOf(item);
         input.setAttribute('aria-activedescendant', item.id);
-        try {
-          item.scrollIntoView({ block: 'nearest' });
-        } catch {
-          /* headless — scrollIntoView is a pure affordance */
-        }
+        scrollIntoViewSafe(item);
       } else {
         active = -1;
         input.removeAttribute('aria-activedescendant');
@@ -101,11 +108,7 @@ export function initCommand({ root } = {}) {
     const move = (delta) => {
       const vis = visible();
       if (!vis.length) return;
-      const cur = vis.indexOf(items[active]);
-      let next = cur + delta;
-      if (next < 0) next = vis.length - 1;
-      if (next >= vis.length) next = 0;
-      setActive(vis[next]);
+      setActive(vis[wrapIndex(vis.indexOf(items[active]), delta, vis.length)]);
     };
 
     const choose = (item) => {

package/behaviors/connectors.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost, collectHosts } from './internal.js';
 import { connectRects, arrowHead, dotMark } from '../connectors/index.js';
 
 const SVGNS = 'http://www.w3.org/2000/svg';
@@ -17,10 +17,9 @@ const SVGNS = 'http://www.w3.org/2000/svg';
  */
 export function initConnectors({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const connectors = [];
-  if (host !== document && host.matches?.('[data-bronto-connector]')) connectors.push(host);
-  connectors.push(...host.querySelectorAll('[data-bronto-connector]'));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const connectors = collectHosts(host, '[data-bronto-connector]');
   if (!connectors.length) return noop;
 
   const draw = () => {

package/behaviors/crosshair.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js';
 
 /**
  * Track the pointer over a plot and drive a crosshair. Each
@@ -14,10 +14,9 @@ import { hasDom, noop, bindOnce } from './internal.js';
  */
 export function initCrosshair({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const plots = [];
-  if (host !== document && host.matches?.('[data-bronto-crosshair]')) plots.push(host);
-  plots.push(...host.querySelectorAll('[data-bronto-crosshair]'));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const plots = collectHosts(host, '[data-bronto-crosshair]');
   if (!plots.length) return noop;
 
   const cleanups = [];

package/behaviors/dialog.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
 
 /**
  * Wire native <dialog> open/close glue (the one bit <dialog> can't do
@@ -17,7 +17,8 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  */
 export function initDialog({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const managedDialogs = new WeakSet();
   const canManageDialog = (dlg, origin) => host.contains(origin) || managedDialogs.has(dlg);
 

package/behaviors/disclosure.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
 
 /**
  * Disclosure: a `[data-bronto-disclosure]` trigger toggles the element
@@ -7,7 +7,8 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  */
 export function initDisclosure({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const onClick = (e) => {
     const trigger = e.target.closest('[data-bronto-disclosure]');
     if (!trigger || !host.contains(trigger)) return;

package/behaviors/dismissible.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, closestSafe } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, closestSafe } from './internal.js';
 
 /**
  * Click on `[data-bronto-dismiss]` removes the nearest ancestor matching
@@ -7,7 +7,8 @@ import { hasDom, noop, bindOnce, closestSafe } from './internal.js';
  */
 export function dismissible({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const onClick = (e) => {
     const btn = e.target.closest('[data-bronto-dismiss]');
     if (!btn || !host.contains(btn)) return;

package/behaviors/forms.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, nextFieldUid, collectHosts } from './internal.js';
 
 /**
  * Accessible form validation glue for `<form data-bronto-validate>`.
@@ -11,7 +11,10 @@ import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
  *  - on blur and on submit sets `aria-invalid` and writes the browser's
  *    `validationMessage` into the field's error slot
  *    (`[data-bronto-error]` inside the `.ui-field`, falling back to a
- *    `.ui-hint`), linked via `aria-describedby`,
+ *    `.ui-hint`), linked via `aria-describedby`. When it falls back to a
+ *    `.ui-hint` the original help text is snapshotted and restored once the
+ *    field is valid again (so the error does not eat the help permanently); a
+ *    dedicated empty `[data-bronto-error]` node is still the recommended slot,
  *  - on an invalid submit, fills the form's
  *    `[data-bronto-error-summary]` (a `.ui-error-summary`) with
  *    in-page links to each bad field, focuses it, and blocks submit.
@@ -21,17 +24,26 @@ import { hasDom, noop, bindOnce, nextFieldUid } from './internal.js';
  */
 export function initFormValidation({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
 
   const ensureId = (el, prefix) => {
     if (!el.id) el.id = `${prefix}-${nextFieldUid()}`;
     return el.id;
   };
 
+  // When the field has no dedicated `[data-bronto-error]` node we fall back to
+  // the shared `.ui-hint` help slot. Snapshot its original help text the first
+  // time we overwrite it with an error, so the valid branch can RESTORE the help
+  // rather than blanking it permanently (component-audit C8).
+  const hintHelp = new WeakMap();
+
   const slotFor = (control) => {
     const field = control.closest('.ui-field');
     if (!field) return null;
-    return field.querySelector('[data-bronto-error]') || field.querySelector('.ui-hint');
+    const dedicated = field.querySelector('[data-bronto-error]');
+    if (dedicated) return dedicated;
+    return field.querySelector('.ui-hint');
   };
 
   const link = (control, slot) => {
@@ -43,21 +55,42 @@ export function initFormValidation({ root } = {}) {
     }
   };
 
+  const unlink = (control, slot) => {
+    if (!slot.id) return;
+    const ids = (control.getAttribute('aria-describedby') || '')
+      .split(/\s+/)
+      .filter((id) => id && id !== slot.id);
+    if (ids.length) control.setAttribute('aria-describedby', ids.join(' '));
+    else control.removeAttribute('aria-describedby');
+  };
+
   const validateField = (control) => {
     if (!control.willValidate) return true;
     const ok = control.validity.valid;
     const slot = slotFor(control);
+    const isHint = slot?.classList.contains('ui-hint');
     if (ok) {
       control.removeAttribute('aria-invalid');
       if (slot) {
-        slot.textContent = '';
-        if (slot.classList.contains('ui-hint')) slot.classList.remove('ui-hint--error');
+        if (isHint) {
+          // Restore the snapshotted help text (or clear if there was none); a
+          // help-bearing hint stays linked via aria-describedby (it describes
+          // the field in the valid state too).
+          slot.textContent = hintHelp.get(slot) ?? '';
+          slot.classList.remove('ui-hint--error');
+        } else {
+          // Dedicated error node: clear it and drop the now-stale describedby
+          // so AT doesn't announce an empty error association.
+          slot.textContent = '';
+          unlink(control, slot);
+        }
       }
     } else {
       control.setAttribute('aria-invalid', 'true');
       if (slot) {
+        if (isHint && !hintHelp.has(slot)) hintHelp.set(slot, slot.textContent);
         slot.textContent = control.validationMessage;
-        if (slot.classList.contains('ui-hint')) slot.classList.add('ui-hint--error');
+        if (isHint) slot.classList.add('ui-hint--error');
         link(control, slot);
       }
     }
@@ -136,12 +169,7 @@ export function initFormValidation({ root } = {}) {
     // otherwise show the native UA bubble instead of the Bronto
     // summary — contradicting the documented contract. (Forms added
     // after init are still covered by the in-handler set.)
-    // Feature-detect rather than `instanceof Element` — `Element` is not
-    // a guaranteed global (SSR / the no-DOM test env), and `host` is
-    // either `document` (no `.matches`) or a root Element.
-    const selfForm =
-      typeof host.matches === 'function' && host.matches('[data-bronto-validate]') ? [host] : [];
-    const forms = [...selfForm, ...(host.querySelectorAll?.('[data-bronto-validate]') ?? [])];
+    const forms = collectHosts(host, '[data-bronto-validate]');
     const priorNoValidate = new Map();
     for (const f of forms) {
       priorNoValidate.set(f, f.noValidate);

package/behaviors/glyph.js

@@ -1,4 +1,4 @@
-import { hasDom, noop } from './internal.js';
+import { hasDom, resolveHost, noop, collectHosts } from './internal.js';
 import { GLYPH_SIZE, glyphCells } from '../glyphs/glyphs.js';
 
 function restoreAttr(el, name, prev) {
@@ -17,10 +17,9 @@ function restoreAttr(el, name, prev) {
  */
 export function initDotGlyph({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const els = [];
-  if (host !== document && host.matches?.('[data-bronto-glyph]')) els.push(host);
-  els.push(...(host.querySelectorAll?.('[data-bronto-glyph]') ?? []));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const els = collectHosts(host, '[data-bronto-glyph]');
   const cleanups = [];
 
   for (const el of els) {

package/behaviors/internal.js

@@ -6,6 +6,22 @@ export const noop = () => {};
 
 export const hasDom = () => typeof document !== 'undefined';
 
+// Resolve the delegation host from an init call's `root` option, distinguishing
+// three cases so an unattached/null root never silently widens to whole-document
+// delegation (the "scoped island hijacks every control" foot-gun):
+//   • root absent/undefined → no scope requested → delegate from `fallback`
+//     (default `document`). This is the intended global-wiring path.
+//   • root === null         → a scope WAS requested but isn't ready yet (e.g. a
+//     framework ref still null at mount). Return null so the caller no-ops
+//     instead of hijacking the whole document.
+//   • root is an element    → use it.
+// The bindings (@ponchia/ui/{react,solid,qwik}) emit `root: null` for the
+// not-ready case precisely so this distinction survives across the boundary.
+export function resolveHost(root, fallback = document) {
+  if (root === null) return null;
+  return root || fallback;
+}
+
 // Monotonic counter for auto-minted field / list ids, shared across
 // initFormValidation and initCombobox so separate calls (and separate
 // behaviors) never collide on an id.
@@ -48,3 +64,34 @@ export function closestSafe(el, selector) {
     return null;
   }
 }
+
+// Collect the hosts an initializer should wire: the descendants matching
+// `selector` PLUS `host` itself when it matches (querySelectorAll only sees
+// descendants, so a `root` that *is* a target would otherwise be skipped).
+// Self-first, null-safe — the shape ~9 delegated behaviors hand-rolled.
+export function collectHosts(host, selector) {
+  const out = host !== document && host.matches?.(selector) ? [host] : [];
+  out.push(...(host.querySelectorAll?.(selector) ?? []));
+  return out;
+}
+
+// scrollIntoView is a pure affordance and throws in jsdom/layout-less envs;
+// never let that break a keyboard/roving handler. (combobox/command/carousel.)
+export function scrollIntoViewSafe(el, opts = { block: 'nearest' }) {
+  try {
+    el?.scrollIntoView(opts);
+  } catch {
+    /* headless / no layout — the scroll is cosmetic */
+  }
+}
+
+// Wrap an index by `delta` within [0, len), the roving keyboard math shared by
+// the combobox and command listboxes (a -1 `cur` lands on the first/last as
+// before). Only this core is shared — the surrounding setActive/filter/group
+// logic diverges between the two for real reasons. (code-quality audit Q12.)
+export function wrapIndex(cur, delta, len) {
+  let next = cur + delta;
+  if (next < 0) next = len - 1;
+  if (next >= len) next = 0;
+  return next;
+}

package/behaviors/legend.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
 /**
  * Wire `[data-bronto-legend]` interactive legends. Each entry is a
@@ -17,12 +17,18 @@ import { hasDom, noop, bindOnce } from './internal.js';
  */
 export function initLegend({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const isButton = (el) => el.tagName === 'BUTTON' || el.getAttribute('role') === 'button';
   const onClick = (e) => {
     const item = e.target.closest('.ui-legend__item');
     if (!item || !host.contains(item)) return;
     const legend = item.closest('[data-bronto-legend]');
     if (!legend || !host.contains(legend)) return;
+    // The contract requires a real `<button>` (keyboard-operable, focusable). A
+    // non-button item is mouse-only — refuse to toggle it rather than ship a
+    // pointer-only control (WCAG 2.1.1 — C11). The author is warned at bind.
+    if (!isButton(item)) return;
     const active = item.getAttribute('aria-pressed') !== 'false';
     const next = !active;
     item.setAttribute('aria-pressed', String(next));
@@ -40,6 +46,21 @@ export function initLegend({ root } = {}) {
     );
   };
   return bindOnce(host, 'legend', () => {
+    // Warn once per non-button item present at bind: it gets cursor:pointer from
+    // the CSS but is neither focusable nor keyboard-operable (C11).
+    if (typeof console !== 'undefined') {
+      for (const legend of host.querySelectorAll?.('[data-bronto-legend]') ?? []) {
+        const stray = [...legend.querySelectorAll('.ui-legend__item')].some(
+          (el) => el.closest('[data-bronto-legend]') === legend && !isButton(el),
+        );
+        if (stray) {
+          console.warn(
+            '[bronto] initLegend(): interactive legend entries must be <button> (or role="button") to be keyboard-operable — a non-button .ui-legend__item is ignored.',
+          );
+          break;
+        }
+      }
+    }
     host.addEventListener('click', onClick);
     return () => host.removeEventListener('click', onClick);
   });

package/behaviors/menu.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
 /**
  * Dropdown-menu close affordances for a native `<details data-bronto-menu>`
@@ -13,7 +13,8 @@ import { hasDom, noop, bindOnce } from './internal.js';
  */
 export function initMenu({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const openMenus = () => host.querySelectorAll?.('[data-bronto-menu][open]') ?? [];
   const shut = (menu) => {
     if (!menu || !menu.open) return;

package/behaviors/popover.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
 
 /**
  * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
@@ -12,15 +12,43 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  * `aria-expanded` / `aria-controls`, closes on Escape and outside
  * click, and re-positions on scroll/resize while open. SSR-safe,
  * idempotent; returns a cleanup function.
+ *
+ * The trigger advertises `aria-haspopup="dialog"`, so on open the panel is
+ * given `role="dialog"` (unless the author set a role) and focus is moved into
+ * it — the first focusable descendant, or the panel itself. It is a *non-modal*
+ * dialog: the rest of the page stays interactive and there is no focus trap.
+ * Author an accessible name on the panel (`aria-label` / `aria-labelledby`); a
+ * dev-time `console.warn` fires when it is missing.
+ *
+ * Escape returns focus to the trigger; closing via outside-click leaves focus
+ * where the click landed (treated as deliberate intent to move on).
  */
 export function initPopover({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const view = document.defaultView;
   const GAP = 8;
   let openPanel = null;
   let openTrigger = null;
 
+  const FOCUSABLE =
+    'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  // The trigger advertises `aria-haspopup="dialog"`, so the open panel must BE a
+  // dialog: a role, an accessible name, and focus moved into it (C6). Focus the
+  // first focusable descendant, else the panel itself (made programmatically
+  // focusable) so a content-only panel still receives focus.
+  const focusInto = (panel) => {
+    const first = panel.querySelector(FOCUSABLE);
+    if (first) {
+      first.focus?.();
+      return;
+    }
+    if (!panel.hasAttribute('tabindex')) panel.setAttribute('tabindex', '-1');
+    panel.focus?.();
+  };
+
   const place = (trigger, panel) => {
     const r = trigger.getBoundingClientRect();
     const pw = panel.offsetWidth;
@@ -39,6 +67,10 @@ export function initPopover({ root } = {}) {
     if (!openPanel) return;
     const panel = openPanel;
     const trigger = openTrigger;
+    // Only steal focus back to the trigger when focus is still inside the panel
+    // (Escape / programmatic re-toggle). An outside-click leaves focus where the
+    // click landed — deliberate intent to move on, per the doc contract.
+    const focusWasInside = panel.contains(document.activeElement);
     openPanel = openTrigger = null;
     if (panel.hasAttribute('popover') && typeof panel.hidePopover === 'function') {
       try {
@@ -50,10 +82,15 @@ export function initPopover({ root } = {}) {
       panel.classList.remove('is-open');
     }
     if (trigger) trigger.setAttribute('aria-expanded', 'false');
+    if (focusWasInside && trigger?.isConnected) trigger.focus?.();
   };
 
   const open = (trigger, panel) => {
     close();
+    // Live up to the advertised `aria-haspopup="dialog"`: give the panel a
+    // dialog role (unless the author set one) so AT announces it as the promised
+    // dialog rather than a generic group (C6).
+    if (!panel.hasAttribute('role')) panel.setAttribute('role', 'dialog');
     trigger.setAttribute('aria-controls', panel.id);
     trigger.setAttribute('aria-expanded', 'true');
     if (panel.hasAttribute('popover') && typeof panel.showPopover === 'function') {
@@ -68,6 +105,7 @@ export function initPopover({ root } = {}) {
     openPanel = panel;
     openTrigger = trigger;
     place(trigger, panel);
+    focusInto(panel);
   };
 
   const onClick = (e) => {
@@ -83,22 +121,55 @@ export function initPopover({ root } = {}) {
     if (openPanel && !openPanel.contains(e.target)) close();
   };
   const onKey = (e) => {
-    if (e.key === 'Escape' && openPanel) {
-      const t = openTrigger;
-      close();
-      t?.focus?.();
-    }
+    // close() returns focus to the trigger because focus is inside the panel.
+    if (e.key === 'Escape' && openPanel) close();
   };
   const onReflow = () => {
     if (openPanel && openTrigger) place(openTrigger, openPanel);
   };
 
+  // Seed resting ARIA on every trigger and keep it in sync when the UA itself
+  // toggles a native popover (light-dismiss / Escape on the `popover` attribute
+  // never routes through close(), so aria-expanded would otherwise go stale).
+  const seedTeardowns = [];
+  const seed = () => {
+    for (const trigger of host.querySelectorAll('[data-bronto-popover]')) {
+      const panel = byIdInHost(host, trigger.getAttribute('data-bronto-popover'));
+      if (!panel) continue;
+      if (!trigger.hasAttribute('aria-haspopup')) trigger.setAttribute('aria-haspopup', 'dialog');
+      trigger.setAttribute('aria-controls', panel.id);
+      if (!trigger.hasAttribute('aria-expanded')) trigger.setAttribute('aria-expanded', 'false');
+      // A dialog with no accessible name is announced as just "dialog". We can't
+      // invent a good name, so warn the author at dev time (C6).
+      const named =
+        panel.hasAttribute('aria-label') ||
+        panel.hasAttribute('aria-labelledby') ||
+        panel.hasAttribute('title');
+      if (!named && typeof console !== 'undefined') {
+        console.warn(
+          `[bronto] initPopover(): panel #${panel.id} has no accessible name — add aria-label or aria-labelledby so it is announced as a named dialog.`,
+        );
+      }
+      if (panel.hasAttribute('popover')) {
+        const onToggle = (e) => {
+          const isOpen = e.newState === 'open';
+          trigger.setAttribute('aria-expanded', isOpen ? 'true' : 'false');
+          if (!isOpen && openPanel === panel) openPanel = openTrigger = null;
+        };
+        panel.addEventListener('toggle', onToggle);
+        seedTeardowns.push(() => panel.removeEventListener('toggle', onToggle));
+      }
+    }
+  };
+
   return bindOnce(host, 'popover', () => {
+    seed();
     document.addEventListener('click', onClick);
     document.addEventListener('keydown', onKey);
     view?.addEventListener('scroll', onReflow, true);
     view?.addEventListener('resize', onReflow);
     return () => {
+      for (const t of seedTeardowns.splice(0)) t();
       document.removeEventListener('click', onClick);
       document.removeEventListener('keydown', onKey);
       view?.removeEventListener('scroll', onReflow, true);

package/behaviors/spotlight.js

@@ -1,4 +1,4 @@
-import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost, collectHosts } from './internal.js';
 
 /**
  * Position a spotlight cutout over a target element. Each
@@ -14,10 +14,9 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  */
 export function initSpotlight({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const spots = [];
-  if (host !== document && host.matches?.('[data-bronto-spotlight]')) spots.push(host);
-  spots.push(...host.querySelectorAll('[data-bronto-spotlight]'));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const spots = collectHosts(host, '[data-bronto-spotlight]');
   if (!spots.length) return noop;
 
   const place = () => {