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

@apliteni/apliteni-ui 0.32.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 (11) hide show

package/README.md +10 -6
package/package.json +1 -1
package/src/components/dropdown.js +77 -30
package/src/components/footer.js +6 -1
package/src/components/nav.js +4 -3
package/src/components/shell.js +197 -30
package/src/components/success.js +12 -1
package/src/styles/dropdown.css +18 -9
package/src/styles/layout.css +201 -55
package/src/styles/nav.css +88 -10
package/src/styles/topbar.css +28 -2

package/README.md CHANGED Viewed

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

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

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

package/src/components/success.js CHANGED Viewed

@@ -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/dropdown.css CHANGED Viewed

@@ -65,6 +65,10 @@
   padding: 6px;
   opacity: 0;
   visibility: hidden;
+  /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a
+     box that is drawn is a box that is hit. The open rules take this back.
+     why: docs/specification.md#the-dropdown-panel */
+  pointer-events: none;
   transform: translateY(-6px);
   transition:
     opacity var(--dur-med) var(--ease),
@@ -89,7 +93,13 @@
   transform: translateY(6px);
 }
-.ui-dropdown.open .ui-dropdown__panel { opacity: 1; visibility: visible; transform: translateY(0); }
+.ui-dropdown.open .ui-dropdown__panel { opacity: 1; visibility: visible; pointer-events: auto; transform: translateY(0); }
+/* Open, the panel is visible AT ONCE: `visibility` is off the list, so it is not
+   held at `hidden` for the frame a key opens the panel in — the frame the focus
+   call happens in. Closing still fades on every property it always did.
+   why: docs/specification.md#the-dropdown-panel */
+.ui-dropdown.open .ui-dropdown__panel,
+.ui-dropdown__panel--portal.is-open { transition-property: opacity, transform; }
 /* Portalled panel — wireDropdown() moves it onto <body>, clear of every
    ancestor's overflow and every ancestor's stacking context. The descendant
@@ -101,7 +111,7 @@
   position: fixed;
   top: auto; right: auto; bottom: auto; left: auto;
 }
-.ui-dropdown__panel--portal.is-open { opacity: 1; visibility: visible; transform: translateY(0); }
+.ui-dropdown__panel--portal.is-open { opacity: 1; visibility: visible; pointer-events: auto; transform: translateY(0); }
 /* Item row — [icon] [main: label + desc] [badge] [tick]. A row is a <div>, an
    <a href> or a <button>: `is-selected` and __tick below mean a row gets
@@ -160,7 +170,7 @@
 }
 .ui-dropdown__badge.is-live { color: var(--chip-success-ink); background: var(--chip-success-fill); }
 /* The accent counter keeps the badge's flat surface and changes only the ink — the shape
-   src/styles/nav.css:128 `.ui-nav__item.is-active .ui-nav__badge.is-accent` already holds.
+   src/styles/nav.css:163 `.ui-nav__item.is-active .ui-nav__badge.is-accent` already holds.
    The accent wash goes on a base surface, never a raised one, and #295 made this panel a
    raised one. why: docs/specification.md#elevation */
 .ui-dropdown__badge.is-accent { color: var(--accent); background: var(--surface-3); }
@@ -169,8 +179,12 @@
 .ui-dropdown__item.is-disabled { color: var(--disabled-ink); cursor: not-allowed; pointer-events: none; }
 .ui-dropdown__item.is-disabled .ui-dropdown__label,
 .ui-dropdown__item.is-disabled .ui-dropdown__desc { color: inherit; }
+/* Quiet at rest, --pink on the way to being pressed. Both states, not hover alone:
+   the ring says where the reader is, not that this row ends something.
+   why: docs/specification.md#a-dropdown-row-is-a-div-a-link-or-a-button */
 .ui-dropdown__item.is-danger .ui-dropdown__label { color: var(--muted); }
-.ui-dropdown__item.is-danger:hover .ui-dropdown__label { color: var(--pink); }
+.ui-dropdown__item.is-danger:hover .ui-dropdown__label,
+.ui-dropdown__item.is-danger:focus-visible .ui-dropdown__label { color: var(--pink); }
 /* Grouped sections. `~` and :not([hidden]), because `+` counts a group a search
    query has hidden and drew the divider above the first group left showing. */
@@ -200,11 +214,6 @@
    variant emits, so the plain dropdown renders as it did.
    why: docs/specification.md#a-dropdown-with-a-search-field */
 .ui-dropdown__panel--search { min-width: 280px; }
