@apliteni/apliteni-ui 0.33.0 → 0.34.0

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/callout.css

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

package/src/styles/command-palette.css

@@ -69,7 +69,10 @@
   flex-direction: column;
   font-family: var(--font-sans);
   background: var(--cmdk-surface);
-  border: 1px solid var(--border);
+  /* The two-step edge and the drop: --border-strong outside, --border one pixel
+     inside it, then the broad faint drop. why: docs/specification.md#elevation */
+  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);
   overflow: hidden;
   opacity: 0;
@@ -79,7 +82,11 @@
     transform var(--dur-med) var(--ease);
 }
 .ui-cmdk.is-open .ui-cmdk__panel { opacity: 1; transform: translate(-50%, 0); }
-.ui-cmdk__panel:focus-visible { outline: none; box-shadow: var(--ring); }
+/* The ring is COMPOSED with the floating treatment, not written over it: a
+   box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
+   took the panel's edge and its drop off for as long as it held focus.
+   why: docs/specification.md#elevation */
+.ui-cmdk__panel:focus-visible { outline: none; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
 
 /* -- The text box --------------------------------------------------------- */
 

package/src/styles/confirm.css

@@ -62,7 +62,10 @@
   gap: var(--space-2);
   padding: var(--space-5);
   background: var(--confirm-surface);
-  border: 1px solid var(--border);
+  /* The two-step edge and the drop: --border-strong outside, --border one pixel
+     inside it, then the broad faint drop. why: docs/specification.md#elevation */
+  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);
   opacity: 0;
   transform: translateY(8px);
@@ -71,7 +74,11 @@
     transform var(--dur-med) var(--ease);
 }
 .ui-confirm.is-open .ui-confirm__panel { opacity: 1; transform: none; }
-.ui-confirm__panel:focus-visible { outline: none; box-shadow: var(--ring); }
+/* The ring is COMPOSED with the floating treatment, not written over it: a
+   box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
+   took the panel's edge and its drop off for as long as it held focus.
+   why: docs/specification.md#elevation */
+.ui-confirm__panel:focus-visible { outline: none; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
 
 /* -- Slots ----------------------------------------------------------------- */
 /* The question and the answers keep their size; the consequence between them is

package/src/styles/drawer.css

@@ -58,9 +58,19 @@
   display: flex;
   flex-direction: column;
   background: var(--drawer-surface);
+  /* A drawer is flush to a screen edge, so it has one edge rather than four and the
+     two-step edge runs along that one: --border-strong on the edge rule below, the
+     inner line one pixel inside it. This is the one floating surface that writes no
+     inset RING — a full ring would draw 1px lines across the top and bottom of a
+     full-height panel, where there is no edge — so it composes its own directional
+     line with the drops instead. The line is a variable so the focus rule can
+     compose all three layers without knowing which edge it is on; its default is a
+     no-op layer rather than `none`, which is valid only alone and would invalidate
+     the list. why: docs/specification.md#elevation */
+  --drawer-line: 0 0 0 0 transparent;
+  box-shadow: var(--drawer-line), var(--elev-drop);
   transition: transform var(--dur-med) var(--ease);
 }
-.ui-drawer__panel:focus-visible { outline: none; box-shadow: var(--ring); }
 .ui-drawer.is-open .ui-drawer__panel { transform: none; }
 
 /* -- Edge anchoring + slide-in direction ---------------------------------- */
@@ -72,12 +82,14 @@
 }
 .ui-drawer--right .ui-drawer__panel {
   right: 0;
-  border-left: 1px solid var(--border);
+  border-left: 1px solid var(--border-strong);
+  --drawer-line: inset 1px 0 0 var(--border);
   transform: translateX(100%);
 }
 .ui-drawer--left .ui-drawer__panel {
   left: 0;
-  border-right: 1px solid var(--border);
+  border-right: 1px solid var(--border-strong);
+  --drawer-line: inset -1px 0 0 var(--border);
   transform: translateX(-100%);
 }
 .ui-drawer--top .ui-drawer__panel,
@@ -88,15 +100,23 @@
 }
 .ui-drawer--top .ui-drawer__panel {
   top: 0;
-  border-bottom: 1px solid var(--border);
+  border-bottom: 1px solid var(--border-strong);
+  --drawer-line: inset 0 -1px 0 var(--border);
   transform: translateY(-100%);
 }
 .ui-drawer--bottom .ui-drawer__panel {
   bottom: 0;
-  border-top: 1px solid var(--border);
+  border-top: 1px solid var(--border-strong);
+  --drawer-line: inset 0 1px 0 var(--border);
   transform: translateY(100%);
 }
 
+/* The ring is COMPOSED with the floating treatment rather than written over it — a
+   box-shadow list replaces the whole list, so a bare `box-shadow: var(--ring)` would
+   take the drawer's edge and its drop off for as long as it held focus.
+   why: docs/specification.md#elevation */
+.ui-drawer__panel:focus-visible { outline: none; box-shadow: var(--ring), var(--drawer-line), var(--elev-drop); }
+
 /* -- Sizes ----------------------------------------------------------------- */
 /* left|right → width; top|bottom → height. Same names, axis chosen by side. */
 .ui-drawer--right.ui-drawer--sm, .ui-drawer--left.ui-drawer--sm { --drawer-w: var(--panel-sm); }

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
@@ -60,9 +71,12 @@
   /* The floating step, not the sunken one — a panel held open over a card cannot be
      painted the colour of an inset. why: docs/specification.md#elevation */
   background: var(--bg-elevated);
-  border: 1px solid var(--border);
+  /* The two-step edge and the drop: --border-strong outside, --border one pixel
+     inside it, then the broad faint drop. why: docs/specification.md#elevation */
+  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
@@ -200,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
@@ -243,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); }