npm - @apliteni/apliteni-ui - Versions diffs - 0.31.0 → 0.33.0 - Mend

@apliteni/apliteni-ui 0.31.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/README.md +33 -34
package/package.json +1 -1
package/react/README.md +7 -9
package/react/dist/index.css +10 -2
package/react/dist/index.d.ts +25 -1
package/react/dist/index.js +136 -92
package/src/components/dropdown.js +77 -30
package/src/components/footer.js +6 -1
package/src/components/index.js +2 -2
package/src/components/nav.js +4 -3
package/src/components/pagination.js +9 -31
package/src/components/shell.js +197 -30
package/src/components/stat.js +75 -0
package/src/components/success.js +12 -1
package/src/index.css +2 -0
package/src/index.js +1 -0
package/src/inline.js +4 -0
package/src/styles/button.css +6 -5
package/src/styles/callout.css +7 -4
package/src/styles/card.css +12 -19
package/src/styles/command-palette.css +6 -5
package/src/styles/confirm.css +10 -19
package/src/styles/drawer.css +6 -6
package/src/styles/dropdown.css +36 -20
package/src/styles/feedback.css +11 -13
package/src/styles/field-zoom.css +20 -0
package/src/styles/input.css +17 -2
package/src/styles/layout.css +208 -57
package/src/styles/motion.css +3 -3
package/src/styles/nav.css +88 -10
package/src/styles/pagination.css +1 -0
package/src/styles/segmented.css +1 -2
package/src/styles/stat.css +121 -0
package/src/styles/success.css +2 -2
package/src/styles/tooltip.css +3 -4
package/src/styles/topbar.css +36 -10
package/src/tokens/accents.css +7 -6
package/src/tokens/tokens.css +51 -38

package/src/components/dropdown.js CHANGED Viewed

