@apliteni/apliteni-ui 0.96.1 → 0.98.0

package/package.json

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

package/react/README.md

@@ -658,9 +658,10 @@ size. Neither has a filled disc behind it.
 there is no backdrop layer and no `backdrop` prop. Pass `title`, one short `body`
 line, and React `actions`. There is no `eyebrow` prop: a confirmation carries one
 title and at most one line under it, so put the outcome in the title rather than in a
-label above it. A kit `Button` carries the focus ring already; a router link or
-a plain `<a>` must also take `className="ui-focusable"`, or it falls back to the
-browser's own focus outline. An omitted or empty `actions`
+label above it. A kit `Button` carries the focus ring already, and so does
+a router link or a plain `<a>`: the kit rings every anchor on `:focus-visible`. A
+focusable that is neither — a `div` or `span` given `tabIndex` — still needs
+`className="ui-focusable"`, or it falls back to the browser's own focus outline. An omitted or empty `actions`
 leaves out the actions row. Hero and split default to h1; compact defaults to h2.
 `level` overrides the heading rank, and a value outside 1–6 falls back to that layout
 default. `confetti` enables the existing decorative animation. All three components

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 })

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

@@ -141,6 +141,13 @@ svg:where(:not([width]):not([height])) {
    .ui-focusable, in the vanilla topbar, React ThemeToggle and the React shell's bar
    alike, so keyboard focus on it fell back to the browser's own outline in all three.
    It has no class of its own to opt in with; it joins the list instead. Found on #385. */
+/* `a` is here as an ELEMENT, not a class, because a link in running text is the one
+   control a consumer writes with no class on it at all — so it took the browser's
+   outline, which #457 refused. The net is over every anchor; a component that rings
+   its own anchor outranks this at two classes and keeps the shape it chose. The band
+   sits at whatever corner the link carries, which is the rule .ui-table's links
+   already take. Found on #586, decided on #587. */
+a:focus-visible,
 .ui-focusable:focus-visible,
 .ui-snippet :focus-visible,
 .ui-btn:focus-visible,

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

@@ -145,14 +145,12 @@
   top: 50%;
   translate: 0 -50%;
 }
-/* And on keyboard focus every link in a table takes the kit ring, at whatever corner it
-   carries, so none falls back to the browser's own outline. `.ui-btn` has the ring already.
-   why: guidelines/state-set.md#focus-rings
-   held by: src/styles/table-focus.test.js */
-.ui-table a:not(.ui-btn):focus-visible {
-  outline: var(--ring);
-  outline-offset: var(--ring-offset);
-}
+/* No focus rule here any more. #510 gave a cell link the ring with a rule of this file's
+   own, because `base.css` reached no bare `a`; #587 put `a` on that shared list, so this
+   one painted the same two declarations a second time. The guarantee is unchanged and
+   still held by src/styles/table-focus.test.js — the corner the band follows is the
+   `border-radius` above, which is this file's and stays.
+   why: guidelines/state-set.md#focus-rings */
 
 .ui-table__num { text-align: right; font-variant-numeric: tabular-nums; }
 /* A numeric column is sized to its content while .ui-table__title claims the rest,

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); }