@apliteni/apliteni-ui 0.9.1 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.9.1",
+  "version": "0.11.1",
   "workspaces": [
     "react"
   ],

package/src/components/account-nav.js

@@ -0,0 +1,47 @@
+// The one account navigation definition, and the one way to hand it to a sink
+// that interpolates raw. It lives here rather than in shell.js because both
+// shell.js and topbar.js need it and shell.js already imports topbar.js — the
+// other direction would be a cycle. shell.js re-exports ACCOUNT_NAV, which is
+// the published name docs/library.md documents.
+// why: docs/adr/0007-one-page-shell-built-from-the-kits-own-nav.md
+import { esc } from './index.js';
+
+// nav.js item objects. Labels are raw text — every nav primitive escapes, so a
+// pre-escaped `&` would come out as `&`. `key` means credentials;
+// `plug` means integration. These two are the kit's default, so each is a live
+// link on a consumer's /account page — a screen the kit does not ship belongs
+// in the caller's own nav, not here.
+export const ACCOUNT_NAV = [
+  { id: 'prefs', icon: 'gear', label: 'Preferences' },
+  { id: 'access', icon: 'key', label: 'Access & agents' },
+];
+
+// topbar()'s account menu speaks [id, icon, label, href?, target?] tuples, and
+// it interpolates every field raw — the label, the href and the target alike.
+// Escape all three on the way in rather than sending the menu a string the rail
+// would have escaped a second time.
+export const toMenuTuple = (it) => [
+  esc(it.id ?? ''), it.icon, esc(it.label || ''),
+  it.href ? esc(it.href) : it.href,
+  it.target ? esc(it.target) : it.target,
+];
+
+// What accountMenu() falls back to. Derived on call, not frozen at import, so
+// the menu and the rail cannot answer differently about the same definition.
+export const accountMenuNav = () => ACCOUNT_NAV.map(toMenuTuple);
+
+// One reader, one pair of initials. The rail (shell.js) and the topbar's
+// account menu (topbar.js) both draw an avatar for the same person, and each
+// computed it for itself: the rail preferred the display name, the menu only
+// ever read the email's local part. So the /account preset — the one screen
+// with both on it — said "AL" in the rail and "A" in the topbar. This lives
+// beside ACCOUNT_NAV for the same reason ACCOUNT_NAV lives here: both files
+// need it and shell.js already imports topbar.js.
+//
+// The display name is what a reader recognises, so it wins; the address is the
+// fallback. `?` is what nobody at all comes out as.
+export const initials = (name, email) => {
+  const from = String(name ?? '').trim() || String(email ?? '').split('@')[0] || '';
+  const parts = from.split(/[\s._-]+/).filter(Boolean).map((w) => w[0]);
+  return (parts.slice(0, 2).join('') || '?').toUpperCase();
+};

package/src/components/confirm.js

