@apliteni/apliteni-ui 0.27.0 → 0.30.0

package/src/components/drawer.js

@@ -68,6 +68,33 @@ export function drawer({
     + `</aside></div>`;
 }
 
+/**
+ * One group inside a drawer's body: an optional heading over label/value rows,
+ * then any trailing markup (an action that belongs to the group). Rows render as
+ * a <dl>, so a screen reader hears each label with its value.
+ *
+ *   drawer({ title, body: drawerSection({ title: 'Source', rows: [['Statement', '#4102']] }) })
+ *
+ * why: docs/specification.md#the-drawer
+ *
+ * @param {object} [o]
+ * @param {string} [o.title]  group heading (escaped)
+ * @param {Array<[string, string | { html: string }]>} [o.rows]  [label, value] pairs. Both are
+ *   escaped, since a value is usually data (a bank feed's description); pass the value as
+ *   `{ html: '…' }` to write trusted markup as it is
+ * @param {string} [o.body]   trailing markup after the rows (trusted)
+ * @returns {string} html
+ */
+export function drawerSection({ title, rows = [], body = '' } = {}) {
+  const head = title ? `<h3 class="ui-drawer__section-title">${esc(title)}</h3>` : '';
+  const value = (v) => (v !== null && typeof v === 'object' && 'html' in v ? String(v.html) : esc(v));
+  const list = rows.length
+    ? `<dl class="ui-drawer__rows">${rows.map(([term, detail]) =>
+      `<div class="ui-drawer__row"><dt>${esc(term)}</dt><dd>${value(detail)}</dd></div>`).join('')}</dl>`
+    : '';
+  return `<section class="ui-drawer__section">${head}${list}${body}</section>`;
+}
+
 // ---- Shared behaviour ----------------------------------------------------
 // One open/close/scrim/close-button implementation for every drawer in the kit;
 // inertness, Escape and Tab belong to the overlay stack. Per-instance handlers
@@ -92,11 +119,13 @@ export function openDrawer(root, returnFocusTo) {
 export function closeDrawer(root) {
   if (!root || !root.classList.contains('is-open')) return;
   root.classList.remove('is-open');
-  popOverlay(root);
   const back = root.__drawerReturn;
   root.__drawerReturn = null;
   // The trigger can be gone by now — focus() on a detached node does nothing at
-  // all, which leaves the reader with no place on the page.
+  // all, which leaves the reader with no place on the page. popOverlay is told
+  // where focus is headed so it can catch the other way that happens: a trigger
+  // still on the page, inside what an overlay left open underneath has re-hidden.
+  popOverlay(root, back);
   returnFocus(back, root.ownerDocument);
 }
 

package/src/components/dropdown.js

@@ -16,7 +16,8 @@ import { esc, icon } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
 
-// A trailing status badge. `badge` is a string ("live") or { text, tone }.
+// A trailing status badge. `badge` is the text shown, in the case it is written
+// ("Live"), or { text, tone }; a string reading "live" in any case takes the live tone.
 function ddBadge(badge) {
   if (!badge) return '';
   const text = typeof badge === 'string' ? badge : badge.text;
@@ -26,8 +27,8 @@ function ddBadge(badge) {
 }
 
 // One item row. `listbox` picks role=option (selectable) vs role=menuitem (action).
-function ddItem(it, listbox) {
-  if (it === '---' || it.separator) return '<div class="ui-dropdown__sep" role="separator"></div>';
+function ddItem(it, listbox, ext) {
+  if (it === '---' || it.separator) return `<div class="ui-dropdown__sep" role="separator"${ext?.filtering ? ' hidden' : ''}></div>`;
   const disabled = !!it.disabled;
   const selected = !!it.selected;
   const role = listbox ? 'option' : 'menuitem';
@@ -48,19 +49,89 @@ function ddItem(it, listbox) {
     disabled ? 'aria-disabled="true"' : '',
     asLink ? `href="${esc(it.href)}"` : '',
     asLink && it.target ? `target="${esc(it.target)}"` : '',
+    ext?.id ? `id="${esc(ext.id)}"` : '',
+    ext?.hidden ? 'hidden' : '',
   ].filter(Boolean).join(' ');
   return `<${tag} ${attrs}>${lead}${main}${badge}${tick}</${tag}>`;
 }
 
-// Render a flat item list or grouped sections ([{ label, items }]).
-function ddBody({ items, sections }, listbox) {
+// Render a flat item list or grouped sections ([{ label, items }]). `sx` is the
+// search variant's context; the plain dropdown passes none and its markup is
+// unchanged.
+function ddBody({ items, sections }, listbox, sx) {
+  const one = (it) => ddItem(it, listbox, sx && ddRowExt(it, sx));
   if (sections && sections.length) {
     return sections.map((s) => {
       const head = s.label ? `<div class="ui-dropdown__group" role="presentation">${esc(s.label)}</div>` : '';
-      return `<div class="ui-dropdown__section" role="group"${s.label ? ` aria-label="${esc(s.label)}"` : ''}>${head}${(s.items || []).map((it) => ddItem(it, listbox)).join('')}</div>`;
+      const gone = sx && ddFiltering(sx.q) && !(s.items || []).some((it) => ddIsRow(it) && ddMatch(it.label, sx.q));
+      return `<div class="ui-dropdown__section" role="group"${s.label ? ` aria-label="${esc(s.label)}"` : ''}${gone ? ' hidden' : ''}>${head}${(s.items || []).map(one).join('')}</div>`;
     }).join('');
   }
-  return (items || []).map((it) => ddItem(it, listbox)).join('');
+  return (items || []).map(one).join('');
+}
+
+// ---- Search --------------------------------------------------------------
+// The match is a substring of the label, anywhere in it, ignoring case and
+// accents; rows keep their order. The factory and the wiring both ask
+// ddMatch(), so a preset query and a typed one hide the same rows.
+// why: docs/specification.md#a-dropdown-with-a-search-field
+// NFD takes the mark off é or ö; ł, ø, đ and the rest are letters of their own
+// with nothing to take off, so they are mapped by hand.
+const FOLD = { ł: 'l', ø: 'o', đ: 'd', ð: 'd', ß: 'ss', æ: 'ae', œ: 'oe', ı: 'i', þ: 'th' };
+const fold = (s) => String(s == null ? '' : s).normalize('NFD').replace(/\p{M}/gu, '').toLowerCase()
+  .replace(/[łøđðßæœıþ]/g, (c) => FOLD[c]);
+const ddFiltering = (q) => fold(q).trim() !== '';
+const ddMatch = (label, q) => fold(label).includes(fold(q).trim());
+const ddIsRow = (it) => it && it !== '---' && !it.separator;
+
+let _ddSeq = 0;
+
+function ddSearchContext(search, id) {
+  const o = search === true ? {} : search;
+  return {
+    base: id || `ui-dd-${++_ddSeq}`,
+    n: 0,
+    q: o.query || '',
+    label: o.label,
+    placeholder: o.placeholder || 'Search',
+    empty: o.empty || 'No match for “{q}”',
+    hint: o.hint || 'Check the spelling, or try fewer letters.',
+  };
+}
+
+function ddRowExt(it, sx) {
+  if (!ddIsRow(it)) return { filtering: ddFiltering(sx.q) };
+  return { id: `${sx.base}-opt-${sx.n++}`, hidden: !ddMatch(it.label, sx.q) };
+}
+
+// The no-match state. A function replacer, so a `$&` typed into the field is
+// text rather than a replacement pattern.
+function ddNone(empty, hint, q) {
+  return `<span class="ui-dropdown__none-title">${esc(empty.replace('{q}', () => q.trim()))}</span>`
+    + `<span class="ui-dropdown__none-hint">${esc(hint)}</span>`;
+}
+
+// The field is a combobox that owns the list; the rows stay options, and the
+// one Enter would pick is named by aria-activedescendant, so focus never
+// leaves the field while the reader types.
+function ddSearchBody({ items, sections }, sx, name, scroll) {
+  const listId = `${sx.base}-list`;
+  const rows = ddBody({ items, sections }, true, sx);
+  const flat = (sections ? sections.flatMap((s) => s.items || []) : (items || [])).filter(ddIsRow);
+  const shown = flat.some((it) => ddMatch(it.label, sx.q));
+  const cap = scroll && scroll !== true ? ` style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '';
+  const input = [
+    'class="ui-dropdown__search-input"', 'type="text"', 'role="combobox"',
+    'aria-autocomplete="list"', 'aria-expanded="true"', `aria-controls="${esc(listId)}"`,
+    `aria-label="${esc(sx.label || `Search ${name}`)}"`, `placeholder="${esc(sx.placeholder)}"`,
+    'autocomplete="off"', 'spellcheck="false"', 'data-dd-search',
+    sx.q ? `value="${esc(sx.q)}"` : '',
+  ].filter(Boolean).join(' ');
+  return `<div class="ui-dropdown__search">`
+    + `<span class="ui-dropdown__search-ic" aria-hidden="true">${icon('search')}</span><input ${input}></div>`
+    + `<div class="ui-dropdown__list" role="listbox" id="${esc(listId)}" aria-label="${esc(name)}"${cap}>${rows}</div>`
+    + `<div class="ui-dropdown__none" role="status" data-dd-none data-dd-empty="${esc(sx.empty)}" data-dd-hint="${esc(sx.hint)}">`
+    + `${shown || !ddFiltering(sx.q) ? '' : ddNone(sx.empty, sx.hint, sx.q)}</div>`;
 }
 
 /**
@@ -81,18 +152,22 @@ function ddBody({ items, sections }, listbox) {
  * @param {boolean|number} [o.scroll] true, or a maxHeight in px, to cap and scroll
  * @param {boolean} [o.open]       render already-open (handy for screenshots)
  * @param {string} [o.ariaLabel]   accessible name for the panel and trigger
+ * @param {boolean|object} [o.search] true, or { placeholder, label, empty, hint, query } —
+ *   a field above the rows that filters them; `empty` may carry {q}
  * @returns {string} html
  */
 export function dropdown({
   label, value, placeholder = 'Select…', variant, items, sections,
   header = '', footer = '', triggerContent, triggerClass = '', chevron = true,
   align = 'start', direction = 'down', portal = false,
-  scroll = false, open = false, ariaLabel, id, panelClass = '',
+  scroll = false, open = false, ariaLabel, id, panelClass = '', search = false,
 } = {}) {
   const flat = sections ? sections.flatMap((s) => s.items || []) : (items || []);
   const isSelect = variant === 'select' || (variant == null && flat.some((it) => it && (it.selected || it.value != null)));
   const listRole = isSelect ? 'listbox' : 'menu';
   const cur = value != null ? value : (isSelect ? (flat.find((it) => it && it.selected)?.label) : null);
+  const sx = search ? ddSearchContext(search, id) : null;
+  const name = ariaLabel || (label ? String(label).replace(/:\s*$/, '') : '') || 'Options';
 
   const trig = triggerContent != null
     ? triggerContent
@@ -102,7 +177,7 @@ export function dropdown({
     `class="${cx('ui-dropdown__trigger', triggerClass)}"`,
     'type="button"',
     'data-dropdown-trigger',
-    `aria-haspopup="${listRole}"`,
+    `aria-haspopup="${sx ? 'dialog' : listRole}"`,
     `aria-expanded="${open ? 'true' : 'false'}"`,
     ariaLabel && triggerContent != null ? `aria-label="${esc(ariaLabel)}"` : '',
   ].filter(Boolean).join(' ');
@@ -114,15 +189,17 @@ export function dropdown({
       'ui-dropdown__panel',
       align === 'end' && 'is-end',
       direction === 'up' && 'is-up',
-      scroll && 'is-scroll',
+      scroll && !sx && 'is-scroll',
+      sx && 'ui-dropdown__panel--search',
       portal && 'ui-dropdown__panel--portal',
       portal && open && 'is-open',
       panelClass,
     )}"`,
     'data-dropdown-panel',
-    `role="${listRole}"`,
-    ariaLabel ? `aria-label="${esc(ariaLabel)}"` : '',
-    scroll && scroll !== true ? `style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
+    // With search the panel holds a field and a list, which a listbox may not.
+    `role="${sx ? 'dialog' : listRole}"`,
+    sx ? `aria-label="${esc(name)}"` : (ariaLabel ? `aria-label="${esc(ariaLabel)}"` : ''),
+    scroll && scroll !== true && !sx ? `style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
   ].filter(Boolean).join(' ');
 
   const ddAttrs = 'data-dropdown'
@@ -132,7 +209,7 @@ export function dropdown({
 
   return `<div class="${cx('ui-dropdown', open && 'open')}" ${ddAttrs}${id ? ` id="${esc(id)}"` : ''}>` +
     `<button ${triggerAttrs}>${trig}${chevron ? '<span class="ui-dropdown__chevron" aria-hidden="true"></span>' : ''}</button>` +
-    `<div ${panelAttrs}>${header}${ddBody({ items, sections }, isSelect)}${footer}</div>` +
+    `<div ${panelAttrs}>${header}${sx ? ddSearchBody({ items, sections }, sx, name, scroll) : ddBody({ items, sections }, isSelect)}${footer}</div>` +
     `</div>`;
 }
 
@@ -165,7 +242,59 @@ function ddItemsOf(dd) {
   const panel = ddPanelOf(dd);
   if (!panel) return [];
   return Array.from(panel.querySelectorAll('[data-dd-item]'))
-    .filter((el) => el.getAttribute('aria-disabled') !== 'true');
+    .filter((el) => el.getAttribute('aria-disabled') !== 'true' && !el.hidden);
+}
+
+// ---- Search wiring ---------------------------------------------------------
+// why: docs/specification.md#a-dropdown-with-a-search-field
+const ddSearchOf = (dd) => ddPanelOf(dd)?.querySelector('[data-dd-search]') || null;
+const ddActiveOf = (dd) => ddPanelOf(dd)?.querySelector('[data-dd-item].is-active') || null;
+const ddComposing = (e) => e.isComposing || e.keyCode === 229;
+
+// Mark the row Enter would pick and keep it inside the list's scroll box,
+// without scrolling the page the way scrollIntoView() would.
+function ddSetActive(dd, row) {
+  const search = ddSearchOf(dd);
+  if (!search) return;
+  ddActiveOf(dd)?.classList.remove('is-active');
+  if (!row) { search.removeAttribute('aria-activedescendant'); return; }
+  row.classList.add('is-active');
+  search.setAttribute('aria-activedescendant', row.id);
+  const list = row.closest('.ui-dropdown__list');
+  if (!list || !list.clientHeight) return;
+  const top = row.offsetTop - list.offsetTop;
+  if (top < list.scrollTop) list.scrollTop = top;
+  else if (top + row.offsetHeight > list.scrollTop + list.clientHeight) list.scrollTop = top + row.offsetHeight - list.clientHeight;
+}
+
+function ddFilter(dd) {
+  const panel = ddPanelOf(dd);
+  const search = ddSearchOf(dd);
+  if (!panel || !search) return;
+  const q = search.value;
+  let shown = 0;
+  panel.querySelectorAll('[data-dd-item]').forEach((row) => {
+    row.hidden = !ddMatch((row.querySelector('.ui-dropdown__label') || row).textContent, q);
+    if (!row.hidden) shown += 1;
+  });
+  panel.querySelectorAll('.ui-dropdown__sep').forEach((el) => { el.hidden = ddFiltering(q); });
+  panel.querySelectorAll('.ui-dropdown__section').forEach((el) => { el.hidden = !el.querySelector('[data-dd-item]:not([hidden])'); });
+  const none = panel.querySelector('[data-dd-none]');
+  if (none) {
+    none.innerHTML = shown || !ddFiltering(q) ? ''
+      : ddNone(none.getAttribute('data-dd-empty') || '', none.getAttribute('data-dd-hint') || '', q);
+  }
+  ddSetActive(dd, ddItemsOf(dd)[0] || null);
+}
+
+// Every open starts from the whole list. Reset here rather than on close, so
+// a panel fading out after a pick does not flash back to every row.
+function ddResetSearch(dd, panel, search) {
+  search.value = '';
+  ddFilter(dd);
+  panel.style.minWidth = '';
+  // Hold the width the whole list needs, so the panel does not narrow as rows go.
+  if (panel.offsetWidth) panel.style.minWidth = `${panel.offsetWidth}px`;
 }
 
 // `auto` is the only direction the wiring decides; `up` and the default are the
@@ -225,12 +354,22 @@ function closeAllDropdowns(except) {
 function openDropdown(dd, focusIdx) {
   closeAllDropdowns(dd);
   const panel = ddPanelOf(dd);
+  const search = ddSearchOf(dd);
+  if (panel && search) ddResetSearch(dd, panel, search);
   if (panel) {
     ddResolveDirection(dd, panel);
     if (dd.__ddPanel) { positionPortalPanel(dd, panel); panel.classList.add('is-open'); }
   }
   dd.classList.add('open');
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'true');
+  // With search, focus goes to the field however the panel was opened, and
+  // the selected row (or the first) is the one Enter would pick.
+  if (search) {
+    const items = ddItemsOf(dd);
+    ddSetActive(dd, items.find((el) => el.getAttribute('aria-selected') === 'true') || items[0] || null);
+    search.focus();
+    return;
+  }
   if (focusIdx != null) {
     const items = ddItemsOf(dd);
     const sel = items.findIndex((el) => el.getAttribute('aria-selected') === 'true');
@@ -241,7 +380,9 @@ function openDropdown(dd, focusIdx) {
 // Single-select: reflect the picked option into aria-selected + the trigger value.
 function selectOption(dd, item) {
   if (!dd.hasAttribute('data-dropdown-select')) return;
-  ddItemsOf(dd).forEach((el) => el.setAttribute('aria-selected', el === item ? 'true' : 'false'));
+  // Every enabled row, the ones a search query has hidden included.
+  ddPanelOf(dd)?.querySelectorAll('[data-dd-item]:not([aria-disabled="true"])')
+    .forEach((el) => el.setAttribute('aria-selected', el === item ? 'true' : 'false'));
   ddPanelOf(dd)?.querySelectorAll('[data-dd-item].is-selected').forEach((el) => el.classList.remove('is-selected'));
   item.classList.add('is-selected');
   const valueEl = dd.querySelector('[data-dropdown-trigger] .ui-dropdown__value');
@@ -292,11 +433,45 @@ export function wireDropdown(root = document) {
         closeDropdown(dd);
         trigger.focus();
       });
+      const field = panel.querySelector('[data-dd-search]');
+      if (field) {
+        field.addEventListener('input', () => ddFilter(dd));
+        // The pointer moves the pick too, so Enter takes the row under it. A
+        // move to the same point is the browser's own after a scroll, not the
+        // reader's, and would snatch the pick from the arrows.
+        let at = '';
+        panel.addEventListener('mousemove', (e) => {
+          const here = `${e.clientX},${e.clientY}`;
+          if (here === at) return;
+          at = here;
+          const row = e.target.closest('[data-dd-item]');
+          if (row && row.getAttribute('aria-disabled') !== 'true' && !row.classList.contains('is-active')) ddSetActive(dd, row);
+        });
+      }
     }
 
     const onKeydown = (e) => {
       const open = dd.classList.contains('open');
       const onTrigger = e.target === trigger;
+      const search = ddSearchOf(dd);
+      // While an IME is composing, its keys commit or steer the text, not the
+      // list. Safari's committing Enter carries keyCode 229, not isComposing.
+      if (e.target === search && ddComposing(e)) return;
+      if (search && open) {
+        // Arrows walk the rows still showing; focus stays in the field.
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+          e.preventDefault();
+          const items = ddItemsOf(dd);
+          if (!items.length) return;
+          const i = items.indexOf(ddActiveOf(dd));
+          const next = e.key === 'ArrowDown' ? (i + 1) % items.length : (i <= 0 ? items.length - 1 : i - 1);
+          ddSetActive(dd, items[next]);
+          return;
+        }
+        if (e.target === search && e.key === 'Enter') { e.preventDefault(); ddActiveOf(dd)?.click(); return; }
+        // Home and End move the caret in a text field; they are not the list's.
+        if (e.target === search && (e.key === 'Home' || e.key === 'End')) return;
+      }
       if ((e.key === 'ArrowDown' || e.key === 'ArrowUp') && (onTrigger || open)) {
         e.preventDefault();
         if (!open) return openDropdown(dd, e.key === 'ArrowDown' ? 0 : 'selected');
@@ -337,7 +512,7 @@ export function wireDropdown(root = document) {
     _ddGlobalWired = true;
     document.addEventListener('click', () => closeAllDropdowns());
     document.addEventListener('keydown', (e) => {
-      if (e.key !== 'Escape') return;
+      if (e.key !== 'Escape' || ddComposing(e)) return;
       const open = document.querySelector('[data-dropdown].open');
       if (open) { closeDropdown(open); open.querySelector('[data-dropdown-trigger]')?.focus(); }
     });

package/src/components/feedback.js

@@ -9,6 +9,7 @@
 // (onSend does the POST / issue / whatever) and any deep-link shaping. Styles
 // ship in styles/feedback.css (part of the kit stylesheet). Accent-aware.
 import { esc } from './index.js';
+import { playEntrance } from '../motion.js';
 
 // Decorative, like every glyph in the kit — the pill and the buttons carry their
 // own text or aria-label, so the SVGs stay out of the accessibility tree.
@@ -16,7 +17,6 @@ const IC_MSG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strok
 const IC_LINES = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true" focusable="false"><path d="M4 5h16M4 12h10M4 19h7"/></svg>';
 const IC_X = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false"><path d="M6 6l12 12M18 6L6 18"/></svg>';
 const CHECK = '<svg class="ui-fbck" viewBox="0 0 150 150" aria-hidden="true"><path class="ui-fbck-t" d="M40 78l24 24 46-50"/><path class="ui-fbck-m" d="M40 78l24 24 46-50"/><path class="ui-fbck-s" d="M40 78l24 24 46-50"/></svg>';
-
 // The widget markup — append once to the page (e.g. document.body). Copy is
 // static here; behaviour + the dynamic chip/quote come from wireFeedback().
 export function feedbackWidget({
@@ -164,7 +164,7 @@ export function wireFeedback(opts = {}) {
 
   function fail(msg) {
     errEl.textContent = msg || 'Could not send just now — try again in a moment.';
-    errEl.classList.add('show'); sendLb.textContent = 'Send feedback'; sendBtn.disabled = false;
+    errEl.classList.add('show'); playEntrance(errEl); sendLb.textContent = 'Send feedback'; sendBtn.disabled = false;
   }
   sendBtn.addEventListener('click', async () => {
     if (sendBtn.disabled || !pending) return;

package/src/components/index.js

@@ -56,11 +56,14 @@ export function statusDot(live = false) {
 }
 
 // ---- Card ----------------------------------------------------------------
-export function card({ title, sub, body = '', variant, pad, icon: ic } = {}) {
+// The title is a heading one level under the page's h1 unless `level` says
+// otherwise. why: docs/specification.md#labels-and-titles
+export function card({ title, sub, body = '', variant, pad, icon: ic, level = 2 } = {}) {
   const cls = cx('ui-card', variant && `ui-card--${variant}`, pad && `ui-card--pad-${pad}`);
+  const h = [2, 3, 4, 5, 6].includes(Number(level)) ? `h${Number(level)}` : 'h2';
   // title/sub are trusted markup (may carry a badge/icon) — not escaped.
   const head = title
-    ? `<div class="ui-card__title">${ic ? `<span class="ui-card__icon">${icon(ic)}</span>` : ''}${title}</div>${sub ? `<div class="ui-card__sub">${sub}</div>` : ''}`
+    ? `<${h} class="ui-card__title">${ic ? `<span class="ui-card__icon">${icon(ic)}</span>` : ''}${title}</${h}>${sub ? `<div class="ui-card__sub">${sub}</div>` : ''}`
     : '';
   return `<div class="${cls}">${head}${body}</div>`;
 }

package/src/components/loading.js

@@ -8,9 +8,9 @@
 // why: docs/specification.md#pending-and-denied-states
 import { icon } from '../assets/icons.js';
 import { button, esc } from './index.js';
+import { playEntrance } from '../motion.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
-
 // ---- Skeleton ------------------------------------------------------------
 // The placeholder shape. `lines` is a count, or an array of widths when the
 // varied ragged edge of real prose matters (['100%','92%','60%']). `height`
@@ -80,7 +80,8 @@ export function setBusy(root, { busy = false, message, body } = {}) {
   region.setAttribute('aria-busy', busy ? 'true' : 'false');
   if (body != null) {
     const slot = region.querySelector('[data-busy-body]');
-    if (slot) slot.innerHTML = body;
+    // The new body fades in. Only here — the region the page loads with is still.
+    if (slot) { slot.innerHTML = body; playEntrance(slot); }
   }
   const msg = region.querySelector('[data-busy-msg]');
   if (msg) {

package/src/components/nav.js

@@ -7,6 +7,7 @@
 // <nav> + <a aria-current="page">, not role="tablist" (that is what segmented()
 // is for). Only the collapsible sidebar groups need JS; wire with wireNav().
 import { esc, icon } from './index.js';
+import { playEntrance } from '../motion.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
 
@@ -44,7 +45,7 @@ const leafName = (label, collapsed, badge) => {
 
 // One sidebar leaf: a link (or a plain, aria-disabled span). `collapsed` also
 // hides the label visually, leaving the icon hoverable.
-function sideLeaf(it, active, { collapsed, sub } = {}) {
+function sideLeaf(it, active, { collapsed, sub, current = 'page' } = {}) {
   const on = it.id != null && it.id === active;
   const disabled = !!it.disabled;
   const label = it.label || '';
@@ -60,7 +61,7 @@ function sideLeaf(it, active, { collapsed, sub } = {}) {
     `class="${cls}"`,
     `href="${esc(it.href || '#' + (it.id ?? ''))}"`,
     it.target ? `target="${esc(it.target)}"` : '',
-    on ? 'aria-current="page"' : '',
+    on ? `aria-current="${current}"` : '',
     name.trim(),
   ].filter(Boolean).join(' ');
   return `<li><a ${attrs}>${lead}${text}${badge}</a></li>`;
@@ -69,14 +70,14 @@ function sideLeaf(it, active, { collapsed, sub } = {}) {
 // A collapsible group: a toggle button (aria-expanded/-controls) over a nested
 // list. In collapsed (icon-only) mode groups don't expand, so we render the
 // group head as a plain, non-collapsing icon row.
-function sideGroup(it, active, { collapsed } = {}) {
+function sideGroup(it, active, { collapsed, current } = {}) {
   const listId = nextId('nav-grp');
   const childActive = (it.items || []).some((c) => c.id != null && c.id === active);
   const open = collapsed ? false : (it.open != null ? !!it.open : childActive);
   const lead = it.icon ? `<span class="ui-nav__ic">${icon(it.icon)}</span>` : '';
   const label = it.label || '';
   const text = `<span class="ui-nav__label">${esc(label)}</span>`;
-  const kids = (it.items || []).map((c) => sideLeaf(c, active, { collapsed, sub: true })).join('');
+  const kids = (it.items || []).map((c) => sideLeaf(c, active, { collapsed, sub: true, current })).join('');
   const name = leafName(label, collapsed);
   const btn =
     `<button type="button" class="${cx('ui-nav__item', 'ui-nav__toggle', childActive && 'is-current')}"` +
@@ -94,13 +95,17 @@ function sideItem(it, active, opts) {
 //   items/section items: { id, label, icon?, href?, target?, badge?, danger?,
 //                           disabled?, items?, open? }  (items ⇒ collapsible group)
 //   active     id of the current item (gets aria-current="page")
+//   activeIs   'page', or 'section' when the page on screen sits below the active
+//              row: the row then carries aria-current="true", because "page" would
+//              announce the list as the page the reader is on
 //   collapsed  icon-only rail; every item is aria-labelled at every width, and
 //              collapsed adds the hover tooltip on top
 //   footer     trusted HTML pinned below a divider (e.g. a sign-out link)
 //   ariaLabel  accessible name for the <nav> landmark
 export function sidebarNav({
-  sections, items, active, collapsed = false, footer = '', ariaLabel = 'Sidebar', id,
+  sections, items, active, activeIs = 'page', collapsed = false, footer = '', ariaLabel = 'Sidebar', id,
 } = {}) {
+  const current = activeIs === 'section' ? 'true' : 'page';
   const blocks = (sections && sections.length)
     ? sections
     : [{ items: items || [] }];
@@ -110,7 +115,7 @@ export function sidebarNav({
       ? `<div class="ui-nav__cap" id="${capId}"${collapsed ? ' aria-hidden="true"' : ''}>${esc(sec.label)}</div>`
       : '';
     const list = `<ul class="ui-nav__list"${capId ? ` aria-labelledby="${capId}"` : ''}>` +
-      (sec.items || []).map((it) => sideItem(it, active, { collapsed })).join('') + `</ul>`;
+      (sec.items || []).map((it) => sideItem(it, active, { collapsed, current })).join('') + `</ul>`;
     return `<div class="ui-nav__section">${cap}${list}</div>`;
   }).join('');
   const foot = footer ? `<div class="ui-nav__foot">${footer}</div>` : '';
@@ -182,7 +187,10 @@ function toggleGroup(btn) {
   const open = btn.getAttribute('aria-expanded') === 'true';
   btn.setAttribute('aria-expanded', open ? 'false' : 'true');
   if (li) li.classList.toggle('is-open', !open);
-  if (list) { if (open) list.setAttribute('hidden', ''); else list.removeAttribute('hidden'); }
+  if (list) {
+    if (open) list.setAttribute('hidden', '');
+    else { list.removeAttribute('hidden'); playEntrance(list); }
+  }
 }
 
 export function wireNav(root = document) {