-/* Open, the panel is visible at once instead of at the first step of the
-   `visibility` transition, because a browser will not focus a field in a box
-   that is still `hidden` and opening puts focus in the field. Closing still fades. */
-.ui-dropdown.open .ui-dropdown__panel--search,
-.ui-dropdown__panel--search.is-open { transition-property: opacity, transform; }
 .ui-dropdown__search { position: relative; display: flex; align-items: center; margin-bottom: 6px; }
 .ui-dropdown__search-ic {

package/src/styles/layout.css CHANGED Viewed

@@ -16,6 +16,11 @@
   background: var(--bg);
   color: var(--text);
   font-family: var(--font-sans);
+  /* The rail's width, and the one property the fold moves: the nav's own column
+     plus the inset either side plus the rule, so the shell has no geometry of its
+     own to drift from the rows inside it. why: docs/specification.md#the-page-shell */
+  --ui-rail-rule: 1px;
+  --ui-rail-w: calc(var(--ui-nav-col) + 2 * var(--space-4) + var(--ui-rail-rule));
 }
 /* With a topbar above it, the shell starts below one. 52px is .topbar's height
    in topbar.css; the topbar sticks so the rail below it can too. */
@@ -33,21 +38,27 @@
   flex-direction: column;
   gap: var(--space-5);
   padding: var(--space-5) var(--space-4);
-  border-right: 1px solid var(--border);
+  border-right: var(--ui-rail-rule) solid var(--border);
   background: var(--surface-2);
   position: sticky;
   top: var(--ui-app-top, 0px);
   height: calc(100vh - var(--ui-app-top, 0px));
+  width: var(--ui-rail-w);
+  /* hidden across, auto down: the fold clips what leaves the screen rather than
+     laying it out again. Two longhands, not the shorthand — the gates' CSS engine
+     does not read the pair. why: docs/specification.md#the-page-shell */
+  overflow-x: hidden;
   overflow-y: auto;
+  transition: width var(--dur-med) var(--ease);
 }
+/* Each block of the rail keeps the open column while the box closes over it. The
+   nav declares its own; these are the two that are not the nav. */
+.ui-app__head,
+.ui-app__user { width: var(--ui-nav-col); flex: none; }
 /* The rail's hover WAS --surface-2, so moving the rail onto it would have made
-   hovering a row do nothing. Scoped, so a sidebarNav() anywhere else is
-   untouched — and the destructive row is left out, because this rule ties with
-   nav.css's danger wash on specificity and wins on source order alone. Sign out
-   was quietly losing the --pink wash the guideline page cites nav.css for. The
-   current row is left out for the same reason: this rule outranks nav.css's
-   active hover, and painting --surface-3 over a row already resting on it is
-   what made the row you are standing on the one row that ignores the pointer. */
+   hovering a row do nothing. The danger row and the current row are left out by
+   name, because this rule outranks the states nav.css writes for them.
+   why: CONTRIBUTING.md#a-rule-that-outranks-another-cancels-every-state-that-other-one-writes */
 .ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface-3); }
 .ui-app__brand {
   display: flex;
@@ -55,6 +66,10 @@
   gap: var(--space-2);
   padding: 2px 6px;
   text-decoration: none;
+  /* The lockup leaves on the words' clock, `visibility` with it so the link leaves
+     the tab order — `linear`, as every discrete property in the kit is.
+     why: docs/specification.md#the-page-shell */
+  transition: opacity var(--dur-fast) var(--ease), visibility var(--dur-fast) linear;
   /* display: brand — the rail's lockup is the same mark topbar.css sets, and the
      two have to be the same face or the shell reads as two products. */
   font-family: var(--font-display);
@@ -66,11 +81,23 @@
 .ui-app .ui-app__brand { color: var(--strong); }
 .ui-app__brand svg { display: block; flex: none; }
+/* The head band: the product's mark, and the rail's own control at the far end of
+   the same line. `min-width: 0` so a long word shrinks the lockup rather than pushing
+   the control off the band. why: docs/specification.md#the-page-shell */
+.ui-app__head {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding-bottom: var(--space-3);
+  border-bottom: 1px solid var(--border);
+}
+.ui-app__head > .ui-app__brand { min-width: 0; }
 /* The nav grows, so the reader block below it pins to the bottom of a full-height
-   rail instead of hugging the last nav row, and the nav's own footer — sign out —
-   sits directly above it. */
+   rail instead of hugging the last nav row. The nav's own footer slot is unused —
+   sign out is in the reader's menu, because it ends a session rather than going
+   anywhere — so the rail's foot is the account block alone. */
 .ui-app__rail .ui-nav--side { flex: 1 1 auto; }
-.ui-app__rail .ui-nav__foot { margin-top: auto; }
 /* Which row is current is structural here, not chromatic: the resting glyphs
    step down so the current one is the brightest whatever --accent is doing, and
@@ -78,30 +105,37 @@
    smallest of three weak signals doing the most work, so it grows with the row. */
 /* Re-tuned at #295, which took the light rail down a step with the page. Below 720px
    the glyph is the whole row, so it is held at text grade rather than at 1.4.11's bar —
-   stories/apps/shell-states.test.js:427 `a resting glyph is dimmer but still legible`. */
+   stories/apps/shell-states.test.js:1340 `a resting glyph is dimmer but still legible`. */
 .ui-app__rail .ui-nav__ic svg { opacity: 0.66; }
 .ui-app__rail .ui-nav__item.is-active .ui-nav__ic svg,
 .ui-app__rail .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: currentColor; } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
 .ui-app__rail .ui-nav__item.is-active::before { width: 3px; height: 62%; }
