@ponchia/ui 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@
 |> `^0` / `*` wildcard does **not** protect you. See README → Versioning, and
 |> the deprecation policy in CONTRIBUTING.md.
 
+## 0.14.0 — 2026-10-01
+
+### Added
+
+- **`initCommand({ match })` and `initCommand({ headless: true })`.** `match(row,
+  query)` replaces the substring test, so a row can match on keywords it does
+  not show, or stay visible for every query (a "Search everything" row inside
+  the list, where the keyboard reaches it). Headless mode leaves the result set
+  to the host: Bronto hides nothing and reads the list live, so the host can
+  render new rows on every keystroke without re-running `initCommand`, and
+  Bronto keeps ids, roles, the active row, the keyboard and the empty state's
+  live region. Cleanup restores rows added after init as well.
+- **`@ponchia/ui/css/tool.css`**, the default bundle for a tool, imported
+  instead of `@ponchia/ui`. It is core in core's order without the
+  `navigation`, `site`, `table` and `app` leaves, about 15 kB less.
+- **`css/fonts-inter.css` and `css/fonts-jetbrains-mono.css`**, opt-in leaves
+  that ship the faces `--sans` and `--mono` name first. Before, the package
+  shipped Doto only and every OS drew its own fallback. Inter 4.1 is one
+  variable face per style, and JetBrains Mono 2.304 comes in regular, bold and
+  their italics. Both are unmodified upstream files under the SIL OFL 1.1, with
+  their licenses in `fonts/`.
+- **`ui-body-state` and `ui-alert--band`** for node, panel and card bodies of
+  200–400px. A body state replaces the content: it fills the body and centres
+  one sentence. Use `ui.bodyState()` when empty or loading (`aria-busy` says
+  loading) and `ui.bodyState({ state: 'error' | 'stale' })` for a tone dot. A
+  band is a full-bleed, one-line alert above content the body still shows
+  (`ui.alert({ tone, band: true })`). See usage.md → "Small bodies".
+
+### Changed
+
+- The default bundle grows from 95.8 kB / 16.6 kB gzip to 97.1 kB / 16.8 kB,
+  for the body state, the band and `--alert-tone`. `css/tool.css` is 81.8 kB /
+  14.7 kB.
+- Each `ui-alert--<tone>` also sets `--alert-tone`, which the band variant
+  tints with.
+- `.ui-meta` (the date · author line) moved from `css/site.css` to
+  `css/content.css`, so the tool entry keeps it. The default bundle is
+  unchanged, since content follows site in its cascade. A direct import of
+  `css/site.css` that used `.ui-meta` also needs `css/content.css`.
+
 ## 0.13.0 — 2026-10-01
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@ponchia/ui?logo=npm)](https://www.npmjs.com/package/@ponchia/ui)
 [![npm provenance](https://img.shields.io/badge/npm-provenance-blue?logo=npm)](https://www.npmjs.com/package/@ponchia/ui#provenance)
 [![runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](https://github.com/Ponchia/bronto-ui/blob/main/package.json)
-[![default CSS](https://img.shields.io/badge/default%20CSS-~96kB%20%2F%20~17kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
+[![default CSS](https://img.shields.io/badge/default%20CSS-~97kB%20%2F%20~17kB%20gzip-informational)](https://github.com/Ponchia/bronto-ui/blob/main/scripts/check-dist.mjs)
 [![CI](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/Ponchia/bronto-ui/actions/workflows/ci.yml)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Ponchia/bronto-ui/badge)](https://scorecard.dev/viewer/?uri=github.com/Ponchia/bronto-ui)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE)
@@ -93,12 +93,12 @@ Or drop it in with no build step, straight from a CDN (replace the version only
 when deliberately upgrading across a breaking pre-1.0 minor):
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.13.0/dist/bronto.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ponchia/ui@0.14.0/dist/bronto.css">
 ```
 
 ## Quick start
 
-**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~96 kB raw / ~17 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
+**1. Load the CSS.** One flattened, minified default CSS bundle — the standard component set, one request (~97 kB raw / ~17 kB gzip) — that is `dist/bronto.css`, not the whole package tarball:
 
 ```css
 @import '@ponchia/ui';            /* via a bundler */
@@ -256,4 +256,4 @@ Release candidates publish to the `next` dist-tag, never to `latest` — opt in
 
 [MIT](https://github.com/Ponchia/bronto-ui/blob/main/LICENSE) © Ponchia.
 
-The bundled **Doto** font (`fonts/*.woff2`) is © 2024 The Doto Project Authors and licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt) — see `fonts/OFL.txt`.
+The bundled fonts are licensed separately under the [SIL Open Font License 1.1](https://github.com/Ponchia/bronto-ui/blob/main/fonts/OFL.txt): **Doto** (`fonts/doto-*.woff2`, © 2024 The Doto Project Authors, `fonts/OFL.txt`), and the opt-in **Inter** (`fonts/inter-*.woff2`, © 2016 The Inter Project Authors, `fonts/OFL-Inter.txt`) and **JetBrains Mono** (`fonts/jetbrains-mono-*.woff2`, © 2020 The JetBrains Mono Project Authors, `fonts/OFL-JetBrainsMono.txt`).

package/behaviors/command.d.ts

@@ -1,8 +1,3 @@
-/**
- * @typedef {object} CommandSelectDetail
- * @property {string} value The chosen command's value.
- * @property {string} label The chosen command's visible label.
- */
 /**
  * Command palette — filter + keyboard-navigate a DOM-authored command list.
  * The CSS shell (`.ui-command`) is opt-in; this wires the listbox behavior the
@@ -15,19 +10,21 @@
  * and a list (`.ui-command__list`) of `.ui-command__item` rows (optional
  * `data-value`), interleaved with `.ui-command__group` labels and an optional
  * `.ui-command__empty`. The behavior owns ids, `role=combobox/listbox/option`,
- * `aria-activedescendant`, a roving active item, substring filtering (hiding
- * empty groups), keyboard list navigation (Down/Up/Enter/Escape), and pointer
- * 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.
+ * `aria-activedescendant`, a roving active item, filtering (substring by
+ * default, `match` to replace it, hiding empty groups), keyboard list
+ * navigation (Down/Up/Enter/Escape), and pointer 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.
+ * command list so filtering/navigation see the current nodes — or pass
+ * `headless: true` and render the results yourself.
  *
- * @param {import('./internal.js').DelegateOpts} [opts]
+ * @param {CommandOpts} [opts]
  * @returns {import('./internal.js').Cleanup}
  */
-export function initCommand({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export function initCommand({ root, match, headless }?: CommandOpts): import("./internal.js").Cleanup;
 export type CommandSelectDetail = {
     /**
      * The chosen command's value.
@@ -38,4 +35,28 @@ export type CommandSelectDetail = {
      */
     label: string;
 };
+export type CommandOpts = {
+    /**
+     * Event-delegation root; also scopes which palettes are queried. Default: `document`.
+     * `null` means a scope was requested but is not ready yet, so the behavior no-ops.
+     */
+    root?: Element | Document | null | undefined;
+    /**
+     * Decides whether an item stays visible for a query. `query` is the trimmed
+     * input, lower-cased in the palette's locale; an empty query shows every item.
+     * Default: the item's text contains the query. Use it to match on keywords
+     * (`data-keywords`, say) or to keep a row such as "Search everything" visible
+     * for every query. Not called in headless mode.
+     */
+    match?: ((item: HTMLElement, query: string) => boolean) | undefined;
+    /**
+     * The host renders the result set. Bronto never hides an item or group; it
+     * reads the list live, so the host can replace rows on every keystroke
+     * without re-running `initCommand`. It still owns ids, roles, the roving
+     * active item, the keyboard, pointer select and the empty state's live
+     * region. After the query changes, the first row the host renders becomes
+     * active.
+     */
+    headless?: boolean | undefined;
+};
 //# sourceMappingURL=command.d.ts.map

package/behaviors/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["command.js"],"names":[],"mappings":"AA6BA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,uCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAiP3C;;;;;WA3Qa,MAAM;;;;WACN,MAAM"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["command.js"],"names":[],"mappings":"AA6GA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wDAHW,WAAW,GACT,OAAO,eAAe,EAAE,OAAO,CAuO3C;;;;;WA7Ua,MAAM;;;;WACN,MAAM;;;;;;;;;;;;;;;oBAQC,WAAW,SAAS,MAAM,KAAK,OAAO"}

package/behaviors/command.js

@@ -33,6 +33,80 @@ const lowerForSearch = (value, locale) => {
  * @property {string} label The chosen command's visible label.
  */
 
+/**
+ * @typedef {object} CommandOpts
+ * @property {Document | Element | null} [root]
+ *   Event-delegation root; also scopes which palettes are queried. Default: `document`.
+ *   `null` means a scope was requested but is not ready yet, so the behavior no-ops.
+ * @property {(item: HTMLElement, query: string) => boolean} [match]
+ *   Decides whether an item stays visible for a query. `query` is the trimmed
+ *   input, lower-cased in the palette's locale; an empty query shows every item.
+ *   Default: the item's text contains the query. Use it to match on keywords
+ *   (`data-keywords`, say) or to keep a row such as "Search everything" visible
+ *   for every query. Not called in headless mode.
+ * @property {boolean} [headless]
+ *   The host renders the result set. Bronto never hides an item or group; it
+ *   reads the list live, so the host can replace rows on every keystroke
+ *   without re-running `initCommand`. It still owns ids, roles, the roving
+ *   active item, the keyboard, pointer select and the empty state's live
+ *   region. After the query changes, the first row the host renders becomes
+ *   active.
+ */
+
+const ITEM = '.ui-command__item, [role="option"]';
+
+/** The first non-blank text node under `el`, depth first. */
+function firstTextNode(el) {
+  for (const node of el.childNodes) {
+    if (node.nodeType === 3 && node.nodeValue.trim()) return node;
+    if (node.nodeType === 1) {
+      const child = firstTextNode(node);
+      if (child) return child;
+    }
+  }
+  return null;
+}
+
+/** Re-set an element's first text so a live region announces it again. */
+function refreshLiveText(el) {
+  const node = firstTextNode(el);
+  if (!node) return;
+  const text = node.nodeValue;
+  node.nodeValue = '';
+  node.nodeValue = text;
+}
+
+/**
+ * Records everything a palette changes the first time it is touched, so
+ * cleanup restores rows the host added after init as well.
+ */
+function changeRecorder() {
+  const touched = new Map();
+  const touch = (el, names) => {
+    let saved = touched.get(el);
+    if (!saved) {
+      saved = { hidden: el.hidden, active: el.classList.contains('is-active'), attrs: {} };
+      touched.set(el, saved);
+    }
+    for (const name of names) {
+      if (name in saved.attrs) continue;
+      saved.attrs[name] = { had: el.hasAttribute(name), value: el.getAttribute(name) };
+    }
+  };
+  const restore = () => {
+    for (const [el, saved] of touched) {
+      el.hidden = saved.hidden;
+      el.classList.toggle('is-active', saved.active);
+      for (const [name, attr] of Object.entries(saved.attrs)) {
+        if (attr.had) el.setAttribute(name, attr.value);
+        else el.removeAttribute(name);
+      }
+    }
+    touched.clear();
+  };
+  return { touch, restore };
+}
+
 /**
  * Command palette — filter + keyboard-navigate a DOM-authored command list.
  * The CSS shell (`.ui-command`) is opt-in; this wires the listbox behavior the
@@ -45,178 +119,148 @@ const lowerForSearch = (value, locale) => {
  * and a list (`.ui-command__list`) of `.ui-command__item` rows (optional
  * `data-value`), interleaved with `.ui-command__group` labels and an optional
  * `.ui-command__empty`. The behavior owns ids, `role=combobox/listbox/option`,
- * `aria-activedescendant`, a roving active item, substring filtering (hiding
- * empty groups), keyboard list navigation (Down/Up/Enter/Escape), and pointer
- * 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.
+ * `aria-activedescendant`, a roving active item, filtering (substring by
+ * default, `match` to replace it, hiding empty groups), keyboard list
+ * navigation (Down/Up/Enter/Escape), and pointer 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.
+ * command list so filtering/navigation see the current nodes — or pass
+ * `headless: true` and render the results yourself.
  *
- * @param {import('./internal.js').DelegateOpts} [opts]
+ * @param {CommandOpts} [opts]
  * @returns {import('./internal.js').Cleanup}
  */
-export function initCommand({ root } = {}) {
+export function initCommand({ root, match, headless = false } = {}) {
   if (!hasDom()) return noop;
   const host = resolveHost(root);
   if (!host) return noop;
   const palettes = collectHosts(host, '[data-bronto-command]');
   const cleanups = [];
 
-  const snapshotAttrs = (el, names) => {
-    const out = {};
-    for (const name of names) {
-      out[name] = {
-        had: el.hasAttribute(name),
-        value: el.getAttribute(name),
-      };
-    }
-    return out;
-  };
-
-  const restoreAttrs = (el, attrs) => {
-    for (const [name, attr] of Object.entries(attrs)) {
-      if (attr.had) el.setAttribute(name, attr.value);
-      else el.removeAttribute(name);
-    }
-  };
-
-  const firstTextNode = (el) => {
-    for (const node of el.childNodes) {
-      if (node.nodeType === 3 && node.nodeValue.trim()) return node;
-      if (node.nodeType === 1) {
-        const child = firstTextNode(node);
-        if (child) return child;
-      }
-    }
-    return null;
-  };
-
-  const refreshLiveText = (el) => {
-    const node = firstTextNode(el);
-    if (!node) return;
-    const text = node.nodeValue;
-    node.nodeValue = '';
-    node.nodeValue = text;
-  };
-
-  const prepareEmptyState = (el) => {
-    if (!el) return;
-    el.setAttribute('role', 'status');
-    el.setAttribute('aria-live', 'polite');
-  };
-
   for (const box of palettes) {
     const input = box.querySelector('.ui-command__input, input');
     const list = box.querySelector('.ui-command__list, [role="listbox"]');
     if (!input || !list) continue;
-    const empty = box.querySelector('.ui-command__empty');
-    const items = [...list.querySelectorAll('.ui-command__item, [role="option"]')];
-    const groups = [...list.querySelectorAll('.ui-command__group')];
     const locale = localeOf(box);
+    const initialItems = [...list.querySelectorAll(ITEM)];
+    const initialGroups = [...list.querySelectorAll('.ui-command__group')];
+    // Headless reads the host's current rows; otherwise the rows at init.
+    const itemsNow = () => (headless ? [...list.querySelectorAll(ITEM)] : initialItems);
+    const groupsNow = () =>
+      headless ? [...list.querySelectorAll('.ui-command__group')] : initialGroups;
+    const emptyNow = () => box.querySelector('.ui-command__empty');
 
-    const rememberState = () => ({
-      input: snapshotAttrs(input, [
-        'role',
-        'aria-controls',
-        'aria-autocomplete',
-        'aria-expanded',
-        'aria-activedescendant',
-        'autocomplete',
-      ]),
-      list: snapshotAttrs(list, ['id', 'role']),
-      empty: empty
-        ? {
-            hidden: empty.hidden,
-            attrs: snapshotAttrs(empty, ['role', 'aria-live']),
-          }
-        : null,
-      groups: groups.map((g) => ({
-        el: g,
-        hidden: g.hidden,
-        attrs: snapshotAttrs(g, ['role']),
-      })),
-      items: items.map((it) => ({
-        el: it,
-        hidden: it.hidden,
-        active: it.classList.contains('is-active'),
-        attrs: snapshotAttrs(it, ['id', 'role', 'aria-selected']),
-      })),
-    });
+    const { touch, restore } = changeRecorder();
 
-    const restoreState = (state) => {
-      restoreAttrs(input, state.input);
-      restoreAttrs(list, state.list);
-      if (empty && state.empty) {
-        empty.hidden = state.empty.hidden;
-        restoreAttrs(empty, state.empty.attrs);
-      }
-      for (const group of state.groups) {
-        group.el.hidden = group.hidden;
-        restoreAttrs(group.el, group.attrs);
-      }
-      for (const item of state.items) {
-        item.el.hidden = item.hidden;
-        item.el.classList.toggle('is-active', item.active);
-        restoreAttrs(item.el, item.attrs);
-      }
+    const optionIdBase = `bronto-cmd-opt-${nextFieldUid()}`;
+    let nextOption = 0;
+    const prepared = new WeakSet();
+    const prepareItem = (it) => {
+      if (prepared.has(it)) return;
+      prepared.add(it);
+      touch(it, ['id', 'role', 'aria-selected']);
+      if (!it.id) it.id = `${optionIdBase}-${nextOption++}`;
+      it.setAttribute('role', 'option');
+    };
+    const prepareGroup = (g) => {
+      if (prepared.has(g)) return;
+      prepared.add(g);
+      touch(g, ['role']);
+      g.setAttribute('role', 'presentation');
+    };
+    const prepareEmpty = (el) => {
+      if (!el || prepared.has(el)) return;
+      prepared.add(el);
+      touch(el, ['role', 'aria-live']);
+      el.setAttribute('role', 'status');
+      el.setAttribute('aria-live', 'polite');
+    };
+    const prepareRows = () => {
+      itemsNow().forEach(prepareItem);
+      groupsNow().forEach(prepareGroup);
+      prepareEmpty(emptyNow());
     };
 
-    let active = -1;
-    const visible = () => items.filter((it) => !it.hidden);
+    let activeItem = null;
+    const visible = () => itemsNow().filter((it) => !it.hidden);
 
     const setActive = (item) => {
-      items.forEach((it) => {
+      for (const it of itemsNow()) {
+        prepareItem(it);
         it.classList.toggle('is-active', it === item);
         it.setAttribute('aria-selected', String(it === item));
-      });
+      }
+      activeItem = item;
       if (item) {
-        active = items.indexOf(item);
         input.setAttribute('aria-activedescendant', item.id);
         scrollIntoViewSafe(item);
       } else {
-        active = -1;
         input.removeAttribute('aria-activedescendant');
       }
     };
 
     // Hide a group whose items are all filtered out.
     const syncGroups = () => {
-      for (const g of groups) {
+      for (const g of groupsNow()) {
         let any = false;
         for (
           let n = g.nextElementSibling;
           n && !n.matches('.ui-command__group');
           n = n.nextElementSibling
         ) {
-          if (n.matches('.ui-command__item, [role="option"]') && !n.hidden) any = true;
+          if (n.matches(ITEM) && !n.hidden) any = true;
         }
         g.hidden = !any;
       }
     };
 
+    const matches = match
+      ? (it, q) => !q || Boolean(match(it, q))
+      : (it, q) => !q || lowerForSearch(it.textContent, locale).includes(q);
+
     const filter = () => {
       const q = lowerForSearch(input.value.trim(), locale);
       let any = false;
-      for (const it of items) {
-        const match = !q || lowerForSearch(it.textContent, locale).includes(q);
-        it.hidden = !match;
-        if (match) any = true;
+      for (const it of itemsNow()) {
+        const shown = matches(it, q);
+        it.hidden = !shown;
+        if (shown) any = true;
       }
       syncGroups();
+      const empty = emptyNow();
       if (empty) {
         empty.hidden = any;
         if (!any) refreshLiveText(empty);
       }
-      const vis = visible();
-      setActive(vis[0] || null);
+      setActive(visible()[0] || null);
+    };
+
+    // Headless: the host re-renders after the query changes, so the first row
+    // it renders becomes active then; a row that disappears hands its place to
+    // the first one left. An empty state the host reveals is announced.
+    let queryChanged = false;
+    let emptyShown = false;
+    const onRowsChanged = () => {
+      prepareRows();
+      const rows = visible();
+      if (queryChanged || !activeItem || !rows.includes(activeItem)) {
+        queryChanged = false;
+        setActive(rows[0] || null);
+      }
+      const empty = emptyNow();
+      const shown = Boolean(empty && !empty.hidden);
+      if (shown && !emptyShown) refreshLiveText(empty);
+      emptyShown = shown;
     };
 
     const move = (delta) => {
+      queryChanged = false;
       const vis = visible();
       if (!vis.length) return;
-      setActive(vis[wrapIndex(vis.indexOf(items[active]), delta, vis.length)]);
+      setActive(vis[wrapIndex(vis.indexOf(activeItem), delta, vis.length)]);
     };
 
     const choose = (item) => {
@@ -234,7 +278,10 @@ export function initCommand({ root } = {}) {
       );
     };
 
-    const onInput = () => filter();
+    const onInput = () => {
+      if (headless) queryChanged = true;
+      else filter();
+    };
     const onKey = (e) => {
       switch (e.key) {
         case 'ArrowDown':
@@ -246,8 +293,8 @@ export function initCommand({ root } = {}) {
           move(-1);
           break;
         case 'Enter':
-          if (active >= 0 && !items[active].hidden) {
-            choose(items[active]);
+          if (activeItem && activeItem.isConnected && !activeItem.hidden) {
+            choose(activeItem);
             e.preventDefault();
           }
           break;
@@ -259,21 +306,23 @@ export function initCommand({ root } = {}) {
       }
     };
     const onClick = (e) => {
-      const item = closestSafe(e.target, '.ui-command__item, [role="option"]');
+      const item = closestSafe(e.target, ITEM);
       if (item && list.contains(item)) choose(item);
     };
 
     const bound = bindOnce(box, 'command', () => {
-      const state = rememberState();
+      touch(input, [
+        'role',
+        'aria-controls',
+        'aria-autocomplete',
+        'aria-expanded',
+        'aria-activedescendant',
+        'autocomplete',
+      ]);
+      touch(list, ['id', 'role']);
       const listId = list.id || (list.id = `bronto-cmd-${nextFieldUid()}`);
-      const optionIdBase = `bronto-cmd-opt-${nextFieldUid()}`;
-      items.forEach((it, i) => {
-        if (!it.id) it.id = `${optionIdBase}-${i}`;
-        it.setAttribute('role', 'option');
-      });
-      groups.forEach((g) => g.setAttribute('role', 'presentation'));
+      prepareRows();
       list.setAttribute('role', 'listbox');
-      prepareEmptyState(empty);
       input.setAttribute('role', 'combobox');
       input.setAttribute('aria-controls', listId);
       input.setAttribute('aria-autocomplete', 'list');
@@ -282,14 +331,31 @@ export function initCommand({ root } = {}) {
       input.addEventListener('input', onInput);
       input.addEventListener('keydown', onKey);
       list.addEventListener('click', onClick);
-      // Seed the initial active item (first visible).
-      filter();
+      let observer = null;
+      if (headless) {
+        // The palette's own window, so a palette in another realm still observes.
+        const Observer = box.ownerDocument?.defaultView?.MutationObserver;
+        observer = Observer ? new Observer(onRowsChanged) : null;
+        observer?.observe(box, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ['hidden'],
+        });
+        const empty = emptyNow();
+        emptyShown = Boolean(empty && !empty.hidden);
+        setActive(visible()[0] || null);
+      } else {
+        // Seed the initial active item (first visible).
+        filter();
+      }
       return () => {
+        observer?.disconnect();
         input.removeEventListener('input', onInput);
         input.removeEventListener('keydown', onKey);
         list.removeEventListener('click', onClick);
-        restoreState(state);
-        active = -1;
+        restore();
+        activeItem = null;
       };
     });
     cleanups.push(bound);

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 696,
-    "groups": 187
+    "classes": 700,
+    "groups": 188
   },
   "groups": {
     "ui-accordion": {
@@ -23,6 +23,7 @@
       "base": "ui-alert",
       "modifiers": [
         "ui-alert--accent",
+        "ui-alert--band",
         "ui-alert--danger",
         "ui-alert--info",
         "ui-alert--success",
@@ -195,6 +196,14 @@
       ],
       "parts": []
     },
+    "ui-body-state": {
+      "base": "ui-body-state",
+      "modifiers": [
+        "ui-body-state--error",
+        "ui-body-state--stale"
+      ],
+      "parts": []
+    },
     "ui-bracket-note": {
       "base": "ui-bracket-note",
       "modifiers": [
@@ -1604,6 +1613,7 @@
     "ui-activity",
     "ui-alert",
     "ui-alert--accent",
+    "ui-alert--band",
     "ui-alert--danger",
     "ui-alert--info",
     "ui-alert--success",
@@ -1685,6 +1695,9 @@
     "ui-badge--muted",
     "ui-badge--success",
     "ui-badge--warning",
+    "ui-body-state",
+    "ui-body-state--error",
+    "ui-body-state--stale",
     "ui-bracket-note",
     "ui-bracket-note--accent",
     "ui-bracket-note--danger",

package/classes/index.d.ts

@@ -133,6 +133,10 @@ export declare const cls: {
   readonly alertWarning: 'ui-alert--warning';
   readonly alertDanger: 'ui-alert--danger';
   readonly alertInfo: 'ui-alert--info';
+  readonly alertBand: 'ui-alert--band';
+  readonly bodyState: 'ui-body-state';
+  readonly bodyStateError: 'ui-body-state--error';
+  readonly bodyStateStale: 'ui-body-state--stale';
   readonly toastStack: 'ui-toast-stack';
   readonly toastStackAssertive: 'ui-toast-stack--assertive';
   readonly toast: 'ui-toast';
@@ -723,6 +727,10 @@ export interface ButtonOpts {
 export interface EmptyStateOpts {
   invite?: boolean;
 }
+export interface BodyStateOpts {
+  /** Omit for empty and loading (mark a loading region aria-busy). */
+  state?: 'error' | 'stale';
+}
 export interface ToolstripOpts {
   variant?: 'floating' | 'compact' | 'pane';
   anchor?: 'block-start' | 'block-end';
@@ -796,6 +804,7 @@ export interface StaggerOpts {
 export type Tone = 'accent' | 'success' | 'warning' | 'danger' | 'info';
 export interface AlertOpts {
   tone?: Tone;
+  band?: boolean;
 }
 export interface ToastOpts {
   tone?: Tone;
@@ -1015,6 +1024,7 @@ export interface Ui {
   job(opts?: JobOpts): string;
   originLabel(opts?: OriginLabelOpts): string;
   emptyState(opts?: EmptyStateOpts): string;
+  bodyState(opts?: BodyStateOpts): string;
   toolstrip(opts?: ToolstripOpts): string;
   selectionbar(opts?: SelectionbarOpts): string;
 }