@ponchia/ui 0.6.0 → 0.6.4

package/behaviors/index.js

@@ -12,11 +12,28 @@
  *   import { applyStoredTheme, initThemeToggle } from '@ponchia/ui/behaviors';
  *   applyStoredTheme();                 // before paint, avoids theme flash
  *   const stop = initThemeToggle();     // wire [data-bronto-theme-toggle]
+ *
+ * The public option/detail types are JSDoc `@typedef`s on the modules below,
+ * re-exported here by name; the shipped `index.d.ts` is generated from this
+ * source by `tsc --emitDeclarationOnly` (so the declarations cannot drift).
+ *
+ * @typedef {import('./internal.js').Cleanup} Cleanup
+ * @typedef {import('./internal.js').DelegateOpts} DelegateOpts
+ * @typedef {import('./theme.js').ThemeStorageOpts} ThemeStorageOpts
+ * @typedef {import('./theme.js').ApplyThemeOpts} ApplyThemeOpts
+ * @typedef {import('./theme.js').ThemeChangeDetail} ThemeChangeDetail
+ * @typedef {import('./toast.js').ToastOpts} ToastOpts
+ * @typedef {import('./modal.js').ModalCloseDetail} ModalCloseDetail
+ * @typedef {import('./legend.js').LegendToggleDetail} LegendToggleDetail
+ * @typedef {import('./crosshair.js').CrosshairMoveDetail} CrosshairMoveDetail
+ * @typedef {import('./command.js').CommandSelectDetail} CommandSelectDetail
  */
 export { applyStoredTheme, initThemeToggle } from './theme.js';
 export { dismissible } from './dismissible.js';
+export { initDisabledGuard } from './inert.js';
 export { initTabs } from './tabs.js';
 export { initDialog } from './dialog.js';
+export { initModal } from './modal.js';
 export { toast } from './toast.js';
 export { initDisclosure } from './disclosure.js';
 export { initMenu } from './menu.js';