-/* Sign out is a navigation row and rests like one. The danger intent is the
-   step nav.css writes for it, which a resting --muted was pre-empting — it made
-   the last row of the rail the quietest thing in it. Both of nav.css's danger
-   states are named here, not hover alone: this rule outranks them, so a state
-   it forgets is a state it silently cancels. */
+/* A destructive row of the rail is a navigation row and rests like one; the danger
+   intent is the step nav.css writes for it. Both of nav.css's danger states are
+   named, not hover alone.
+   why: CONTRIBUTING.md#a-rule-that-outranks-another-cancels-every-state-that-other-one-writes */
 .ui-app__rail .ui-nav__item.is-danger:not(:hover):not(:focus-visible) { color: var(--text); }
-/* One rule closes the rail, not two twenty pixels apart: the nav's own footer
-   keeps its hairline and the reader block is separated by space alone — it has
-   an avatar and a weight change already. */
+/* One rule closes the rail, and it is this one: the nav's footer slot is empty now
+   that sign out is in the menu this block opens, so the hairline that fenced sign
+   out off moved down onto the block it was fencing. Two of them twenty pixels apart
+   read as a third region of the rail rather than as its foot. */
 .ui-app__user {
   display: flex;
   align-items: center;
   gap: var(--space-2);
-  padding: var(--space-5) var(--space-1) 0;
+  padding-top: var(--space-5);
+  border-top: 1px solid var(--border);
 }