@@ -0,0 +1,131 @@
+// Confirm — the kit's confirmation dialog: a question the page stops for.
+//
+//   container.innerHTML = confirm({ title, body, confirmLabel, cancelLabel });
+//   wireConfirm(container);   // scrim/Esc/answers + focus trap
+//
+// A page trigger opens it by id:  <button data-confirm-open="ID">…</button>
+// (or call openConfirm(rootEl) directly). Pass `open: true` to render it already
+// open, or `specimen: true` for a picture of one on a documentation page.
+//
+// Answering is the caller's job: both answers close the dialog, and a listener
+// on [data-confirm-accept] is where the destructive work goes. Focus opens on
+// the SAFE answer, never the destructive one, so a reader who hits Enter out of
+// habit keeps what they have.
+//
+// Inertness, Escape and the focus trap come from ./overlay.js — one stack for
+// every overlay on the page, so a confirm over a drawer never has to guess which
+// of the two the keyboard belongs to.
+import { button, esc } from './index.js';
+import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Module counter (never Date/random) → stable, unique ids for aria-labelledby.
+let _uid = 0;
+const nextId = (p = 'confirm') => `${p}-${++_uid}`;
+
+// The public factory. Returns an HTML string; wire it with wireConfirm().
+//   title         the question — also the dialog's accessible name
+//   body          the consequence — the dialog's accessible description
+//   confirmLabel  the destructive answer (default 'Confirm')
+//   cancelLabel   the safe answer (default 'Cancel')
+//   variant       'danger' (default) | 'primary' — which button the answer is
+//   open          render already-open, as a real dialog: wireConfirm() adopts it
+//                 onto the overlay stack, so the page behind it goes inert, Tab
+//                 is trapped in the panel and Escape closes it
+//   specimen      render open as a *picture* of the dialog: same markup, minus
+//                 the data-confirm hook and aria-modal, so no wiring and no key
+//                 handler can reach it. A documentation page shows several at
+//                 once and none of them owns the page or answers Escape — an
+//                 answered specimen would erase itself with nothing to bring it
+//                 back, and three modal dialogs on one page trap the reader in
+//                 the first. `open` is the one to use when the dialog is real.
+//   id            root id — a [data-confirm-open="id"] trigger targets it
+export function confirm({
+  title = 'Are you sure?', body = '', confirmLabel = 'Confirm', cancelLabel = 'Cancel',
+  variant = 'danger', id, open = false, specimen = false,
+} = {}) {
+  const titleId = nextId('confirm-title');
+  const bodyId = body ? nextId('confirm-body') : null;
+  const describedBy = bodyId ? ` aria-describedby="${bodyId}"` : '';
+
+  // The safe answer comes FIRST in the DOM, so the trap's first stop and the
+  // reader's first Tab both land on the answer that changes nothing.
+  const cancelBtn = button({ label: cancelLabel, variant: 'ghost' })
+    .replace('<button ', '<button data-confirm-cancel ');
+  const acceptBtn = button({ label: confirmLabel, variant })
+    .replace('<button ', '<button data-confirm-accept ');
+
+  const rootCls = cx('ui-confirm', (open || specimen) && 'is-open');
+  return `<div class="${rootCls}"${specimen ? '' : ' data-confirm'}${id ? ` id="${esc(id)}"` : ''}>`
+    + `<div class="ui-confirm__scrim" data-confirm-scrim></div>`
+    + `<div class="ui-confirm__panel" role="alertdialog"${specimen ? '' : ' aria-modal="true"'}`
+    + ` aria-labelledby="${titleId}"${describedBy} tabindex="-1" data-confirm-panel>`
+    + `<h2 class="ui-confirm__title" id="${titleId}">${esc(title)}</h2>`
+    + (bodyId ? `<p class="ui-confirm__body" id="${bodyId}">${esc(body)}</p>` : '')
+    + `<div class="ui-confirm__acts">${cancelBtn}${acceptBtn}</div>`
+    + `</div></div>`;
+}
+
+// ---- Shared behaviour ----------------------------------------------------
+// Per-instance handlers are attached once (guarded by a flag on the node);
+// the [data-confirm-open] delegation is attached once per document. Safe to
+// call repeatedly (Storybook re-renders).
+
+export function openConfirm(root, returnFocusTo) {
+  if (!root || root.classList.contains('is-open')) return;
+  root.__confirmReturn = returnFocusTo
+    || (document.activeElement instanceof HTMLElement ? document.activeElement : null);
+  root.classList.add('is-open');
+  const panel = root.querySelector('[data-confirm-panel]');
+  pushOverlay(root, panel, () => closeConfirm(root), OVERLAY_LAYER.confirm);
+  // The safe answer, else the first control, else the panel itself. Asked for by
+  // name and not by position: DOM order puts the safe answer first today, and a
+  // preference that only agrees with the order proves nothing about either.
+  const safe = panel && (panel.querySelector('[data-confirm-cancel]') || focusablesIn(panel)[0]);
+  (safe || panel)?.focus();
+}
+
+export function closeConfirm(root) {
+  if (!root || !root.classList.contains('is-open')) return;
+  root.classList.remove('is-open');
+  popOverlay(root);
+  const back = root.__confirmReturn;
+  root.__confirmReturn = null;
+  // The destructive work a caller hangs off [data-confirm-accept] usually deletes
+  // the row the trigger stood in, so the trigger can be detached by now — and
+  // focus() on a detached node is a silent no-op that strands the reader.
+  returnFocus(back, root.ownerDocument);
+}
+
+export function wireConfirm(scope = document) {
+  const root = scope === document ? document : scope;
+  root.querySelectorAll('[data-confirm]').forEach((cf) => {
+    if (cf.__confirmWired) return;
+    cf.__confirmWired = true;
+
+    cf.querySelector('[data-confirm-scrim]')?.addEventListener('click', () => closeConfirm(cf));
+    cf.querySelectorAll('[data-confirm-cancel],[data-confirm-accept]').forEach((btn) =>
+      btn.addEventListener('click', () => closeConfirm(cf)));
+
+    // Rendered with `open: true`, so nothing called openConfirm() and nothing
+    // put it on the stack. Adopting it here is what makes its aria-modal true.
+    adoptOverlay(cf, cf.querySelector('[data-confirm-panel]'), () => closeConfirm(cf), OVERLAY_LAYER.confirm);
+  });
+
+  const doc = scope === document ? document : (scope.ownerDocument || document);
+  if (!doc.__confirmGlobalWired) {
+    doc.__confirmGlobalWired = true;
+    // Any [data-confirm-open="ID"] trigger opens the matching dialog.
+    doc.addEventListener('click', (e) => {
+      const opener = e.target.closest?.('[data-confirm-open]');
+      if (!opener) return;
+      e.preventDefault();
+      const target = doc.getElementById(opener.getAttribute('data-confirm-open'));
+      if (target) openConfirm(target, opener);
+    });
+  }
+  // This runs on every re-render, which is the moment to notice that an overlay
+  // was destroyed while it was open and hand the page back.
+  syncOverlays(doc);
+}

