@gemboss/ui 0.47.0 → 0.50.0

package/src/list-page.tsx

@@ -0,0 +1,239 @@
+"use client";
+/**
+ * ListPage (23/10/2026, step 3 of the ⋯ / list standard, Gems/CLAUDE.md §13): the frame of a page that lists one kind of
+ * thing. Its header (a way back, the title, one line under it, the primary action, the rest), its notices, its toolbar, and
+ * ONE card holding the list, or, in the list's place, what the list is doing: loading, empty, nothing matching, or not read.
+ *
+ * Until now every admin list page drew this itself on Polaris `Page`, and each drew the states its own way: five kinds of
+ * empty state, four labels on a retry ("Try again", "Retry", "Reload", "Refresh"), a skeleton of 3 or 4 lines or a spinner or
+ * nothing. Here there is one of each: a page says WHICH state it is in, and the kit draws it.
+ *
+ * The header takes Polaris Page's numbers, measured in the admin (_local/gemboss/list-page-2026-10-23): title 20/24/700 on a
+ * 28px row, the line under it 12/16 muted 2px below that row, actions 28px tall 8px apart, 24px above the header and under it
+ * from 768px up, 16 below. What it does differently, on purpose:
+ *   - secondary actions: in a page column of 560px or more the first two are buttons and the rest go behind ⋯; in a narrower
+ *     column (the admin at 768, beside its rail) and below 768px all of them are behind ⋯. Polaris measures the room in
+ *     script and folds a different number at every width; this folds the same way every time.
+ *   - below 768 the controls are 44px tall (the kit's rule for a finger and a phone width, §9.1), not Polaris' 32.
+ *
+ * `primaryAction` is a node, so a page passes its own button (the admin's Polaris Button, its Publish button that counts
+ * changes). Secondary actions are data, so the kit can put them behind ⋯ when there is no room; an action is the same as a
+ * button and as a ⋯ row (its URL through `linkAs`, its `onAction` on both, its reason when disabled). `linkAs` draws the back
+ * link and every URL action with the app's link (Next's Link), as IndexTable does.
+ *
+ * The states are drawn here, not with collections.tsx' CollectionState / CollectionSkeleton: importing that module brings
+ * collections.css (15.6 KB gzip, tables, boards, grids) into every page that lists something. The markup is the same
+ * core classes (ui.css: `ui-empty`, `ui-notice--danger`, `ui-skeleton__line`); the no-match padding is this entry's own, since
+ * `ui-empty--no-match` lives in collections.css (the parts gate holds a component to the CSS it imports).
+ */
+import "./list-page.css";
+import React, { useId } from "react";
+import { Icon } from "./icons";
+import { Menu, MenuGroup, MenuItem, MenuSeparator } from "./menu";
+
+export interface ListPageAction {
+  content: string;
+  onAction?: () => void;
+  url?: string;
+  /** A new tab. */
+  external?: boolean;
+  disabled?: boolean;
+  destructive?: boolean;
+  /** Why it is disabled, or what it will do: the button's title, the menu row's hint. */
+  helpText?: string;
+}
+
+/** A choice in an action group: the one that is on is `active` (a check before it; the others none). */
+export interface ListPageChoice extends ListPageAction {
+  active?: boolean;
+}
+
+export type ListPageState = "ready" | "loading" | "empty" | "no-match" | "error";
+
+
+/** How many secondary actions stand as buttons from 768px up; the rest are behind ⋯. */
+const WIDE_SECONDARY = 2;
+
+export function ListPage({
+  title, subtitle, back, titleMeta, primaryAction, secondaryActions = [], actionGroups = [], notices, toolbar,
+  state = "ready", empty, noMatch, error, loadingRows = 3, loadingText = "Loading…", cardTitle, cardMeta, cardLead, card = true, cardProps, after, children, linkAs = "a",
+}: {
+  title: React.ReactNode;
+  /** One line under the title: what the page holds, with its count first when it has one ("12 rules · 9 on."). */
+  subtitle?: React.ReactNode;
+  /** The page this one sits in ("Types" from a type's entries). */
+  back?: { href: string; label: string };
+  /** Beside the title: a badge (a count, a status). */
+  titleMeta?: React.ReactNode;
+  /** The ONE thing to do here, as the page's own button. */
+  primaryAction?: React.ReactNode;
+  secondaryActions?: ListPageAction[];
+  /** Choices of one kind, always behind ⋯ (Polaris Page's actionGroups): a title, and the one that is on marked `active`
+   *  (Products' Auto-refresh: Daily, Off). Never header buttons, at any width. */
+  actionGroups?: { title: string; actions: ListPageChoice[] }[];
+  /** What sits between the header and the toolbar: banners about the page (a change failed, a note), a band, the one item
+   *  shown apart (Themes' current theme). Not the list's read error: that is `state`. */
+  notices?: React.ReactNode;
+  /** Search, filters, sort, a view switch: above the card. */
+  toolbar?: React.ReactNode;
+  /** What the card shows: the list (`children`), or the state the list is in. */
+  state?: ListPageState;
+  /** The empty state, the page's own (an EmptyStage). Default: one line. */
+  empty?: React.ReactNode;
+  /** Filters found nothing: the header and the toolbar stay, the card says so and offers to clear them. */
+  noMatch?: { title?: React.ReactNode; body?: React.ReactNode; onClear?: () => void };
+  /** The list could not be read: what failed, and "Try again" (`retrying` while the new read is on its way). A failed action
+   *  over a list that IS there is a notice. */
+  error?: { title?: React.ReactNode; message?: React.ReactNode; onRetry?: () => void; retrying?: boolean };
+  /** Rows the loading placeholder draws (at most 10). */
+  loadingRows?: number;
+  /** What a screen reader hears while the list loads ("Loading your rules…"). */
+  loadingText?: string;
+  /** A heading at the top of the card ("Your rules"). */
+  cardTitle?: React.ReactNode;
+  /** Beside and under that heading, not in it: a hint about the card ("Drop images here to upload"), so a screen reader's heading
+   *  list reads the heading alone. */
+  cardMeta?: React.ReactNode;
+  /** false: no card around a list that draws its own (a grid of cards), and its `empty` is drawn as given: a page's own
+   *  starting point (StartingPoint) stands on the page. Loading, no match and a failed read still draw in a card. */
+  card?: boolean;
+  /** Attributes on the card itself (a drop zone's class and drag handlers), so a state drawn in it keeps them: an empty
+   *  library is still where files are dropped. */
+  cardProps?: React.HTMLAttributes<HTMLElement>;
+  /** Rows at the top of the card in EVERY state, the state's loading, empty or error after them: a row that does not wait for the
+   *  list's read (Funnels' Website, the funnel every store has). A page with a lead always has its card, so the lead stays the
+   *  same element (an open row stays open) from one state to the next. */
+  cardLead?: React.ReactNode;
+  /** Sections after the list (a library to add from, ready-made templates). */
+  after?: React.ReactNode;
+  children?: React.ReactNode;
+  /** The app's link (Next's Link), as IndexTable takes it. */
+  linkAs?: React.ElementType;
+}) {
+  const Link = linkAs;
+  const uid = useId();
+  const wide = secondaryActions.slice(0, WIDE_SECONDARY);
+  const overflow = secondaryActions.slice(WIDE_SECONDARY);
+  const hasActions = Boolean(primaryAction) || secondaryActions.length > 0 || actionGroups.length > 0;
+  // Each group is a titled set of choices, every one of them a menuitemradio (its `active` true or false), after a line when
+  // rows come before it.
+  const groups = (after: boolean) => actionGroups.map((g, gi) => (
+    <React.Fragment key={`${gi}:${g.title}`}>
+      {after || gi > 0 ? <MenuSeparator /> : null}
+      <MenuGroup title={g.title}>{g.actions.map((a, i) => item(a, i, !!a.active))}</MenuGroup>
+    </React.Fragment>
+  ));
+  // A ⋯ that holds only one group of choices is named by it ("Auto-refresh options"), as the caret beside Refresh now was;
+  // any other is "More actions" (review of 3f).
+  const wideMore = overflow.length === 0 && actionGroups.length === 1 ? `${actionGroups[0].title} options` : "More actions";
+  // `checked` only for a group's choices: an action is never a radio row in the ⋯ and a plain button beside it.
+  const item = (a: ListPageAction, i: number, checked?: boolean) => (
+    <MenuItem key={`${i}:${a.content}`} checked={checked} href={a.url} linkAs={a.url && !a.external ? Link : undefined} danger={a.destructive} disabled={a.disabled} hint={a.helpText}
+      onClick={a.onAction ? () => a.onAction!() : undefined}
+      {...(a.url && a.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}>{a.content}</MenuItem>
+  );
+  // A button says the same as its ⋯ row: a disabled one stays focusable (aria-disabled) with its reason as its description,
+  // which a keyboard and a screen reader reach; a `title` alone, on a `disabled` button, reaches neither.
+  const button = (a: ListPageAction, i: number) => {
+    const cls = `ui-btn ui-list-page__action${a.destructive ? " ui-list-page__action--danger" : ""} ui-list-page__wide`;
+    const why = a.helpText ? `${uid}-why-${i}` : undefined;
+    const run = a.onAction ? () => a.onAction!() : undefined;
+    // An external action (a new tab, a download) is a plain link: through the app's Link, Next would prefetch it, and a
+    // download route would build its file on every visit (review of 3e, Tests' Export CSV).
+    const To: React.ElementType = a.external ? "a" : Link;
+    return (
+      <React.Fragment key={`${i}:${a.content}`}>
+        {a.url && !a.disabled ? (
+          <To href={a.url} className={cls} title={a.helpText} aria-describedby={why} onClick={run}
+            {...(a.external ? { target: "_blank", rel: "noopener noreferrer" } : {})}>{a.content}</To>
+        ) : (
+          <button type="button" className={cls} aria-disabled={a.disabled || undefined} title={a.helpText} aria-describedby={why}
+            onClick={a.disabled ? undefined : run}>{a.content}</button>
+        )}
+        {why ? <span id={why} hidden>{a.helpText}</span> : null}
+      </React.Fragment>
+    );
+  };
+
+  // The words are said by the page's one status region (below), not by the busy rows: a screen reader may hold back a live
+  // region inside an aria-busy one.
+  const placeholder = (
+    <div className="ui-list-page__loading">
+      <div aria-busy="true" aria-hidden="true">
+        {Array.from({ length: Math.max(1, Math.min(10, loadingRows)) }, (_, i) => (
+          <div key={i} className="ui-list-page__skeleton"><span className="ui-skeleton__line" /><span className="ui-skeleton__line" /></div>
+        ))}
+      </div>
+    </div>
+  );
+  const body = state === "loading" ? placeholder
+    : state === "empty" ? (empty ?? <div className="ui-empty"><p className="ui-empty__title">Nothing here yet</p></div>)
+    : state === "no-match" ? (
+      <div className="ui-empty ui-list-page__no-match">
+        <p className="ui-empty__title">{noMatch?.title ?? "Nothing matches"}</p>
+        {noMatch?.body ? <p className="ui-empty__body">{noMatch.body}</p> : null}
+        {noMatch?.onClear ? <button type="button" className="ui-btn" onClick={noMatch.onClear}>Clear filters</button> : null}
+      </div>
+    )
+    : state === "error" ? (
+      <div className="ui-list-page__error">
+        <div className="ui-notice ui-notice--danger" role="alert">
+          <div><b>{error?.title ?? "This list couldn’t be read."}</b>{error?.message ? <> {error.message}</> : null}</div>
+          {error?.onRetry ? (
+            <button type="button" className="ui-btn" aria-disabled={error.retrying || undefined}
+              onClick={error.retrying ? undefined : error.onRetry}>{error.retrying ? "Trying again…" : "Try again"}</button>
+          ) : null}
+        </div>
+      </div>
+    )
+    : children;
+  // A page with no card around its list draws its OWN empty as given (a starting point stands on the page); the kit's default
+  // line is still boxed, as every other state (review of 3c).
+  // A lead is card content, and a card that came and went would remount it (review of 3d).
+  const boxed = card || (cardLead != null && cardLead !== false) || (state !== "ready" && !(state === "empty" && empty != null));
+
+  return (
+    <div className="ui-list-page">
+      <header className={`ui-list-page__head${back ? " ui-list-page__head--back" : ""}`}>
+        {back ? (
+          <Link href={back.href} className="ui-btn ui-btn--icon ui-list-page__back" aria-label={`Back to ${back.label}`} title={back.label}>
+            <Icon name="arrowLeft" />
+          </Link>
+        ) : null}
+        <div className="ui-list-page__title-row">
+          <h1 className="ui-list-page__title">{title}</h1>
+          {titleMeta}
+        </div>
+        {/* Its own cell: under the title from 768px up, across the whole header below (where the actions share the title's row). */}
+        {subtitle ? <p className="ui-list-page__subtitle">{subtitle}</p> : null}
+        {hasActions ? (
+          <div className="ui-list-page__actions">
+            {wide.map(button)}
+            {overflow.length || actionGroups.length ? <span className="ui-list-page__wide"><Menu label={wideMore} end className="ui-list-page__more">{overflow.map((a, i) => item(a, i))}{groups(overflow.length > 0)}</Menu></span> : null}
+            {secondaryActions.length || actionGroups.length ? <span className="ui-list-page__narrow"><Menu label="More actions" end className="ui-list-page__more">{secondaryActions.map((a, i) => item(a, i))}{groups(secondaryActions.length > 0)}</Menu></span> : null}
+            {primaryAction}
+          </div>
+        ) : null}
+      </header>
+      {/* ONE status region for the page, there in every state: a live region added with its words already in it is often not
+          read out, so the region stays and only its words change (review of 3d). */}
+      <span className="ui-sr-only" role="status">{state === "loading" ? loadingText : ""}</span>
+      {notices ? <div className="ui-list-page__notices">{notices}</div> : null}
+      {toolbar ? <div className="ui-list-page__toolbar">{toolbar}</div> : null}
+      {boxed ? (
+        <section {...cardProps} className={["ui-card ui-list-page__card", cardProps?.className].filter(Boolean).join(" ")}>
+          {cardTitle ? <div className="ui-list-page__card-head"><h2 className="ui-list-page__card-title">{cardTitle}</h2>{cardMeta}</div> : null}
+          {cardLead}
+          {body}
+        </section>
+      ) : (
+        // No card around a list that draws its own (a grid of cards): the heading stays, so it does not come and go with the state.
+        <>
+          {cardTitle ? <h2 className="ui-list-page__card-title ui-list-page__section-title">{cardTitle}</h2> : null}
+          {body}
+        </>
+      )}
+      {after}
+    </div>
+  );
+}

package/src/menu-extras.css

@@ -0,0 +1 @@
+.ui-menu__busy{width:16px;height:16px;box-sizing:border-box;border:2px solid currentColor;border-right-color:transparent;border-radius:50%;animation:ui-menu-busy .8s linear infinite}@keyframes ui-menu-busy{to{transform:rotate(360deg)}}@media (prefers-reduced-motion: reduce){.ui-menu__busy{animation-duration:2s}}.ui-menu__list{max-width:calc(100vw - 16px)}.ui-menu__item{flex-wrap:wrap}.ui-menu__hint{max-width:32ch;white-space:normal;text-align:right}.ui-menu:not([open])>.ui-menu__list{display:none}.ui-menu__check{display:inline-flex;flex:none;width:16px;height:16px;visibility:hidden}.ui-menu__item[aria-checked=true]>.ui-menu__check{visibility:visible}.ui-menu__item[aria-checked=true]{font-weight:600}.ui-menu__group-title{padding:6px 6px 2px;color:var(--ui-text-muted);font-size:var(--ui-fs-caption);line-height:16px}@media (pointer: coarse),(max-width: 47.9975em){.ui-menu__group-title{padding:8px 16px 4px}}

package/src/menu-keys.ts

@@ -0,0 +1,199 @@
+/**
+ * menu-keys.ts (23/10/2026): what a kit menu (`details.ui-menu`) does from the keyboard, and the page-wide rules every
+ * React menu shares. Used by `Menu` (menu.tsx) and `LanguageSwitcher`; menu-plain.js is the plain-HTML copy, and
+ * menu-browser.test.ts runs one script against both, so they cannot drift apart.
+ *
+ * - The list is `role="menu"` named by the trigger's label, its rows `role="menuitem"` out of the Tab order (tabindex -1):
+ *   the arrows move between them, not Tab. `armMenu` adds whatever hand-written markup leaves out.
+ * - An opening by a click, Enter or Space on the trigger, or ↓, puts focus on the first row that can act; ↑ on the last.
+ * - On a ROW (a field or a checkbox in the list keeps its own keys): ↓ ↑ move to the next / previous row that can act and
+ *   wrap; a disabled row (`disabled`, `aria-disabled="true"`) is skipped. Home / End: the first / last. Enter and Space
+ *   act on the row (a button does both natively, a link only Enter, so Space clicks a link row here).
+ * - Escape closes the menu and puts focus back on the trigger; it is taken (default prevented, propagation stopped), so a
+ *   popup holding the menu stays open. Tab closes it and lets focus go on from the trigger, forward or back.
+ * - One menu open at a time: opening one closes every other open `details.ui-menu` on the page, however it was opened
+ *   (a click, a key, a script), not only by a click outside, which a key never is. A menu that holds it stays open.
+ * - ONE set of page-wide listeners for every mounted React menu (`registerMenu`): a click outside closes it, Escape closes
+ *   it with focus back on its trigger, its toggle floats or sinks it. A 100-row table has 100 Menus, not 300 listeners.
+ */
+import { canFloatMenus, floatMenu, partsOf, sinkMenu } from "./menu-layer";
+
+/** A row of a kit menu. */
+export const MENU_ROW = ".ui-menu__item";
+const MENU = "details.ui-menu";
+
+/** The rows the keys land on: in the list, not disabled. */
+export function menuRows(d: HTMLDetailsElement, selector = MENU_ROW): HTMLElement[] {
+  const { list } = partsOf(d);
+  if (!list) return [];
+  return Array.from(list.querySelectorAll<HTMLElement>(selector)).filter((r) => !r.matches(':disabled, [aria-disabled="true"]'));
+}
+
+/** Gives a menu what `Menu` renders, where the markup has not said it already: `aria-haspopup` on the trigger, the list a
+ *  `menu` named by the trigger's label, each row a `menuitem` out of the Tab order. Never overwrites (LanguageSwitcher's
+ *  rows are `menuitemradio`). */
+export function armMenu(d: HTMLDetailsElement): void {
+  const { button, list } = partsOf(d);
+  if (button && !button.hasAttribute("aria-haspopup")) button.setAttribute("aria-haspopup", "menu");
+  if (!list) return;
+  if (!list.hasAttribute("role")) list.setAttribute("role", "menu");
+  if (!list.hasAttribute("aria-label") && !list.hasAttribute("aria-labelledby")) {
+    const name = button ? button.getAttribute("aria-label") || (button.textContent ?? "").trim() : "";
+    if (name) list.setAttribute("aria-label", name);
+  }
+  list.querySelectorAll<HTMLElement>(MENU_ROW).forEach((r) => {
+    if (!r.hasAttribute("role")) r.setAttribute("role", "menuitem");
+    if (!r.hasAttribute("tabindex")) r.setAttribute("tabindex", "-1");
+  });
+}
+
+/** Closes every other open kit menu (not one that holds `d`). */
+export function closeOtherMenus(d: HTMLDetailsElement): void {
+  document.querySelectorAll<HTMLDetailsElement>(`${MENU}[open]`).forEach((o) => {
+    if (o !== d && !o.contains(d)) o.open = false;
+  });
+}
+
+// Menus an opening has already closed the others for: the page-wide toggle listener skips them once, so the others are
+// closed once per opening, in the task of the click or key that opened it.
+const closedFor = new WeakSet<HTMLDetailsElement>();
+
+/** Opens a menu the way a click on its trigger does: the others close, it floats in the same task where it can. */
+export function openMenu(d: HTMLDetailsElement): void {
+  // (Already open: no toggle will come to use up the mark.)
+  if (!d.open) {
+    closeOtherMenus(d);
+    closedFor.add(d);
+    d.open = true;
+  }
+  armMenu(d);
+  if (canFloatMenus()) floatMenu(d);
+}
+
+/** Closes it; `focusTrigger` puts focus back on its button. */
+export function closeMenu(d: HTMLDetailsElement, focusTrigger = true): void {
+  d.open = false;
+  if (focusTrigger) partsOf(d).button?.focus();
+}
+
+/** Focus where an opening lands: the first row that can act, or the last. */
+export function focusRow(d: HTMLDetailsElement, which: "first" | "last", selector = MENU_ROW): void {
+  const rows = menuRows(d, selector);
+  (which === "first" ? rows[0] : rows[rows.length - 1])?.focus();
+}
+
+const mounted = new Set<HTMLDetailsElement>();
+let wired = false;
+/** The page-wide listeners, once: the one-open rule for every `details.ui-menu` (React or hand-written), and for the
+ *  menus `registerMenu` holds, the outside click, Escape and the float. */
+export function listenForMenus(): void {
+  if (wired || typeof document === "undefined") return;
+  wired = true;
+  const openMounted = () => Array.from(document.querySelectorAll<HTMLDetailsElement>(`${MENU}[open]`)).filter((d) => mounted.has(d));
+  document.addEventListener("click", (e) => {
+    for (const d of openMounted()) if (!d.contains(e.target as Node)) d.open = false;
+  });
+  document.addEventListener("keydown", (e) => {
+    // An Escape something else already took (a dialog over the page, a combobox) is not the menus' (review of #5179).
+    if (e.key !== "Escape" || e.isComposing || e.defaultPrevented) return;
+    const open = openMounted().reverse();
+    if (!open.length) return;
+    // Taken (default prevented), as kit-plain.js takes it: a dialog listening after this one, on the document or the window,
+    // must not close on the Escape that closed the menu. Focus on the ⋯ of a menu whose rows are all disabled closed the
+    // menu AND the admin's Modal or funnel popup around it (review of the admin's step 2, measured in Chromium): the menu
+    // was already shut when the dialog looked.
+    e.preventDefault();
+    // Innermost first, so focus ends on the outermost trigger that stays on screen.
+    for (const d of open) closeMenu(d);
+  });
+  document.addEventListener("toggle", (e) => {
+    const d = e.target as HTMLDetailsElement | null;
+    if (!d || typeof d.matches !== "function" || !d.matches(MENU)) return;
+    // A close uses up the mark too: an opening closed again before its toggle came left it, and the next opening skipped
+    // the one-open rule (review of #5179).
+    if (!d.open) { closedFor.delete(d); if (mounted.has(d)) sinkMenu(d); return; }
+    if (!closedFor.delete(d)) closeOtherMenus(d);
+    if (mounted.has(d)) {
+      if (canFloatMenus()) floatMenu(d);
+      armMenu(d);
+    }
+  }, true);
+}
+
+/** A mounted React menu joins the page-wide listeners; the return value takes it out (the effect's cleanup). */
+export function registerMenu(d: HTMLDetailsElement): () => void {
+  listenForMenus();
+  mounted.add(d);
+  return () => { mounted.delete(d); };
+}
+
+/** A keydown, native or React's. */
+export interface MenuKeyEvent {
+  key: string;
+  target: EventTarget | null;
+  defaultPrevented: boolean;
+  preventDefault(): void;
+  stopPropagation(): void;
+  isComposing?: boolean;
+  nativeEvent?: { isComposing?: boolean };
+}
+
+export interface MenuKeyOptions {
+  /** What a row is (default `.ui-menu__item`). Only a row's keys are the menu's. */
+  row?: string;
+  /** Where ↓ / ↑ on the trigger put focus (default: the first / the last row). LanguageSwitcher: the checked row. */
+  entry?: (d: HTMLDetailsElement, which: "first" | "last") => void;
+}
+
+/** The menu's keys, for a keydown inside `d` (its trigger or one of its rows). True when it took the key. */
+export function menuKeyDown(d: HTMLDetailsElement, e: MenuKeyEvent, o: MenuKeyOptions = {}): boolean {
+  if (e.defaultPrevented || e.isComposing || e.nativeEvent?.isComposing) return false;
+  const { button, list } = partsOf(d);
+  const t = e.target as HTMLElement | null;
+  // A key in a menu inside this one is that menu's.
+  if (!t || !button || !list || t.closest(MENU) !== d) return false;
+  const row = o.row ?? MENU_ROW;
+  const entry = o.entry ?? ((m, which) => focusRow(m, which, row));
+  if (t === button) {
+    // Tab from the button of an open menu: its rows are out of the Tab order, so focus would go on with the list still over
+    // the page. It closes, and focus goes on (not prevented), forward or back (review of #5179).
+    if (e.key === "Tab" && d.open) { closeMenu(d, false); return true; }
+    if (e.key !== "ArrowDown" && e.key !== "ArrowUp") return false;
+    e.preventDefault();
+    if (!d.open) openMenu(d);
+    entry(d, e.key === "ArrowUp" ? "last" : "first");
+    return true;
+  }
+  if (!d.open || !t.matches(row) || !list.contains(t)) return false;
+  if (e.key === "Escape") {
+    e.preventDefault();
+    e.stopPropagation();
+    closeMenu(d);
+    return true;
+  }
+  // Tab leaves: the menu closes and focus goes on from its button (not prevented), forward or back.
+  if (e.key === "Tab") { closeMenu(d); return true; }
+  const rows = menuRows(d, row);
+  const i = rows.indexOf(t);
+  if (e.key === " " && t.tagName === "A" && i > -1) { e.preventDefault(); t.click(); return true; }
+  const n = rows.length;
+  if (!n) return false;
+  const next = e.key === "ArrowDown" ? (i + 1) % n
+    : e.key === "ArrowUp" ? (i < 1 ? n - 1 : i - 1)
+      : e.key === "Home" ? 0 : e.key === "End" ? n - 1 : -1;
+  if (next < 0) return false;
+  e.preventDefault();
+  rows[next].focus();
+  return true;
+}
+
+/** A row was chosen (its click): focus goes back on the trigger BEFORE the row's own handler, so a popup it opens returns
+ *  focus there and not to a row about to be hidden; then the menu closes. Only when focus is in the menu: a row's handler
+ *  that moved focus on purpose keeps it. Returns the close to run after the handler. */
+export function chooseRow(row: Element): () => void {
+  const d = row.closest<HTMLDetailsElement>(MENU);
+  if (!d) return () => {};
+  const { button } = partsOf(d);
+  if (button && d.contains(document.activeElement)) button.focus();
+  return () => { d.open = false; };
+}

package/src/menu-layer.ts

@@ -24,7 +24,8 @@ export function canFloatMenus(): boolean {
   return typeof HTMLElement !== "undefined" && Object.prototype.hasOwnProperty.call(HTMLElement.prototype, "popover");
 }
 
-const partsOf = (d: HTMLDetailsElement) => ({
+/** A kit menu's two parts: its list and its button (the summary). menu-keys.ts reads them through this too. */
+export const partsOf = (d: HTMLDetailsElement) => ({
   list: d.querySelector<HTMLElement>(":scope > .ui-menu__list"),
   button: d.querySelector<HTMLElement>(":scope > summary"),
 });

package/src/menu-plain.js

@@ -0,0 +1 @@
+(function(m){"use strict";if(typeof document>"u")return;var l="details.ui-menu",d=".ui-menu__item",b=!1,a=null,s=function(e){return{list:e.querySelector(":scope > .ui-menu__list"),button:e.querySelector(":scope > summary")}},g=function(e){var t=m.gembossUI;t&&t.floatMenu&&t.floatMenu(e)},p=function(e,t){var n=e&&e.closest&&e.closest(t);return n&&n.closest(l)};function h(e){var t=s(e).list;return t?[].filter.call(t.querySelectorAll(d),function(n){return!n.matches(':disabled,[aria-disabled="true"]')}):[]}function c(e){var t=s(e),n=t.button,r=t.list,u=function(i,o,f){i&&f&&!i.hasAttribute(o)&&i.setAttribute(o,f)};u(n,"aria-haspopup","menu"),r&&(u(r,"role","menu"),r.hasAttribute("aria-labelledby")||u(r,"aria-label",n&&(n.getAttribute("aria-label")||n.textContent.trim())),r.querySelectorAll(d).forEach(function(i){u(i,"role","menuitem"),u(i,"tabindex","-1")}))}function y(e){document.querySelectorAll(l+"[open]").forEach(function(t){t!==e&&!t.contains(e)&&(t.open=!1)})}function A(e,t){var n=h(e);n.length&&n[t?n.length-1:0].focus()}function w(e){e.open=!1,s(e).button.focus()}var v=function(e){return e.matches(".gb-lang")};function E(){b||(b=!0,addEventListener("focusin",function(e){var t=p(e.target,l+" > summary");t&&c(t)},!0),addEventListener("click",function(e){var t=p(e.target,l+" > summary");t&&v(t)||(a=t&&!t.open?t:null,t&&c(t))},!0),addEventListener("click",function(e){a&&e.defaultPrevented&&!a.open&&(a=null)}),document.addEventListener("toggle",function(e){var t=e.target,n;if(!(!t.matches||!t.matches(l))){if(!t.open){a===t&&(a=null);return}y(t),!v(t)&&(c(t),n=s(t).list,a===t&&(a=null,g(t),n&&!n.contains(document.activeElement)&&A(t)))}},!0),document.addEventListener("keydown",function(e){var t=e.target,n=e.key,r=!e.defaultPrevented&&!e.isComposing&&p(t,l),u=r&&s(r);if(!(!u||!u.list||!u.button||v(r))){if(t===u.button){if(n==="Tab"&&r.open){r.open=!1;return}return n!=="ArrowDown"&&n!=="ArrowUp"?void 0:(e.preventDefault(),r.open||(y(r),r.open=!0,c(r),g(r)),A(r,n==="ArrowUp"))}if(!(!r.open||!t.matches(d)||!u.list.contains(t))){if(n==="Escape")return e.preventDefault(),e.stopPropagation(),w(r);if(n==="Tab")return w(r);var i=h(r),o=i.indexOf(t),f=i.length;if(n===" "&&t.tagName==="A"&&o>-1)return e.preventDefault(),t.click();o=n==="ArrowDown"?(o+1)%f:n==="ArrowUp"?(o<1?f:o)-1:n==="Home"?0:n==="End"?f-1:-1,!(o<0||!f)&&(e.preventDefault(),i[o].focus())}}}))}E(),m.gembossUI&&(m.gembossUI.initMenuKeys=E)})(globalThis);

package/src/menu.css

@@ -0,0 +1 @@
+.ui-btn--icon{flex:none;width:var(--ui-btn-h);padding:0}.ui-btn--icon svg{width:18px;height:18px}.ui-menu{position:relative;display:inline-block}.ui-menu>summary{list-style:none;cursor:pointer}.ui-menu>summary::-webkit-details-marker{display:none}.ui-menu__list{position:absolute;z-index:20;top:calc(100% + 4px);left:0;display:grid;min-width:220px;padding:6px;box-sizing:border-box}.ui-menu--end .ui-menu__list{left:auto;right:0}.ui-menu__list[popover]{position:fixed;inset:auto;margin:0;overflow:auto}.ui-menu__list[popover]:not(:popover-open){display:none}:where(.ui-menu__list[popover]){border:0;background:none;color:inherit}:root[data-gb-menus=float] .ui-menu[open]>.ui-menu__list:not([popover]){visibility:hidden}.ui-menu__item:is([disabled],[aria-disabled=true]){opacity:.5;cursor:not-allowed;pointer-events:none}.ui-menu__hint{margin-left:auto;padding-left:var(--ui-space-4);color:var(--ui-text-muted);font-size:var(--ui-fs-caption)}.ui-menu__sep{height:1px;margin:var(--ui-space-1) 0;border:0;background:var(--ui-border)}@media (pointer: coarse){.ui-btn--icon:not(.ui-btn--sm){min-width:44px}}@media (max-width: 47.9975em){.ui-btn--icon:not(.ui-btn--sm){min-width:44px;min-height:44px}}

package/src/menu.tsx

@@ -8,64 +8,96 @@
 // had no clean way to close it). The catalog renders its example from these components.
 // 0.18.0: the open list floats in the top layer (./menu-layer), so a table's scrolling frame no longer cuts it; it
 // closes when the page scrolls or the window resizes.
+// 23/10/2026: a menu's semantics and keys (./menu-keys, shared with LanguageSwitcher; menu-plain.js is the plain twin): the
+// list is `role="menu"` named by `label`, rows are `menuitem`s out of the Tab order, an opening puts focus on the first row
+// that can act, ↑ ↓ (wrapping, skipping disabled rows) Home End move, Escape closes with focus back on ⋯, Tab closes and
+// goes on; one menu open at a time. Its CSS is its own file (./menu.css), so a surface without the core (the admin) draws it.
+import "./menu.css";
+import "./menu-extras.css";
 import React, { useEffect, useRef } from "react";
 import { Icon } from "./icons";
 import { canFloatMenus, floatMenu, listenForDetachedMenus, sinkMenu } from "./menu-layer";
+import { chooseRow, closeMenu, focusRow, menuKeyDown, menuRows, openMenu, registerMenu } from "./menu-keys";
 
-/** The trigger is an icon button (`label` is its accessible name). `end` aligns the list to the right edge. */
-export function Menu({ label, icon, end, children, className }: {
+/** The trigger is an icon button (`label` is its accessible name, and the menu's). `end` aligns the list to the right edge.
+ *  `disabled`: the ⋯ takes no click and no key and leaves the Tab order (a row's work runs). `loading`: a ring in place of the
+ *  dots, `aria-busy`, and disabled the same way (what it started runs: a rename, a duplicate). */
+export function Menu({ label, icon, end, children, className, disabled, loading }: {
   label: string;
   icon?: React.ReactNode;
   end?: boolean;
   children?: React.ReactNode;
   className?: string;
+  disabled?: boolean;
+  loading?: boolean;
 }) {
   const ref = useRef<HTMLDetailsElement>(null);
+  const off = Boolean(disabled || loading);
+  // Turned off while open (its work started from a row): it closes, and focus that was in it goes back to ⋯, not to the page
+  // (review of the admin's step 2: on a row the close hid, the next Tab started from the top).
+  useEffect(() => {
+    const el = ref.current;
+    if (off && el?.open) { closeMenu(el, el.contains(document.activeElement)); sinkMenu(el); }
+  }, [off]);
   useEffect(() => {
     const el = ref.current;
     if (!el) return undefined;
-    const onDoc = (e: MouseEvent) => { if (el.open && !el.contains(e.target as Node)) el.open = false; };
-    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape" && el.open) { el.open = false; el.querySelector("summary")?.focus(); } };
-    const float = canFloatMenus();
-    const onToggle = () => { if (el.open) floatMenu(el); else sinkMenu(el); };
-    document.addEventListener("click", onDoc);
-    document.addEventListener("keydown", onKey);
-    if (float) {
-      el.addEventListener("toggle", onToggle);
-      // One page-wide pair of listeners for all menus (a 100-row table has 100 Menus), not one per menu.
+    // The outside click, Escape (focus back on ⋯), the float on its toggle and one menu open at a time: one page-wide set
+    // of listeners for every Menu (./menu-keys registerMenu), not three per menu.
+    const off = registerMenu(el);
+    if (canFloatMenus()) {
       listenForDetachedMenus();
       // Opened before this effect ran (a click during hydration): float it now.
       if (el.open) floatMenu(el);
     }
-    return () => {
-      document.removeEventListener("click", onDoc);
-      document.removeEventListener("keydown", onKey);
-      el.removeEventListener("toggle", onToggle);
-    };
+    return off;
   }, []);
-  // The summary toggles the menu itself and floats it in the same task, so the list is never painted inside the frame
-  // first (the details' own `toggle` event comes a task later). Nothing page-wide: kit-plain.js's `data-gb-menus` rule
-  // would hide a hand-written `details.ui-menu` on a React page that nobody floats.
+  // The summary opens the menu itself, floats it in the same task (so the list is never painted inside the frame first:
+  // the details' own `toggle` event comes a task later) and puts focus on its first row, with or without the popover API.
+  // Nothing page-wide: kit-plain.js's `data-gb-menus` rule would hide a hand-written `details.ui-menu` on a React page that
+  // nobody floats.
   const onSummary = (e: React.MouseEvent<HTMLElement>) => {
     const el = ref.current;
-    if (!el || !canFloatMenus()) return;
+    if (!el) return;
     e.preventDefault();
-    el.open = !el.open;
-    if (el.open) floatMenu(el); else sinkMenu(el);
+    if (off) return;
+    if (el.open) { el.open = false; sinkMenu(el); return; }
+    openMenu(el);
+    enter(el, "first");
   };
   return (
-    <details ref={ref} className={["ui-menu", end ? "ui-menu--end" : "", className ?? ""].filter(Boolean).join(" ")}>
-      <summary className="ui-btn ui-btn--icon" aria-label={label} title={label} onClick={onSummary}>{icon ?? <Icon name="more" />}</summary>
-      <div className="ui-menu__list gemboss-popover-surface">{children}</div>
+    <details ref={ref} className={["ui-menu", end ? "ui-menu--end" : "", className ?? ""].filter(Boolean).join(" ")}
+      onKeyDown={(e) => { if (ref.current && !off) menuKeyDown(ref.current, e, { entry: enter }); }}
+      // Opened while off by anything but its button (find-in-page opens a closed details that holds a match, a script):
+      // closed again.
+      onToggle={(e) => { if (off && e.currentTarget.open) e.currentTarget.open = false; }}>
+      <summary className="ui-btn ui-btn--icon" aria-label={label} title={label} aria-haspopup="menu" onClick={onSummary}
+        aria-disabled={off || undefined} aria-busy={loading || undefined} tabIndex={off ? -1 : undefined}>
+        {loading ? <span className="ui-menu__busy" aria-hidden="true" /> : (icon ?? <Icon name="more" />)}
+      </summary>
+      <div className="ui-menu__list gemboss-popover-surface" role="menu" aria-label={label}>{children}</div>
     </details>
   );
 }
 
 /** One row: a link (`href`) or a button. `hint` is the quiet text on the right; `danger` for destructive rows.
  *  A disabled link is not a link: no href, aria-disabled, out of the tab order (an `<a disabled>` still follows
- *  on Enter). A caller's `className` is added to the row's class, not put in its place. */
-export function MenuItem({ href, danger, hint, children, className, disabled, onClick, ...rest }: {
+ *  on Enter). A caller's `className` is added to the row's class, not put in its place. `linkAs` draws a link row with
+ *  the app's link (Next's Link), so a row and a button with the same URL navigate the same way (ListPage). */
+/** Where an opening puts focus: a menu whose rows are all choices (MenuItem `checked`) opens on the one that is on, as
+ *  LanguageSwitcher does; any other menu on its first (or, from ↑, its last) row. */
+function enter(el: HTMLDetailsElement, which: "first" | "last"): void {
+  const rows = menuRows(el);
+  const on = rows.length > 0 && rows.every((r) => r.getAttribute("role") === "menuitemradio")
+    ? rows.find((r) => r.getAttribute("aria-checked") === "true") : undefined;
+  if (on) on.focus(); else focusRow(el, which);
+}
+
+export function MenuItem({ href, danger, hint, children, className, disabled, onClick, linkAs, checked, ...rest }: {
   href?: string;
+  /** A choice among others (in a MenuGroup): `menuitemradio`, a check before the one that is on. Left out: a plain row. */
+  checked?: boolean;
+  linkAs?: React.ElementType;
   danger?: boolean;
   hint?: React.ReactNode;
   children?: React.ReactNode;
@@ -73,16 +105,32 @@ export function MenuItem({ href, danger, hint, children, className, disabled, on
   onClick?: React.MouseEventHandler<HTMLElement>;
 } & Omit<React.HTMLAttributes<HTMLElement>, "onClick"> & Pick<React.AnchorHTMLAttributes<HTMLAnchorElement>, "target" | "rel">) {
   const cls = ["ui-menu__item", danger ? "ui-menu__item--danger" : "", className ?? ""].filter(Boolean).join(" ");
-  const body = <>{children}{hint ? <span className="ui-menu__hint">{hint}</span> : null}</>;
+  const choice = checked === undefined ? { role: "menuitem" } : { role: "menuitemradio", "aria-checked": checked };
+  const body = <>{checked === undefined ? null : <span className="ui-menu__check" aria-hidden="true"><Icon name="check" size={16} /></span>}
+    {children}{hint ? <span className="ui-menu__hint">{hint}</span> : null}</>;
+  // Every row closes its menu once chosen, a link too (a new tab, an anchor, a client router leave the page as it was).
+  // Focus is back on ⋯ before the row's handler runs (./menu-keys chooseRow).
+  const choose: React.MouseEventHandler<HTMLElement> = (e) => {
+    const close = chooseRow(e.currentTarget);
+    try { onClick?.(e); } finally { close(); }
+  };
   if (href) {
-    if (disabled) return <a className={cls} aria-disabled="true" tabIndex={-1} {...rest}>{body}</a>;
-    return <a className={cls} href={href} onClick={onClick} {...rest}>{body}</a>;
+    if (disabled) return <a className={cls} {...choice} aria-disabled="true" tabIndex={-1} {...rest}>{body}</a>;
+    const A = linkAs ?? "a";
+    return <A className={cls} href={href} {...choice} tabIndex={-1} onClick={choose} {...rest}>{body}</A>;
   }
-  const close: React.MouseEventHandler<HTMLButtonElement> = (e) => {
-    onClick?.(e);
-    e.currentTarget.closest("details")?.removeAttribute("open");
-  };
-  return <button type="button" className={cls} disabled={disabled} onClick={close} {...rest}>{body}</button>;
+  return <button type="button" className={cls} {...choice} tabIndex={-1} disabled={disabled} onClick={choose} {...rest}>{body}</button>;
+}
+
+/** Rows that are choices of one kind (Products' Auto-refresh: Daily, Off), named: `role="group"` with the title as its name,
+ *  and the title shown above them. Its rows are MenuItems with `checked`. */
+export function MenuGroup({ title, children }: { title: string; children?: React.ReactNode }) {
+  return (
+    <div className="ui-menu__group" role="group" aria-label={title}>
+      <div className="ui-menu__group-title" aria-hidden="true">{title}</div>
+      {children}
+    </div>
+  );
 }
 
 export function MenuSeparator() {

package/src/pager-extras.css

@@ -0,0 +1 @@
+.ui-pager>button{display:inline-flex;align-items:center;justify-content:center;box-sizing:border-box;gap:4px;min-width:32px;min-height:32px;padding:0 12px;border:1px solid var(--ui-border);border-radius:var(--ui-radius-md);background:none;color:var(--ui-text);font:inherit;font-size:var(--ui-fs-body);cursor:pointer}.ui-pager>button:hover{background:var(--ui-surface-2)}.ui-pager>button:focus-visible{outline:2px solid var(--p-color-border-focus, var(--ui-focus));outline-offset:1px}.ui-pager>button[aria-current=page]{background:var(--ui-text);border-color:var(--ui-text);color:var(--ui-surface);font-size:var(--ui-fs-body);font-weight:600;cursor:default}.ui-pager>button[aria-disabled=true]{cursor:default}@media (pointer: coarse),(max-width: 47.9975em){.ui-pager>button{min-width:44px;min-height:44px}}@media (max-width: 35.9975em){.ui-pager>button:not([data-rel]):not([aria-current]){display:none}}@media (max-width: 35.9975em){.ui-pager>a[aria-disabled=true]:not([data-rel]):not([aria-current]){display:none}}.ui-pager.ui-pager--flush{margin-block:0}