+/* The avatar is the reader block's own glyph, so half the difference between the
+   glyph column and itself is the inset that centres it on the line every glyph above
+   it stands on. The arithmetic and not the 5.5 it comes to: both numbers are declared
+   elsewhere. why: docs/specification.md#the-page-shell */
+.ui-app { --ui-app-av: 30px; }
 .ui-app__av {
-  width: 30px; height: 30px; flex: none;
+  width: var(--ui-app-av); height: var(--ui-app-av); flex: none;
+  margin-inline-start: calc((var(--ui-nav-strip) - var(--ui-app-av)) / 2);
   border-radius: var(--radius-pill);
   background: var(--surface-3);
   color: var(--strong);
@@ -115,6 +149,112 @@
    the rail column is max-content, so a long one widens the rail instead. */
 .ui-app__who span { display: block; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+/* -- the reader's menu ---------------------------------------------------- */
+/* The account block is a dropdown() trigger, so it takes the rail's own row skin
+   rather than the dropdown's pill — in place it is the last row of the rail. The
+   dropdown's own ring is left standing. why: docs/specification.md#the-page-shell */
+.ui-app__user .ui-dropdown { width: 100%; }
+.ui-app .ui-app__user-trigger {
+  width: 100%;
+  gap: var(--space-2);
+  /* As tall as the mark inside it plus its own padding — 30 + 4 + 4, written out
+     rather than as the calc() it comes from, and held to that arithmetic by
+     stories/apps/shell-states.test.js.
+     why: CONTRIBUTING.md#an-unresolved-var-measures-nothing-and-reports-green */
+  min-height: 38px;
+  padding: var(--space-1) 0;
+  border: 0;
+  border-radius: var(--radius-sm);
+  background: none;
+  color: var(--text);
+  font-size: inherit;
+  font-weight: inherit;
+  letter-spacing: normal;
+}
+.ui-app .ui-app__user-trigger:hover { background: var(--surface-3); }
+.ui-app__user-trigger .ui-app__who { flex: 1 1 auto; text-align: left; }
+/* The panel is portalled onto <body>, so nothing here may hang off .ui-app: by the
+   time it is open it is no longer inside the rail that drew it.
+   why: docs/specification.md#the-dropdown-panel */
+.ui-app__user-panel .ui-dropdown__head { display: flex; flex-direction: column; gap: 2px; }
+.ui-app__user-panel .ui-dropdown__head b { display: block; color: var(--strong); font-size: 12.5px; font-weight: var(--weight-semibold); }
+/* The address wraps rather than truncating: nothing bounds this line, so
+   `text-overflow` would have nothing to fire against — the inert pair
+   .ui-app__who's own comment warns about. `anywhere` keeps an address with no
+   break in it from widening the panel instead. */
+.ui-app__user-panel .ui-dropdown__head span { display: block; color: var(--muted); font-size: 11px; overflow-wrap: anywhere; }
+/* The toggle's cell, at the far end of the brand row: the auto margin puts it there
+   with or without a wordmark beside it, and the offset below rides it back onto the
+   glyph column as the rail closes. `position: relative` and not a transform, because
+   the chip inside is `position: fixed`. why: docs/specification.md#the-page-shell */
+.ui-app__fold-row {
+  flex: none;
+  margin-inline-start: auto;
+  position: relative;
+  inset-inline-start: 0;
+  transition: inset-inline-start var(--dur-med) var(--ease);
+}
+/* One box on the glyph column at both widths — --ui-nav-strip, the width nav.css
+   derives the closed rail from. `gap: 0` leaves that column the whole of the
+   content box, so the label below is squeezed to nothing until the chip rule lifts
+   it out. why: docs/specification.md#the-page-shell */
+.ui-app__fold { width: var(--ui-nav-strip); gap: 0; }
+/* The chip rule lifts the name out of the flow, and a 17px glyph is shorter than
+   the line the name occupied — so the button lost 0.39px on hover and moved every
+   row under it. The glyph box carries the line instead, in both states.
+   why: docs/specification.md#the-page-shell */
+.ui-app__fold .ui-nav__ic { height: 1lh; }
+.ui-app .ui-app__fold { color: var(--dim); }
+.ui-app .ui-app__fold:hover,
+.ui-app .ui-app__fold:focus-visible { color: var(--strong); }
+/* The width's own clock, not the words', so the mark and the closing edge arrive
+   together; no `!important`, so the reduced-motion net still takes it. 6 is not a
+   number: shell.js draws the frame 3..21 and the seam at 9, and 6 mirrors it about
+   the centre. why: docs/specification.md#the-page-shell */
+.ui-app__fold .ui-app__fold-seam { transition: transform var(--dur-med) var(--ease); }
+.ui-app.is-collapsed .ui-app__fold .ui-app__fold-seam { transform: translateX(6px); }
+/* -- The collapsed rail --------------------------------------------------- */
+/* Each rule here has its twin in the 720px block below; nothing lays a row out
+   again. why: docs/specification.md#the-page-shell */
+.ui-app.is-collapsed { --ui-rail-w: calc(var(--ui-nav-strip) + 2 * var(--space-4) + var(--ui-rail-rule)); }
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__cap,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__label,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__badge,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__caret,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-app__who,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-dropdown__chevron,
+:where(.ui-app.is-collapsed) .ui-app__brand span { opacity: 0; pointer-events: none; }
+/* The toggle rides onto the glyph column — the two widths' own difference — and the
+   lockup goes whole, since that column is where its mark stood. The mark may only go
+   where the control arrives: below 720px the toggle is not drawn, so the 720px block
+   gives the lockup back rather than leaving an empty band with a hairline under it.
+   why: docs/specification.md#the-page-shell */
+:where(.ui-app.is-collapsed) .ui-app__fold-row { inset-inline-start: calc(var(--ui-nav-strip) - var(--ui-nav-col)); }
+:where(.ui-app.is-collapsed) .ui-app__brand { opacity: 0; visibility: hidden; pointer-events: none; }
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__sub { margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0; }
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
+/* The label IS the chip. `fixed` is the fallback placement, out of the rail's own
+   clip; the @supports branch below pins it to the row and is the only one that
+   survives a scroll. The toggle's selector is unscoped, because it is wordless at
+   both widths. why: docs/specification.md#the-page-shell */
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
+:where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who,
+.ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border); border-radius: var(--radius-xs); background: var(--surface-3); color: var(--strong); box-shadow: var(--shadow-md); opacity: 1; pointer-events: none; }
+@supports (anchor-name: --a) and (anchor-scope: --a) {
+  .ui-app.is-collapsed,
+  .ui-app:has(.ui-app__fold) { anchor-scope: --ui-rail; }
+  :where(.ui-app.is-collapsed) .ui-app__rail,
+  .ui-app__rail:has(.ui-app__fold) { anchor-name: --ui-rail; }
+  :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item,
+  :where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger,
+  .ui-app__rail .ui-app__fold { anchor-name: --ui-rail-row; anchor-scope: --ui-rail-row; }
+  :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
+  :where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who,
+  .ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position-anchor: --ui-rail-row; left: calc(anchor(--ui-rail right) + var(--space-2)); top: anchor(top); bottom: anchor(bottom); align-self: center; margin-block: 0; }
+}
 /* The reading column centres in the track it is given — without width: 100% it
    was hugging the rail, 519px of dead background on the right at 1728px wide.
    The width is what keeps the auto margins honest: an auto inline margin takes
@@ -166,45 +306,51 @@
 .ui-toolbar > .ui-input-group { flex: 1 1 6rem; min-width: 0; }
 /* -- The narrow rail ------------------------------------------------------ */
-/* Below this width the rail folds to an icon strip instead of disappearing.
-   sidebarNav() names every row at every width, so folding the label out of view
-   costs a screen reader nothing. Scoped to the shell's own rail — a sidebarNav()
-   somewhere else keeps its labels. The 44px floor is the touch target, and the
-   column is that floor plus the rail's own padding and border — measured, not
-   guessed. Nothing here resizes the glyph: an icon-sizing rule inside a media
-   query is one src/styles/icon-size.test.js cannot measure, and it says so. */
+/* Below this width the rail folds to the icon strip instead of disappearing, and
+   it is the fold the reader's own press makes — every rule here has its twin
+   above. Scoped to the shell's own rail; a sidebarNav() elsewhere keeps its
+   labels. Nothing here resizes a glyph: an icon-sizing rule inside a media query
+   is one src/styles/icon-size.test.js cannot measure, and it says so. */
 @media (max-width: 720px) {
-  .ui-app { grid-template-columns: 58px 1fr; }
-  .ui-app__rail { padding: var(--space-3) 6px; gap: var(--space-3); }
-  .ui-app__rail .ui-nav--side { width: auto; }
+  .ui-app { --ui-rail-w: calc(var(--ui-nav-strip) + 2 * var(--space-4) + var(--ui-rail-rule)); }
+  /* The strip is the only layout this width has, so there is nothing to fold. */
+  .ui-app__rail .ui-app__fold-row { display: none; }
+  /* …and with it the band, when the band has nothing else in it: a head with no
+     wordmark is the toggle alone, so at this width it is padding and a hairline
+     drawn over nothing. The reader's fold cannot take this rule — there the toggle
+     IS drawn. why: docs/specification.md#the-page-shell */
+  .ui-app__head:not(:has(> .ui-app__brand)) { display: none; }
+  /* And where the band does hold the mark, the mark stays — at this width the press
+     that folded the rail on a desktop still reads out of the cookie, and the control
+     that would undo it is the one above. A head band faded to nothing here is an empty
+     41px box over a rule, with no way home. The reader's fold cannot take this rule —
+     there the toggle lands on the column the mark gives up.
+     why: docs/specification.md#the-page-shell */
+  .ui-app__brand { opacity: 1; visibility: visible; pointer-events: auto; }
   .ui-app__rail .ui-nav__cap,
   .ui-app__rail .ui-nav__label,
   .ui-app__rail .ui-nav__badge,
   .ui-app__rail .ui-nav__caret,
   .ui-app__rail .ui-app__who,
-  .ui-app__brand span { display: none; }
-  .ui-app__rail .ui-nav__item { justify-content: center; gap: 0; padding: 0; min-height: 44px; }
-  .ui-app__rail .ui-nav__item.is-active::before { left: 3px; }
-  .ui-app__rail .ui-nav__foot { padding-top: var(--space-2); }
-  .ui-app__brand { justify-content: center; padding: 2px 0; }
-  .ui-app__user { justify-content: center; padding-left: 0; padding-right: 0; }
-  /* A group's children are rail rows at this width too. The nested list is NOT
-     folded away: wireNav() toggles the `hidden` attribute and nothing else, so
-     a display:none here left the toggle announcing aria-expanded over a list it
-     could not reach — and took the row carrying aria-current with it. What goes
-     instead is the indent and its guide hairline; a 46px column has no room. */
-  .ui-app__rail .ui-nav__sub { margin: 0; padding-left: 0; border-left: 0; }
-  .ui-app__rail .ui-nav__item--sub.is-active::before { left: 3px; }
-  /* sidebarNav() takes `icon` as optional at every level, and the glyph is the
-     whole of a row on screen here — so a row without one, at any level, would be
-     a blank 44px target. It gets a dot in the row's own ink instead; the
-     aria-label names it either way. */
-  .ui-app__rail .ui-nav__item:not(:has(.ui-nav__ic))::after {
-    content: "";
-    width: 5px; height: 5px;
-    border-radius: 50%;
-    background: currentColor;
-    opacity: 0.62;
+  .ui-app__rail .ui-dropdown__chevron,
+  .ui-app__brand span { opacity: 0; pointer-events: none; }
+  .ui-app__rail .ui-nav__sub { margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0; }
+  .ui-app__rail .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
+  /* The one line of this block that is deliberately NOT the reader's fold: a finger
+     is the only pointer this width has, so a row and the account block are held to
+     44px. Neither floor can spread to the press, where growing the box is the one
+     thing the travel promises nothing does. why: docs/specification.md#the-page-shell */
+  .ui-app__rail .ui-nav__item,
+  .ui-app__rail .ui-app__user-trigger { min-height: 44px; }
+  .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
+  .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border); border-radius: var(--radius-xs); background: var(--surface-3); color: var(--strong); box-shadow: var(--shadow-md); opacity: 1; pointer-events: none; }
+  @supports (anchor-name: --a) and (anchor-scope: --a) {
+    .ui-app { anchor-scope: --ui-rail; }
+    .ui-app__rail { anchor-name: --ui-rail; }
+    .ui-app__rail .ui-nav__item,
+    .ui-app__rail .ui-app__user-trigger { anchor-name: --ui-rail-row; anchor-scope: --ui-rail-row; }
+    .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
+    .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position-anchor: --ui-rail-row; left: calc(anchor(--ui-rail right) + var(--space-2)); top: anchor(top); bottom: anchor(bottom); align-self: center; margin-block: 0; }
   }
   .ui-app__main { padding: 28px var(--space-4) 56px; }
   .ui-app__main h1 { font-size: 25px; }