package/behaviors/inert.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Make `aria-disabled="true"` controls keyboard-inert, not just pointer-inert.
+ *
+ * CSS can dim an `aria-disabled` control and set `pointer-events: none`, but it
+ * cannot block keyboard activation: a focused `<a aria-disabled>` or
+ * `<button aria-disabled>` still fires on Enter/Space, so a keyboard user can
+ * activate a control that looks dead. (Native `disabled` is already fully inert;
+ * this guard brings the ARIA path up to parity.) The element intentionally stays
+ * focusable and announced — the WAI-ARIA disabled pattern keeps it in the tab
+ * order — but it no longer *acts*.
+ *
+ * Wire once near the root, like {@link applyStoredTheme}. Capturing listeners
+ * intercept activation before any component handler (tabs, pagination, menus)
+ * sees it. (component audit C4.)
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initDisabledGuard({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=inert.d.ts.map

package/behaviors/inert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inert.d.ts","sourceRoot":"","sources":["inert.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,6CAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAyB3C"}

package/behaviors/inert.js

@@ -0,0 +1,46 @@
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
+
+const DISABLED = '[aria-disabled="true"]';
+
+/**
+ * Make `aria-disabled="true"` controls keyboard-inert, not just pointer-inert.
+ *
+ * CSS can dim an `aria-disabled` control and set `pointer-events: none`, but it
+ * cannot block keyboard activation: a focused `<a aria-disabled>` or
+ * `<button aria-disabled>` still fires on Enter/Space, so a keyboard user can
+ * activate a control that looks dead. (Native `disabled` is already fully inert;
+ * this guard brings the ARIA path up to parity.) The element intentionally stays
+ * focusable and announced — the WAI-ARIA disabled pattern keeps it in the tab
+ * order — but it no longer *acts*.
+ *
+ * Wire once near the root, like {@link applyStoredTheme}. Capturing listeners
+ * intercept activation before any component handler (tabs, pagination, menus)
+ * sees it. (component audit C4.)
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initDisabledGuard({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const block = (e) => {
+    const el = e.target.closest?.(DISABLED);
+    if (el && host.contains(el)) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+  const onKeydown = (e) => {
+    // Only the activation keys; Tab/arrows must still move focus PAST the control.
+    if (e.key === 'Enter' || e.key === ' ' || e.key === 'Spacebar') block(e);
+  };
+  return bindOnce(host, 'disabled-guard', () => {
+    host.addEventListener('click', block, true);
+    host.addEventListener('keydown', onKeydown, true);
+    return () => {
+      host.removeEventListener('click', block, true);
+      host.removeEventListener('keydown', onKeydown, true);
+    };
+  });
+}

package/behaviors/internal.d.ts

@@ -0,0 +1,25 @@
+export function resolveHost(root: any, fallback?: Document): any;
+export function bindOnce(target: any, key: any, add: any): () => void;
+export function byIdInHost(host: any, id: any): any;
+export function closestSafe(el: any, selector: any): any;
+export function collectHosts(host: any, selector: any): any[];
+export function scrollIntoViewSafe(el: any, opts?: {
+    block: string;
+}): void;
+export function focusInto(container: any): void;
+export function wrapIndex(cur: any, delta: any, len: any): any;
+export function noop(): void;
+export function hasDom(): boolean;
+export function nextFieldUid(): number;
+/**
+ * Cleanup function returned by every initializer; calling it tears down the
+ * behavior's listeners/observers.
+ */
+export type Cleanup = () => void;
+export type DelegateOpts = {
+    /**
+     * Event-delegation root; also scopes which controls are queried. Default: `document`.
+     */
+    root?: Document | Element | undefined;
+};
+//# sourceMappingURL=internal.d.ts.map

package/behaviors/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.js"],"names":[],"mappings":"AA8BA,iEAGC;AAeD,sEAUC;AAED,oDAQC;AAED,yDAMC;AAMD,8DAIC;AAID;;SAMC;AAUD,gDAQC;AAMD,+DAKC;AA9GM,6BAAqB;AAErB,kCAAoD;AAsBpD,uCAAqC;;;;;sBAjC/B,MAAM,IAAI"}

package/behaviors/internal.js

@@ -1,6 +1,17 @@
 // Shared, dependency-free DOM helpers for the behavior modules.
 // Not part of the public @ponchia/ui/behaviors surface (the barrel
-// re-exports only the documented behaviors).
+// re-exports only the documented behaviors' values — these shared option
+// types are re-exported by name from index.js).
+
+/**
+ * @typedef {() => void} Cleanup
+ *   Cleanup function returned by every initializer; calling it tears down the
+ *   behavior's listeners/observers.
+ *
+ * @typedef {object} DelegateOpts
+ * @property {Document | Element} [root]
+ *   Event-delegation root; also scopes which controls are queried. Default: `document`.
+ */
 
 export const noop = () => {};
 
@@ -85,6 +96,24 @@ export function scrollIntoViewSafe(el, opts = { block: 'nearest' }) {
   }
 }
 
+// The focusable-element selector + "move focus into a container" helper shared
+// by the modal and popover focus paths (a dialog/modal must move focus into
+// itself on open). Focus the first focusable descendant, else make the
+// container programmatically focusable and focus it, so a content-only
+// panel/modal still receives focus. (code-quality audit Q4.)
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function focusInto(container) {
+  const first = container.querySelector(FOCUSABLE);
+  if (first) {
+    first.focus?.();
+    return;
+  }
+  if (!container.hasAttribute('tabindex')) container.setAttribute('tabindex', '-1');
+  container.focus?.();
+}
+
 // 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

package/behaviors/legend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @typedef {object} LegendToggleDetail
+ * @property {string | number} series The entry's `data-series`, or its 0-based index when unset.
+ * @property {boolean} active The new state (`true` ⇒ series shown).
+ */
+/**
+ * Wire `[data-bronto-legend]` interactive legends. Each entry is a
+ * `.ui-legend__item` authored as a `<button aria-pressed>`; clicking it (or
+ * Enter/Space, native to `<button>`) flips `aria-pressed`, toggles the
+ * `.is-inactive` class, and dispatches `bronto:legend:toggle` on the legend
+ * with `{ detail: { series, active } }` (`series` is the entry's
+ * `data-series`, or its 0-based index if unset).
+ *
+ * Bronto owns only the control and its pressed/inactive *state*. It does not
+ * know the chart's series, hide anything, or announce the change: the host
+ * listens for the event, hides its own series, and owns any `aria-live`
+ * announcement. The convention is `aria-pressed="true"` ⇒ the series is shown
+ * (the default); the entry's label never changes on toggle (WAI-ARIA). SSR-safe
+ * and idempotent per host; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initLegend({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type LegendToggleDetail = {
+    /**
+     * The entry's `data-series`, or its 0-based index when unset.
+     */
+    series: string | number;
+    /**
+     * The new state (`true` ⇒ series shown).
+     */
+    active: boolean;
+};
+//# sourceMappingURL=legend.d.ts.map

