@ponchia/ui 0.5.0 → 0.6.3

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

@@ -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
@@ -11,13 +11,15 @@ import { hasDom, noop, bindOnce, byIdInHost } from './internal.js';
  * 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;
-  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 = () => {

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"}

package/behaviors/table.js

@@ -1,14 +1,16 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js';
 
 /**
  * Client-side sortable + selectable data table. Wires
  * `[data-bronto-sortable]`:
  *
- *  - clicking a header's `.ui-table__sort` (or a `th[data-sort]`)
- *    sorts the tbody by that column, cycling `aria-sort`
- *    none → ascending → descending and clearing the other headers.
+ *  - 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.
+ *    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
@@ -16,40 +18,101 @@ import { hasDom, noop, bindOnce } from './internal.js';
  *    ({ 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 } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
-  const tables = [];
-  if (host !== document && host.matches?.('[data-bronto-sortable]')) tables.push(host);
-  tables.push(...(host.querySelectorAll?.('[data-bronto-sortable]') ?? []));
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const tables = collectHosts(host, '[data-bronto-sortable]');
   const cleanups = [];
 
   for (const table of tables) {
     const tbody = table.tBodies[0];
     if (!tbody) continue;
 
+    // Seed the resting `aria-sort="none"` on every sortable header so AT
+    // announces the column as sortable from the start (it was unset until the
+    // first click — C10).
+    for (const sort of table.querySelectorAll('.ui-table__sort')) {
+      const th = sort.closest('th');
+      if (th && !th.hasAttribute('aria-sort')) th.setAttribute('aria-sort', 'none');
+    }
+
     const colIndex = (th) => [...th.parentElement.children].indexOf(th);
     const cellText = (row, i) => row.children[i]?.textContent.trim() ?? '';
+    // Numeric value of a cell for sorting. A `data-sort-value` attribute is the
+    // authoritative escape hatch; otherwise normalize the display text so the
+    // sign survives (U+2212 / en-em dashes → minus, accounting parens →
+    // negative) and `,` grouping is dropped. Returns 0 for unparseable cells so
+    // they cluster rather than scatter. (component audit C3.)
+    const cellNum = (row, i) => {
+      const cell = row.children[i];
+      const explicit = cell?.getAttribute?.('data-sort-value');
+      if (explicit != null && explicit.trim() !== '') {
+        const raw = explicit.trim();
+        let v = Number(raw);
+        // The escape hatch must actually handle the case the doc names it for: a
+        // European decimal comma. `Number("3,5")` is NaN, which silently fell
+        // back to parsing the display text (where `,` is dropped as a thousands
+        // separator → "35"). A lone comma with no dot is a decimal point here.
+        if (!Number.isFinite(v) && /^[+-]?\d+,\d+$/.test(raw)) v = Number(raw.replace(',', '.'));
+        if (Number.isFinite(v)) return v;
+      }
+      let s = (cell?.textContent ?? '').trim();
+      if (!s) return 0;
+      let sign = 1;
+      const paren = /^\((.*)\)$/.exec(s); // accounting negative
+      if (paren) {
+        sign = -1;
+        s = paren[1];
+      }
+      s = s.replace(/[−–—]/g, '-'); // minus / en / em dash → '-'
+      if (/-/.test(s)) sign *= -1;
+      s = s.replace(/,/g, ''); // drop thousands separators
+      const v = parseFloat(s.replace(/[^\d.]/g, '')); // magnitude
+      return Number.isFinite(v) ? sign * v : 0;
+    };
 
     const sortBy = (th, numeric) => {
       const headers = th.closest('tr').querySelectorAll('th');
       const dir = th.getAttribute('aria-sort') === 'ascending' ? 'descending' : 'ascending';
-      headers.forEach((h) => h.removeAttribute('aria-sort'));
+      // Reset the OTHER sortable headers to `none` (not removed) so they keep
+      // announcing sortability; only previously-sortable headers carry aria-sort.
+      headers.forEach((h) => {
+        if (h !== th && h.hasAttribute('aria-sort')) h.setAttribute('aria-sort', 'none');
+      });
       th.setAttribute('aria-sort', dir);
       const i = colIndex(th);
       const sign = dir === 'ascending' ? 1 : -1;
+      // Empty/sentinel rows sort out of the data set AND must re-append LAST,
+      // or after a sort they float above the real rows (C29).
+      const emptyRows = [...tbody.rows].filter((r) => r.classList.contains('ui-table__empty'));
       const rows = [...tbody.rows].filter((r) => !r.classList.contains('ui-table__empty'));
       rows.sort((a, b) => {
-        const x = cellText(a, i);
-        const y = cellText(b, i);
         const cmp = numeric
-          ? (parseFloat(x.replace(/[^\d.-]/g, '')) || 0) -
-            (parseFloat(y.replace(/[^\d.-]/g, '')) || 0)
-          : x.localeCompare(y);
+          ? cellNum(a, i) - cellNum(b, i)
+          : cellText(a, i).localeCompare(cellText(b, i));
         return cmp * sign;
       });
-      rows.forEach((r) => tbody.appendChild(r));
+      // Re-parent in document order: sorted data rows, then any empty/sentinel
+      // row last. A single appendChild pass over the existing <tr> nodes (no
+      // markup is created — these are trusted DOM elements being moved).
+      for (const r of [...rows, ...emptyRows]) tbody.appendChild(r);
     };
 
     const allBox = table.querySelector('[data-bronto-select-all]');
@@ -71,7 +134,11 @@ export function initTableSort({ root } = {}) {
     };
 
     const onClick = (e) => {
-      const sorter = e.target.closest('.ui-table__sort, th[data-sort]');
+      // Only the focusable `.ui-table__sort` button is a sort trigger — it is
+      // keyboard-operable and carries the `::after` sort glyph. The bare
+      // `th[data-sort]` path was mouse-only with no affordance, so it is gone
+      // (C10); `data-sort="num"` is still read from the button or its th.
+      const sorter = e.target.closest('.ui-table__sort');
       if (sorter && table.contains(sorter)) {
         const th = sorter.closest('th');
         const numeric =

package/behaviors/tabs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wire `[data-bronto-tabs]` groups for full keyboard a11y. The framework
+ * ships the look + the ARIA/`.is-active` contract; this adds the WAI-ARIA
+ * Tabs pattern: roving `tabindex`, `aria-selected`, Arrow/Home/End
+ * navigation with automatic activation, and panel `hidden` sync. Tabs are
+ * `.ui-tab[data-tab]`; panels are `.ui-tabs__panel[data-panel]` with
+ * matching values. SSR-safe and idempotent (re-init replaces, never
+ * stacks, the per-group listeners); returns a cleanup function.
+ *
+ * Accessibility caveat: this is what makes tabs operable. Do **not**
+ * author `hidden` on `.ui-tabs__panel` in server-rendered markup unless
+ * `initTabs` is guaranteed to run client-side — without it the panels
+ * stay hidden with no keyboard/pointer way to reveal them. Prefer
+ * authoring all panels visible and letting `initTabs` add `hidden`.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initTabs({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=tabs.d.ts.map

package/behaviors/tabs.d.ts.map

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

package/behaviors/tabs.js

@@ -1,9 +1,4 @@
-import { hasDom, noop, bindOnce } from './internal.js';
-
-// Module-global so tab ids stay unique across *every* initTabs() call.
-// A per-call counter makes separate islands/roots all mint `bronto-tab-1`,
-// which collides aria-controls/aria-labelledby across the document.
-let tabUid = 0;
+import { hasDom, resolveHost, noop, bindOnce, nextFieldUid, collectHosts } from './internal.js';
 
 /**
  * Wire `[data-bronto-tabs]` groups for full keyboard a11y. The framework
@@ -19,16 +14,16 @@ let tabUid = 0;
  * `initTabs` is guaranteed to run client-side — without it the panels
  * stay hidden with no keyboard/pointer way to reveal them. Prefer
  * authoring all panels visible and letting `initTabs` add `hidden`.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initTabs({ root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const cleanups = [];
-  // querySelectorAll only matches descendants, so a `root` that *is* a
-  // tab group would be skipped — include it explicitly.
-  const groups = [];
-  if (host !== document && host.matches?.('[data-bronto-tabs]')) groups.push(host);
-  groups.push(...host.querySelectorAll('[data-bronto-tabs]'));
+  const groups = collectHosts(host, '[data-bronto-tabs]');
   for (const group of groups) {
     // Own group only — a tab/panel inside a nested [data-bronto-tabs]
     // belongs to that inner group, not this one.
@@ -44,7 +39,7 @@ export function initTabs({ root } = {}) {
     for (const t of tabs) {
       const p = panels.find((x) => x.dataset.panel === t.dataset.tab);
       if (!p) continue;
-      const n = ++tabUid;
+      const n = nextFieldUid();
       if (!t.id) t.id = `bronto-tab-${n}`;
       if (!p.id) p.id = `bronto-tabpanel-${n}`;
       t.setAttribute('aria-controls', p.id);
@@ -59,9 +54,17 @@ export function initTabs({ root } = {}) {
         t.setAttribute('aria-selected', String(on));
         t.tabIndex = on ? 0 : -1;
       }
+      // Only retarget panels when this tab actually controls one. A panel-less
+      // tab must NOT hide every panel — leave the prior panel visible (C30).
+      if (!panels.some((p) => p.dataset.panel === tab.dataset.tab)) return;
       for (const p of panels) {
         p.setAttribute('role', 'tabpanel');
-        p.hidden = p.dataset.panel !== tab.dataset.tab;
+        const shown = p.dataset.panel === tab.dataset.tab;
+        p.hidden = !shown;
+        // APG: a tabpanel is focusable so keyboard users can reach a text-only
+        // panel; hidden panels drop out of the tab order (C30).
+        if (shown) p.tabIndex = 0;
+        else p.removeAttribute('tabindex');
       }
     };
     const onClick = (e) => {

package/behaviors/theme.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @typedef {object} ThemeStorageOpts
+ * @property {string} [storageKey] localStorage key for the persisted theme. Default: `"bronto-theme"`.
+ *
+ * @typedef {ThemeStorageOpts & { root?: Element }} ApplyThemeOpts
+ *   `root` is the element to set `data-theme` on. Default: `<html>`.
+ *
+ * @typedef {object} ThemeChangeDetail
+ * @property {'light' | 'dark'} theme `bronto:themechange` CustomEvent detail.
+ */
+/**
+ * Apply the persisted theme to <html data-theme>. Call as early as
+ * possible (an inline module in <head>) to avoid a flash before the
+ * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ *
+ * @param {ApplyThemeOpts} [opts]
+ * @returns {void}
+ */
+export function applyStoredTheme({ storageKey, root }?: ApplyThemeOpts): void;
+/**
+ * Wire `[data-bronto-theme-toggle]` controls. Click toggles light/dark,
+ * persists to localStorage, and **always** sets `data-theme` on <html>
+ * (a theme is document-global). State is reflected via `aria-pressed`
+ * and a `bronto:themechange` CustomEvent ({ detail: { theme } }) is
+ * dispatched on <html> so consumers can sync their own UI without
+ * racing the click handler. A control may set
+ * `data-bronto-theme-toggle="dark"` to force a specific theme.
+ *
+ * `root` scopes event delegation and which controls are queried/reflected
+ * (default `document`); it does not change where the theme is applied.
+ *
+ * @param {ThemeStorageOpts & import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initThemeToggle({ storageKey, root }?: ThemeStorageOpts & import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type ThemeStorageOpts = {
+    /**
+     * localStorage key for the persisted theme. Default: `"bronto-theme"`.
+     */
+    storageKey?: string | undefined;
+};
+/**
+ * `root` is the element to set `data-theme` on. Default: `<html>`.
+ */
+export type ApplyThemeOpts = ThemeStorageOpts & {
+    root?: Element;
+};
+export type ThemeChangeDetail = {
+    /**
+     * `bronto:themechange` CustomEvent detail.
+     */
+    theme: "light" | "dark";
+};
+//# sourceMappingURL=theme.d.ts.map