package/src/styles/nav.css CHANGED Viewed

@@ -9,12 +9,32 @@
 .ui-nav :where(ul, ol) { list-style: none; margin: 0; padding: 0; } /* floor, not ceiling */
 /* -- Sidebar rail -------------------------------------------------------- */
+/* The rail's two widths, and the one place they are written. --ui-nav-col is the
+   open column. --ui-nav-strip is twice a row's own glyph centre — the row's
+   padding plus half a glyph — so a strip that wide has the glyph standing in the
+   middle of it, exactly where it stood in the open rail. That is what lets the
+   fold animate: the column keeps --ui-nav-col and is clipped to the strip, so
+   the width travels and nothing inside it is laid out again. layout.css adds the
+   shell rail's own inset to both. stories/apps/shell-states.test.js derives the
+   strip from the resolved cascade and refuses a number that has drifted from it.
+   Declared for the shell as well as the nav, because the shell's rail is this
+   nav with an inset around it, and two copies of 41 is the drift itself. */
+.ui-nav--side,
+.ui-app { --ui-nav-col: 216px; --ui-nav-strip: 41px; }
 .ui-nav--side {
   display: flex;
   flex-direction: column;
   gap: 4px;
-  width: 216px;
+  width: var(--ui-nav-col);
+  /* The width is the only property the fold travels. Nothing is clipped here:
+     inside the shell it is the rail that clips, and a clip of its own would have
+     been a second scroll box cutting the rows off at the rail's height. */
+  transition: width var(--dur-med) var(--ease);
 }