package/behaviors/legend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legend.d.ts","sourceRoot":"","sources":["legend.js"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmD3C;;;;;YAvEa,MAAM,GAAG,MAAM;;;;YACf,OAAO"}

package/behaviors/legend.js

@@ -1,5 +1,11 @@
 import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
+/**
+ * @typedef {object} LegendToggleDetail
+ * @property {string | number} series The entry's `data-series`, or its 0-based index when unset.
+ * @property {boolean} active The new state (`true` ⇒ series shown).
+ */
+
 /**
  * Wire `[data-bronto-legend]` interactive legends. Each entry is a
  * `.ui-legend__item` authored as a `<button aria-pressed>`; clicking it (or
@@ -14,6 +20,9 @@ import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
  * announcement. The convention is `aria-pressed="true"` ⇒ the series is shown
  * (the default); the entry's label never changes on toggle (WAI-ARIA). SSR-safe
  * and idempotent per host; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initLegend({ root } = {}) {
   if (!hasDom()) return noop;

package/behaviors/menu.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dropdown-menu close affordances for a native `<details data-bronto-menu>`
+ * holding a `.ui-menu`. `<details>` alone won't close on Escape, on an
+ * outside click, or when a `.ui-menu__item` is activated — this adds
+ * exactly those, returning focus to the `<summary>` on Esc/activate.
+ *
+ * Deliberately NOT a full WAI-ARIA menu (no arrow-key roving): the items
+ * are real buttons, Tab-reachable; this is a disclosure of actions, and
+ * over-claiming `role="menu"` semantics would be worse. SSR-safe,
+ * idempotent; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initMenu({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=menu.d.ts.map

package/behaviors/menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menu.d.ts","sourceRoot":"","sources":["menu.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,oCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAmC3C"}

package/behaviors/menu.js

@@ -10,6 +10,9 @@ import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
  * are real buttons, Tab-reachable; this is a disclosure of actions, and
  * over-claiming `role="menu"` semantics would be worse. SSR-safe,
  * idempotent; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initMenu({ root } = {}) {
   if (!hasDom()) return noop;

package/behaviors/modal.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @typedef {object} ModalCloseDetail
+ * @property {'escape'} reason What asked the modal to close (currently only Escape).
+ */
+/**
+ * Focus management for the **controlled, non-`<dialog>` modal** — the
+ * `.ui-modal.is-open` path a portal/React overlay uses when it genuinely can't
+ * be a native `<dialog>`. The native `<dialog>` path gets a focus trap, Escape,
+ * and the top layer for free (use `initDialog`); this supplies the equivalent
+ * for the `.is-open` path, which otherwise leaves focus management to the
+ * consumer.
+ *
+ * Mark the overlay `[data-bronto-modal]` (opt-in). On bind it gives the modal a
+ * `role="dialog"` + `aria-modal="true"` (unless the author set a role) and
+ * dev-warns when it has no accessible name, so it announces as a named modal
+ * dialog — parity with `initPopover`. The behavior watches its
+ * `class` for `is-open`: on open it remembers the focused element, moves focus
+ * into the modal (first focusable, else the panel itself), and **traps focus by
+ * marking every sibling at each ancestor level `inert`** so the rest of the page
+ * is non-focusable and non-interactive — the modern, robust trap. On close it
+ * un-inerts exactly what it inerted and returns focus to the opener. Bronto owns
+ * focus only: the **consumer still owns open/close state** (the `is-open`
+ * class). Escape dispatches a cancelable `bronto:modal:close`
+ * ({@link ModalCloseDetail}) on the modal so the consumer can drop `is-open` in
+ * response; the behavior never changes visibility itself.
+ *
+ * Best suited to a body-/portal-level overlay (the documented `.is-open` use
+ * case); a deeply-nested modal still gets focus-into, focus-return, and the
+ * Escape signal. SSR-safe, idempotent per modal; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initModal({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type ModalCloseDetail = {
+    /**
+     * What asked the modal to close (currently only Escape).
+     */
+    reason: "escape";
+};
+//# sourceMappingURL=modal.d.ts.map

