@apliteni/apliteni-ui 0.26.0 → 0.30.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/pagination.js

@@ -0,0 +1,344 @@
+// Pagination — the strip under a table or a list, as an HTML string.
+//
+// It renders a page the CALLER computed. Rows never come in here: `page`,
+// `pageSize` and `total` are numbers, so a page counted by a server and a page
+// sliced out of an array in memory produce the same markup.
+//
+// `total: null` is the honest shape for an API that cannot count what it has not
+// fetched. The component then knows no last page, so it draws Prev and Next and
+// nothing else — see `ui-pager--open` below.
+import { esc } from './index.js';
+
+// The sizes a table offers, and the one it starts on. Named here so no call site
+// writes either number: both moved once already and would have moved in thirteen
+// files. MUI's DataGrid ships exactly this pair (default 100, options 25/50/100),
+// AG Grid defaults to 100, and the finance portal's two data-heavy surfaces
+// already page at 100. A 250 step was in the first draft of this component and
+// no surveyed kit offers one, so it went rather than being invented.
+export const PAGE_SIZES = [25, 50, 100];
+export const DEFAULT_PAGE_SIZE = 100;
+
+// The classes button({ variant: 'ghost', size: 'sm' }) emits, written out because
+// button() takes no extra class and every control here needs one of its own for
+// the React component to key on. src/components/pagination.test.js asserts the
+// two agree, so a change to button()'s class list fails there instead of drifting.
+const GHOST_SM = 'ui-btn ui-btn--ghost ui-btn--sm';
+
+const VARIANTS = ['steps', 'numbered', 'jump'];
+
+// The id seeds a <label for> and the control it names, so two pagers that share
+// one are two labels pointing at one control: the second table's "Rows" label
+// focuses the FIRST table's select, and the second select has no accessible name
+// at all. `tabs()` states the same requirement in words and leaves it there; a
+// pager is dropped under a table by a caller who is not thinking about ids, and
+// two tables on a page is the ordinary case rather than the exotic one. So an
+// omitted id is unique by construction instead. A caller who needs a stable id —
+// a server rendering the same page twice, a test — passes one.
+let seq = 0;
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Every number here arrives from a URL in real use — `?page=-2`, `?page=abc`,
+// `?page=` — so each is coerced before it is clamped, and nothing that is not a
+// finite integer reaches the markup.
+//
+// `Number()` alone is not that check, and the first draft of this used it. It
+// reads '', '  ', null, [] and false as 0, all of which are finite: `?total=` then
+// meant "this result holds zero rows" and erased the whole component, and
+// `?pageSize=` meant one row per page. Only a number, or a string with something
+// in it, is a number here. A Symbol is refused rather than thrown on — a string
+// factory that raises a TypeError is a worse answer than a pager.
+//
+// The cap is Number.MAX_SAFE_INTEGER because above it arithmetic stops moving:
+// `at - 1 === at === at + 1`, so Prev and Next would carry the same target while
+// both rendered live, and a page past 1e21 prints as `1e+21`, which parseInt reads
+// back as 1.
+const CAP = Number.MAX_SAFE_INTEGER;
+const int = (v, fallback) => {
+  const raw = typeof v === 'number' ? v
+    : (typeof v === 'string' && v.trim() !== '') ? Number(v)
+      : NaN;
+  if (!Number.isFinite(raw)) return fallback;
+  return Math.min(Math.max(Math.trunc(raw), -CAP), CAP);
+};
+const fmt = (n) => n.toLocaleString('en-US');
+
+// A control at an end is DISABLED, never removed. Polaris states the rule as
+// "Hint when merchants are at the first or the last page by disabling the
+// corresponding button": removing it slides the next control sideways under a
+// pointer already travelling toward it, and takes away the only evidence a
+// screen-reader user has that they are at the start.
+//
+// An <a> has no disabled state, so an end that is off renders as
+// <button disabled> even when `href` was given — a link that goes nowhere reads
+// as available right up until it is followed.
+function control({ cls, page, label, href, disabled = false, current = false }) {
+  const attrs = `class="${cls}" data-page="${page}"${current ? ' aria-current="page"' : ''}`;
+  return href && !disabled
+    ? `<a href="${esc(href(page))}" ${attrs}>${esc(label)}</a>`
+    : `<button type="button" ${attrs}${disabled ? ' disabled aria-disabled="true"' : ''}>${esc(label)}</button>`;
+}
+
+/**
+ * The page numbers a `numbered` pager shows, with `null` where a run was cut.
+ *
+ * Seven slots at most: page 1, the last page, the current page with one
+ * neighbour each side, and a gap for each run removed between them. Two rules
+ * keep the strip honest — no two gaps side by side, and no gap standing in for a
+ * single page, because an ellipsis hiding one number is wider than the number
+ * and costs a click to find out what it was.
+ */
+function slotsFor(page, pageCount) {
+  const wanted = [1, pageCount, page - 1, page, page + 1]
+    .filter((n) => n >= 1 && n <= pageCount);
+  const shown = [...new Set(wanted)].sort((a, b) => a - b);
+  const out = [];
+  for (const n of shown) {
+    const prev = out.length ? out[out.length - 1] : null;
+    if (prev != null) {
+      if (n - prev === 2) out.push(prev + 1); // one page hidden — draw it, not a gap
+      else if (n - prev > 2) out.push(null);
+    }
+    out.push(n);
+  }
+  return out;
+}
+
+/**
+ * pagination({ … }) → the <nav> a caller drops under a table.
+ *
+ * A pager for a single page draws no steps: GOV.UK's guidance is "Do not show
+ * pagination if there's only one page of content", and the kit was rendering
+ * two permanently dead buttons under every short table. With no size control to
+ * offer, such a pager has no job at all and returns the empty string; with one,
+ * the <nav> stays for the size control alone — somebody looking at 25 of 25 rows
+ * may still want 100 per page — and carries `ui-pager--single`.
+ */
+export function pagination({
+  page = 1,
+  pageSize = DEFAULT_PAGE_SIZE,
+  total = null,
+  hasMore = false,
+  pageSizes = null,
+  variant = 'steps',
+  label = 'Pagination',
+  loading = false,
+  href = null,
+  id,
+} = {}) {
+  const uid = esc(String(id ?? `pager-${++seq}`));
+  const kind = VARIANTS.includes(variant) ? variant : 'steps';
+  // A size of zero or less is not a size, so it is read as absent rather than
+  // clamped to 1 — clamping turns `?pageSize=0` into 4,812 pages of one row.
+  const asked = int(pageSize, DEFAULT_PAGE_SIZE);
+  const size = asked > 0 ? asked : DEFAULT_PAGE_SIZE;
+  // A total that is not a number is a total nobody knows — the open shape is the
+  // truthful answer to it, and it is the same answer `total: null` asks for.
+  const asRows = int(total, null);
+  const counted = total != null && asRows !== null;
+  const rows = counted ? Math.max(0, asRows) : null;
+  const last = counted ? Math.max(1, Math.ceil(rows / size)) : null;
+  // One below the cap when nothing is counted, because the open shape emits
+  // `at + 1` as Next's target and MAX_SAFE_INTEGER + 1 is not representable — it
+  // rounds back onto its neighbour, so Prev and Next would carry one page again.
+  const at = counted
+    ? Math.min(Math.max(1, int(page, 1)), last)
+    : Math.min(Math.max(1, int(page, 1)), CAP - 1);
+
+  // The current size is offered even when the caller's list forgot it: a select
+  // whose value is not among its options renders as the first one, which reports
+  // a page size the table is not using.
+  // Capped: this is a string factory, and a caller who hands it a hundred thousand
+  // sizes gets a hundred thousand <option>s and megabytes of HTML rather than an
+  // error. Twelve is past any real size menu — MUI ships four.
+  const offered = (Array.isArray(pageSizes) ? pageSizes : [])
+    .slice(0, 12)
+    .map((s) => int(s, 0))
+    .filter((s) => s > 0);
+  const sizes = offered.length
+    ? [...new Set([...offered, size])].sort((a, b) => a - b)
+    : [];
+
+  const single = counted && last === 1;
+  if (single && !sizes.length) return '';
+
+  const from = (at - 1) * size + 1;
+  const to = counted ? Math.min(at * size, rows) : null;
+  // Not "1–0 of 0" for an empty result, and not "7–7 of 7" for a single row:
+  // both are arithmetic a reader has to undo.
+  const status = !counted ? `Page ${fmt(at)}`
+    : rows === 0 ? '0 of 0'
+      : from === to ? `${fmt(from)} of ${fmt(rows)}`
+        : `${fmt(from)}–${fmt(to)} of ${fmt(rows)}`;
+
+  const sizeBlock = sizes.length
+    ? `<div class="ui-pager__size">`
+      + `<label class="ui-pager__size-label" for="${uid}-size">Rows</label>`
+      + `<select class="ui-select ui-pager__size-select" id="${uid}-size"${loading ? ' disabled' : ''}>`
+      + sizes.map((s) => `<option value="${s}"${s === size ? ' selected' : ''}>${fmt(s)}</option>`).join('')
+      + `</select></div>`
+    : '';
+
+  const step = (spec) => control({ cls: `${GHOST_SM} ui-pager__step`, href, ...spec, disabled: loading || spec.disabled });
+  const atStart = at === 1;
+  const atEnd = counted && at === last;
+
+  let steps = '';
+  if (single) {
+    steps = ''; // GOV.UK: no pagination for one page of content.
+  } else if (!counted) {
+    // The open shape: no last page exists, so no control may claim to reach one.
+    // Next is off when the caller says there is nothing after this page.
+    steps = `<div class="ui-pager__steps">`
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + step({ page: at + 1, label: 'Next', disabled: !hasMore })
+      + `</div>`;
+  } else {
+    let middle = '';
+    if (kind === 'numbered') {
+      middle = slotsFor(at, last).map((n) => (n == null
+        ? '<span class="ui-pager__gap" aria-hidden="true">…</span>'
+        : control({
+          cls: cx(`${GHOST_SM} ui-pager__page`, n === at && 'is-current'),
+          href,
+          page: n,
+          label: fmt(n),
+          current: n === at,
+          disabled: loading,
+        }))).join('');
+    } else if (kind === 'jump') {
+      middle = `<span class="ui-pager__jump"><label for="${uid}-jump">Page</label>`
+        + `<input class="ui-input ui-pager__jump-input" id="${uid}-jump" type="number"`
+        + ` min="1" max="${last}" value="${at}"${loading ? ' disabled' : ''}>`
+        + `<span class="ui-pager__jump-of">of ${fmt(last)}</span></span>`;
+    }
+    // First and Last are the numbered variant's own job — its first and last
+    // slots are always those two pages, so a second pair of controls for them
+    // would be the same jump written twice.
+    const ends = kind !== 'numbered';
+    steps = `<div class="ui-pager__steps">`
+      + (ends ? step({ page: 1, label: 'First', disabled: atStart }) : '')
+      + step({ page: Math.max(1, at - 1), label: 'Prev', disabled: atStart })
+      + middle
+      + step({ page: Math.min(last, at + 1), label: 'Next', disabled: atEnd })
+      + (ends ? step({ page: last, label: 'Last', disabled: atEnd }) : '')
+      + `</div>`;
+  }
+
+  // The status line is the only live region in the component: a strip where the
+  // numbers, the size control and four buttons all announced would read the same
+  // change out four times.
+  return `<nav class="${cx('ui-pager', `ui-pager--${kind}`, !counted && 'ui-pager--open', single && 'ui-pager--single')}"`
+    + ` aria-label="${esc(label)}"${loading ? ' aria-busy="true"' : ''}>`
+    + `<p class="ui-pager__status" aria-live="polite" aria-atomic="true">${esc(status)}</p>`
+    + sizeBlock
+    + steps
+    + `</nav>`;
+}
+
+/**
+ * Make a rendered pager work.
+ *
+ * Every control the factory draws is inert markup until this runs: the steps
+ * carry `data-page` and nothing reads it, the size control is a `<select>` with
+ * no handler, and the jump input is an `<input>` with no handler. Shipping the
+ * `jump` variant without this meant shipping the one control that reaches an
+ * arbitrary page and having it do nothing.
+ *
+ * It reads the class contract rather than hooks of its own — `.ui-pager__step`,
+ * `.ui-pager__page`, `.ui-pager__size-select`, `.ui-pager__jump-input` — so the
+ * markup is exactly what `pagination()` already returns and the React component
+ * is still class-for-class identical to it.
+ *
+ *   const pager = wirePagination(root, {
+ *     onPage: (page) => load({ page }),
+ *     onPageSize: (size) => load({ page: 1, size }),
+ *   });
+ *
+ * Listeners are delegated from `root`, so a pager re-rendered underneath stays
+ * wired. Returns a function that removes them.
+ *
+ * A step rendered as an `<a href>` is left alone: it is a link, the browser owns
+ * it, and calling it back as well would navigate twice.
+ */
+export function wirePagination(root = document, { onPage, onPageSize } = {}) {
+  const scope = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!scope || typeof scope.addEventListener !== 'function') return () => {};
+
+  const pageOf = (el) => int(el.getAttribute('data-page'), null);
+  const inPager = (el) => el && el.closest && el.closest('.ui-pager');
+
+  const onClick = (e) => {
+    const step = e.target.closest?.('.ui-pager__step, .ui-pager__page');
+    if (!step || !inPager(step) || step.tagName === 'A' || step.disabled) return;
+    const page = pageOf(step);
+    if (page !== null) onPage?.(page);
+  };
+
+  const onChange = (e) => {
+    const select = e.target.closest?.('.ui-pager__size-select');
+    if (!select || !inPager(select)) return;
+    const size = int(select.value, null);
+    if (size !== null && size > 0) onPageSize?.(size);
+  };
+
+  // Enter commits; so does leaving the box. A value the input cannot parse — it
+  // is type="number", so a rejected keystroke leaves it empty — is not a page,
+  // and the box goes back to the one it was showing rather than to page 1.
+  const commit = (box) => {
+    const asked = int(box.value, null);
+    const max = int(box.getAttribute('max'), null);
+    if (asked === null || asked < 1) {
+      box.value = box.defaultValue;
+      return;
+    }
+    const page = max === null ? asked : Math.min(asked, max);
+    box.value = String(page);
+    if (String(page) !== box.defaultValue) onPage?.(page);
+  };
+  const onKeydown = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (!box || !inPager(box) || e.key !== 'Enter') return;
+    // A lone number input inside a <form> submits it on Enter, which reloads the
+    // page the reader was trying to move within.
+    e.preventDefault();
+    commit(box);
+  };
+  const onBlur = (e) => {
+    const box = e.target.closest?.('.ui-pager__jump-input');
+    if (box && inPager(box)) commit(box);
+  };
+
+  scope.addEventListener('click', onClick);
+  scope.addEventListener('change', onChange);
+  scope.addEventListener('keydown', onKeydown);
+  scope.addEventListener('focusout', onBlur);
+  return () => {
+    scope.removeEventListener('click', onClick);
+    scope.removeEventListener('change', onChange);
+    scope.removeEventListener('keydown', onKeydown);
+    scope.removeEventListener('focusout', onBlur);
+  };
+}
+
+/**
+ * Rewrite a pager's row range, in place. THIS is the announcement.
+ *
+ * The factory returns a whole `<nav>`, so the obvious way to show a new page is
+ * to replace it — which inserts a brand-new live region that already contains its
+ * text, and several screen readers say nothing at all about a region that arrived
+ * with its content. The kit has met this before and answered it the same way:
+ * `setBusy()` rewrites the line its region already holds rather than inserting a
+ * new one. why: docs/specification.md#pending-and-denied-states
+ *
+ * So a consumer re-rendering a pager should hand the new range here instead of
+ * relying on the replacement to speak. Returns the status element, or null when
+ * there is nothing to update — safe against a torn-down view.
+ */
+export function setPagerStatus(root, text) {
+  const el = typeof root === 'string' ? document.querySelector(root) : root;
+  if (!el || typeof el.querySelector !== 'function') return null;
+  const status = el.matches?.('.ui-pager__status') ? el : el.querySelector('.ui-pager__status');
+  if (!status) return null;
+  if (status.textContent !== String(text)) status.textContent = String(text);
+  return status;
+}

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();
     };