@apliteni/apliteni-ui 0.33.1 → 0.34.1

package/src/components/shell.js

@@ -1,6 +1,6 @@
-// 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.
+// The kit's one page shell: a full-height rail beside one <main>, in two layouts.
+// 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';
@@ -9,6 +9,7 @@ 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';
+import { paletteHotkey } from './command-palette.js';
 
 // The one account navigation definition lives in account-nav.js because topbar.js needs
 // it too; re-exported here so the name docs/library.md publishes keeps working.
@@ -78,6 +79,26 @@ const toTopbar = (t) => {
   return out;
 };
 
+// ---- the two layouts, and the two widths ---------------------------------
+//
+// Each is a name the kit knows or the default — read strictly, and not through
+// String(), which turned `['topbar']` into a layout and drew half a page.
+// why: docs/specification.md#the-page-shell
+const toLayout = (v) => (v === 'topbar' ? 'topbar' : 'rail');
+
+// why: docs/specification.md#widths
+const toWidth = (v) => (v === 'wide' ? 'wide' : 'centered');
+
+// `search: 'palette-id'`, or the same id in `{ palette }` with a placeholder beside
+// it. No palette to open, no field — the argument `signOutHref` takes.
+// why: docs/specification.md#the-page-shell
+const toSearch = (v) => {
+  const given = typeof v === 'string' ? { palette: v } : (isRecord(v) && !Array.isArray(v) ? v : null);
+  const palette = given && typeof given.palette === 'string' ? given.palette.trim() : '';
+  if (!palette) return null;
+  return { palette, placeholder: str(given.placeholder) || 'Search or run a command…' };
+};
+
 // `maxWidth` lands inside a style attribute, so a length is all this accepts — a number
 // and a unit, or `none`. Anything else yields '' and the caller writes no style
 // attribute, falling through to --measure. It must REMOVE the property rather than pass
@@ -137,6 +158,7 @@ const railToggle = (collapsed) =>
 // 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,
+  layout: toLayout, width: toWidth, search: toSearch,
   // 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,