@@ -222,7 +222,27 @@ export function dropdown({
 // Per-instance trigger + keyboard handlers are attached once (guarded by a flag
 // on the element). Document-level click-outside + Esc are attached once per
 // document. Safe to call repeatedly (e.g. Storybook re-renders).
-let _ddGlobalWired = false;
+// Every wired container, so the close handlers can reach a dropdown wherever it
+// was drawn: `document.querySelectorAll` enters no shadow root and sees no other
+// document. A Set and not a WeakSet, because this has to be walked.
+// why: docs/specification.md#the-dropdown-panel
+const _ddAll = new Set();
+// One pair of close handlers per document that holds a dropdown, the same way
+// wireShell() listens once per document it is handed.
+const _ddWiredDocs = new WeakSet();
+/** Where a portalled panel goes: the top of the tree its trigger lives in. A
+ *  shadow root is its own top — moving the panel out to the page's <body> would
+ *  leave every style scoped to that root behind. */
+const ddHostOf = (node) => {
+  const root = node.getRootNode ? node.getRootNode() : node.ownerDocument;
+  return root.nodeType === 9 ? root.body : root;
+};
+/** The window a box is measured in. A panel in a frame is laid out against the
+ *  frame's viewport, not the top page's. */
+const ddViewOf = (node) => node.ownerDocument?.defaultView || window;
 // The trigger-to-panel offset is --ui-dropdown-gap in src/styles/dropdown.css.
 // This is the fallback for a document that has not loaded the sheet;
@@ -234,7 +254,7 @@ const DD_GAP = 9;
 const ddPanelOf = (dd) => dd.__ddPanel || dd.querySelector('[data-dropdown-panel]');
 function ddGap(panel) {
-  const declared = parseFloat(getComputedStyle(panel).getPropertyValue('--ui-dropdown-gap'));
+  const declared = parseFloat(ddViewOf(panel).getComputedStyle(panel).getPropertyValue('--ui-dropdown-gap'));
   return Number.isFinite(declared) ? declared : DD_GAP;
 }
@@ -305,7 +325,7 @@ function ddResolveDirection(dd, panel) {
   const trigger = dd.querySelector('[data-dropdown-trigger]');
   if (!trigger || typeof trigger.getBoundingClientRect !== 'function') return;
   const t = trigger.getBoundingClientRect();
-  const below = window.innerHeight - t.bottom;
+  const below = ddViewOf(panel).innerHeight - t.bottom;
   panel.classList.toggle('is-up', below < panel.offsetHeight + ddGap(panel) && t.top > below);
 }
@@ -314,29 +334,31 @@ function ddResolveDirection(dd, panel) {
 function positionPortalPanel(dd, panel) {
   const trigger = dd.querySelector('[data-dropdown-trigger]');
   if (!trigger || typeof trigger.getBoundingClientRect !== 'function') return;
+  const view = ddViewOf(panel);
   const t = trigger.getBoundingClientRect();
   const gap = ddGap(panel);
   const s = panel.style;
   if (panel.classList.contains('is-up')) {
     s.top = 'auto';
-    s.bottom = `${window.innerHeight - t.top + gap}px`;
+    s.bottom = `${view.innerHeight - t.top + gap}px`;
   } else {
     s.bottom = 'auto';
     s.top = `${t.bottom + gap}px`;
   }
   if (panel.classList.contains('is-end')) {
     s.left = 'auto';
-    s.right = `${window.innerWidth - t.right}px`;
+    s.right = `${view.innerWidth - t.right}px`;
   } else {
     s.right = 'auto';
     s.left = `${t.left}px`;
   }
 }
-// A panel left on <body> outlives the container that owned it — a re-render
-// replaces the container and the old panel has nothing pointing at it.
-function sweepOrphanPanels() {
-  document.querySelectorAll('body > [data-dropdown-panel][data-dropdown-portal]')
+// A portalled panel outlives the container that owned it — a re-render replaces
+// the container and the old panel has nothing pointing at it. Swept in the host
+// it was put in, which is the tree the new container is in too.
+function sweepOrphanPanels(host) {
+  host.querySelectorAll(':scope > [data-dropdown-panel][data-dropdown-portal]')
     .forEach((p) => { if (!p.__ddOwner || !p.__ddOwner.isConnected) p.remove(); });
 }
@@ -347,8 +369,19 @@ function closeDropdown(dd) {
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'false');
 }
+/** Every wired dropdown still in a tree, the ones in frames and shadow roots
+ *  included. Disconnected containers are dropped as they are passed. */
+function ddLive() {
+  const out = [];
+  for (const dd of _ddAll) {
+    if (dd.isConnected) out.push(dd);
+    else _ddAll.delete(dd);
+  }
+  return out;
+}
 function closeAllDropdowns(except) {
-  document.querySelectorAll('[data-dropdown].open').forEach((dd) => { if (dd !== except) closeDropdown(dd); });
+  for (const dd of ddLive()) if (dd !== except && dd.classList.contains('open')) closeDropdown(dd);
 }
 function openDropdown(dd, focusIdx) {
@@ -390,11 +423,39 @@ function selectOption(dd, item) {
   if (valueEl && label) valueEl.textContent = label.textContent;
 }
+// Click-outside, Escape and the repositioning sweep, registered once per document
+// that holds a dropdown — the same shape wireShell()'s listen() has, and for the
+// same reason: a frame is its own document and a listener on the page's never
+// fires there. why: docs/specification.md#the-dropdown-panel
+function ddListen(doc) {
+  if (!doc || _ddWiredDocs.has(doc)) return;
+  _ddWiredDocs.add(doc);
+  doc.addEventListener('click', () => closeAllDropdowns());
+  doc.addEventListener('keydown', (e) => {
+    if (e.key !== 'Escape' || ddComposing(e)) return;
+    const open = ddLive().find((dd) => dd.classList.contains('open') && dd.ownerDocument === doc);
+    if (open) { closeDropdown(open); open.querySelector('[data-dropdown-trigger]')?.focus(); }
+  });
+  // Viewport coordinates go stale the moment anything scrolls. Capture, so a
+  // scroll inside the rail the panel was lifted out of counts too.
+  const reposition = () => {
+    for (const dd of ddLive()) {
+      if (dd.classList.contains('open') && dd.__ddPanel) positionPortalPanel(dd, dd.__ddPanel);
+    }
+  };
+  const view = doc.defaultView;
+  if (!view) return;
+  view.addEventListener('scroll', reposition, true);
+  view.addEventListener('resize', reposition);
+}
 export function wireDropdown(root = document) {
   const scope = root === document ? document : root;
   scope.querySelectorAll('[data-dropdown]').forEach((dd) => {
     if (dd.__ddWired) return;
     dd.__ddWired = true;
+    _ddAll.add(dd);
+    ddListen(dd.ownerDocument);
     const trigger = dd.querySelector('[data-dropdown-trigger]');
     const panel = dd.querySelector('[data-dropdown-panel]');
     if (!trigger) return;
@@ -404,11 +465,15 @@ export function wireDropdown(root = document) {
     // a stacking context whatever z-index the panel carries — the app rail is
     // both at once. why: docs/specification.md#the-dropdown-panel
     if (panel && dd.hasAttribute('data-dropdown-portal')) {
-      sweepOrphanPanels();
+      // The tree the trigger is in, not the page's: a panel lifted out of a
+      // frame or a shadow root into the top document leaves its stylesheet and
+      // its close handler behind. why: docs/specification.md#the-dropdown-panel
+      const host = ddHostOf(dd);
+      sweepOrphanPanels(host);
       panel.setAttribute('data-dropdown-portal', '');
       panel.__ddOwner = dd;
       dd.__ddPanel = panel;
-      document.body.appendChild(panel);
+      host.appendChild(panel);
       if (dd.classList.contains('open')) {
         ddResolveDirection(dd, panel);
         positionPortalPanel(dd, panel);
@@ -508,22 +573,4 @@ export function wireDropdown(root = document) {
     }
   });
-  if (!_ddGlobalWired) {
-    _ddGlobalWired = true;
-    document.addEventListener('click', () => closeAllDropdowns());
-    document.addEventListener('keydown', (e) => {
-      if (e.key !== 'Escape' || ddComposing(e)) return;
-      const open = document.querySelector('[data-dropdown].open');
-      if (open) { closeDropdown(open); open.querySelector('[data-dropdown-trigger]')?.focus(); }
-    });
-    // Viewport coordinates go stale the moment anything scrolls. Capture, so a
-    // scroll inside the rail the panel was lifted out of counts too.
-    const reposition = () => {
-      document.querySelectorAll('[data-dropdown].open').forEach((dd) => {
-        if (dd.__ddPanel) positionPortalPanel(dd, dd.__ddPanel);
-      });
-    };
-    window.addEventListener('scroll', reposition, true);
-    window.addEventListener('resize', reposition);
-  }
 }

package/src/components/footer.js CHANGED Viewed

@@ -32,9 +32,14 @@ function linkList(links = []) {
     `<li><a href="${href}"${target ? ` target="${target}" rel="noreferrer"` : ''}>${esc(label)}</a></li>`).join('')}</ul>`;
 }
+// The column title is an h2: it names a top-level section of the page's end
+// matter, and h2 is the one rank that cannot skip whatever heading came before
+// it. It was an h4 — the only h4 the kit drew — which read h2 → h4 on the
+// landing page and left a rank a reader hears missing. The look is the class's,
+// not the tag's. why: docs/specification.md#the-page
 function column({ title, links = [] } = {}) {
   return `<div class="ui-footer__col">` +
-    (title ? `<h4 class="ui-footer__col-title">${esc(title)}</h4>` : '') +
+    (title ? `<h2 class="ui-footer__col-title">${esc(title)}</h2>` : '') +
     linkList(links) + `</div>`;
 }

package/src/components/index.js CHANGED Viewed

@@ -2,9 +2,9 @@
 // viz/ server-render idiom so the portal can adopt them with no framework.
 import { icon } from '../assets/icons.js';
 import { illo } from '../assets/illustrations.js';
+const HTML_ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
 const cx = (...a) => a.filter(Boolean).join(' ');
-export const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+export const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => HTML_ENTITIES[c]);
 // ---- Button --------------------------------------------------------------
 // `iconSvg` is a raw leading-icon SVG string (trusted markup, not escaped) for

package/src/components/nav.js CHANGED Viewed

@@ -68,12 +68,13 @@ function sideLeaf(it, active, { collapsed, sub, current = 'page' } = {}) {
 }
 // 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.
+// list. It opens and closes the same way on the folded rail: forcing it shut
+// there hid the current page's own row and left the toggle announcing a list
+// nobody could reach.
 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 open = 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>`;

package/src/components/pagination.js CHANGED Viewed

@@ -236,29 +236,12 @@ export function pagination({
 }
 /**
- * Make a rendered pager work.
+ * Make a rendered pager work: delegate the steps, the size control and the jump
+ * input from `root`, so a pager re-rendered underneath stays wired.
  *
- * 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.
+ * @returns {() => void} a function that removes the listeners.
  *
- * 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.
+ * why: CONTRIBUTING.md#pagination-event-wiring
  */
 export function wirePagination(root = document, { onPage, onPageSize } = {}) {
   const scope = typeof root === 'string' ? document.querySelector(root) : root;
@@ -321,18 +304,13 @@ export function wirePagination(root = document, { onPage, onPageSize } = {}) {
 }
 /**
- * Rewrite a pager's row range, in place. THIS is the announcement.
+ * Rewrite a pager's row range in place, so the live region it already holds is
+ * the thing that announces — as `setBusy()` does.
  *
- * 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
+ * @returns {Element|null} the status element, or null when there is nothing to
+ * update — safe against a torn-down view.
  *
- * 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.
+ * why: CONTRIBUTING.md#pagination-status-updates
  */
 export function setPagerStatus(root, text) {
   const el = typeof root === 'string' ? document.querySelector(root) : root;

package/src/components/shell.js CHANGED Viewed

@@ -1,12 +1,11 @@
-// The kit's one page shell. `appShell()` is a full-height rail — brand, the
-// kit's own sidebarNav(), the signed-in reader — beside one <main> that opens
-// with a breadcrumb trail the caller owns. `accountShell()` is a thin preset
-// over it that keeps the topbar, so the published /account API still works.
-// Call wireTopbar() once after mounting to wire the account menu + theme toggle.
+// The kit's one page shell: a full-height rail beside one <main>. accountShell()
+// is a thin preset over it that keeps the topbar. wireShell() once after mounting
+// wires the fold, the nav's groups and the reader's menu.
 // why: docs/specification.md#the-page-shell
 import { topbar as productTopbar } from './topbar.js';
 import { esc, icon } from './index.js';
-import { sidebarNav, breadcrumbs } from './nav.js';
+import { sidebarNav, breadcrumbs, wireNav } from './nav.js';
+import { dropdown, wireDropdown } from './dropdown.js';
 import { backLink } from './back.js';
 import { prism } from '../assets/brand.js';
 import { ACCOUNT_NAV, toMenuTuple, initials } from './account-nav.js';
@@ -91,10 +90,58 @@ const mainMax = (v) => {
   return s === 'none' || LENGTH.test(s) ? s : '';
 };
+// ---- the fold, and where the reader's choice is kept ---------------------
+//
+// A cookie rather than localStorage, because a server can read one and paint the
+// rail at the width the reader left it. why: docs/specification.md#the-page-shell
+export const RAIL_COOKIE = 'apliteni-ui-rail';
+const RAIL_MAX_AGE = 60 * 60 * 24 * 365;
+const RAIL_VALUE = new RegExp(`(?:^|;\\s*)${RAIL_COOKIE}=(collapsed|expanded)(?:;|$)`);
+// A sandboxed frame throws on document.cookie; it has no stored choice.
+const cookieOf = (doc) => {
+  try { return doc ? doc.cookie : ''; } catch (e) { return ''; }
+};
+/** The reader's stored choice — true, false, or null when there is none. With no
+ *  argument it reads `document.cookie`; handed a Cookie header, only that. */
+export function railCollapsed(cookies) {
+  const src = arguments.length ? cookies : cookieOf(typeof document === 'undefined' ? null : document);
+  const m = RAIL_VALUE.exec(String(src ?? ''));
+  return m ? m[1] === 'collapsed' : null;
+}
+// The name says what the press will do, and aria-expanded says what the rail is.
+const railName = (collapsed) => (collapsed ? 'Expand sidebar' : 'Collapse sidebar');
+// A frame that holds still and a seam that crosses it. Only the two nodes are
+// written here — a seam that travels has to be a child a stylesheet can reach —
+// and they are spliced into icon()'s own wrapper rather than a copy of it.
+// why: docs/specification.md#the-page-shell
+const MARK = '<rect x="3" y="3" width="18" height="18" rx="2"/>'
+  + '<path class="ui-app__fold-seam" d="M9 3v18"/>';
+const railMark = () => icon('').replace('></svg>', `>${MARK}</svg>`);
+// The rail's own skin, outside the <nav>: folding the rail is not a place to go.
+// It stands at the far end of the head band's brand row, and its name is written
+// out rather than put in a tooltip, because the name IS the chip layout.css lands
+// beside the glyph — at both widths. why: docs/specification.md#the-page-shell
+const railToggle = (collapsed) =>
+  `<div class="ui-app__fold-row">`
+  + `<button type="button" class="ui-nav__item ui-app__fold" data-rail-toggle`
+  + ` aria-expanded="${collapsed ? 'false' : 'true'}" aria-label="${railName(collapsed)}">`
+  + `<span class="ui-nav__ic">${railMark()}</span>`
+  + `<span class="ui-nav__label">${railName(collapsed)}</span></button></div>`;
 // 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, back: toBack, account: toReader, maxWidth: mainMax, topbar: toTopbar,
+  // Drawn by default; `collapsible: false` is the way out, for a page that will
+  // never call wireShell(). why: docs/specification.md#the-page-shell
+  collapsible: (v) => v !== false,
+  // A boolean is the caller's answer. Anything else leaves it to the reader.
+  collapsed: (v) => (typeof v === 'boolean' ? v : null),
 };
 // The text options settle by the same argument. `body: null` from a record with no
@@ -109,28 +156,46 @@ function settle(options) {
   return out;
 }
-// Signing out is a navigation action, so it belongs in the rail nav's footer slot.
-// Opt-in: rendering it unasked puts a dead link on a page with no session behind it.
-const signOut = (href) =>
-  `<a class="ui-nav__item is-danger" href="${esc(href)}" aria-label="Sign out">` +
-  `<span class="ui-nav__ic">${icon('logout')}</span>` +
-  `<span class="ui-nav__label">Sign out</span></a>`;
-// Who is signed in. A sibling of the <nav>, not its footer: a name and address are not
-// navigation, and inside the landmark a screen reader announces the address as an entry.
-// Empty when nobody is. The initials carry the name and the spelled-out half is
-// aria-hidden, because the narrow rail folds `.ui-app__who` out of view and a name that
-// lived only there left nothing in the accessibility tree.
-function railUser({ name, email }) {
+// The face of the reader block: the initials, and the two lines beside them that
+// the fold takes away. `named` is the accessible name when nothing else carries
+// one; under the menu trigger it is null, because the button is named by the words
+// inside it. why: docs/specification.md#the-page-shell
+const readerFace = (name, email, named) =>
+  `<span class="ui-app__av"${named ? ` role="img" aria-label="Signed in as ${esc(named)}"` : ' aria-hidden="true"'}>`
+  + `${esc(initials(name, email))}</span>`
+  + `<span class="ui-app__who"${named ? ' aria-hidden="true"' : ''}>`
+  + (name ? `<b>${esc(name)}</b>` : '')
+  + (email ? `<span>${esc(email)}</span>` : '')
+  + `</span>`;
+// Who is signed in, and the one action on the session. A sibling of the <nav>, not
+// its footer: a name and address are not navigation. Given a sign-out href the block
+// is the trigger of the kit's own dropdown(), with Sign out inside it; without one
+// there is no menu, and with nobody signed in there is no block.
+// `portal: true` and `direction: 'up'` are what the rail asks of a panel at its foot.
+// why: docs/specification.md#the-page-shell
+function railUser({ name, email }, signOutHref) {
   if (!name && !email) return '';
   const who = [name, email].filter(Boolean).join(', ');
-  return `<div class="ui-app__user">` +
-    `<span class="ui-app__av" role="img" aria-label="Signed in as ${esc(who)}">` +
-    `${esc(initials(name, email))}</span>` +
-    `<span class="ui-app__who" aria-hidden="true">` +
-    (name ? `<b>${esc(name)}</b>` : '') +
-    (email ? `<span>${esc(email)}</span>` : '') +
-    `</span></div>`;
+  if (!signOutHref) {
+    return `<div class="ui-app__user">${readerFace(name, email, who)}</div>`;
+  }
+  // The head says who the menu belongs to — and on a folded rail it is the only place
+  // a sighted reader can read the address. why: docs/specification.md#the-page-shell
+  const head = `<div class="ui-dropdown__head">`
+    + (name ? `<b>${esc(name)}</b>` : '')
+    + (email ? `<span>${esc(email)}</span>` : '')
+    + `</div>`;
+  return `<div class="ui-app__user">${dropdown({
+    variant: 'menu',
+    portal: true,
+    direction: 'up',
+    triggerClass: 'ui-app__user-trigger',
+    triggerContent: readerFace(name, email, null),
+    panelClass: 'ui-app__user-panel',
+    header: head,
+    items: [{ label: 'Sign out', icon: 'logout', href: signOutHref, danger: true }],
+  })}</div>`;
 }
 // Unique-per-render suffix for the brand mark's clip id — the same reason
@@ -155,14 +220,17 @@ export function appShell(options = {}) {
     signOutHref = '',
     topbar,
     maxWidth,
+    collapsible,
+    collapsed,
   } = settle(options);
   const up = back ? backLink(back) : '';
+  // No footer slot: the nav is places to go, and the one thing that was in it —
+  // sign out — is in the reader's menu at the rail's foot.
   const rail = sidebarNav({
     sections: [{ label: navLabel, items: nav }],
     active,
     activeIs: up ? 'section' : 'page',
     ariaLabel: navLabel,
-    footer: signOutHref ? signOut(signOutHref) : '',
   });
   // The topbar already says the product word, so the rail head steps aside when there is
   // one. The word is the link's only text and the narrow rail folds it out of view, so
@@ -172,11 +240,22 @@ export function appShell(options = {}) {
   // A <div>, not an <aside>: <aside> is the `complementary` landmark, and this holds the
   // page's primary navigation and the signed-in reader. The <nav> inside it is already
   // the landmark that names the menu.
-  const grid = `<div class="ui-app">
+  // A fold needs the toggle that undoes it. `data-rail="auto"` marks a shell whose
+  // caller left the choice to the reader; wireShell() applies the stored one there.
+  const folded = collapsible && collapsed === true;
+  const auto = collapsible && collapsed === null ? ' data-rail="auto"' : '';
+  // The head band: the product's mark, and the rail's own control at the far end of
+  // the same line, under one rule. Either may be absent — a shell with a topbar says
+  // the word up there, and `collapsible: false` draws no toggle — so the band itself
+  // goes when both are.
+  const head = brand || collapsible
+    ? `<div class="ui-app__head">${brand}${collapsible ? railToggle(folded) : ''}</div>`
+    : '';
+  const grid = `<div class="ui-app${folded ? ' is-collapsed' : ''}"${auto}>
     <div class="ui-app__rail">
-      ${brand}
+      ${head}
       ${rail}
-      ${railUser(account)}
+      ${railUser(account, signOutHref)}
     </div>
     <main class="ui-app__main"${maxWidth ? ` style="--ui-app-main: ${maxWidth}"` : ''}>
       ${up || (crumbs.length ? breadcrumbs({ items: crumbs }) : '')}
@@ -188,6 +267,90 @@ export function appShell(options = {}) {
   return topbar ? `<div class="ui-app-page">${productTopbar(topbar)}${grid}</div>` : grid;
 }
+// ---- Behaviour -----------------------------------------------------------
+// One click listener per document, so a shell rendered after wiring folds too
+// and a frame is wired in its own document. wireShell(root, { persist: false })
+// keeps every shell under root out of the cookie, shells drawn there later
+// included; only `persist: true` on that root turns it back on.
+const _wiredDocs = new WeakSet();
+const _unpersisted = new WeakSet();
+// The toggle, addressed from the rail that owns it: the head band of a shell's own
+// rail and nowhere else, so a stray [data-rail-toggle] in the page body folds nothing.
+// The path is written once — the listener, the reflector and wireShell() all have to
+// mean the same control, and the head band put one more step between them.
+// why: docs/specification.md#the-page-shell
+const FOLD_PATH = '.ui-app__head > .ui-app__fold-row > [data-rail-toggle]';
+const RAIL_FOLD = `.ui-app__rail > ${FOLD_PATH}`;
+// Under an opted-out root? Steps out of a shadow root through its host.
+const optedOut = (node) => {
+  for (let n = node; n; n = n.parentNode || n.host) if (_unpersisted.has(n)) return true;
+  return false;
+};
+function setRail(app, collapsed) {
+  app.classList.toggle('is-collapsed', collapsed);
+  const rail = app.querySelector(':scope > .ui-app__rail');
+  if (!rail) return;
+  for (const btn of rail.querySelectorAll(`:scope > ${FOLD_PATH}`)) {
+    btn.setAttribute('aria-expanded', collapsed ? 'false' : 'true');
+    btn.setAttribute('aria-label', railName(collapsed));
+    const label = btn.querySelector('.ui-nav__label');
+    if (label) label.textContent = railName(collapsed);
+  }
+}
+function listen(doc) {
+  if (_wiredDocs.has(doc)) return;
+  _wiredDocs.add(doc);
+  doc.addEventListener('click', (e) => {
+    // A shell's own toggle only, in the head of its own rail: a stray
+    // [data-rail-toggle] in the page body folds nothing. composedPath() rather
+    // than target, so a shell inside an open shadow root is found. closest()
+    // rather than a chain of parents, which the head band made one link longer
+    // and which said nothing about what it was walking through.
+    const btn = e.composedPath().find((n) => n.nodeType === 1 && n.matches(RAIL_FOLD));
+    const app = btn && btn.closest('.ui-app');
+    if (!app) return;
+    const next = !app.classList.contains('is-collapsed');
+    setRail(app, next);
+    if (!optedOut(app)) {
+      try {
+        doc.cookie = `${RAIL_COOKIE}=${next ? 'collapsed' : 'expanded'}; path=/; `
+          + `max-age=${RAIL_MAX_AGE}; SameSite=Lax`;
+      } catch (err) { /* a sandboxed frame: the fold works, nothing is kept */ }
+    }
+    // A document with no window (DOMParser, createHTMLDocument) has no CustomEvent to send.
+    const view = doc.defaultView;
+    if (view) {
+      app.dispatchEvent(new view.CustomEvent('ui-rail', { bubbles: true, composed: true, detail: { collapsed: next } }));
+    }
+  });
+}
+export function wireShell(root = document, { persist } = {}) {
+  wireNav(root);
+  // The reader's menu is a dropdown() like any other, so it is wired like any
+  // other. Idempotent, and a shell with no account draws none to find.
+  wireDropdown(root);
+  const doc = root.nodeType === 9 ? root : root.ownerDocument;
+  listen(doc);
+  if (persist === false) _unpersisted.add(root);
+  else if (persist === true) _unpersisted.delete(root);
+  const saved = railCollapsed(cookieOf(doc));
+  const apps = [...root.querySelectorAll('.ui-app')];
+  if (root.matches && root.matches('.ui-app')) apps.push(root);
+  for (const app of apps) {
+    if (!app.querySelector(`:scope > ${RAIL_FOLD}`)) continue;
+    // The stored choice goes to a shell whose caller left it to the reader — a
+    // paint late, where a server drew it without reading the cookie. Any other
+    // shell keeps what it was drawn with, and gets its rows' titles if folded.
+    const auto = saved != null && !optedOut(app) && app.getAttribute('data-rail') === 'auto';
+    setRail(app, auto ? saved : app.classList.contains('is-collapsed'));
+  }
+}
 // The /account preset: appShell() with the topbar switched on, and the old
 // `cap` + `crumb` strings folded into the trail the caller now owns.
 export function accountShell({
@@ -203,6 +366,8 @@ export function accountShell({
   sub = '',
   body = '',
   signOutHref = '#logout',
+  collapsible = true,
+  collapsed,
 } = {}) {
   // The same normaliser appShell() runs, called once here so the rail and the
   // topbar menu are handed one list rather than two readings of `nav`.
@@ -222,6 +387,8 @@ export function accountShell({
     body,
     account,
     signOutHref,
+    collapsible,
+    collapsed,
     topbar: {
       word,
       view: 'text',