+/* Every block keeps the open column while the nav clips to the strip. Without
+   this each one stretches to whatever the nav is wide and every row inside it is
+   laid out again on each frame of the fold. */
+.ui-nav--side > * { width: var(--ui-nav-col); flex: none; }
 .ui-nav__section + .ui-nav__section { margin-top: 14px; }
 .ui-nav__list { display: flex; flex-direction: column; gap: 2px; }
 .ui-nav__cap {
@@ -23,6 +43,9 @@
   font-weight: var(--weight-medium);
   color: var(--muted);
   padding: 4px 12px 8px;
+  /* Goes on the labels' clock — a section heading is words, and the fold takes
+     every word on the rail together. */
+  transition: opacity var(--dur-fast) var(--ease);
 }
 /* Item row — link, group toggle, and leaf share the same skin */
@@ -72,7 +95,15 @@
 .ui-nav__ic svg { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.2; opacity: 0.72; }
 .ui-nav__item.is-active .ui-nav__ic svg,
 .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: var(--accent); } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
-.ui-nav__label { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.ui-nav__label {
+  flex: 1 1 auto; min-width: 0;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  /* The words go before the closing edge reaches them, which is most of why the
+     fold is worth animating — a label cut through by that edge reads as the rail
+     eating it. --dur-fast against the width's --dur-med, as the reference times
+     its own. */
+  transition: opacity var(--dur-fast) var(--ease);
+}
 /* Destructive row (sign out, revoke). Quiet at rest, --pink once a pointer or
    the keyboard reaches it — as .ui-btn--danger and .ui-dropdown__item do. */
@@ -111,6 +142,10 @@
   line-height: 1;
   background: var(--surface-3);
   color: var(--dim);
+  /* The count fades with the words. It is never lost: sidebarNav() spells it
+     into the row's aria-label, so "Pending 3" is what a reader hears at either
+     width. */
+  transition: opacity var(--dur-fast) var(--ease);
 }
 .ui-nav__badge.is-accent { background: var(--glow-purple); color: var(--accent); }
 .ui-nav__badge.is-live { background: var(--chip-success-fill); color: var(--chip-success-ink); }
@@ -135,7 +170,7 @@
   border-right: 1.6px solid var(--muted);
   border-bottom: 1.6px solid var(--muted);
   transform: rotate(-45deg);