package/src/components/drawer.js

@@ -8,14 +8,14 @@
 //
 // A page trigger opens it by id:  <button data-drawer-open="ID">…</button>
 // (or call openDrawer(rootEl) directly). Pass `open: true` to render it already
-// open — handy for specimens/screenshots.
+// open, or `specimen: true` for a picture of one on a documentation page.
 //
-// This deliberately shares its scrim + focus-trap concept with a future Modal /
-// Dialog: both are "content over a scrim, focus-trapped, Esc-dismissable". The
-// data hooks ([data-drawer]/[data-drawer-scrim]/[data-drawer-close]) and the
-// wireDrawer trap below are the primitive a Modal would reuse (centered instead
-// of edge-anchored). Kept as one component for now per issue #34.
+// Inertness, Escape and the focus trap are shared with confirm(): both are
+// "content over a scrim, focus-trapped, Esc-dismissable", and they push onto one
+// stack in ./overlay.js so the two can never disagree about which of them the
+// keyboard currently belongs to.
 import { esc, icon } from './index.js';
+import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
 
@@ -29,14 +29,20 @@ const nextId = (p = 'drawer') => `${p}-${++_uid}`;
 //   title       header heading (also the dialog's accessible name)
 //   body        scrollable body HTML (trusted markup)
 //   footer      pinned footer actions HTML (trusted markup)
