@apliteni/apliteni-ui 0.97.0 → 0.100.0

package/package.json

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

package/react/dist/index.css

@@ -820,7 +820,7 @@
 .rx-toast-stack {
   position: fixed;
   right: var(--space-4);
-  bottom: var(--space-4);
+  bottom: calc(var(--space-4) + var(--ui-app-bottom-clearance, 0px));
   max-width: calc(100% - 2 * var(--space-4));
   z-index: var(--z-toast);
   pointer-events: none;
@@ -846,15 +846,28 @@
 .ui-react-app__bottom .ui-nav__item {
   min-height: 48px;
 }
+.ui-react-app:not(:has(> .ui-app__rail)) {
+  grid-template-columns: minmax(0, 1fr);
+}
+.ui-react-app .ui-app__bar > .ui-app__brand {
+  flex: none;
+  margin-inline-end: var(--space-2);
+}
 @media (max-width: 560px) {
+  :root:has(.ui-react-app__bottom) {
+    --ui-app-bottom-clearance: calc(96px + env(safe-area-inset-bottom));
+  }
+  :root:has(.ui-react-app) {
+    scroll-padding-bottom: calc(var(--space-5) + var(--ui-app-bottom-clearance, 0px));
+  }
   .ui-react-app {
     display: block;
   }
   .ui-react-app > .ui-app__rail {
     display: none;
   }
-  .ui-react-app .ui-app__main {
-    padding-bottom: calc(96px + env(safe-area-inset-bottom));
+  :root:has(.ui-react-app__bottom) .ui-react-app .ui-app__main {
+    padding-bottom: var(--ui-app-bottom-clearance, 0px);
   }
   .ui-react-app .ui-app__bar {
     padding-inline: var(--space-4);
@@ -865,6 +878,9 @@
   .ui-react-app .ui-app__search kbd {
     display: none;
   }
+  .ui-react-app .ui-app__bar > .ui-app__brand {
+    display: none;
+  }
   .ui-react-app__bottom {
     display: block;
     position: fixed;

package/react/dist/index.js

@@ -1892,7 +1892,8 @@ import {
   dropdownFiltering,
   filterPanelFit,
   transitionMs as transitionMs2,
-  dropdownViewportFit
+  dropdownViewportFit,
+  dropdownHeightFit
 } from "@apliteni/apliteni-ui";
 import { Fragment as Fragment5, jsx as jsx20, jsxs as jsxs16 } from "react/jsx-runtime";
 var EXIT_SLACK_MS2 = 50;
@@ -2102,6 +2103,27 @@ function Dropdown({
       doc.removeEventListener("keydown", onKey2);
     };
   }, [open]);
+  useIsoLayoutEffect(() => {
+    if (!open) return;
+    const el = panel.current;
+    if (!el) return;
+    const size = () => {
+      const avail = dropdownHeightFit(root.current, el);
+      if (avail == null) return;
+      if (Number.isFinite(avail)) el.style.setProperty("--ui-dropdown-avail", `${avail}px`);
+      else el.style.removeProperty("--ui-dropdown-avail");
+      const cap2 = el.ownerDocument.defaultView?.getComputedStyle(el).getPropertyValue("--ui-dropdown-cap").trim();
+      el.classList.toggle("is-unbounded", !Number.isFinite(avail) && !cap2);
+    };
+    size();
+    const view = el.ownerDocument?.defaultView ?? window;
+    view.addEventListener("scroll", size, true);
+    view.addEventListener("resize", size);
+    return () => {
+      view.removeEventListener("scroll", size, true);
+      view.removeEventListener("resize", size);
+    };
+  }, [open, direction]);
   useIsoLayoutEffect(() => {
     const want = landOn.current;
     landOn.current = null;
@@ -2328,7 +2350,7 @@ function Dropdown({
       section.label ?? `s${si}`
     );
   }) : (items || []).map((entry, i) => renderRow(entry, `i${i}`));
-  const cap = scroll && scroll !== true ? { maxHeight: typeof scroll === "number" ? `${scroll}px` : scroll } : void 0;
+  const cap = scroll && scroll !== true ? { "--ui-dropdown-cap": typeof scroll === "number" ? `${scroll}px` : scroll } : void 0;
   const none = sx && filtering && !visible.length ? /* @__PURE__ */ jsxs16(Fragment5, { children: [
     /* @__PURE__ */ jsx20("span", { className: "ui-dropdown__none-title", children: sx.empty.replace("{q}", () => query.trim()) }),
     /* @__PURE__ */ jsx20("span", { className: "ui-dropdown__none-hint", children: sx.hint })
@@ -3466,15 +3488,17 @@ function AppShell({
     }
   );
   const foldLabel = collapsed ? "Expand sidebar" : "Collapse sidebar";
+  const navigable = sections.length > 1 || Boolean(back);
   const visible = sections.length > 4 ? sections.slice(0, 3) : sections;
   const remaining = sections.slice(visible.length);
   const initials = account.name.trim().split(/\s+/).map((part) => part[0]).slice(0, 2).join("");
+  const lockup = /* @__PURE__ */ jsxs29("a", { className: "ui-app__brand", href: brandHref, "aria-label": word, children: [
+    brand ?? /* @__PURE__ */ jsx34("i", { "aria-hidden": "true", className: "ui-react-app__mark", dangerouslySetInnerHTML: { __html: prism(uid, 24) } }),
+    /* @__PURE__ */ jsx34("span", { children: word })
+  ] });
   return /* @__PURE__ */ jsxs29("div", { className: `ui-app ui-app--topbar ui-react-app${collapsed ? " is-collapsed" : ""}`, children: [
-    /* @__PURE__ */ jsxs29("div", { className: "ui-app__rail", children: [
-      /* @__PURE__ */ jsx34("div", { className: "ui-app__head", children: /* @__PURE__ */ jsxs29("a", { className: "ui-app__brand", href: brandHref, "aria-label": word, children: [
-        brand ?? /* @__PURE__ */ jsx34("i", { "aria-hidden": "true", className: "ui-react-app__mark", dangerouslySetInnerHTML: { __html: prism(uid, 24) } }),
-        /* @__PURE__ */ jsx34("span", { children: word })
-      ] }) }),
+    navigable && /* @__PURE__ */ jsxs29("div", { className: "ui-app__rail", children: [
+      /* @__PURE__ */ jsx34("div", { className: "ui-app__head", children: lockup }),
       sidebar(sections, "Sections"),
       /* @__PURE__ */ jsx34("div", { className: "ui-app__foot", children: /* @__PURE__ */ jsx34("div", { className: "ui-app__fold-row", children: /* @__PURE__ */ jsxs29("button", { type: "button", className: "ui-nav__item ui-app__fold", "aria-expanded": !collapsed, "aria-label": foldLabel, onClick: fold, children: [
         /* @__PURE__ */ jsx34("span", { className: "ui-nav__ic", children: /* @__PURE__ */ jsxs29("svg", { className: "ui-icon", viewBox: "0 0 24 24", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [
@@ -3487,6 +3511,7 @@ function AppShell({
     ] }),
     /* @__PURE__ */ jsxs29("div", { className: "ui-app__well", children: [
       /* @__PURE__ */ jsxs29("header", { className: "ui-app__bar", children: [
+        !navigable && lockup,
         /* @__PURE__ */ jsxs29("button", { type: "button", className: "ui-app__search", "aria-haspopup": "dialog", onClick: () => setSearch(true), children: [
           /* @__PURE__ */ jsx34("span", { className: "ui-app__search-ic", children: /* @__PURE__ */ jsx34(Icon, { name: "search" }) }),
           /* @__PURE__ */ jsx34("span", { className: "ui-app__search-txt", children: "Search or run a command\u2026" }),
@@ -3522,7 +3547,7 @@ function AppShell({
         /* @__PURE__ */ jsx34("div", { className: "ui-app__body", children })
       ] })
     ] }),
-    /* @__PURE__ */ jsx34("nav", { className: "ui-nav ui-react-app__bottom", "aria-label": "Sections on mobile", children: /* @__PURE__ */ jsxs29("ul", { className: "ui-nav__list", children: [
+    navigable && /* @__PURE__ */ jsx34("nav", { className: "ui-nav ui-react-app__bottom", "aria-label": "Sections on mobile", children: /* @__PURE__ */ jsxs29("ul", { className: "ui-nav__list", children: [
       links(visible),
       remaining.length > 0 && /* @__PURE__ */ jsx34("li", { children: /* @__PURE__ */ jsxs29(
         "button",

package/src/components/dropdown.js

@@ -1,5 +1,5 @@
-import { dropdownMatch, dropdownFiltering } from '../logic/dropdown.js';
-export { dropdownMatch, dropdownFiltering } from '../logic/dropdown.js';
+import { dropdownMatch, dropdownFiltering, dropdownAvail } from '../logic/dropdown.js';
+export { dropdownMatch, dropdownFiltering, dropdownAvail } from '../logic/dropdown.js';
 // Dropdown — the kit's one popover-list primitive. A trigger opens a panel of
 // item rows; two flavours share the same panel and the same open/close JS:
 //
@@ -120,7 +120,10 @@ function ddSearchBody({ items, sections }, sx, name, scroll) {
   const rows = ddBody({ items, sections }, true, sx);
   const flat = (sections ? sections.flatMap((s) => s.items || []) : (items || [])).filter(ddIsRow);
   const shown = flat.some((it) => dropdownMatch(it.label, sx.q));
-  const cap = scroll && scroll !== true ? ` style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '';
+  // The cap property and not `max-height`: an inline height outranks the sheet's
+  // min() and would put the panel back past the viewport edge. #489
+  const cap = scroll && scroll !== true
+    ? ` style="--ui-dropdown-cap:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '';
   const input = [
     'class="ui-dropdown__search-input"', 'type="text"', 'role="combobox"',
     'aria-autocomplete="list"', 'aria-expanded="true"', `aria-controls="${esc(listId)}"`,
@@ -202,7 +205,10 @@ export function dropdown({
     // With search the panel holds a field and a list, which a listbox may not.
     `role="${sx ? 'dialog' : listRole}"`,
     sx ? `aria-label="${esc(name)}"` : (ariaLabel ? `aria-label="${esc(ariaLabel)}"` : ''),
-    scroll && scroll !== true && !sx ? `style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
+    // The cap property and not `max-height`: an inline height outranks the
+    // sheet's min() and would put the panel back past the viewport edge. #489
+    scroll && scroll !== true && !sx
+      ? `style="--ui-dropdown-cap:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
   ].filter(Boolean).join(' ');
 
   // The block the sheet bleeds to the panel's bottom edge. It sits OUTSIDE the
@@ -278,6 +284,16 @@ function ddEdge(panel) {
   return Number.isFinite(declared) ? declared : DD_EDGE;
 }
 
+// The least height a capped panel keeps, below which it would rather spend the
+// edge inset than shrink further. The number is --ui-dropdown-min in
+// src/styles/dropdown.css. #489
+const DD_MIN = 120;
+
+function ddMin(panel) {
+  const declared = parseFloat(ddViewOf(panel).getComputedStyle(panel).getPropertyValue('--ui-dropdown-min'));
+  return Number.isFinite(declared) ? declared : DD_MIN;
+}
+
 /** The width a panel has to stay inside: the LAYOUT viewport, which is what both
  *  `position: fixed` and a page's scrollable width are measured against. A classic
  *  scrollbar is in `innerWidth` and not in the box either of those means, so an
@@ -515,10 +531,65 @@ function ddUnwatchRow(dd) {
  * taken for the middle of an animation, is stated with the rule.
  * why: docs/components.md#the-dropdown-panel */
 
+/**
+ * How tall a panel may be: the room between its trigger and the viewport edge,
+ * from dropdownAvail() in src/logic/dropdown.js — one calculation, so the
+ * vanilla wiring and the React `<Dropdown>` cannot disagree about where a panel
+ * ends. Measured from the trigger, not the panel, the way dropdownViewportFit()
+ * is measured from the panel and not the trigger: each is the box the number it
+ * answers actually depends on. `null` when there is nothing to measure.
+ * why: docs/components.md#the-dropdown-panel
+ *
+ * @param {Element} dd the `[data-dropdown]` container the trigger lives in
+ * @param {Element} panel a `[data-dropdown-panel]`, for its gap/edge/min and its
+ *   `is-up` direction
+ */
+export function dropdownHeightFit(dd, panel) {
+  const trigger = dd?.querySelector?.('[data-dropdown-trigger]');
+  if (!trigger || typeof trigger.getBoundingClientRect !== 'function' || !panel) return null;
+  const t = trigger.getBoundingClientRect();
+  const view = ddViewOf(panel);
+  return dropdownAvail({
+    anchorTop: t.top,
+    anchorBottom: t.bottom,
+    viewport: view.innerHeight,
+    gap: ddGap(panel),
+    inset: ddEdge(panel),
+    min: ddMin(panel),
+    up: panel.classList.contains('is-up'),
+  });
+}
+
+function ddSizeHeight(dd, panel) {
+  if (!panel?.style) return;
+  const avail = dropdownHeightFit(dd, panel);
+  if (avail == null) return;
+  // Infinity means the floor could not be met even by spending the whole inset:
+  // the property is removed rather than written, so the sheet's own fallback — the
+  // viewport less the edge inset, not a trigger-sized sliver — takes over. why:
+  // dropdownAvail(), src/logic/dropdown.js
+  //
+  // `.is-unbounded` is only added where that leaves NO cap at all: a consumer's
+  // own `--ui-dropdown-cap` (`.is-scroll` or a numeric `scroll`) still clamps the
+  // panel, and that clamp is still real room to scroll. why: src/styles/dropdown.css
+  const cap = ddViewOf(panel).getComputedStyle(panel).getPropertyValue('--ui-dropdown-cap').trim();
+  panel.classList.toggle('is-unbounded', !Number.isFinite(avail) && !cap);
+  // A number that has not changed is not written again, the way the width fit's
+  // own write is guarded: a mutation inside the row that moved nothing vertically
+  // would otherwise answer its own write, over and over, through the document
+  // observer below. why: dropdownViewportFit()'s own "moved" guard, same file
+  const next = Number.isFinite(avail) ? `${avail}px` : '';
+  if (panel.style.getPropertyValue('--ui-dropdown-avail') === next) return;
+  if (next) panel.style.setProperty('--ui-dropdown-avail', next);
+  else panel.style.removeProperty('--ui-dropdown-avail');
+}
+
 /** Fit a panel again where it now is, whichever placement it uses. */
 function ddPlace(dd) {
+  const panel = dd.__ddPanel || ddPanelOf(dd);
   if (dd.__ddPanel) positionPortalPanel(dd, dd.__ddPanel);
   else ddFitViewport(dd, ddPanelOf(dd));
+  ddSizeHeight(dd, panel);
 }
 
 /* A few frames past the sheet's own end, so the timer never cuts the fade's last
@@ -778,6 +849,7 @@ function openDropdown(dd, focusIdx) {
        is null inside a filter row, whose own row already bounds its panels.
        why: docs/components.md#a-filter-row-holds-its-panels */
     else { ddFitFilterPanel(dd, panel); ddWatchRow(dd, panel); ddFitViewport(dd, panel); }
+    ddSizeHeight(dd, panel);
   }
   dd.classList.add('open');
   /* After `open`, and after the fit: ddResetSearch() pins the width it reads off
@@ -949,6 +1021,7 @@ export function wireDropdown(root = document) {
       ddFitFilterPanel(dd, panel);
       ddWatchRow(dd, panel);
     }
+    if (panel && dd.classList.contains('open')) ddSizeHeight(dd, panel);
 
     trigger.addEventListener('click', (e) => {
       e.stopPropagation();

package/src/index.d.ts

@@ -34,6 +34,13 @@ export declare function wireDropdown(root?: Document | Element): void;
 /** The kit's own match, asked rather than re-implemented by <Dropdown>. */
 export declare function dropdownMatch(label: unknown, query: unknown): boolean;
 export declare function dropdownFiltering(query: unknown): boolean;
+/** How tall a floating panel may be: the room between its anchor and the
+ *  viewport edge, less `gap` and `inset`. `min` is a floor that spends `inset`,
+ *  down to nothing, rather than room past the edge, which does not exist. */
+export declare function dropdownAvail(opts: {
+  anchorTop: number; anchorBottom: number; viewport: number;
+  gap: number; inset: number; min: number; up?: boolean;
+}): number;
 /** The kit's menu floor, the width `.ui-dropdown__panel` writes. */
 export declare const DD_MENU_FLOOR: number;
 /** Where a filter chip's open menu can sit: the room from the edge it is
@@ -58,6 +65,14 @@ export declare function dropdownViewportFit(
   panel: Element | null | undefined,
   at?: { left: number; width: number },
 ): { shift: number; left: number; width: number; view: number; edge: number; max: number } | null;
+/** How tall a panel may be: the room between its trigger (inside `dd`) and the
+ *  viewport edge, from the same dropdownAvail() dropdownViewportFit's `max`
+ *  shares its calculation with. `null` when there is nothing to measure.
+ *  why: docs/components.md#the-dropdown-panel */
+export declare function dropdownHeightFit(
+  dd: Element | null | undefined,
+  panel: Element | null | undefined,
+): number | null;
 export declare function backLink(opts?: Record<string, unknown>): string;
 export declare function statBand(opts?: Record<string, unknown>): string;
 export declare function commandPalette(opts?: Record<string, unknown>): string;

package/src/index.js

@@ -27,7 +27,7 @@ export * from './components/table-values.js';
 export * from './components/segmented.js';
 export * from './components/filter-bar.js';
 
-export { dropdownMatch, dropdownFiltering } from './logic/dropdown.js';
+export { dropdownMatch, dropdownFiltering, dropdownAvail } from './logic/dropdown.js';
 export { SCORE, rankGroups, rankCommands, scoreCommand, paletteHotkey } from './logic/command-palette.js';
 export { segmentedNextIndex } from './logic/segmented.js';
 export { filterChipText, filterChipName, filterChipUnset, filterChipItems, nextFocusStop, focusNextStop } from './logic/filter-bar.js';

package/src/logic/dropdown.js

@@ -14,3 +14,26 @@ export const dropdownFiltering = (query) => fold(query).trim() !== '';
 
 /** Does `label` match `query`? A substring, anywhere, ignoring case and accents. */
 export const dropdownMatch = (label, query) => fold(label).includes(fold(query).trim());
+
+/**
+ * How tall a floating panel may be: the room between its anchor and the viewport
+ * edge, less the gap it keeps from the anchor and the edge inset it keeps from
+ * that edge. `up` measures the room above the anchor, otherwise below it.
+ *
+ * Public for the same reason the two above are: the vanilla wiring and the React
+ * <Dropdown> both have to arrive at the same number, and a panel that ends inside
+ * the viewport in one and past it in the other is the bug this answers (#489).
+ *
+ * `min` is a floor: a trigger near the edge has little room, and a panel reduced
+ * to a sliver is worse than one left to its content height. The floor never
+ * spends room PAST the edge to reach itself, because that room does not exist.
+ * Once even the whole inset cannot reach it, there is no cap a reader could
+ * use, so this returns `Infinity`: "nothing measured," the word a caller
+ * already reads from an unmeasured panel. The panel then keeps its content
+ * height, the document grows, and a reader reaches every row by scrolling the
+ * page — a 27px sliver hiding 446px of rows was danger 1 in #641's review.
+ */
+export const dropdownAvail = ({ anchorTop, anchorBottom, viewport, gap, inset, min, up = false }) => {
+  const room = Math.max(up ? anchorTop - gap : viewport - anchorBottom - gap, 0);
+  return room < min ? Infinity : Math.max(room - inset, min);
+};

package/src/styles/dropdown.css

@@ -62,6 +62,12 @@
      the screen's edge sets it to 0.
      why: docs/components.md#the-dropdown-panel */
   --ui-dropdown-edge: 8px;
+  /* The least height a capped panel keeps before it would rather spend the edge
+     inset above than shrink further — three rows or so. Below it the panel
+     still ends at or before the edge; it never spends room past the edge to
+     reach this floor, because that room does not exist. #489
+     why: docs/components.md#the-dropdown-panel */
+  --ui-dropdown-min: 120px;
   /* 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/components.md#the-dropdown-panel */
@@ -107,6 +113,24 @@
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
   border-radius: var(--radius-lg);
   padding: var(--ui-dropdown-pad);
+  /* The cap, and the whole of #489: a panel took its content's height until that
+     height ran off the screen, and then it took what was left. Two numbers decide
+     it and the smaller wins — --ui-dropdown-cap is what the consumer asked for
+     (the `scroll` option writes it), --ui-dropdown-avail is the room between the
+     trigger and the viewport edge, which the wiring measures on every open and
+     every scroll. Neither is declared here: an unset cap means the consumer wants
+     the whole list, and an unset avail means nothing has measured yet, which is a
+     server-rendered page before hydration — so the fallback promises the same
+     thing at a coarser grain, the viewport less the edge inset at each end.
+     why: docs/components.md#the-dropdown-panel */
+  max-height: min(
+    var(--ui-dropdown-cap, 100dvh),
+    var(--ui-dropdown-avail, calc(100dvh - 2 * var(--ui-dropdown-edge)))
+  );
+  overflow-y: auto;
+  /* The wheel stops at the panel's own end instead of carrying on down the page
+     underneath it — the second half of #489. */
+  overscroll-behavior: contain;
   opacity: 0;
   visibility: hidden;
   /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a
@@ -123,7 +147,21 @@
   z-index: var(--z-dropdown);
 }
 .ui-dropdown__panel.is-end { left: auto; right: 0; }
-.ui-dropdown__panel.is-scroll { max-height: 300px; overflow-y: auto; }
+/* `.is-scroll` asks for 300px specifically; the panel above caps every panel at
+   the room the viewport left either way. #489 */
+.ui-dropdown__panel.is-scroll { --ui-dropdown-cap: 300px; }
+
+/* The wiring adds this where the floor (above) left the panel uncapped: below
+   120px even spending the whole edge inset, there is no usable cap, so the
+   panel keeps its content height and the page grows to hold it instead —
+   #641's danger 1. That panel has nothing of its own to scroll, so the
+   `overflow-y: auto` above still claims a wheel over it for nothing, and
+   `overscroll-behavior: contain` then stops the gesture from reaching the
+   page that is now the only way to the rows below the fold. `visible` lets it
+   through. A panel that also carries `.is-scroll` or a numeric cap keeps
+   `auto`: that cap is still real room to scroll inside. why: dropdownAvail(),
+   src/logic/dropdown.js */
+.ui-dropdown__panel.is-unbounded { overflow-y: visible; }
 
 /* Chrome makes a scroll container a keyboard stop on its own — no tabindex, no
    author rule — so `.is-scroll` took the browser's outline, black in light mode.
@@ -286,7 +324,13 @@
    while the list scrolls. Every rule below keys on a class only the search
    variant emits, so the plain dropdown renders as it did.
    why: docs/components.md#a-dropdown-with-a-search-field */
-.ui-dropdown__panel--search { min-width: 280px; }
+/* A column, so the panel's own avail-based max-height (above) lands on the rows
+   and not on the field: the field and the empty-state block keep their content
+   height, and the list — the child that can overflow — gives up the room they
+   take. #489 */
+.ui-dropdown__panel--search { min-width: 280px; display: flex; flex-direction: column; }
+.ui-dropdown__panel--search > * { flex: none; }
+.ui-dropdown__panel--search > .ui-dropdown__list { flex: 1 1 auto; min-height: 0; }
 
 .ui-dropdown__search { position: relative; display: flex; align-items: center; margin-bottom: 6px; }
 .ui-dropdown__search-ic {
@@ -324,7 +368,9 @@
 .ui-dropdown__search-input:hover { border-color: var(--field-edge-hover); }
 .ui-dropdown__search-input:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 
-.ui-dropdown__list { max-height: 300px; overflow-y: auto; }
+/* The rows' own cap, read from the same property the panel reads: the `scroll`
+   option lands on the list when there is a field above it. #489 */
+.ui-dropdown__list { max-height: var(--ui-dropdown-cap, 300px); overflow-y: auto; overscroll-behavior: contain; }
 /* Rows are `role="option" tabindex="-1"`, so the LIST takes the keyboard stop and
    answered with the native outline. The band is drawn INWARD, on the list: an outset
    one 6px inside a --radius-lg corner leaves the panel, and the panel is not the box

package/src/styles/layout.css

@@ -422,7 +422,10 @@
   letter-spacing: var(--tracking-tight);
   margin-bottom: 8px;
 }
-.ui-app__sub { color: var(--text); font-size: calc(var(--text-base) + 0.5px); line-height: 1.6; max-width: var(--prose-body); margin-bottom: 32px; }
+/* The head keeps the kit's second step below it whether or not a lede is there to
+   carry it: with no lede the title's own margin takes the step instead. */
+.ui-app__main h1:not(.ui-card h1):not(:has(+ .ui-app__sub)) { margin-bottom: var(--space-8); }
+.ui-app__sub { color: var(--text); font-size: calc(var(--text-base) + 0.5px); line-height: 1.6; max-width: var(--prose-body); margin-bottom: var(--space-8); }
 .ui-app__body { display: flex; flex-direction: column; gap: var(--space-5); }
 /* A flex child's min-width is its content by default, so one wide block — a
    ledger, a code sample — pushes the whole page sideways instead of scrolling

package/src/styles/table.css

@@ -204,7 +204,35 @@
 .ui-table--compact th { padding: var(--space-2) var(--space-3); }
 .ui-table--compact th:last-child,
 .ui-table--compact td:last-child { padding-right: var(--space-3); }
-.ui-table-scroll { overflow: auto; max-height: var(--ui-table-height, 70vh); padding: 0 var(--space-1); }
+/* Columns past the box's edge, said in paint. Two shades, one per side, under two
+   cover layers that ride the content: `local` moves a cover with the scroll, so
+   reaching an end slides that cover over its shade. A cover is solid for its first
+   half, so at 24px it hides a 12px shade outright — which is why the two sizes are
+   not one. why: guidelines/dense-tables.md */
+.ui-table-scroll {
+  overflow: auto; max-height: var(--ui-table-height, 70vh); padding: 0 var(--space-1);
+  background-color: var(--table-bg);
+  background-image:
+    linear-gradient(to right, var(--table-bg) 50%, transparent),
+    linear-gradient(to left, var(--table-bg) 50%, transparent),
+    radial-gradient(farthest-side at 0 50%, var(--table-edge), transparent),
+    radial-gradient(farthest-side at 100% 50%, var(--table-edge), transparent);
+  background-position: 0 0, 100% 0, 0 0, 100% 0;
+  background-size: var(--space-6) 100%, var(--space-6) 100%, var(--space-3) 100%, var(--space-3) 100%;
+  background-repeat: no-repeat;
+  background-attachment: local, local, scroll, scroll;
+}
+/* The edge darkens on a light ground and lightens on a dark one: ink has nowhere to
+   go on a near-black page, which is why --elev-drop splits its spend and a raised
+   dark surface takes a light --elev-edge. */
+.ui-table-scroll { --table-edge: color-mix(in srgb, var(--sheen) 12%, transparent); }
+:root[data-theme="light"] .ui-table-scroll { --table-edge: color-mix(in srgb, var(--shadow-ink) 13%, transparent); }
+/* The surface belongs to the box that scrolls, so the shades land under the cells
+   rather than behind them; the row fills repeat that same surface and step aside.
+   The sticky header and pinned column keep their paint: they hide what scrolls
+   beneath them. */
+.ui-table-scroll > .ui-table,
+.ui-table-scroll > .ui-table tbody td:not(.ui-table__identity, .ui-table__selection) { background-color: transparent; }
 /* The kit's first ringed scroller, and a scroll region inside a card like the rest, so
    it draws the band inward too rather than spending a halo across the card around it.
    It had no room of its own to draw in — the padding above is horizontal — which is the
@@ -216,6 +244,45 @@
 .ui-table--sticky thead th { position: sticky; top: 0; z-index: var(--z-sticky); background: var(--table-bg); padding-top: var(--space-2); }
 .ui-table--pinned .ui-table__identity, .ui-table--pinned .ui-table__selection { position: sticky; left: 0; z-index: var(--z-base); background: var(--table-bg); border-right: 1px solid var(--border); }
 .ui-table--pinned thead .ui-table__identity, .ui-table--pinned thead .ui-table__selection { z-index: calc(var(--z-sticky) + 1); }
+/* The divider is the pin's edge: it says the column stayed while the rest moved under it.
+   Columns that all fit never move, so the line divides nothing and reads as an arbitrary
+   rule. The resting rule keeps it, so an engine that cannot answer the query is unchanged;
+   scroll-state makes a query container, not a size one. why: guidelines/dense-tables.md */
+.ui-table-scroll { container-type: scroll-state; }
+/* A shared grid cell puts the edge shade over the opaque sticky header, on both
+   sides: the radial-gradient shades below answer only the table's own background
+   and fall to nothing where the sticky header paints over them, so an engine that
+   can ask whether the scrollport still has room sticks a shade of its own above
+   it instead and the base radial pair is sized to 0 here. #434 review round 2 */
+@supports (container-type: scroll-state) {
+  .ui-table-scroll {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    background-size: var(--space-6) 100%, var(--space-6) 100%, 0 100%, 0 100%;
+  }
+  .ui-table-scroll > .ui-table { grid-area: 1 / 1; }
+  .ui-table-scroll::before,
+  .ui-table-scroll::after {
+    content: '';
+    grid-area: 1 / 1;
+    position: sticky;
+    top: 0;
+    width: var(--space-3);
+    z-index: calc(var(--z-sticky) + 2);
+    pointer-events: none;
+  }
+  .ui-table-scroll::before { left: 0; right: calc(100% - var(--space-3)); justify-self: start; }
+  .ui-table-scroll::after { left: calc(100% - var(--space-3)); right: 0; justify-self: end; }
+  @container scroll-state(scrollable: left) {
+    .ui-table-scroll::before { background: linear-gradient(to right, var(--table-edge), transparent); }
+  }
+  @container scroll-state(scrollable: right) {
+    .ui-table-scroll::after { background: linear-gradient(to left, var(--table-edge), transparent); }
+  }
+}
+@container not scroll-state(scrollable: x) {
+  .ui-table--pinned :is(.ui-table__identity, .ui-table__selection) { border-right-color: transparent; }
+}
 .ui-value, .ui-delta { white-space: nowrap; font-variant-numeric: tabular-nums; }
 .ui-value__unit { margin-left: var(--space-1); font-size: var(--text-xs); color: var(--text); }
 .ui-delta--success { color: var(--chip-success-ink); }

package/src/styles/topbar.css

@@ -141,6 +141,13 @@
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
   border-radius: 16px;
   padding: 6px;
+  /* The same cap `.ui-dropdown__panel` writes itself, in bespoke clothes: this
+     menu is `wireDropdown()` too, so wireDropdown() measures it the same way and
+     writes the same two properties. #489
+     why: docs/components.md#the-dropdown-panel */
+  max-height: min(var(--ui-dropdown-cap, 100dvh), var(--ui-dropdown-avail, calc(100dvh - 16px)));
+  overflow-y: auto;
+  overscroll-behavior: contain;
   opacity: 0;
   visibility: hidden;
   /* Drawn for the whole of the fade out, so the rows do not vanish mid-fade — and a box
@@ -157,6 +164,13 @@
     visibility var(--dur-med) linear;
   z-index: var(--z-dropdown);
 }
+/* Chrome makes a scroll container a keyboard stop on its own — no tabindex, no
+   author rule — and #489's cap is what gave this menu the `overflow-y` that
+   makes it one, the same way `.ui-dropdown__panel` got it. `.vopt` is
+   `tabindex="-1"` and reached only by the arrow keys, so Tab lands on the menu
+   itself rather than a row inside it, and the ring belongs here for the same
+   reason `.ui-dropdown__panel` keeps it. why: docs/foundations.md#elevation */
+.vsw__menu:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 /* 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
@@ -192,10 +206,10 @@
   transition: background var(--dur-fast) var(--ease);
 }
 /* Menu rows use the reading surface and an edge on hover — see
-   src/styles/dropdown.css:207 `.ui-dropdown__item:hover`.
+   src/styles/dropdown.css:245 `.ui-dropdown__item:hover`.
    why: docs/foundations.md#elevation */
 .vopt:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
-/* The row is a keyboard stop: src/components/dropdown.js:1015
+/* The row is a keyboard stop: src/components/dropdown.js:1088
    `items[next < 0 ? 0 : next]?.focus()` moves focus onto a `[data-dd-item]` with
    the arrow keys, and this is one. It takes the ring on its own 10px radius, the
    same way `.amenu a` above does. #482 */
@@ -277,10 +291,24 @@
   border: 1px solid var(--float-edge);
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
   border-radius: 14px;
-  /* No clip. The rows reach this panel's edges, and the ring a focused row draws reaches
-     3px past itself; `overflow: hidden` here cut that down to the one pixel of border it
-     had, and the reader met two accent bars instead of a ring. The ring crosses the edge
-     now. #519 why: docs/components.md#a-menu-panel-does-not-cut-off-its-rows-ring */
+  /* #519 chose no clip over padding: `overflow: hidden` with no room cut the ring down to
+     the one pixel of border this panel had, so the rule took the clip away instead and let
+     the ring cross the edge. #489's cap takes that choice away — `overflow-y: auto` clips
+     again, because a menu that scrolls has to stop its content at its own edge — so this
+     reserves the room instead, the same 6px `.vsw__menu` and `.ui-dropdown__panel` already
+     keep rather than a new figure. why: docs/components.md#a-menu-panel-does-not-cut-off-its-rows-ring */
+  padding: 6px;
+  /* The same cap `.ui-dropdown__panel` writes itself — see .vsw__menu above. #489 */
+  max-height: min(var(--ui-dropdown-cap, 100dvh), var(--ui-dropdown-avail, calc(100dvh - 16px)));
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  /* Chromium scrolls a focused row flush with the scrollport edge, which is 3px
+     short of the row's own ring: 1px of gap plus a 2px band. The padding above
+     reserves that room while the menu stands still; this keeps it reserved once
+     scrolling the menu — reaching the first row this PR made it do — puts a
+     focused row at either end. #641's danger 2.
+     why: docs/components.md#a-menu-panel-does-not-cut-off-its-rows-ring */
+  scroll-padding-block: 3px;
   opacity: 0;
   visibility: hidden;
   pointer-events: none; /* see .vsw__menu above */
@@ -292,6 +320,10 @@
     visibility var(--dur-med) linear;
   z-index: var(--z-dropdown);
 }
+/* The same gap as `.vsw__menu` above, from the same cause: #489's cap. `.amenu
+   a` is `tabindex="-1"` too, so Tab still lands on the menu and not a row, and
+   the ring belongs here. why: docs/foundations.md#elevation */
+.amenu:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 /* 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 {
@@ -301,12 +333,28 @@
   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; }
+/* `margin` bleeds the head back through the 6px panel padding above, the way
+   `.ui-dropdown__panel > .ui-dropdown__head` already does for its own panel:
+   the border-bottom hairline reaches the panel's edge instead of stopping a
+   notch short of it. #641's warning.
+   why: docs/components.md#the-dropdown-panel */
+.amenu .ahead {
+  padding: 13px 15px;
+  margin: -6px -6px 0;
+  border-bottom: 1px solid var(--border);
+  border-radius: 14px 14px 0 0;
+  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; }
 .amenu .ahead .anm { color: var(--strong); font-size: var(--text-sm); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu .ahead .aem { color: var(--text); font-size: calc(var(--text-xs) + 0.5px); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.amenu a { display: flex; align-items: center; gap: 11px; padding: 10px 15px; color: var(--text); text-decoration: none; font-family: var(--font-sans); font-size: var(--text-sm); cursor: pointer; }
+/* `scroll-margin-block` on the row, beside `scroll-padding-block` on the panel
+   above: Chromium's own focus-follow scroll honoured the padding scrolling
+   toward the end of the list and not the start, so the row carries its own
+   reserve too rather than leaving the start of the list short. #641's danger 2.
+   why: docs/components.md#a-menu-panel-does-not-cut-off-its-rows-ring */
+.amenu a { display: flex; align-items: center; gap: 11px; padding: 10px 15px; color: var(--text); text-decoration: none; font-family: var(--font-sans); font-size: var(--text-sm); cursor: pointer; scroll-margin-block: 3px; }
 .amenu a:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
 .amenu a:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); border-radius: var(--radius-xs); }
 .amenu a.cur { color: var(--accent); }

package/src/tokens/tokens.css

@@ -534,6 +534,7 @@
 .ui-snippet--reveal,
 .ui-sx,
 .ui-table,
+.ui-table-scroll,
 .ui-table--sticky thead th,
 .ui-table--pinned .ui-table__identity, .ui-table--pinned .ui-table__selection,
 .ui-table--hover:not(.ui-table--zebra) tbody tr:hover td,
@@ -557,6 +558,7 @@
  * toward the page and leaves the page 1.02 away, while the card it is a variant of stays
  * 1.07-1.14 off in both themes. Measured in stories/code-chip.test.js. */
 .ui-table,
+.ui-table-scroll,
 .ui-table--sticky thead th,
 .ui-table--pinned .ui-table__identity, .ui-table--pinned .ui-table__selection,
 .ui-table--hover:not(.ui-table--zebra) tbody tr:hover td,