-  transition: transform var(--dur-fast) var(--ease);
+  transition: transform var(--dur-fast) var(--ease), opacity var(--dur-fast) var(--ease);
 }
 .ui-nav__group.is-open > .ui-nav__toggle .ui-nav__caret { transform: rotate(45deg); }
 .ui-nav__sub {
@@ -164,16 +199,59 @@
 /* Footer slot (divider + trailing links, e.g. sign-out) */
 .ui-nav__foot { margin-top: 12px; padding-top: 10px; border-top: 1px solid var(--border); }
-/* Collapsed (icon-only) rail */
-.ui-nav--side.is-collapsed { width: 60px; align-items: stretch; }
+/* A row with no glyph, on a rail folded to its glyphs, would be a blank target.
+   It gets a dot on the glyph column instead — out of flow, so the open rail's
+   labels stay where they are, and resting at nothing, so what the fold does is
+   raise it rather than conjure it. 18px is the row's own 12px padding plus half
+   a 17px glyph less half the dot: the column the glyph beside it stands on.
+   sidebarNav() takes `icon` as optional at every level, sub rows included. */
+.ui-nav--side .ui-nav__item:not(:has(.ui-nav__ic))::after {
+  content: "";
+  position: absolute;
+  left: 18px; top: 50%;
+  width: 5px; height: 5px;
+  margin-top: -2.5px;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0;
+  transition: opacity var(--dur-fast) var(--ease);
+}
+/* The nested list's indent, which the strip has no room for. It travels with the
+   width rather than vanishing under it: the guide hairline thins to nothing and
+   the children walk back onto the glyph column their parent stands on. */
+.ui-nav__sub {
+  transition: margin-inline-start var(--dur-med) var(--ease),
+    padding-inline-start var(--dur-med) var(--ease),
+    border-inline-start-width var(--dur-med) var(--ease);
+}
+/* Collapsed (icon-only) rail — the same fold the shell's rail makes, drawn once
+   rather than pressed: the column keeps its width and the nav clips to the
+   strip, so no row is laid out again and no glyph moves. A group's children stay
+   rows here, because wireNav() toggles the list's `hidden` attribute and nothing
+   else, so folding .ui-nav__sub away left the toggle announcing a list it could
+   not open. What goes is the indent and the words, and sidebarNav({ collapsed })
+   hands each row its name as a `title` so a pointer can still read it. The
+   shell's rail draws a chip of its own instead, on keyboard focus as well — see
+   layout.css. */
+.ui-nav--side.is-collapsed {
+  width: var(--ui-nav-strip);
+  /* clip, not hidden: a standalone rail has nothing around it to clip for it,
+     and `hidden` would make this a scroll box in both axes and cut the rows off
+     at whatever height it was given. `clip` across leaves `visible` down alone,
+     which is the one pair that does. */
+  overflow-x: clip;
+  overflow-y: visible;
+}
 .ui-nav--side.is-collapsed .ui-nav__cap,
 .ui-nav--side.is-collapsed .ui-nav__label,
 .ui-nav--side.is-collapsed .ui-nav__badge,
-.ui-nav--side.is-collapsed .ui-nav__caret { display: none; } /* motion: still — folding the rail is a layout change of the whole rail; animating these would reflow the page */
-.ui-nav--side.is-collapsed .ui-nav__item { justify-content: center; padding: 11px 0; gap: 0; }
-.ui-nav--side.is-collapsed .ui-nav__ic svg { width: 19px; height: 19px; stroke-width: 2; }
-.ui-nav--side.is-collapsed .ui-nav__item.is-active::before { left: 3px; }
-.ui-nav--side.is-collapsed .ui-nav__foot { text-align: center; }
+.ui-nav--side.is-collapsed .ui-nav__caret { opacity: 0; pointer-events: none; }
+.ui-nav--side.is-collapsed .ui-nav__sub {
+  margin-inline-start: 0; padding-inline-start: 0; border-inline-start-width: 0;
+}
+.ui-nav--side.is-collapsed .ui-nav__item:not(:has(.ui-nav__ic))::after { opacity: 0.62; }
 /* -- Horizontal tabs ----------------------------------------------------- */
 .ui-nav--tabs {

package/src/styles/topbar.css CHANGED Viewed

@@ -128,6 +128,10 @@
   padding: 6px;
   opacity: 0;
   visibility: hidden;
+  /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a box
+     that is drawn is a box that is hit. The open rule takes this back.
+     why: docs/specification.md#the-dropdown-panel */
+  pointer-events: none;
   transform: translateY(-6px);
   /* Named properties, not the bare shorthand: `transition: 0.18s` is `all`, and `all`
      includes visibility — held at the OLD value for the whole duration, so the menu is
@@ -138,7 +142,20 @@
     visibility var(--dur-med) linear;
   z-index: var(--z-dropdown);
 }
-.vsw.open .vsw__menu { opacity: 1; visibility: visible; transform: translateY(0); }
+/* Open, the menu is clickable and visible AT ONCE. Both menus in this file are
+   `wireDropdown()` in bespoke clothes — same hooks, same keyboard, same fade — so they
+   owe a panel's two rules as much as `.ui-dropdown__panel` does: `visibility` off the
+   open transition, because the frame the open class lands is the frame the wiring moves
+   focus onto a row in and a browser will not focus inside a hidden box; and
+   `pointer-events` back on, because the closed rule turned it off.
+   why: docs/specification.md#the-dropdown-panel */
+.vsw.open .vsw__menu {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translateY(0);
+  transition-property: opacity, transform;
+}
 .vopt {
   display: flex;
   gap: 11px;
@@ -210,6 +227,7 @@
   overflow: hidden;
   opacity: 0;
   visibility: hidden;
+  pointer-events: none; /* see .vsw__menu above */
   transform: translateY(-6px);
   /* Named properties — see .vsw__menu above. */
   transition:
@@ -218,7 +236,15 @@
     visibility var(--dur-med) linear;
   z-index: var(--z-dropdown);
 }
-.acct.open .amenu { opacity: 1; visibility: visible; transform: translateY(0); }
+/* Clickable and visible at once — see .vsw.open .vsw__menu above. The row this one
+   costs is `.aout`: a stray click in the fade out ends the reader's session. */
+.acct.open .amenu {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translateY(0);
+  transition-property: opacity, transform;
+}
 .amenu .ahead { padding: 13px 15px; border-bottom: 1px solid var(--border); display: flex; align-items: center; gap: 11px; }
 .amenu .ahead .avatar { cursor: default; }
 .amenu .ahead .aw { min-width: 0; display: flex; flex-direction: column; gap: 1px; line-height: 1.35; }