package/behaviors/modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal.d.ts","sourceRoot":"","sources":["modal.js"],"names":[],"mappings":"AAEA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAyF3C;;;;;YAvHa,QAAQ"}

package/behaviors/modal.js

@@ -0,0 +1,124 @@
+import { hasDom, resolveHost, noop, bindOnce, collectHosts, focusInto } from './internal.js';
+
+/**
+ * @typedef {object} ModalCloseDetail
+ * @property {'escape'} reason What asked the modal to close (currently only Escape).
+ */
+
+/**
+ * Focus management for the **controlled, non-`<dialog>` modal** — the
+ * `.ui-modal.is-open` path a portal/React overlay uses when it genuinely can't
+ * be a native `<dialog>`. The native `<dialog>` path gets a focus trap, Escape,
+ * and the top layer for free (use `initDialog`); this supplies the equivalent
+ * for the `.is-open` path, which otherwise leaves focus management to the
+ * consumer.
+ *
+ * Mark the overlay `[data-bronto-modal]` (opt-in). On bind it gives the modal a
+ * `role="dialog"` + `aria-modal="true"` (unless the author set a role) and
+ * dev-warns when it has no accessible name, so it announces as a named modal
+ * dialog — parity with `initPopover`. The behavior watches its
+ * `class` for `is-open`: on open it remembers the focused element, moves focus
+ * into the modal (first focusable, else the panel itself), and **traps focus by
+ * marking every sibling at each ancestor level `inert`** so the rest of the page
+ * is non-focusable and non-interactive — the modern, robust trap. On close it
+ * un-inerts exactly what it inerted and returns focus to the opener. Bronto owns
+ * focus only: the **consumer still owns open/close state** (the `is-open`
+ * class). Escape dispatches a cancelable `bronto:modal:close`
+ * ({@link ModalCloseDetail}) on the modal so the consumer can drop `is-open` in
+ * response; the behavior never changes visibility itself.
+ *
+ * Best suited to a body-/portal-level overlay (the documented `.is-open` use
+ * case); a deeply-nested modal still gets focus-into, focus-return, and the
+ * Escape signal. SSR-safe, idempotent per modal; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initModal({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const modals = collectHosts(host, '[data-bronto-modal]');
+  const cleanups = [];
+
+  for (const modal of modals) {
+    let opener = null;
+    let inerted = [];
+
+    // A controlled modal must announce AS a modal dialog, not a generic group —
+    // parity with initPopover. Apply a dialog role + aria-modal (unless the
+    // author set a role), and dev-warn on a missing accessible name since we
+    // can't invent a good one. (component audit C13.)
+    if (!modal.hasAttribute('role')) modal.setAttribute('role', 'dialog');
+    if (!modal.hasAttribute('aria-modal')) modal.setAttribute('aria-modal', 'true');
+    const named =
+      modal.hasAttribute('aria-label') ||
+      modal.hasAttribute('aria-labelledby') ||
+      modal.hasAttribute('title');
+    if (!named && typeof console !== 'undefined') {
+      console.warn(
+        `[bronto] initModal(): a [data-bronto-modal] has no accessible name — add aria-label or aria-labelledby so it is announced as a named dialog.`,
+      );
+    }
+
+    // Inert every sibling at each ancestor level up to <body>: the rest of the
+    // page becomes non-focusable/non-interactive while the modal subtree stays
+    // live. Skip already-inert nodes so release() can't un-inert something the
+    // app inerted for its own reasons.
+    const trap = () => {
+      if (opener) return; // already trapped
+      opener = document.activeElement;
+      let el = modal;
+      while (el && el.parentElement && el !== document.body) {
+        for (const sib of el.parentElement.children) {
+          if (sib !== el && !sib.inert) {
+            sib.inert = true;
+            inerted.push(sib);
+          }
+        }
+        el = el.parentElement;
+      }
+      focusInto(modal);
+    };
+
+    const release = () => {
+      if (!opener) return;
+      for (const el of inerted) el.inert = false;
+      inerted = [];
+      const back = opener;
+      opener = null;
+      if (back?.isConnected && typeof back.focus === 'function') back.focus();
+    };
+
+    const sync = () => (modal.classList.contains('is-open') ? trap() : release());
+
+    const onKey = (e) => {
+      if (e.key === 'Escape' && opener) {
+        modal.dispatchEvent(
+          new CustomEvent('bronto:modal:close', {
+            detail: { reason: 'escape' },
+            bubbles: true,
+            cancelable: true,
+          }),
+        );
+      }
+    };
+
+    const observer = typeof MutationObserver === 'function' ? new MutationObserver(sync) : null;
+
+    cleanups.push(
+      bindOnce(modal, 'modal', () => {
+        observer?.observe(modal, { attributes: true, attributeFilter: ['class'] });
+        document.addEventListener('keydown', onKey, true);
+        if (modal.classList.contains('is-open')) trap(); // already open at init
+        return () => {
+          observer?.disconnect();
+          document.removeEventListener('keydown', onKey, true);
+          release();
+        };
+      }),
+    );
+  }
+
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/popover.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
+ * trigger toggles the `.ui-popover` panel whose id it names. The panel
+ * is placed under the trigger and **flips above** when it would
+ * overflow the viewport, with its inline edge clamped on-screen — the
+ * thing the CSS-only tooltip can't do near edges / inside scroll
+ * containers. If the panel has the native `popover` attribute and the
+ * Popover API is available it is shown in the top layer (never
+ * clipped); otherwise an `.is-open` class is toggled. Manages
+ * `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).
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initPopover({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=popover.d.ts.map

package/behaviors/popover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popover.d.ts","sourceRoot":"","sources":["popover.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAwJ3C"}

package/behaviors/popover.js

@@ -1,4 +1,4 @@
-import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, byIdInHost, focusInto } from './internal.js';
 
 /**
  * Collision-aware popover, dependency-free. A `[data-bronto-popover]`
@@ -22,6 +22,9 @@ import { hasDom, resolveHost, noop, bindOnce, byIdInHost } from './internal.js';
  *
  * Escape returns focus to the trigger; closing via outside-click leaves focus
  * where the click landed (treated as deliberate intent to move on).
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initPopover({ root } = {}) {
   if (!hasDom()) return noop;
@@ -32,22 +35,9 @@ export function initPopover({ root } = {}) {
   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?.();
-  };
+  // dialog: a role, an accessible name, and focus moved into it (C6) — see the
+  // shared `focusInto` in internal.js.
 
   const place = (trigger, panel) => {
     const r = trigger.getBoundingClientRect();
@@ -122,7 +112,17 @@ export function initPopover({ root } = {}) {
   };
   const onKey = (e) => {
     // close() returns focus to the trigger because focus is inside the panel.
-    if (e.key === 'Escape' && openPanel) close();
+    if (e.key !== 'Escape' || !openPanel) return;
+    // A popover open *inside* a <dialog>/modal owns this Escape. Without this,
+    // the same keypress closed BOTH: we hidePopover() the panel synchronously,
+    // the browser's close-request then finds the dialog as the new topmost
+    // element and dismisses it too. preventDefault() stops that native
+    // close-request and stopPropagation() keeps it off other delegated keydown
+    // listeners (e.g. initModal's), so only the popover closes — the documented
+    // "popover + dialog open together" contract.
+    e.preventDefault();
+    e.stopPropagation();
+    close();
   };
   const onReflow = () => {
     if (openPanel && openTrigger) place(openTrigger, openPanel);

package/behaviors/spotlight.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Position a spotlight cutout over a target element. Each
+ * `[data-bronto-spotlight]` is a `.ui-spotlight` overlay; `data-target` is the
+ * id of the element to highlight. The behavior measures the target and sets
+ * `--spot-x/y/w/h` (viewport coordinates) on the overlay, re-placing on
+ * resize/scroll and whenever `data-target` changes.
+ *
+ * Bronto owns only positioning + the visual language. It is NOT a tour engine:
+ * the host decides which target is current, when to advance, and whether to
+ * show/hide the overlay — just update `data-target` (or toggle `hidden`) and
+ * the cutout follows. SSR-safe, idempotent per host; returns a cleanup.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initSpotlight({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=spotlight.d.ts.map

package/behaviors/spotlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spotlight.d.ts","sourceRoot":"","sources":["spotlight.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,yCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAuC3C"}

package/behaviors/spotlight.js

@@ -11,6 +11,9 @@ import { hasDom, resolveHost, noop, bindOnce, byIdInHost, collectHosts } from '.
  * the host decides which target is current, when to advance, and whether to
  * show/hide the overlay — just update `data-target` (or toggle `hidden`) and
  * the cutout follows. SSR-safe, idempotent per host; returns a cleanup.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initSpotlight({ root } = {}) {
   if (!hasDom()) return noop;

package/behaviors/table.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Client-side sortable + selectable data table. Wires
+ * `[data-bronto-sortable]`:
+ *
+ *  - clicking a header's `.ui-table__sort` button sorts the tbody by
+ *    that column. Sortable headers are seeded `aria-sort="none"`; a
+ *    click toggles that header ascending ⇄ descending (first click =
+ *    ascending) and resets the other sortable headers to `none`.
+ *    Numeric columns (`data-sort="num"` or `.is-num` cells) sort
+ *    numerically; everything else, locale string compare. Any
+ *    `.ui-table__empty` sentinel row is kept last after a sort.
+ *  - a `[data-bronto-select-all]` checkbox toggles every
+ *    `[data-bronto-select]` row checkbox and the rows'
+ *    `aria-selected`; toggling a row keeps the header checkbox's
+ *    checked/indeterminate state in sync. Emits `bronto:selectionchange`
+ *    ({ detail: { count } }) on the table.
+ *
+ * SSR-safe, idempotent per table; returns a cleanup function.
+ *
+ * The numeric sort parses each cell's display text after normalizing the
+ * common report shapes: a Unicode minus (U+2212) and en/em dashes count as a
+ * sign (so a "−5" loss sorts BELOW a "5" gain, not above it), accounting
+ * parentheses `(1,234)` read as negative, and `,` thousands separators are
+ * dropped. Note the consequence: a bare `,` in the *display text* is read as a
+ * thousands separator, so a European decimal "3,5" sorts as 35, not 3.5 — for a
+ * European decimal comma (or mixed units, or any ambiguous text) put the
+ * canonical number in a `data-sort-value` attribute on the cell. That escape
+ * hatch wins over the parsed text and accepts either a dot ("3.5") or a single
+ * decimal comma ("3,5"). It is a client-side convenience sorter, not a data
+ * grid. (component audit C3/C5.)
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initTableSort({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=table.d.ts.map

package/behaviors/table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.d.ts","sourceRoot":"","sources":["table.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,yCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CA6I3C"}