-//   open        render already-open (specimens / screenshots)
+//   open        render already-open, as a real panel: wireDrawer() adopts it onto
+//               the overlay stack, so the page behind it goes inert, Tab is
+//               trapped in the panel and Escape closes it
+//   specimen    render open as a *picture* of the panel: same markup, minus the
+//               data-drawer hook and aria-modal, so no wiring and no key handler
+//               can reach it. See confirm() for why a documentation page wants
+//               that; `open` is the one to use when the drawer is real.
 //   id          root id — a [data-drawer-open="id"] trigger targets it
 //   ariaLabel   accessible name when there's no visible title
 //   dismissible show the close button + allow scrim/Esc dismiss (default true)
 //   closeLabel  accessible name for the close button (default 'Close')
 export function drawer({
   side = 'right', size = 'md', title, body = '', footer = '',
-  open = false, id, ariaLabel, dismissible = true, closeLabel = 'Close',
+  open = false, specimen = false, id, ariaLabel, dismissible = true, closeLabel = 'Close',
 } = {}) {
   const titleId = title ? nextId('drawer-title') : null;
   const nameAttr = titleId
@@ -54,71 +60,31 @@ export function drawer({
   const bodyEl = `<div class="ui-drawer__body">${body}</div>`;
   const footEl = footer ? `<footer class="ui-drawer__footer">${footer}</footer>` : '';
 
-  const rootCls = cx('ui-drawer', `ui-drawer--${side}`, `ui-drawer--${size}`, open && 'is-open');
-  return `<div class="${rootCls}" data-drawer data-drawer-side="${esc(side)}"`
+  const rootCls = cx('ui-drawer', `ui-drawer--${side}`, `ui-drawer--${size}`, (open || specimen) && 'is-open');
+  return `<div class="${rootCls}"${specimen ? '' : ' data-drawer'} data-drawer-side="${esc(side)}"`
     + `${dismissible ? '' : ' data-drawer-static'}${id ? ` id="${esc(id)}"` : ''}>`
     + `<div class="ui-drawer__scrim" data-drawer-scrim></div>`
-    + `<aside class="ui-drawer__panel" role="dialog" aria-modal="true" ${nameAttr} tabindex="-1" data-drawer-panel>`
+    + `<aside class="ui-drawer__panel" role="dialog"${specimen ? '' : ' aria-modal="true"'} ${nameAttr} tabindex="-1" data-drawer-panel>`
     + `${header}${bodyEl}${footEl}`
     + `</aside></div>`;
 }
 
 // ---- Shared behaviour ----------------------------------------------------
-// One open/close/scrim/Esc/focus-trap implementation for every drawer in the
-// kit. Per-instance handlers are attached once (guarded by a flag on the node);
-// document-level Esc + the [data-drawer-open] delegation are attached once per
-// document (guarded by a flag on the document node, so multiple documents each
-// get their own). Safe to call repeatedly (Storybook re-renders).
-
-const FOCUSABLE = [
-  'a[href]', 'button:not([disabled])', 'input:not([disabled])',
-  'select:not([disabled])', 'textarea:not([disabled])',
-  '[tabindex]:not([tabindex="-1"])',
-].join(',');
-
-// Focusable controls inside the panel, in DOM order. Scoped to the panel, so
-// nothing outside the trap is returned; hidden closed drawers are never queried
-// (we only call this while open).
-function focusablesIn(panel) {
-  return Array.from(panel.querySelectorAll(FOCUSABLE));
-}
-
-// Hide everything *outside* the drawer from AT + tab order: walk root→body and
-// mark each ancestor's other children inert + aria-hidden, remembering prior
-// state so close can restore it exactly. The scrim + panel live inside the root,
-// so they stay interactive. This is the focus-trap primitive a Modal reuses.
-function inertOutside(root, on) {
-  if (on) {
-    const touched = [];
-    let node = root;
-    while (node && node.parentElement && node !== document.body) {
-      for (const sib of node.parentElement.children) {
-        if (sib === node || sib.hasAttribute('data-drawer')) continue;
-        touched.push([sib, sib.getAttribute('aria-hidden'), sib.hasAttribute('inert')]);
-        sib.setAttribute('aria-hidden', 'true');
-        sib.setAttribute('inert', '');
-        sib.inert = true;
-      }
-      node = node.parentElement;
-    }
-    root.__drawerInert = touched;
-  } else {
-    (root.__drawerInert || []).forEach(([el, ariaHidden, hadInert]) => {
-      if (ariaHidden == null) el.removeAttribute('aria-hidden');
-      else el.setAttribute('aria-hidden', ariaHidden);
-      if (!hadInert) { el.removeAttribute('inert'); el.inert = false; }
-    });
-    root.__drawerInert = null;
-  }
-}
+// 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
+// are attached once (guarded by a flag on the node); the [data-drawer-open]
+// delegation is attached once per document (guarded by a flag on the document
+// node, so multiple documents each get their own). Safe to call repeatedly
+// (Storybook re-renders).
 
 export function openDrawer(root, returnFocusTo) {
   if (!root || root.classList.contains('is-open')) return;
   root.__drawerReturn = returnFocusTo
     || (document.activeElement instanceof HTMLElement ? document.activeElement : null);
   root.classList.add('is-open');
-  inertOutside(root, true);
   const panel = root.querySelector('[data-drawer-panel]');
+  const dismissible = !root.hasAttribute('data-drawer-static');
+  pushOverlay(root, panel, dismissible ? () => closeDrawer(root) : null, OVERLAY_LAYER.drawer);
   // Focus the first focusable control, else the panel itself.
   const first = panel && focusablesIn(panel)[0];
   (first || panel)?.focus();
@@ -127,33 +93,12 @@ export function openDrawer(root, returnFocusTo) {
 export function closeDrawer(root) {
   if (!root || !root.classList.contains('is-open')) return;
   root.classList.remove('is-open');
-  inertOutside(root, false);
+  popOverlay(root);
   const back = root.__drawerReturn;
   root.__drawerReturn = null;
-  if (back && typeof back.focus === 'function') back.focus();
-}
-
-// Trap Tab within the panel while open; wrap at both ends.
-function trapTab(root, e) {
-  if (e.key !== 'Tab') return;
-  const panel = root.querySelector('[data-drawer-panel]');
-  if (!panel) return;
-  const items = focusablesIn(panel);
-  if (!items.length) { e.preventDefault(); panel.focus(); return; }
-  const first = items[0];
-  const last = items[items.length - 1];
-  const active = document.activeElement;
-  if (e.shiftKey && (active === first || active === panel)) {
-    e.preventDefault(); last.focus();
-  } else if (!e.shiftKey && active === last) {
-    e.preventDefault(); first.focus();
-  }
-}
-
-// Topmost open drawer (last in document order) — Esc closes that one.
-function topOpenDrawer(doc = document) {
-  const open = doc.querySelectorAll('[data-drawer].is-open');
-  return open.length ? open[open.length - 1] : 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.
+  returnFocus(back, root.ownerDocument);
 }
 
 export function wireDrawer(root = document) {
@@ -169,14 +114,10 @@ export function wireDrawer(root = document) {
     dr.querySelectorAll('[data-drawer-close]').forEach((btn) =>
       btn.addEventListener('click', () => closeDrawer(dr)));
 
-    dr.addEventListener('keydown', (e) => {
-      if (!dr.classList.contains('is-open')) return;
-      if (e.key === 'Escape' && dismissible) {
-        e.preventDefault(); e.stopPropagation(); closeDrawer(dr);
-      } else if (e.key === 'Tab') {
-        trapTab(dr, e);
-      }
-    });
+    // Rendered with `open: true`, so nothing called openDrawer() and nothing put
+    // it on the stack. Adopting it here is what makes its aria-modal true.
+    adoptOverlay(dr, dr.querySelector('[data-drawer-panel]'), dismissible ? () => closeDrawer(dr) : null,
+      OVERLAY_LAYER.drawer);
   });
 
   const doc = root === document ? document : (root.ownerDocument || document);
@@ -190,11 +131,8 @@ export function wireDrawer(root = document) {
       const target = doc.getElementById(opener.getAttribute('data-drawer-open'));
       if (target) openDrawer(target, opener);
     });
-    // Esc closes the topmost open drawer even when focus escaped the panel.
-    doc.addEventListener('keydown', (e) => {
-      if (e.key !== 'Escape') return;
-      const top = topOpenDrawer(doc);
-      if (top && !top.hasAttribute('data-drawer-static')) { e.preventDefault(); closeDrawer(top); }
-    });
   }
+  // This runs on every re-render, which is the moment to notice that an overlay
+  // was destroyed while it was open and hand the page back.
+  syncOverlays(doc);
 }

package/src/components/nav.js

@@ -30,15 +30,33 @@ const nextId = (p = 'nav') => `${p}-${++_uid}`;
 
 // A trailing counter/badge on a nav item. `badge` is a number, a string, or
 // { text, tone }. Tones map to the badge token set (accent | live | neutral…).
-function navBadge(badge) {
+const badgeText = (badge) => {
   if (badge == null || badge === '') return '';
   const text = typeof badge === 'object' ? badge.text : badge;
+  return text == null || text === '' ? '' : String(text);
+};
+
+function navBadge(badge) {
+  const text = badgeText(badge);
+  if (!text) return '';
   const tone = typeof badge === 'object' && badge.tone ? badge.tone : 'neutral';
   return `<span class="${cx('ui-nav__badge', `is-${tone}`)}">${esc(text)}</span>`;
 }
 
-// One sidebar leaf: a link (or a plain, aria-disabled span). `collapsed` folds
-// the label into an aria-label + title so the icon stays named and hoverable.
+// An item's accessible name. It is emitted at every width, not only when
+// `collapsed`, so a shell may fold `.ui-nav__label` out of view in CSS and keep
+// the icon named. An always-on name overrides the row's own text, so the badge
+// has to be spelled into it — otherwise "Pending 3" narrows to "Pending". The
+// `title` tooltip is for the collapsed rail only — a narrow touch device has no
+// hover to show it with, and the badge is folded away there too.
+const leafName = (label, collapsed, badge) => {
+  const count = badgeText(badge);
+  const name = esc(count ? `${label} ${count}` : label);
+  return ` aria-label="${name}"${collapsed ? ` title="${name}"` : ''}`;
+};
+
+// 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 } = {}) {
   const on = it.id != null && it.id === active;
   const disabled = !!it.disabled;
@@ -47,7 +65,7 @@ function sideLeaf(it, active, { collapsed, sub } = {}) {
   const text = `<span class="ui-nav__label">${esc(label)}</span>`;
   const badge = navBadge(it.badge);
   const cls = cx('ui-nav__item', sub && 'ui-nav__item--sub', on && 'is-active', it.danger && 'is-danger', disabled && 'is-disabled');
-  const name = collapsed ? ` aria-label="${esc(label)}" title="${esc(label)}"` : '';
+  const name = leafName(label, collapsed, it.badge);
   if (disabled) {
     return `<li><span class="${cls}" aria-disabled="true"${name}>${lead}${text}${badge}</span></li>`;
   }
@@ -72,7 +90,7 @@ function sideGroup(it, active, { collapsed } = {}) {
   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 name = collapsed ? ` aria-label="${esc(label)}" title="${esc(label)}"` : '';
+  const name = leafName(label, collapsed);
   const btn =
     `<button type="button" class="${cx('ui-nav__item', 'ui-nav__toggle', childActive && 'is-current')}"` +
     ` data-nav-toggle aria-expanded="${open ? 'true' : 'false'}" aria-controls="${listId}"${name}>` +
@@ -89,7 +107,8 @@ 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")
-//   collapsed  icon-only rail; labels fold into aria-label + title
+//   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({