@apliteni/apliteni-ui 0.32.0 → 0.33.1

package/README.md

@@ -28,11 +28,13 @@ They use the vanilla kit's `.ui-*` classes and tokens.
 **Which one:** does the surface hold meaningful client state? No → the HTML-string
 factories below. Yes → the [React components](#react-components-stateful-surfaces).
 
-Either layer follows the same UI rules — which component to reach for, the states it
-owes, how colour and wording work. They live in the **Guidelines** section of Storybook,
-which opens on
-[an overview of the five pages](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview)
-and what the kit does and does not yet meet. Worth reading before you design a screen.
+Either layer follows the same UI rules — what one page may hold, which component to reach
+for, the states it owes, how colour and wording work. They live in the **Guidelines** section
+of Storybook, which opens on
+[an overview of every page](https://ui.apli.tech/storybook/?path=/story/guidelines-overview--overview)
+and what the kit does and does not yet meet.
+[The page](https://ui.apli.tech/storybook/?path=/story/guidelines-the-page--the-page) is the one
+to read before you design a screen: the limits one page keeps, whatever it is about.
 
 ## Install
 
@@ -78,7 +80,7 @@ The whole `/account` layout (topbar + sticky sidebar + page body) ships as one
 factory, so every product renders the same account shell instead of re-building it:
 
 ```js
-import { accountShell, card, switchToggle, wireTopbar } from '@apliteni/apliteni-ui';
+import { accountShell, card, switchToggle, wireTopbar, wireShell } from '@apliteni/apliteni-ui';
 
 el.innerHTML = accountShell({
   word: 'Strategy',                              // the product word in the topbar
@@ -89,8 +91,10 @@ el.innerHTML = accountShell({
   body: card({ title: 'Appearance', body: switchToggle({ label: 'Reduce motion' }) }),
 });
 wireTopbar(el);                                  // menus, theme toggle, segmented controls
+wireShell(el);                                   // the toggle that folds the rail, the reader's menu, the nav's groups
 
 // Custom sidebar nav? pass `nav: [['prefs','gear','Preferences'], ['billing','wallet','Billing']]`
+// A page that will never call wireShell()? pass `collapsible: false` and no toggle is drawn
 ```
 
 Server-rendered apps that inline CSS (like the strategy portal) import the stylesheet

package/package.json

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

package/react/dist/index.css

@@ -44,7 +44,8 @@
 .rx-modal {
   width: min(480px, 92vw);
   background: var(--bg-elevated);
-  border: 1px solid var(--border);
+  border: 1px solid var(--border-strong);
+  box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop);
   border-radius: var(--radius-xl);
   overflow: hidden;
   transform: translateY(8px);

package/src/components/dropdown.js

@@ -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

@@ -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/nav.js

@@ -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/shell.js

@@ -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',

package/src/components/success.js

@@ -64,6 +64,7 @@ function countdownEl({ seconds = 5, label = 'Redirecting' } = {}) {
 // changing one never moves the other.
 export function success({
   layout = 'hero',          // 'hero' | 'split' | 'compact'
+  level,                    // heading level of the title; see the note below
   backdrop = 'aurora',      // 'aurora' | 'glow' | 'flat'
   eyebrow = '',
   title = 'All done',
@@ -76,6 +77,16 @@ export function success({
   const cls = ['ui-sx', `ui-sx--${layout}`, `ui-sx--bd-${backdrop}`, confetti && 'ui-sx--confetti', className]
     .filter(Boolean).join(' ');
 
+  // The title's rank follows the layout, because the layout is the question
+  // "how much of the screen does this own": hero and split ARE the page a flow
+  // lands on, so their title is its h1; compact sits beside other content and
+  // takes h2. It was an h3 either way, which left a page whose whole content is
+  // a success() with no h1 at all — the fault Guidelines / The page names.
+  // A caller who knows better passes `level`. The look is the class's.
+  // why: docs/specification.md#the-page
+  const rank = [1, 2, 3, 4, 5, 6].includes(Number(level)) ? Number(level) : (layout === 'compact' ? 2 : 1);
+  const h = `h${rank}`;
+
   const bd = backdrop === 'aurora'
     ? `<div class="ui-sx__aurora" aria-hidden="true">
         <span class="ui-sx__glow ui-sx__glow--a"></span>
@@ -99,7 +110,7 @@ export function success({
     <div class="ui-sx__visual">${successCheck()}</div>
     <div class="ui-sx__content">
       ${eyebrowEl}
-      <h3 class="ui-sx__title">${esc(title)}</h3>
+      <${h} class="ui-sx__title">${esc(title)}</${h}>
       ${bodyEl}
       ${actionsEl}
       ${countEl}

package/src/styles/callout.css

@@ -44,6 +44,10 @@
   width: 100%;
   max-width: var(--panel-md);
   overflow: hidden; /* clips the timer bar + left marker to the rounded corners */
+  /* A toast floats. It carries a status rather than the neutral hairline, so each
+     style below re-points --elev-edge at its own tint and leaves the outer line
+     where it already drew it. why: docs/specification.md#elevation */
+  box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop);
   animation: ui-toast-in var(--dur-med) var(--ease-out) both;
 }
 
@@ -115,6 +119,7 @@
 .ui-toast--soft {
   background: var(--toast-glow);
   border: 1px solid color-mix(in srgb, var(--toast-accent) 22%, transparent);
+  --elev-edge: color-mix(in srgb, var(--toast-accent) 11%, transparent);
 }
 
 /* style: solid — the status at fill strength, inked with the pole opposite it.
@@ -128,6 +133,8 @@
   --toast-ink: var(--signal-solid-ink);
   background: var(--toast-solid);
   color: var(--toast-ink);
+  /* No inner line: a solid toast has no outer one either. It keeps the drop. */
+  --elev-edge: transparent;
 }
 .ui-toast--solid .ui-toast__title { color: var(--toast-ink); }
 /* The body copy is the quieter of the two, but it stays quiet by dilution the
@@ -147,7 +154,7 @@
 .ui-toast--solid .ui-toast__timer { background: color-mix(in srgb, var(--toast-ink) 55%, transparent); }
 
 /* style: outline — elevated card with a status-tinted border */
-.ui-toast--outline { background: var(--bg-elevated); border: 1px solid color-mix(in srgb, var(--toast-accent) 40%, transparent); }
+.ui-toast--outline { background: var(--bg-elevated); border: 1px solid color-mix(in srgb, var(--toast-accent) 40%, transparent); --elev-edge: color-mix(in srgb, var(--toast-accent) 20%, transparent); }
 
 /* compact — single line, no body text */
 .ui-toast--compact { align-items: center; padding-top: 10px; padding-bottom: 10px; }