@apliteni/apliteni-ui 0.27.0 → 0.31.0

package/src/components/overlay.js

@@ -4,10 +4,15 @@
 // properties of the *page*, so they are answered here from one stack per document rather
 // than from either component's own storage. Internal — not re-exported from src/index.js.
 
-// What each overlay paints on today: a drawer at `--z-overlay` (styles/drawer.css) and a
-// confirm above it (styles/confirm.css). Absolute values, not ranks, so a sheet that moves
-// and a table that did not is a failed test — stories/overlay-css.test.js holds both.
-export const OVERLAY_LAYER = { drawer: 100, confirm: 101 };
+// What each overlay paints on today: a drawer at `--z-overlay` (styles/drawer.css), a
+// command palette one above it (styles/command-palette.css) and a confirm above both
+// (styles/confirm.css). Three steps and not two, because at equal levels paint order falls
+// back to document order and the overlay that owns the keyboard is then not reliably the
+// one the reader can see. A palette is summoned deliberately and must be seen, so it goes
+// over a drawer that was already open; a confirm is a question about whatever is under it,
+// so it goes over both. Absolute values, not ranks, so a sheet that moves and a table that
+// did not is a failed test — stories/overlay-css.test.js holds all three.
+export const OVERLAY_LAYER = { drawer: 100, palette: 101, confirm: 102 };
 
 const FOCUSABLE = [
   'a[href]', 'button:not([disabled])', 'input:not([disabled])',
@@ -32,7 +37,8 @@ function pageOf(doc) {
 function reachable(el) {
   for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
     if (n.inert || n.hasAttribute('inert') || n.hasAttribute('hidden')) return false;
-    const overlayRoot = n.hasAttribute('data-drawer') || n.hasAttribute('data-confirm');
+    const overlayRoot = n.hasAttribute('data-drawer') || n.hasAttribute('data-confirm')
+      || n.hasAttribute('data-cmdk');
     if (overlayRoot && !n.classList.contains('is-open')) return false;
   }
   // Browsers can answer the rest properly; JSDOM has no layout and no such method.
@@ -108,7 +114,7 @@ const PRECEDING = 2;
 
 // One way onto the stack. `where` picks the slot; everything after it — the
 // duplicate guard, the key owner, the recompute — is the same either way. Every
-// entry carries its layer, so the comparisons in adoptOverlay never meet undefined.
+// entry carries its layer, so the comparisons in the slot pickers never meet undefined.
 function place(root, panel, dismiss, layer, where) {
   const doc = root.ownerDocument;
   const page = pageOf(doc);
@@ -130,14 +136,23 @@ function paintedLayer(root, layer) {
 }
 
 /**
- * Put an overlay on top of the page. `dismiss` is what Escape calls — pass null
- * for one that refuses to be dismissed, and Escape then does nothing rather than
- * falling through to the overlay underneath. This one goes on top whatever layer
- * it paints on, because opening is history the stack can order by: the thing just
- * opened is the thing the reader is looking at.
+ * Put an overlay on the page. `dismiss` is what Escape calls — pass null for one
+ * that refuses to be dismissed, and Escape then does nothing rather than falling
+ * through to the overlay underneath.
+ *
+ * It goes on top of everything it paints over, and under anything painted above
+ * it. Opening is history the stack can order by, but only within a layer: an
+ * overlay opened under one already on screen — a drawer opened from a palette
+ * row, a palette opened while a confirm is up — is not the one the reader is
+ * looking at, and giving it Escape and the Tab trap would put the keyboard on a
+ * surface that is covered.
  */
 export function pushOverlay(root, panel, dismiss, layer) {
-  place(root, panel, dismiss, layer, (page) => page.stack.length);
+  const level = paintedLayer(root, layer);
+  place(root, panel, dismiss, level, (page) => {
+    const at = page.stack.findIndex((e) => e.layer > level);
+    return at === -1 ? page.stack.length : at;
+  });
 }
 
 /**
@@ -157,13 +172,45 @@ export function adoptOverlay(root, panel, dismiss, layer) {
   });
 }
 
-/** Take an overlay off the page, wherever in the stack it sits. */
-export function popOverlay(root) {
+// Where an overlay puts focus when it opens: the first stop inside its panel,
+// else the panel itself. One rule serves all three, because the kit's own markup
+// puts each one's opening target first — a drawer's first control, the palette's
+// text box, and the confirm's safe answer, which its panel renders before the
+// destructive one.
+function initialFocus(panel) {
+  return (panel && focusablesIn(panel)[0]) || panel;
+}
+
+// What `el` can actually be handed focus, or null when nothing can take it. An
+// overlay stays open while the page carries on, so by the time it closes the
+// element it came from may be detached — look for whatever inherited its identity
+// in the re-render — or sitting in a subtree that a lower overlay has just made
+// inert again, where focus() is a silent no-op. <body> is null too: with no
+// tabindex it cannot be focused either, and `activeElement === body` is what
+// having no focus looks like, which is what an overlay summoned by its hotkey out
+// of a page nobody had touched yet records as the place it came from.
+function focusTarget(el, doc) {
+  const live = el && !el.isConnected && el.id ? doc?.getElementById(el.id) : el;
+  if (!live || !live.isConnected || live === live.ownerDocument.body) return null;
+  return reachable(live) && typeof live.focus === 'function' ? live : null;
+}
+
+/**
+ * Take an overlay off the page, wherever in the stack it sits. `opener` is what
+ * the caller is about to hand focus back to, which this has to see: one overlay
+ * can close over another that is still open, and the opener is then out on a page
+ * that lower overlay is holding inert. Nobody would place focus at all, and the
+ * reader would be left on <body> looking at a panel that holds neither the
+ * keyboard nor the Tab trap — so open the panel now on top where it opens.
+ */
+export function popOverlay(root, opener) {
   const doc = root.ownerDocument;
   const page = pageOf(doc);
   const at = page.stack.findIndex((e) => e.root === root);
   if (at !== -1) page.stack.splice(at, 1);
   sync(doc);
+  const top = page.stack[page.stack.length - 1];
+  if (top && opener && !focusTarget(opener, doc)) initialFocus(top.panel)?.focus();
 }
 
 /**
@@ -180,8 +227,14 @@ export function syncOverlays(doc = document) {
  * the element it came from may be detached by now — and focus() on a detached
  * node is a silent no-op that leaves the reader with no place on the page. Look
  * for whatever inherited its identity in the re-render, then give up to the page.
+ *
+ * With another overlay still open, the only place worth having focus is inside
+ * it: an opener that overlay is holding inert cannot take focus at all, popOverlay
+ * has already opened the panel now on top for exactly that case, and <body> behind
+ * a live modal is not somewhere to give up to.
  */
 export function returnFocus(el, doc) {
+  if (doc && pageOf(doc).stack.length) { focusTarget(el, doc)?.focus(); return; }
   const live = el && !el.isConnected && el.id ? doc?.getElementById(el.id) : el;
   if (live && live.isConnected && typeof live.focus === 'function') { live.focus(); return; }
   doc?.body?.focus?.();

package/src/components/shell.js

@@ -7,6 +7,7 @@
 import { topbar as productTopbar } from './topbar.js';
 import { esc, icon } from './index.js';
 import { sidebarNav, breadcrumbs } from './nav.js';
+import { backLink } from './back.js';
 import { prism } from '../assets/brand.js';
 import { ACCOUNT_NAV, toMenuTuple, initials } from './account-nav.js';
 
@@ -41,6 +42,11 @@ const toItems = (nav) => (Array.isArray(nav) ? nav : ACCOUNT_NAV)
 const toCrumbs = (crumbs) => (Array.isArray(crumbs) ? crumbs : [])
   .filter((c) => isRecord(c) && !Array.isArray(c) && str(c.label) !== '');
 
+// A back link replaces the trail rather than joining it: the two would name the same parent
+// twice. Anything but a record is no back link; its fields go through as given, so a back
+// backLink() refuses leaves the trail standing. why: docs/specification.md#the-back-link
+const toBack = (b) => (isRecord(b) && !Array.isArray(b) ? { href: b.href, label: b.label } : null);
+
 // The reader, as two strings. railUser() and initials() both read them, and an
 // /auth/me answering `account: null` or a numeric display name reached both.
 const toReader = (a) => (isRecord(a) ? { name: str(a.name), email: str(a.email) } : { name: '', email: '' });
@@ -88,7 +94,7 @@ const mainMax = (v) => {
 // The one pass. Each key names the function that settles it; nothing else in
 // this file re-checks a value that has been through here.
 const SHAPES = {
-  nav: toItems, crumbs: toCrumbs, account: toReader, maxWidth: mainMax, topbar: toTopbar,
+  nav: toItems, crumbs: toCrumbs, back: toBack, account: toReader, maxWidth: mainMax, topbar: toTopbar,
 };
 
 // The text options settle by the same argument. `body: null` from a record with no
@@ -141,6 +147,7 @@ export function appShell(options = {}) {
     active,
     navLabel = 'Account',
     crumbs,
+    back,
     title = '',
     sub = '',
     body = '',
@@ -149,9 +156,11 @@ export function appShell(options = {}) {
     topbar,
     maxWidth,
   } = settle(options);
+  const up = back ? backLink(back) : '';
   const rail = sidebarNav({
     sections: [{ label: navLabel, items: nav }],
     active,
+    activeIs: up ? 'section' : 'page',
     ariaLabel: navLabel,
     footer: signOutHref ? signOut(signOutHref) : '',
   });
@@ -170,7 +179,7 @@ export function appShell(options = {}) {
       ${railUser(account)}
     </div>
     <main class="ui-app__main"${maxWidth ? ` style="--ui-app-main: ${maxWidth}"` : ''}>
-      ${crumbs.length ? breadcrumbs({ items: crumbs }) : ''}
+      ${up || (crumbs.length ? breadcrumbs({ items: crumbs }) : '')}
       ${title ? `<h1>${title}</h1>` : ''}
       ${sub ? `<p class="ui-app__sub">${sub}</p>` : ''}
       <div class="ui-app__body">${body}</div>

package/src/components/tabs.js

@@ -14,6 +14,7 @@
 // Follows the WAI-ARIA tabs pattern: roving tabindex, ArrowLeft/Right + Home/End,
 // aria-selected, and aria-controls / aria-labelledby wiring. `name` must be unique
 // per tabs instance on a page (it seeds the tab/panel ids).
+import { playEntrance } from '../motion.js';
 
 export function tabs({ items = [], active = 0, name = 'tabs', ariaLabel = 'Tabs', className = '' } = {}) {
   const cls = ['ui-tabs', className].filter(Boolean).join(' ');
@@ -57,7 +58,12 @@ export function initTabs(root) {
         t.setAttribute('aria-selected', on ? 'true' : 'false');
         t.tabIndex = on ? 0 : -1;
         const p = panelFor(t);
-        if (p) p.hidden = !on;
+        if (p) {
+          // Only the panel a switch reveals fades in; the one the page loaded with does not.
+          const appearing = on && p.hidden;
+          p.hidden = !on;
+          if (appearing) playEntrance(p);
+        }
       });
       if (focus && tabEls[i]) tabEls[i].focus();
     };

package/src/components/tooltip.js

@@ -0,0 +1,237 @@
+// Tooltip — the readout that shows a value while a pointer rests on the mark
+// holding it. An overlay in every state: one element, rendered once inside its
+// host and absolutely placed there, so showing it moves nothing on the page.
+//
+//   <div class="ui-tip-host" data-tip-host>
+//     <svg>… <rect data-tip-label="Mar 2026" data-tip-value="€48,210" …/> …</svg>
+//     ${tooltip()}
+//   </div>
+//   wireTooltip(container);
+//
+// A mark carries `data-tip-value`, with `data-tip-label` and `data-tip-detail`;
+// a `[data-tip-anchor]` inside it is where the readout opens.
+// why: docs/specification.md#the-hover-readout
+import { esc } from './index.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+const PARTS = ['label', 'value', 'detail'];
+const px = (n) => (typeof n === 'number' && Number.isFinite(n) ? `${n}px` : null);
+let seq = 0;
+
+/**
+ * The readout. Render it once inside a `[data-tip-host]`; wireTooltip() fills it.
+ *
+ * @param {object} [o]
+ * @param {string} [o.label]     which point — a date, a category, a series
+ * @param {string} [o.value]     the number, already formatted
+ * @param {string} [o.detail]    at most one comparison, such as "+4.2% on February"
+ * @param {string} [o.placement] 'top' (default) | 'bottom' — the side it prefers; the wiring flips it when clipped
+ * @param {boolean} [o.open]     render it shown, as a picture; its host leaves off `data-tip-host` so no wiring takes it down
+ * @param {number} [o.x]         with `open`: the mark's centre, px from the host's left
+ * @param {number} [o.y]         with `open`: the mark's top edge (its bottom for 'bottom'), px from the host's top
+ * @param {string} [o.id]
+ * @returns {string} html
+ */
+export function tooltip({
+  label = '', value = '', detail = '', placement = 'top', open = false, x, y, id,
+} = {}) {
+  const text = { label, value, detail };
+  const named = value != null && String(value) !== '';
+  const pos =[['--ui-tip-x', px(x)], ['--ui-tip-y', px(y)]]
+    .filter(([, v]) => v).map(([k, v]) => `${k}:${v}`).join(';');
+  // A tooltip with nothing in it has no name, so an empty readout — the one a
+  // chart renders before any mark is hovered — takes the role with its first value.
+  const attrs = [
+    `class="${cx('ui-tip', placement === 'bottom' && 'is-below', open && 'is-open')}"`,
+    named ? 'role="tooltip"' : '',
+    'data-tip',
+    id ? `id="${esc(id)}"` : '',
+    pos ? `style="${pos}"` : '',
+  ].filter(Boolean).join(' ');
+  const spans = PARTS.map((k) => {
+    const t = text[k] == null ? '' : String(text[k]);
+    return `<span class="ui-tip__${k}"${t ? '' : ' hidden'}>${esc(t)}</span>`;
+  }).join('');
+  return `<div ${attrs}>${spans}</div>`;
+}
+
+// ---- Placement -----------------------------------------------------------
+
+// The mark-to-readout distance is --ui-tip-gap in src/styles/tooltip.css. This is
+// the fallback for a document that has not loaded the sheet;
+// src/components/tooltip.test.js pins the two to each other.
+const TIP_GAP = 8;
+
+function tipGap(tip) {
+  const declared = parseFloat(getComputedStyle(tip).getPropertyValue('--ui-tip-gap'));
+  return Number.isFinite(declared) ? declared : TIP_GAP;
+}
+
+// Hosts nest. A mark or a readout belongs to the nearest [data-tip-host] above it,
+// so one mark opens one readout, and an outer host is never handed an inner one's.
+function holds(host, el) {
+  const nearest = el.parentElement?.closest('[data-tip-host]') ?? null;
+  return host.contains(el) && (nearest === host || !host.contains(nearest));
+}
+
+const tipOf = (host) => [...host.querySelectorAll('[data-tip]')].find((tip) => holds(host, tip)) ?? null;
+const clips = (cs) => [cs.overflow, cs.overflowX, cs.overflowY].some((v) => v && v !== 'visible');
+
+// What the readout has to stay inside: the viewport less its scrollbars, cut
+// down by the host and every ancestor whose overflow clips. <body> is left out —
+// its overflow is the viewport's, and its box can be shorter than the page.
+function clipBox(host) {
+  const view = host.ownerDocument.documentElement;
+  const box = { top: 0, left: 0, right: view.clientWidth, bottom: view.clientHeight };
+  for (let el = host; el && el !== document.body && el !== document.documentElement; el = el.parentElement) {
+    if (!clips(getComputedStyle(el))) continue;
+    const r = el.getBoundingClientRect();
+    box.top = Math.max(box.top, r.top);
+    box.left = Math.max(box.left, r.left);
+    box.right = Math.min(box.right, r.right);
+    box.bottom = Math.min(box.bottom, r.bottom);
+  }
+  return box;
+}
+
+// Flip only when the preferred side is too tight AND the other side is roomier,
+// so a readout that fits on neither side opens on the roomier one. Then slide
+// it along the mark's edge, no further than it takes to stay inside the box.
+function place(host, tip, mark) {
+  const m = (mark.querySelector('[data-tip-anchor]') || mark).getBoundingClientRect();
+  const h = host.getBoundingClientRect();
+  const clip = clipBox(host);
+  const need = tip.offsetHeight + tipGap(tip);
+  const above = m.top - clip.top;
+  const below = clip.bottom - m.bottom;
+  const prefersBelow = tip.__tipPrefersBelow;
+  const flip = prefersBelow ? below < need && above > below : above < need && below > above;
+  const isBelow = prefersBelow !== flip;
+  tip.classList.toggle('is-below', isBelow);
+
+  const centre = m.left + m.width / 2;
+  const ideal = centre - tip.offsetWidth / 2;
+  const left = Math.max(clip.left, Math.min(ideal, clip.right - tip.offsetWidth));
+  // An absolute box is measured from the host's padding edge and rides its scroll.
+  const s = tip.style;
+  s.setProperty('--ui-tip-x', `${centre - h.left - host.clientLeft + host.scrollLeft}px`);
+  s.setProperty('--ui-tip-y', `${(isBelow ? m.bottom : m.top) - h.top - host.clientTop + host.scrollTop}px`);
+  s.setProperty('--ui-tip-shift', `${left - ideal}px`);
+}
+
+function fill(tip, mark) {
+  tip.setAttribute('role', 'tooltip');
+  for (const k of PARTS) {
+    const el = tip.querySelector(`.ui-tip__${k}`);
+    if (!el) continue;
+    const t = mark.getAttribute(`data-tip-${k}`) || '';
+    el.textContent = t;
+    el.hidden = !t;
+  }
+}
+
+// ---- Behaviour -----------------------------------------------------------
+
+/**
+ * Show the host's readout for one mark, until hideTooltip() or Escape. For a chart that does its own
+ * hit-testing; its host needs `.ui-tip-host`. After Escape it shows nothing for the dismissed mark
+ * until another mark shows or hideTooltip() is called, so a chart may call it on every pointer sample.
+ */
+export function showTooltip(host, mark) {
+  const tip = tipOf(host);
+  if (!tip || !mark || mark === host.__tipDismissed) return;
+  if (tip.__tipPrefersBelow == null) tip.__tipPrefersBelow = tip.classList.contains('is-below');
+  if (!tip.id) tip.id = `ui-tip-${++seq}`;
+  releaseMark(host);
+  fill(tip, mark);
+  place(host, tip, mark);
+  // Described only while shown, and only a mark that carried no description of its own.
+  if (!mark.hasAttribute('aria-describedby')) {
+    mark.setAttribute('aria-describedby', tip.id);
+    mark.__tipDescribed = true;
+  }
+  host.__tipMark = mark;
+  host.__tipDismissed = null;
+  tip.__tipHost = host;
+  tip.classList.add('is-open');
+  wireEscape(host.ownerDocument);
+}
+
+function releaseMark(host) {
+  const mark = host.__tipMark;
+  if (mark?.__tipDescribed) { mark.removeAttribute('aria-describedby'); mark.__tipDescribed = false; }
+  host.__tipMark = null;
+}
+
+function close(host) {
+  releaseMark(host);
+  tipOf(host)?.classList.remove('is-open');
+}
+
+/** Hide the host's readout: the pointer has left, so the mark Escape dismissed may show again. */
+export function hideTooltip(host) {
+  close(host);
+  host.__tipDismissed = null;
+}
+
+// Escape dismisses every readout the kit is showing without the pointer having
+// to move — the reader it covers something for. One rendered open and never
+// shown is a picture, and stays. The dismissed mark is remembered until another
+// mark shows or the pointer leaves, so crossing the gap between marks and coming
+// back does not return the readout to the mark it was dismissed from.
+function wireEscape(doc) {
+  if (doc.__tipEscapeWired) return;
+  doc.__tipEscapeWired = true;
+  doc.addEventListener('keydown', (e) => {
+    if (e.key !== 'Escape') return;
+    doc.querySelectorAll('[data-tip].is-open').forEach((tip) => {
+      const host = tip.__tipHost;
+      if (!host) return;
+      const mark = host.__tipMark;
+      close(host);
+      host.__tipDismissed = mark;
+    });
+  });
+}
+
+// The readout is placed in px from its host, so the host has to be the box it is
+// positioned against. .ui-tip-host makes it one; a host without it is given the same.
+// A host outside the document has no computed style to read, so it waits until it is in one.
+function anchorHost(host) {
+  if (host.__tipAnchored || !host.isConnected) return;
+  host.__tipAnchored = true;
+  if (getComputedStyle(host).position === 'static') host.style.position = 'relative';
+}
+
+/**
+ * Wire every `[data-tip-host]` under root: a pointer resting on a mark, or focus
+ * landing on one, shows the readout; leaving the marks hides it. A host with no
+ * readout of its own is given one here, once, never on hover. Safe to call again.
+ */
+export function wireTooltip(root = document) {
+  const hosts = [...root.querySelectorAll('[data-tip-host]')];
+  if (root.matches?.('[data-tip-host]')) hosts.unshift(root);
+  hosts.forEach((host) => {
+    if (host.__tipWired) return;
+    host.__tipWired = true;
+    anchorHost(host);
+    if (!tipOf(host)) host.insertAdjacentHTML('beforeend', tooltip());
+    const markOf = (t) => {
+      const mark = t?.closest?.('[data-tip-value]');
+      return mark && holds(host, mark) ? mark : null;
+    };
+    host.addEventListener('pointerover', (e) => {
+      anchorHost(host);
+      const mark = markOf(e.target);
+      if (!mark) close(host);
+      else if (mark !== host.__tipMark) showTooltip(host, mark);
+    });
+    host.addEventListener('pointerleave', () => hideTooltip(host));
+    host.addEventListener('focusin', (e) => {
+      anchorHost(host);
+      const mark = markOf(e.target);
+      if (mark) showTooltip(host, mark);
+    });
+    host.addEventListener('focusout', (e) => { if (!markOf(e.relatedTarget)) hideTooltip(host); });
+  });
+}

package/src/components/topbar.js

@@ -41,12 +41,17 @@ export function deckTextSwitch(active = 'deck') {
 // Thin consumer of the shared dropdown wiring (wireDropdown): keeps its own
 // bespoke .vsw/.vopt classes for a pixel-identical look, but emits the generic
 // [data-dropdown] hooks so there's ONE open/close/keyboard implementation.
+// `badge` is a tone key and the kit writes the word for it; the stylesheet used
+// to uppercase the key itself. why: docs/specification.md#labels-and-titles
+const VBADGE = { live: 'Live', archive: 'Archive' };
 export function versionSwitcher(versions = [], activeIdx = 0) {
   const cur = versions[activeIdx]?.label || '';
-  const opts = versions.map((v, i) =>
-    `<div class="vopt" role="option" data-dd-item tabindex="-1" aria-selected="${i === activeIdx}" data-active="${i === activeIdx ? '1' : '0'}">` +
-    `<span><div class="vname">${v.label}</div><div class="vmeta">${v.meta || ''}</div></span>` +
-    `<span class="vbadge ${v.badge === 'live' ? 'live' : 'arch'}">${v.badge || 'archive'}</span></div>`).join('');
+  const opts = versions.map((v, i) => {
+    const key = String(v.badge || 'archive').toLowerCase();
+    return `<div class="vopt" role="option" data-dd-item tabindex="-1" aria-selected="${i === activeIdx}" data-active="${i === activeIdx ? '1' : '0'}">` +
+      `<span><div class="vname">${v.label}</div><div class="vmeta">${v.meta || ''}</div></span>` +
+      `<span class="vbadge ${key === 'live' ? 'live' : 'arch'}">${Object.hasOwn(VBADGE, key) ? VBADGE[key] : v.badge}</span></div>`;
+  }).join('');
   return `<div class="vsw" data-dropdown><button type="button" class="vsw__btn" data-dropdown-trigger aria-haspopup="listbox" aria-expanded="false" aria-label="Version — ${esc(cur)}">` +
     `<span class="lbl">version:</span><span class="cur">${cur}</span><span class="car"></span></button>` +
     `<div class="vsw__menu" data-dropdown-panel role="listbox" aria-label="Version">${opts}</div></div>`;

package/src/index.css

@@ -24,9 +24,12 @@
 @import "./styles/tabs.css";
 @import "./styles/input.css";
 @import "./styles/dropdown.css";
+@import "./styles/tooltip.css";
 @import "./styles/nav.css";
+@import "./styles/back.css";
 @import "./styles/drawer.css";
 @import "./styles/confirm.css";
+@import "./styles/command-palette.css";
 @import "./styles/table.css";
 @import "./styles/pagination.css";
 @import "./styles/empty.css";

package/src/index.js

@@ -2,10 +2,13 @@
 // Styles ship separately: `import 'apliteni-ui/css'`.
 export * from './components/index.js';
 export * from './components/dropdown.js';
+export * from './components/tooltip.js';
 export * from './components/tabs.js';
 export * from './components/nav.js';
+export * from './components/back.js';
 export * from './components/drawer.js';
 export * from './components/confirm.js';
+export * from './components/command-palette.js';
 export * from './components/topbar.js';
 export * from './components/shell.js';
 export * from './components/footer.js';

package/src/inline.js

@@ -37,9 +37,12 @@ export const styles = {
   tabs: read('styles/tabs.css'),
   input: read('styles/input.css'),
   dropdown: read('styles/dropdown.css'),
+  tooltip: read('styles/tooltip.css'),
   nav: read('styles/nav.css'),
+  back: read('styles/back.css'),
   drawer: read('styles/drawer.css'),
   confirm: read('styles/confirm.css'),
+  commandPalette: read('styles/command-palette.css'),
   table: read('styles/table.css'),
   pagination: read('styles/pagination.css'),
   empty: read('styles/empty.css'),
@@ -66,9 +69,12 @@ export const cssText = [
   styles.tabs,
   styles.input,
   styles.dropdown,
+  styles.tooltip,
   styles.nav,
+  styles.back,
   styles.drawer,
   styles.confirm,
+  styles.commandPalette,
   styles.table,
   styles.pagination,
   styles.empty,

package/src/motion.js

@@ -1,7 +1,8 @@
 // apliteni-ui — motion hook.
 //
-// The one small, optional piece of JS behind the CSS motion library: a
-// scroll-reveal activator plus a replay helper. Everything else is pure CSS
+// The one small piece of JS behind the CSS motion library: a scroll-reveal
+// activator, the entrance player the components call when something they show
+// appears (playEntrance), and a replay helper. Everything else is pure CSS
 // (src/styles/motion.css). Framework-agnostic, no dependencies, guarded so it
 // no-ops cleanly under `node --test` / SSR (no window, no IntersectionObserver).
 //
@@ -59,6 +60,46 @@ export function initReveal(root) {
   return io;
 }
 
+/**
+ * How long playEntrance() waits for `animationend` before taking the class off
+ * itself. Longer than the slowest --dur-* token, so it only ever fires for an
+ * animation that never ran; src/motion.test.js holds it above that token.
+ */
+export const ENTRANCE_FALLBACK_MS = 1000;
+
+const entering = new WeakMap();
+
+/**
+ * Play the one-shot entrance of something the reader just caused to appear.
+ *
+ * Adds `className` and takes it off at the element's own `animationend`, or
+ * after ENTRANCE_FALLBACK_MS if that never fires (the element was hidden again,
+ * or no stylesheet gives the class an animation) — so the class is never left
+ * half-applied. The sheet decides what the entrance looks like: the component
+ * pairs the class with an animation in its own stylesheet. A component calls
+ * this on a change, never at first render, which is how the page loads still.
+ * Reduced motion needs no branch here: the net in reduced-motion.css shortens
+ * the animation to nothing and `animationend` still fires.
+ */
+export function playEntrance(el, className = 'is-entering') {
+  if (!el || !el.classList) return;
+  entering.get(el)?.();
+  el.classList.remove(className);
+  void el.offsetWidth; // restart the animation when the class was already on
+  el.classList.add(className);
+  let timer;
+  const done = (e) => {
+    if (e && e.target !== el) return; // a descendant's animation bubbling up
+    clearTimeout(timer);
+    el.removeEventListener('animationend', done);
+    el.classList.remove(className);
+    entering.delete(el);
+  };
+  el.addEventListener('animationend', done);
+  timer = setTimeout(done, ENTRANCE_FALLBACK_MS);
+  entering.set(el, () => done());
+}
+
 /** Restart the CSS animation on an element (for a "replay" control). */
 export function replay(el) {
   if (!el || !el.style) return;

package/src/styles/back.css

@@ -0,0 +1,42 @@
+/* ============================================================================
+ * Back link — .ui-back
+ * The way up from a page to the page it sits under. It stands above the page
+ * title, in the slot a breadcrumb trail would take, and it is quiet at rest: it
+ * is on every page below a list, and it is never what the page is for.
+ * why: docs/specification.md#the-back-link
+ * ========================================================================== */
+
+/* Its own line, and only as wide as its words, so the hover ground does not run
+   the width of the column. */
+.ui-back {
+  display: flex;
+  width: fit-content;
+  align-items: center;
+  gap: var(--space-1);
+  /* WCAG 2.5.8's 24px: the line of text alone is 17px tall. */
+  min-height: var(--space-6);
+  padding: 0 var(--space-2) 0 var(--space-1);
+  border-radius: var(--radius-sm);
+  font-family: var(--font-sans);
+  font-size: var(--text-sm);
+  font-weight: var(--weight-medium);
+  line-height: 1.3;
+  text-decoration: none;
+}
+
+/* [href] as well as the class, because a host stylesheet's `a:link` is (0,1,1)
+   and outranks a bare class: it would paint this in the host's link colour.
+   (0,2,0) wins without !important — the argument `.ui-nav .ui-nav__item` makes
+   in nav.css. */
+.ui-back[href] { color: var(--dim); }
+.ui-back[href]:hover { color: var(--strong); background: var(--surface-2); }
+.ui-back:focus-visible { outline: none; box-shadow: var(--ring); }
+
+/* 16px, with the stroke raised to match: the glyph set draws at 1.7 on a 24-unit
+   box, which is 1.13 CSS px at this size and under the kit's 1.5 for a stroked
+   mark. 2.4 paints 1.6. why: docs/specification.md#icons-and-glyphs */
+.ui-back svg { width: 16px; height: 16px; flex: none; stroke-width: 2.4; }
+
+/* In the page shell it takes the trail's place, and the trail's distance from
+   the title with it. */
+.ui-app__main > .ui-back { margin-bottom: var(--space-5); }

package/src/styles/badge.css

@@ -1,6 +1,6 @@
 /* ============================================================================
  * Badge / Pill / Tag
- *   .ui-badge        — uppercase status chip (live / soon / archive / neutral)
+ *   .ui-badge        — status chip (live / soon / archive / neutral)
  *   .ui-tag          — soft solid label
  *   .ui-dot          — leading status dot (pulses when .is-live)
  * ========================================================================== */
@@ -9,10 +9,9 @@
   display: inline-flex;
   align-items: center;
   gap: 6px;
-  font-size: 10px;
-  letter-spacing: 0.12em;
-  text-transform: uppercase;
-  font-weight: var(--weight-bold);
+  /* rank: chip */
+  font-size: var(--text-xs);
+  font-weight: var(--weight-semibold);
   padding: 3px 9px;
   border-radius: var(--radius-pill);
   color: var(--muted);
@@ -45,9 +44,8 @@
   display: inline-flex;
   align-items: center;
   gap: 7px;
+  /* rank: chip */
   font-size: var(--text-xs);
-  letter-spacing: 0.12em;
-  text-transform: uppercase;
   color: var(--muted);
   background: var(--surface-2);
   border-radius: var(--radius-pill);