package/behaviors/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["theme.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,wDAHW,cAAc,GACZ,IAAI,CAahB;AAED;;;;;;;;;;;;;;GAcG;AACH,uDAHW,gBAAgB,GAAG,OAAO,eAAe,EAAE,YAAY,GACrD,OAAO,eAAe,EAAE,OAAO,CAmD3C;;;;;;;;;;6BA5FY,gBAAgB,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;WAIpC,OAAO,GAAG,MAAM"}

package/behaviors/theme.js

@@ -1,15 +1,30 @@
-import { hasDom, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
 const THEMES = ['light', 'dark'];
 
+/**
+ * @typedef {object} ThemeStorageOpts
+ * @property {string} [storageKey] localStorage key for the persisted theme. Default: `"bronto-theme"`.
+ *
+ * @typedef {ThemeStorageOpts & { root?: Element }} ApplyThemeOpts
+ *   `root` is the element to set `data-theme` on. Default: `<html>`.
+ *
+ * @typedef {object} ThemeChangeDetail
+ * @property {'light' | 'dark'} theme `bronto:themechange` CustomEvent detail.
+ */
+
 /**
  * Apply the persisted theme to <html data-theme>. Call as early as
  * possible (an inline module in <head>) to avoid a flash before the
  * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ *
+ * @param {ApplyThemeOpts} [opts]
+ * @returns {void}
  */
 export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
   if (!hasDom()) return;
-  const el = root || document.documentElement;
+  const el = resolveHost(root, document.documentElement);
+  if (!el) return;
   let stored = null;
   try {
     stored = localStorage.getItem(storageKey);
@@ -30,10 +45,14 @@ export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
  *
  * `root` scopes event delegation and which controls are queried/reflected
  * (default `document`); it does not change where the theme is applied.
+ *
+ * @param {ThemeStorageOpts & import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
   if (!hasDom()) return noop;
-  const host = root || document;
+  const host = resolveHost(root);
+  if (!host) return noop;
   const docEl = document.documentElement;
 
   const prefersDark = () =>

package/behaviors/toast.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @typedef {object} ToastOpts
+ * @property {'accent' | 'success' | 'warning' | 'danger' | 'info'} [tone] Status tone — maps to `ui-toast--<tone>`.
+ * @property {string} [title] Optional uppercase label rendered above the message.
+ * @property {number} [duration] Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+ * @property {boolean} [assertive] Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+ * @property {boolean} [closable] Render a dismiss button on the toast.
+ */
+/**
+ * Push a transient toast into a shared, screen-anchored stack. The stack
+ * is the `aria-live="polite"` region: it is created once, appended to
+ * <body>, and **kept resident even when empty** so the live region is
+ * always present before content is inserted (a freshly created region
+ * that receives its first child in the same tick is not reliably
+ * announced by VoiceOver/NVDA). On first creation the empty region is
+ * inserted and the toast is appended on the next frame for the same
+ * reason. `tone` is accent/success/warning/danger/info; `title` is an
+ * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
+ * it until dismissed). Returns a function that dismisses the toast
+ * early. SSR-safe (no-op).
+ *
+ * @param {string} message
+ * @param {ToastOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function toast(message: string, { tone, title, duration, assertive, closable }?: ToastOpts): import("./internal.js").Cleanup;
+export type ToastOpts = {
+    /**
+     * Status tone — maps to `ui-toast--<tone>`.
+     */
+    tone?: "accent" | "success" | "warning" | "danger" | "info" | undefined;
+    /**
+     * Optional uppercase label rendered above the message.
+     */
+    title?: string | undefined;
+    /**
+     * Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+     */
+    duration?: number | undefined;
+    /**
+     * Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+     */
+    assertive?: boolean | undefined;
+    /**
+     * Render a dismiss button on the toast.
+     */
+    closable?: boolean | undefined;
+};
+//# sourceMappingURL=toast.d.ts.map

package/behaviors/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["toast.js"],"names":[],"mappings":"AA2HA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,+BAJW,MAAM,mDACN,SAAS,GACP,OAAO,eAAe,EAAE,OAAO,CAgD3C"}

package/behaviors/toast.js

@@ -1,5 +1,11 @@
 import { hasDom, noop } from './internal.js';
 
+// The tones that have a `.ui-toast--*` rule. The TS type already unions these,
+// but a plain-JS / LLM caller can pass any string — and an unknown tone built a
+// `.ui-toast--error` class that matches no CSS, yielding a silent neutral toast.
+// Validate so an unknown tone degrades to neutral *and warns*, never lies. (C16)
+const TOAST_TONES = new Set(['accent', 'success', 'warning', 'danger', 'info']);
+
 // First-toast deferral queue. The very first toast on a brand-new stack
 // is appended next frame so AT observes the empty aria-live region
 // before its first child. Any further toasts created *before* that frame
@@ -19,7 +25,13 @@ function toastStack(isAssertive) {
     stack = document.createElement('div');
     stack.className = isAssertive ? 'ui-toast-stack ui-toast-stack--assertive' : 'ui-toast-stack';
     stack.setAttribute('aria-live', isAssertive ? 'assertive' : 'polite');
-    if (isAssertive) stack.setAttribute('role', 'alert');
+    if (isAssertive) {
+      stack.setAttribute('role', 'alert');
+      // The assertive region carries one error at a time and must be read whole;
+      // aria-atomic ensures the full toast (title + message) announces, not just
+      // the diff. (component audit C38.)
+      stack.setAttribute('aria-atomic', 'true');
+    }
     document.body.appendChild(stack);
   }
   return { stack, fresh };
@@ -43,9 +55,20 @@ function enqueueToast(place, freshStack) {
 
 function toastElement(message, { tone, title }) {
   const el = document.createElement('div');
-  el.className = tone ? `ui-toast ui-toast--${tone}` : 'ui-toast';
+  const validTone = tone && TOAST_TONES.has(tone) ? tone : null;
+  if (tone && !validTone && typeof console !== 'undefined') {
+    console.warn(
+      `[bronto] toast(): unknown tone "${tone}" — expected ${[...TOAST_TONES].join('/')}. Rendering neutral.`,
+    );
+  }
+  el.className = validTone ? `ui-toast ui-toast--${validTone}` : 'ui-toast';
   // No per-item role: the stack itself is the live region; a nested
-  // live region risks double announcement in some SRs.
+  // live region risks double announcement in some SRs. But mark the toast
+  // aria-atomic so a *titled* toast announces title + message as one unit, not
+  // disjointly — and unlike aria-atomic on the polite STACK (which would re-read
+  // every resident toast on each new one), scoping it to the toast keeps sibling
+  // toasts out of the announcement. (component audit C23.)
+  el.setAttribute('aria-atomic', 'true');
   if (title) {
     const t = document.createElement('p');
     t.className = 'ui-toast__title';
@@ -98,6 +121,15 @@ function addToastClose(el, dismiss) {
   el.appendChild(close);
 }
 
+/**
+ * @typedef {object} ToastOpts
+ * @property {'accent' | 'success' | 'warning' | 'danger' | 'info'} [tone] Status tone — maps to `ui-toast--<tone>`.
+ * @property {string} [title] Optional uppercase label rendered above the message.
+ * @property {number} [duration] Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+ * @property {boolean} [assertive] Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+ * @property {boolean} [closable] Render a dismiss button on the toast.
+ */
+
 /**
  * Push a transient toast into a shared, screen-anchored stack. The stack
  * is the `aria-live="polite"` region: it is created once, appended to
@@ -110,6 +142,10 @@ function addToastClose(el, dismiss) {
  * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
  * it until dismissed). Returns a function that dismisses the toast
  * early. SSR-safe (no-op).
+ *
+ * @param {string} message
+ * @param {ToastOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function toast(message, { tone, title, duration = 4000, assertive, closable } = {}) {
   if (!hasDom()) return noop;
@@ -146,6 +182,14 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
   // it gets a dismiss affordance by default; any toast can opt in via
   // `closable`. The button carries no text node (glyph is a CSS
   // ::before) so the toast's announced/textContent stays the message.
+  // Explicitly opting OUT of the close button on a sticky toast strands it with
+  // no in-UI dismissal — warn that the caller must retain and call the returned
+  // dismiss fn. (component audit C37.)
+  if (duration === 0 && closable === false && typeof console !== 'undefined') {
+    console.warn(
+      '[bronto] toast(): duration:0 + closable:false has no in-UI dismissal — keep the returned dismiss() and call it yourself, or set closable:true.',
+    );
+  }
   if (closable ?? duration === 0) addToastClose(el, dismiss);
   if (duration > 0) timer = setTimeout(dismiss, duration);
   return dismiss;