@@ -160,44 +182,71 @@ function settle(options) {
 // 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) =>
+const readerFace = (name, email, named, markOnly = false) =>
   `<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>`;
+  + (markOnly ? '' : `<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) {
+//
+// One block, two places: only the direction it opens is the layout's answer.
+// `portal: true` either way — the rail and the band are both sticky.
+function readerBlock({ name, email }, signOutHref, { band = false } = {}) {
   if (!name && !email) return '';
+  const cls = `ui-app__user${band ? ' ui-app__user--bar' : ''}`;
   const who = [name, email].filter(Boolean).join(', ');
+  // The name is said once, by whichever part is on screen: the two lines in the rail,
+  // an aria-label on the band where the mark is the whole trigger.
+  const face = band ? readerFace(name, email, null, true) : readerFace(name, email, null);
   if (!signOutHref) {
-    return `<div class="ui-app__user">${readerFace(name, email, who)}</div>`;
+    return `<div class="${cls}">${readerFace(name, email, who, band)}</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
+  // The head says who the menu belongs to — and on a folded rail, or on a band, it is
+  // the only place a sighted reader can read the address.
   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({
+  return `<div class="${cls}">${dropdown({
     variant: 'menu',
     portal: true,
-    direction: 'up',
+    direction: band ? 'down' : 'up',
+    align: band ? 'end' : 'start',
+    chevron: !band,
+    ariaLabel: band ? `Signed in as ${who}` : undefined,
     triggerClass: 'ui-app__user-trigger',
-    triggerContent: readerFace(name, email, null),
+    triggerContent: face,
     panelClass: 'ui-app__user-panel',
     header: head,
     items: [{ label: 'Sign out', icon: 'logout', href: signOutHref, danger: true }],
   })}</div>`;
 }
 
+// A field to look at, a button to press. `data-cmdk-open` and the cap's class are the
+// palette's own, and the cap is NOT aria-hidden: it is half the button's name.
+// why: docs/specification.md#the-page-shell
+const searchField = ({ palette, placeholder }) =>
+  `<button type="button" class="ui-app__search" data-cmdk-open="${esc(palette)}" aria-haspopup="dialog">`
+  + `<span class="ui-app__search-ic" aria-hidden="true">${icon('search')}</span>`
+  + `<span class="ui-app__search-txt">${esc(placeholder)}</span>`
+  + `<kbd class="ui-cmdk__key" data-palette-hotkey>${esc(paletteHotkey())}</kbd>`
+  + `</button>`;
+
+// The band: search at its start, the reader at its end, beside the rail rather than
+// across the top of both. why: docs/specification.md#the-page-shell
+const shellBar = (search, account, signOutHref) =>
+  `<header class="ui-app__bar">`
+  + (search ? searchField(search) : '')
+  + `<span class="ui-app__bar-gap"></span>`
+  + readerBlock(account, signOutHref, { band: true })
+  + `</header>`;
+
 // Unique-per-render suffix for the brand mark's clip id — the same reason
 // nav.js keeps a module counter. Two shells on one page must not collide.
 let _shellUid = 0;
@@ -222,7 +271,12 @@ export function appShell(options = {}) {
     maxWidth,
     collapsible,
     collapsed,
+    layout,
+    width,
+    search,
   } = settle(options);
+  // The layout's one branch, read once. Everything below asks this and not the string.
+  const banded = layout === 'topbar';
   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.
@@ -232,10 +286,15 @@ export function appShell(options = {}) {
     activeIs: up ? 'section' : 'page',
     ariaLabel: navLabel,
   });
+  // One band over a page, never two: the banded layout draws its own, so the
+  // compatibility bag is not drawn beside it. why: docs/specification.md#the-page-shell
+  const compat = banded ? null : topbar;
   // 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
-  // the name is written out — the mark itself is aria-hidden.
-  const brand = topbar ? '' : `<a class="ui-app__brand" href="${esc(brandHref)}" aria-label="${esc(word)}">`
+  // the name is written out — the mark itself is aria-hidden. The banded layout's own
+  // bar says no word, so there the rail keeps the lockup: that layout's head band IS
+  // the product's mark. why: docs/specification.md#the-page-shell
+  const brand = compat ? '' : `<a class="ui-app__brand" href="${esc(brandHref)}" aria-label="${esc(word)}">`
     + `${prism(`appb-${++_shellUid}`, 24)}<span>${esc(word)}</span></a>`;
   // 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
@@ -244,27 +303,40 @@ export function appShell(options = {}) {
   // 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"' : '';
+  // Where this stands is the one thing the two layouts disagree about on the rail.
+  const fold = collapsible ? railToggle(folded) : '';
   // 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 inHead = banded ? '' : fold;
+  const head = brand || inHead
+    ? `<div class="ui-app__head">${brand}${inHead}</div>`
     : '';
-  const grid = `<div class="ui-app${folded ? ' is-collapsed' : ''}"${auto}>
-    <div class="ui-app__rail">
-      ${head}
-      ${rail}
-      ${railUser(account, signOutHref)}
-    </div>
-    <main class="ui-app__main"${maxWidth ? ` style="--ui-app-main: ${maxWidth}"` : ''}>
+  // The rail's foot: the reader, or the control that took their place. One block
+  // either way. why: docs/specification.md#the-page-shell
+  const foot = banded
+    ? (fold ? `<div class="ui-app__foot">${fold}</div>` : '')
+    : readerBlock(account, signOutHref);
+  const main = `<main class="ui-app__main${width === 'wide' ? ' ui-app__main--wide' : ''}"${maxWidth ? ` style="--ui-app-main: ${maxWidth}"` : ''}>
       ${up || (crumbs.length ? breadcrumbs({ items: crumbs }) : '')}
       ${title ? `<h1>${title}</h1>` : ''}
       ${sub ? `<p class="ui-app__sub">${sub}</p>` : ''}
       <div class="ui-app__body">${body}</div>
-    </main>
+    </main>`;
+  // The second column is a box of its own: the band and the page are two rows of it.
+  const well = banded
+    ? `<div class="ui-app__well">${shellBar(search, account, signOutHref)}${main}</div>`
+    : main;
+  const grid = `<div class="ui-app${banded ? ' ui-app--topbar' : ''}${folded ? ' is-collapsed' : ''}"${auto}>
+    <div class="ui-app__rail">
+      ${head}
+      ${rail}
+      ${foot}
+    </div>
+    ${well}
   </div>`;
-  return topbar ? `<div class="ui-app-page">${productTopbar(topbar)}${grid}</div>` : grid;
+  return compat ? `<div class="ui-app-page">${productTopbar(compat)}${grid}</div>` : grid;
 }
 
 // ---- Behaviour -----------------------------------------------------------
@@ -275,13 +347,14 @@ export function appShell(options = {}) {
 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.
+// The toggle, addressed from the rail that owns it: a fold row 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. A descendant and not a child, because the two layouts stand the
+// row in two places: the head band, or the rail's foot.
 // 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}`;
+const FOLD_PATH = '.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) => {
@@ -293,7 +366,7 @@ 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}`)) {
+  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');
@@ -334,6 +407,12 @@ export function wireShell(root = document, { persist } = {}) {
   // 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);
+  // A server cannot know which key the reader holds, so the browser corrects it here —
+  // off the ROOT's window, not the global one. why: docs/specification.md#the-page-shell
+  const here = root.nodeType === 9 ? root : root.ownerDocument;
+  const view = here && here.defaultView;
+  const key = paletteHotkey(view && view.navigator ? view.navigator.platform : '');
+  for (const kbd of root.querySelectorAll('[data-palette-hotkey]')) kbd.textContent = key;
   const doc = root.nodeType === 9 ? root : root.ownerDocument;
   listen(doc);
   if (persist === false) _unpersisted.add(root);
@@ -368,6 +447,9 @@ export function accountShell({
   signOutHref = '#logout',
   collapsible = true,
   collapsed,
+  layout,
+  width,
+  search,
 } = {}) {
   // 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`.
@@ -389,6 +471,11 @@ export function accountShell({
     signOutHref,
     collapsible,
     collapsed,
+    // Settled nowhere but appShell(). Under `layout: 'topbar'` the bag below is not
+    // drawn, which is what that layout costs the preset.
+    layout,
+    width,
+    search,
     topbar: {
       word,
       view: 'text',

package/src/components/tooltip.js

@@ -14,6 +14,9 @@
 import { esc } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
+/* classes: ui-tip__label ui-tip__value ui-tip__detail — built from `k` below, so
+   a sweep reading class names off the source cannot see them.
+   why: CONTRIBUTING.md#a-spelling-the-sweep-cannot-see-costs-coverage-in-silence */
 const PARTS = ['label', 'value', 'detail'];
 const px = (n) => (typeof n === 'number' && Number.isFinite(n) ? `${n}px` : null);
 let seq = 0;

package/src/styles/back.css

@@ -7,10 +7,12 @@
  * ========================================================================== */
 
 /* Its own line, and only as wide as its words, so the hover ground does not run
-   the width of the column. */
+   the width of the column — and never wider than it, which `fit-content` alone
+   does not give once the label below is `nowrap`. why: #303 */
 .ui-back {
   display: flex;
   width: fit-content;
+  max-width: 100%;
   align-items: center;
   gap: var(--space-1);
   /* WCAG 2.5.8's 24px: the line of text alone is 17px tall. */
@@ -40,3 +42,12 @@
 /* In the page shell it takes the trail's place, and the trail's distance from
    the title with it. */
 .ui-app__main > .ui-back { margin-bottom: var(--space-5); }
+
+/* The one part that can run long. It clips rather than wrapping, as .ui-nav__label
+   does. why: docs/specification.md#the-back-link */
+.ui-back__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

package/src/styles/dropdown.css

@@ -28,16 +28,23 @@
 .ui-dropdown__pre { color: var(--muted); }
 .ui-dropdown__value { color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 
-/* Chevron — border caret that flips when the container is .open */
+/* Chevron — border caret that flips when the container is .open. Its ink is an L
+   on a rotated square, so centring the BOX leaves the mark off centre; --caret-off
+   is that gap, derived rather than typed.
+   why: docs/specification.md#the-dropdown-panel */
 .ui-dropdown__chevron {
-  width: 8px; height: 8px;
-  border-right: 1.6px solid var(--muted);
-  border-bottom: 1.6px solid var(--muted);
-  transform: rotate(45deg) translateY(-1px);
+  --caret: 8px;
+  --caret-ink: 1.6px;
+  --caret-off: calc((var(--caret) - var(--caret-ink)) / 2.8284);  /* 2√2 — the 45° turn's projection */
+  width: var(--caret); height: var(--caret);
+  border-right: var(--caret-ink) solid var(--muted);
+  border-bottom: var(--caret-ink) solid var(--muted);
+  /* Shift BEFORE rotate, so it lands in page space rather than on the turned axis. */
+  transform: translateY(calc(var(--caret-off) * -1)) rotate(45deg);
   transition: transform var(--dur-fast) var(--ease);
   flex: none;
 }
-.ui-dropdown.open .ui-dropdown__chevron { transform: rotate(-135deg) translateY(2px); }
+.ui-dropdown.open .ui-dropdown__chevron { transform: translateY(var(--caret-off)) rotate(-135deg); }
 
 /* Panel — the popover surface */
 .ui-dropdown__panel {
@@ -45,6 +52,10 @@
      the portal's JS, so an upward panel cannot drift from a downward one.
      why: docs/specification.md#the-dropdown-panel */
   --ui-dropdown-gap: 9px;
+  /* Named for the same reason the offset is: a block pinned to an edge has to
+     bleed back through it, and #306 is a page copying the number by hand.
+     why: docs/specification.md#the-dropdown-panel */
+  --ui-dropdown-pad: 6px;
   /* The panel states its own role rather than inheriting one, because `portal:
      true` moves it onto <body> and an inherited face is then decided by where
      the panel was MOUNTED rather than by what it is. Measured: the same dropdown
@@ -65,7 +76,7 @@
   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-lg);
-  padding: 6px;
+  padding: var(--ui-dropdown-pad);
   opacity: 0;
   visibility: hidden;
   /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a
@@ -203,13 +214,23 @@
 /* Separator */
 .ui-dropdown__sep { height: 1px; background: var(--border); margin: 5px 4px; }
 
-/* Optional pinned header/footer blocks */
-.ui-dropdown__panel > .ui-dropdown__head {
+/* Optional pinned head/foot blocks — symmetrical: one inner padding, and each
+   bleeding to the edge it sits on, lining the edge it faces.
+   why: docs/specification.md#the-dropdown-panel */
+.ui-dropdown__panel > .ui-dropdown__head,
+.ui-dropdown__panel > .ui-dropdown__foot {
   padding: 11px 13px;
-  margin: -6px -6px 5px;
+}
+.ui-dropdown__panel > .ui-dropdown__head {
+  margin: calc(var(--ui-dropdown-pad) * -1) calc(var(--ui-dropdown-pad) * -1) 5px;
   border-bottom: 1px solid var(--border);
   border-radius: var(--radius-lg) var(--radius-lg) 0 0;
 }
+.ui-dropdown__panel > .ui-dropdown__foot {
+  margin: 5px calc(var(--ui-dropdown-pad) * -1) calc(var(--ui-dropdown-pad) * -1);
+  border-top: 1px solid var(--border);
+  border-radius: 0 0 var(--radius-lg) var(--radius-lg);
+}
 
 /* Search — `search: true` pins a field above the rows and filters them as the
    reader types. The rows move into a list of their own, so the field stays put
@@ -246,6 +267,12 @@
   min-height: 38px;
   transition: border-color var(--dur-fast) var(--ease), box-shadow var(--dur-fast) var(--ease);
 }
+/* Light sinks the field one rung less far: its panel is the only pure white the
+   kit paints, so --surface-2 falls two rungs under it rather than one. The
+   numbers are in the spec and the gate is stories/dropdown-field-ground.test.js.
+   why: docs/specification.md#elevation */
+:root[data-theme="light"] .ui-dropdown__search-input { background: var(--bg); }
+
 .ui-dropdown__search-input::placeholder { color: var(--muted); }
 .ui-dropdown__search-input:hover { border-color: var(--border-strong); }
 .ui-dropdown__search-input:focus-visible { outline: none; border-color: var(--accent); box-shadow: var(--ring); }

package/src/styles/layout.css

@@ -52,9 +52,13 @@
   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; }
+   nav declares its own; these are the three that are not the nav. Scoped to the rail,
+   because the topbar layout draws the reader's block in its band instead and a column
+   the rail's width is no measurement for a box on a 52px line.
+   why: docs/specification.md#the-page-shell */
+.ui-app__rail > .ui-app__head,
+.ui-app__rail > .ui-app__user,
+.ui-app__rail > .ui-app__foot { 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. The danger row and the current row are left out by
    name, because this rule outranks the states nav.css writes for them.
@@ -105,7 +109,7 @@
    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:1340 `a resting glyph is dimmer but still legible`. */
+   stories/apps/shell-states.test.js:1400 `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 */
@@ -128,6 +132,18 @@
   padding-top: var(--space-5);
   border-top: 1px solid var(--border);
 }
+/* The other thing that can close a rail: where the reader's block is in the band,
+   the fold's control takes its place under the same rule.
+   why: docs/specification.md#the-page-shell */
+.ui-app__foot {
+  display: flex;
+  align-items: center;
+  padding-top: var(--space-5);
+  border-top: 1px solid var(--border);
+}
+/* On the glyph column from the first frame, so the fold moves it nowhere — the ride
+   along the closing edge belongs to the head band, where the mark holds that column. */
+.ui-app__foot > .ui-app__fold-row { margin-inline-start: 0; }
 /* 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
@@ -231,8 +247,14 @@
    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__head > .ui-app__fold-row { inset-inline-start: calc(var(--ui-nav-strip) - var(--ui-nav-col)); }
+/* …and only in the layout where something arrives on the mark's column. In the
+   topbar layout the toggle is at the rail's foot, nothing lands where the mark
+   stands, and a lockup faded out there leaves a band with nothing in it and its
+   hairline still under it — the defect the 720px block below exists to avoid. So
+   that layout keeps the mark and lets the shared rule above fold away its words.
+   why: docs/specification.md#the-page-shell */
+:where(.ui-app:not(.ui-app--topbar).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
@@ -277,6 +299,97 @@
   margin-inline: auto;
   padding: 40px clamp(24px, 4vw, 56px) 72px;
 }
+/* The whole of the difference: `centered` is the rule above and `wide` takes its cap
+   off. `maxWidth` is the number under either name. why: docs/specification.md#widths */
+.ui-app__main--wide { max-width: var(--ui-app-main, none); }
+
+/* -- The topbar layout ----------------------------------------------------- */
+/* The band stands BESIDE the rail, not across the top of both, which is the
+   arrangement where the rail's head band and the band close at the same height — what
+   the three heights below are for. Level, not one continuous stroke: the rail insets
+   its own rule, and in light that half is 1.009:1 on the rail's ground.
+   why: docs/specification.md#the-second-layout */
+.ui-app { --ui-app-band: 52px; }
+.ui-app__well { display: flex; flex-direction: column; min-width: 0; }
+.ui-app__bar {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  height: var(--ui-app-band);
+  flex: none;
+  padding-inline: clamp(24px, 4vw, 56px);
+  background: var(--bg);
+  border-bottom: 1px solid var(--border);
+  /* Sticky for the reason the rail beside it is: chrome that scrolls away is chrome
+     you scroll back up for. */
+  position: sticky;
+  top: 0;
+  z-index: var(--z-sticky);
+}
+.ui-app__bar-gap { flex: 1 1 auto; }
+/* The rail's two bands take the band's height, so the rule under the head lands on
+   the line the band's own rule lands on. The rail gives up its top inset to buy it. */
+.ui-app--topbar > .ui-app__rail { padding-top: 0; }
+.ui-app--topbar > .ui-app__rail > .ui-app__head { height: var(--ui-app-band); padding-bottom: 0; }
+.ui-app--topbar > .ui-app__rail > .ui-app__foot { height: var(--ui-app-band); padding-top: 0; }
+
+/* Drawn as a field, behaving as a button. The hairline and the radius are the
+   field's — src/styles/input.css:20 `.ui-input,` sets both — because what it looks
+   like is the point. The STEP is not, and that is the one thing this control does
+   differently from every other field in the kit: the reason is on the declaration
+   below. It gives way before anything else on the band.
+   why: docs/specification.md#the-page-shell */
+.ui-app__search {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  flex: 0 1 var(--panel-sm);
+  min-width: 0;
+  padding: 7px 10px;
+  /* A family alone leaves the browser's leading behind: `font: inherit` first, then
+     the one step this row takes. why: CONTRIBUTING.md#button-chrome-ledgers */
+  font: inherit;
+  font-size: var(--text-sm);
+  text-align: start;
+  color: var(--muted);
+  /* --surface, not the sunken --surface-2 every other field in the kit takes:
+     those sit on a card and this one sits on the band, and the band IS --bg, the
+     bottom of the ladder — so a sunken fill has nowhere to go but down into its
+     own ground. Measured in light, the field was 1.10:1 BELOW the band and its
+     key cap 1.04:1 against the field it sits in; they are 1.08 above and 1.14 now.
+     Dark trades the other way and is stated rather than hidden: the cap goes
+     1.29 -> 1.16, because --surface-3 and --surface are adjacent rungs there.
+     Artur chose this over three alternatives on #318; the survey of what seven
+     other systems do is docs/reviews/318-search-field.md.
+     why: docs/specification.md#elevation */
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: border-color var(--dur-med) var(--ease), color var(--dur-med) var(--ease);
+}
+.ui-app__search:hover { border-color: var(--border-strong); color: var(--strong); }
+/* Every other control on the band takes the kit's ring. This one is a <button>
+   without `.ui-btn`, so base.css's shared rule never reached it and focus fell
+   through to the browser's own square outline, drawn around a 12px radius.
+   why: docs/specification.md#the-focus-ring */
+.ui-app__search:focus-visible { outline: none; box-shadow: var(--ring); border-color: var(--accent); }
+/* The same glyph the palette draws in its own search box, at the same box and the
+   same stroke: the trigger and the thing it opens are not two search marks.
+   src/styles/command-palette.css:107 `.ui-cmdk__search-ic svg` */
+.ui-app__search-ic { display: flex; flex: none; }
+.ui-app__search-ic svg { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.2; }
+/* Part of the button's name, so it is squeezed rather than dropped: an ellipsis
+   still leaves the whole string in the tree. */
+.ui-app__search-txt { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+/* The other half of the name, so it never gives way. */
+.ui-app__search kbd { flex: none; }
+
+/* The mark alone — no room for two lines on a 52px row. No rule over it, since the
+   band's hairline is under the whole of it, and no column, since this is not the rail.
+   why: docs/specification.md#the-page-shell */
+.ui-app__user--bar { flex: none; padding-top: 0; border-top: 0; }
+.ui-app__user--bar .ui-app__av { margin-inline-start: 0; }
 /* Crumb, then the title block. At --space-2 the crumb sat 8px off the h1 and
    the h1 8px off its subtitle, so all three ranks read as one. */
 .ui-app__main .ui-nav--crumbs { margin-bottom: var(--space-5); }
@@ -321,6 +434,11 @@
   .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 the foot goes with it, for the reason the head band does below: in the
+     topbar layout that box holds the toggle and nothing else, so at this width it is
+     padding and a hairline drawn over nothing. Scoped to the shell's own rail, like
+     every other rule in this block. why: docs/specification.md#the-page-shell */
+  .ui-app__rail .ui-app__foot { 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

package/src/styles/topbar.css

@@ -180,7 +180,7 @@
   transition: background var(--dur-fast) var(--ease);
 }
 /* The menu is raised, so a hovered row takes the step ABOVE it — see
-   src/styles/dropdown.css:144 `.ui-dropdown__item:hover`.
+   src/styles/dropdown.css:155 `.ui-dropdown__item:hover`.
    why: docs/specification.md#elevation */
 .vopt:hover { background: var(--surface-3); }
 .vopt .vname { font-family: var(--font-sans); font-size: 12.5px; color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }