staffa 0.15.0 → 0.17.0

package/dist/components/menu.js

@@ -4,68 +4,79 @@ import { drawSlot, mountPortal, focusFirst } from "../core.js";
 import { menu as menuIcon, chevronRight, externalLink as newTabIcon, link as linkIcon } from "../icons.js";
 import { button } from "./button.js";
 import { toast } from "./toast.js";
-// Styles shared by the floating dropdown and the sidebar nav, so both look
-// identical. The item styles aren't scoped to a container, so `drawMenu` can
-// render its items into either one.
+import { addTooltip } from "./tooltip.js";
+import { bindKey, formatKey } from "../keys.js";
+// Styles shared by the floating dropdown and the sidebar nav. The item styles
+// aren't scoped to a container, so `drawMenu` can render into either one.
 A.insertGlobalCss({
-    // Border comes from the `.s-s.neutral` surface; the panel only overrides the radius
-    // (lg) and opts into elevation via `.shadow` (added on the element below).
-    // `visibility` rides the same transition as the fade (flipping only at its
-    // end, per CSS visibility interpolation): a dismissed menu lingers in the
-    // DOM for a while — Aberdeen's `destroy=` removes it on a timer, not at
-    // the transition's end — and without this it would spend that time
-    // invisible yet still hittable by tests and read by assistive tech.
+    // On dismissal (the `.hidden` rule below), `visibility` rides the fade,
+    // flipping only at its end: a dismissed menu lingers in the DOM (`destroy=`
+    // removes it on a timer), and without this it would spend that time invisible
+    // yet still hittable and read by assistive tech. On entry it must flip
+    // instantly (`0s` here) instead: a hidden element refuses focus, so the
+    // menu's own opening focus() would silently fail mid-fade-in.
     ".s-menu-list": "position:fixed z-index:350 min-width:10rem display:flex flex-direction:column p:$1 " +
         "r:$s-radius-lg " +
-        // The 16px off max-width is the 8px gap `positionMenu` leaves at either
-        // window edge: in a window too narrow for the menu, it narrows rather
-        // than hanging off the screen. (A `min-width` from the caller still wins,
-        // as CSS says it must — that ask is the app's to keep sensible.)
+        // The 16px matches the 8px gap `positionMenu` leaves at either window edge, so
+        // a menu too wide for the window narrows instead of hanging off the screen.
         "max-width: calc(100vw - 16px); overflow-y:auto max-height:min(80vh,28rem) " +
+        "transition: opacity 0.15s, transform 0.15s, visibility 0s;",
+    ".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px) visibility:hidden " +
         "transition: opacity 0.15s, transform 0.15s, visibility 0.15s;",
-    ".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px) visibility:hidden",
-    // One class for both the `<a>` (link) and `<button>` forms — they look
-    // identical; the element only differs where link semantics matter (see below).
-    // The scroll-margin keeps a revealed row (see the scrollIntoView in
-    // `drawMenu`) a little clear of the scrollport edge, instead of flush to it.
-    ".s-menu-item": "display:flex align-items:center gap:$2 w:100% outline:0 scroll-margin:$2 " +
+    // One class for both the `<a>` and `<button>` forms. The scroll-margin keeps a
+    // revealed row (the scrollIntoView in `drawLeaf`) clear of the scrollport edge.
+    ".s-menu-item": "display:flex align-items:center gap:$2 w:100% scroll-margin:$2 " +
         "padding: $m2 0; line-height:1.1 r:$s-radius cursor:pointer text-align:left font-weight:450 " +
         "font-size:0.9em border:0 background:transparent fg:$s-text text-decoration:none " +
         "transition: color 0.12s, transform 0.12s, text-shadow 0.12s;",
     ".s-menu-item:focus-visible:not([aria-current=page]), .s-menu-item:hover:not([aria-disabled=true]):not([aria-current=page])": "filter:none color: color-mix(in lab, $s-primary 33%, $s-text);",
-    // The active row is simply drawn in the surface's accent — the brand colour on a
-    // neutral surface, the ink on an accent one. No glow and no brightening: those
-    // pushed it off the brand colour, so it read as a lit-up variant of it rather
-    // than as the colour itself. `filter:none` keeps the global `a:hover` brighten
-    // off it too, since the hover rule above deliberately skips the active row.
+    // Arrowing through a list is aiming blind unless the row you are on says so, and
+    // the hover colour alone doesn't — least of all on the current-page row, which
+    // already wears the accent. So: a tinted band, plus the theme's focus ring, inset
+    // because a row runs the full width of its list and an outset ring would clip.
+    ".s-menu-item:focus-visible": "outline-offset:-2px background: color-mix(in srgb, $s-accent 14%, transparent);",
+    // The active row is simply drawn in the surface's accent — no glow, no brightening.
+    // `filter:none` also keeps the global `a:hover` brighten off it.
     ".s-menu-item[aria-current=page]": "color:$s-accent filter:none",
-    // Inside a floating dropdown the rows carry their own horizontal padding:
-    // the panel's thin `$1` inset alone leaves labels nearly touching its edge.
-    // (Sidebar rows stay flush — their panel brings the breathing room.)
+    // Dropdown rows bring their own horizontal padding; the panel's thin `$1` inset
+    // alone leaves labels nearly touching its edge. Sidebar rows stay flush.
     ".s-menu-list .s-menu-item": "padding-inline:$2",
     ".s-menu-item[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none",
     ".s-menu-icon": "flex-shrink:0",
-    // A floating menu sizes its glyphs, as `.s-btn` and `.s-icon-btn` do (see
-    // button.ts): icons come out of the set at 24px, which towers over a 0.9em
-    // dropdown row. Riding the font size keeps it in step with the label.
-    // Scoped to `.s-menu-list` deliberately: `S.main`'s nav is a roomier thing
-    // than a dropdown — its rows are built around the icon at the size it was
-    // drawn, and shrinking it there tightened the whole sidebar.
+    // Icons come out of the set at 24px, towering over a 0.9em dropdown row; riding
+    // the font size keeps them in step with the label. Scoped to `.s-menu-list`:
+    // `S.main`'s nav rows are built around the icon at the size it was drawn.
     ".s-menu-list .s-menu-icon": "display:flex",
     ".s-menu-list .s-menu-icon > svg": "width:1.25em height:1.25em",
-    // A soft hairline that fades out at both ends, rather than a hard full-width
-    // rule — quieter, and it reads as a grouping cue instead of a divider bar.
-    // `hr.` (not just `.`) so this wins over the global hr flow-margin rule.
+    // A hairline that fades out at both ends, reading as a grouping cue rather than a
+    // divider bar. `hr.` (not just `.`) so this wins over the global hr flow-margin rule.
     "hr.s-menu-sep": "border:0 height:1px margin: $1 0.6rem; " +
         "background: linear-gradient(to right, transparent, $s-faint 18%, $s-faint 82%, transparent);",
-    // A branch row's fold indicator: a › that turns downward while the branch is
-    // open. It rides the row's font size, like the leading icons do.
+    // The shortcut hint (see `MenuItem.key`): pushed to the right end of the row, and
+    // kept quiet — it is there to be found, not read. In the row's own colour at a low
+    // opacity, so it follows the row through hover and the current-page accent.
+    ".s-menu-key": "margin-left:auto padding-left:$2 font-family:inherit font-size:0.8em opacity:0.55 white-space:nowrap flex-shrink:0",
+    // A touch device gets no hint: a row advertising a key there is mostly noise.
+    // These describe the *primary* input, so a laptop with a touchscreen keeps its
+    // hints. The shortcuts stay bound whatever the device says — a keyboard clipped
+    // onto a tablet works, it just isn't advertised.
+    "@media (hover: none) and (pointer: coarse)": {
+        ".s-menu-key": "display:none",
+    },
+    // A nav row's key rides its tooltip instead (see `drawHints`): a quiet line of
+    // its own, under the item's tip content when it has one, split off by the
+    // menu's own fading hairline.
+    ".s-menu-tt-key": "font-family:inherit font-size:0.85em opacity:0.7 white-space:nowrap",
+    ".s-tt-tip hr.s-menu-sep": "margin: 0.35em 0;",
+    // A branch row's fold indicator: a › that turns downward while the branch is open.
     ".s-menu-chevron": "margin-left:auto flex-shrink:0 display:flex transition: transform 0.15s ease;",
+    // Two `margin-left:auto`s in one row would split the free space between them,
+    // stranding the hint in the middle; the hint's is the one that should win.
+    ".s-menu-key + .s-menu-chevron": "margin-left:0",
     ".s-menu-chevron > svg": "width:1em height:1em",
-    // A branch is a native <details>: closed content is *hidden*, not unmounted,
-    // so folding is one attribute flip — no teardown, no sibling redraws — and
-    // the browser animates the height natively via `::details-content` (with
-    // `interpolate-size`; engines without it simply snap, which is fine).
+    // A branch is a native <details>: closed content is hidden, not unmounted, so a fold
+    // is one attribute flip — no teardown, no sibling redraws — and the browser animates
+    // the height via `::details-content` (engines without `interpolate-size` just snap).
     ".s-menu-details": {
         "> summary": "list-style:none",
         "> summary::-webkit-details-marker": "display:none",
@@ -76,8 +87,7 @@ A.insertGlobalCss({
     },
     // A branch's children: indented one step.
     ".s-menu-sub": "display:flex flex-direction:column gap:$1 padding-left:$3",
-    // The standalone `menu()` component's list. The rows style themselves (they
-    // are `.s-menu-item`s like everywhere else); this only stacks them.
+    // The standalone `menu()` component's list; the rows style themselves.
     ".s-menu-inline": "display:flex flex-direction:column gap:$1",
 });
 /**
@@ -96,15 +106,17 @@ A.insertGlobalCss({
  * @param onLeafSelect Optional — run when a *leaf* item is activated (used by
  *   the floating menu to close itself on selection). A branch expanding is
  *   not a selection, so it doesn't run this.
+ * @param keyHints Print each row's `key` at its right end, as the floating
+ *   menus do. Off — any kind of nav — a row tells its key in its tooltip
+ *   instead, keeping the resting rows quiet.
  */
-export function drawMenu(items, onLeafSelect) {
+export function drawMenu(items, onLeafSelect, keyHints) {
     // Roving focus via the DOM: query the live item elements on each keypress.
     A("keydown=", (e) => {
-        // Link items navigate through interceptLinks' own Enter handler, which
-        // preventDefault()s the activation — so no synthetic `click` fires, and the
-        // click-bound `onLeafSelect` (which closes a floating menu) never runs. Close it
-        // ourselves, deferred so this keydown finishes dispatching (and navigates) first.
-        if (e.key === "Enter" && e.target.tagName === "A") {
+        // interceptLinks' own Enter handler preventDefault()s the activation, so no
+        // synthetic `click` fires and the click-bound `onLeafSelect` never runs. Close
+        // it ourselves, deferred so this keydown finishes navigating first.
+        if (e.key === "Enter" && !e.ctrlKey && !e.metaKey && !e.shiftKey && !e.altKey && e.target.tagName === "A") {
             queueMicrotask(() => onLeafSelect?.());
             return;
         }
@@ -124,15 +136,16 @@ export function drawMenu(items, onLeafSelect) {
                     (cur + dir + els.length) % els.length;
         els[next].focus();
     });
-    // Whether the current page is in this menu *at all*, shared by every branch
-    // below: a navigation to a page the menu doesn't hold must leave the folds
-    // alone (see `drawBranch`), and that is a fact about the whole menu, which
-    // no branch can tell on its own. Derived, so the branches re-run only when
-    // the answer flips — not on every navigation between two held pages.
-    const $menuHasCurrent = A.derive(() => anyCurrent(items));
-    drawEntries(items, onLeafSelect, $menuHasCurrent);
+    drawEntries(items, {
+        onLeafSelect,
+        keyHints,
+        // Whether the current page is in this menu *at all* — a fact no single
+        // branch can tell, and one the fold logic needs (see `drawBranch`).
+        // Derived, so branches re-run only when the answer flips.
+        $hasCurrent: A.derive(() => anyCurrent(items)),
+    });
 }
-function drawEntries(items, onLeafSelect, $menuHasCurrent) {
+function drawEntries(items, ctx) {
     for (const entry of items) {
         if (typeof entry === "string" || typeof entry === "function") {
             drawSlot(entry);
@@ -143,23 +156,18 @@ function drawEntries(items, onLeafSelect, $menuHasCurrent) {
             continue;
         }
         if (entry.items)
-            drawBranch(entry, onLeafSelect, $menuHasCurrent);
+            drawBranch(entry, ctx);
         else
-            drawLeaf(entry, onLeafSelect);
+            drawLeaf(entry, ctx);
     }
 }
-function drawLeaf(entry, onLeafSelect) {
-    // Whether the aria-current scope below has run before: it re-runs on
-    // every navigation, and only a *later* one should animate the reveal.
+function drawLeaf(entry, ctx) {
+    // Whether the aria-current scope below has run before: only a *later* run
+    // should animate the reveal.
     let drawn = false;
-    // `data-panel=open` because a menu row is navigation, not a link in the
-    // content: it leads somewhere else in the app, and the panel it was clicked
-    // from isn't the context to keep. A floating dropdown (portalled to the
-    // body) and `S.main()`'s sidebar are outside every panel and behave this way
-    // already; saying it outright makes an inline `menu()` — which may well sit
-    // *inside* a panel — behave the same wherever it's drawn. `attrs` comes
-    // after, so an item that really does want to stack can say
-    // `attrs: "data-panel=push"`.
+    // `data-panel=open`: a menu row is navigation, not a link in the content, so the
+    // panel it was clicked from isn't context to keep — including for an inline `menu()`
+    // drawn inside one. `attrs` comes after, so a row can opt into `data-panel=push`.
     const itemEl = A(entry.href ? "a.s-menu-item data-panel=open" : "button.s-menu-item type=button", entry.attrs, () => {
         if (entry.href) {
             A("href=", entry.href);
@@ -171,38 +179,34 @@ function drawLeaf(entry, onLeafSelect) {
                 if (!isCurrent(entry))
                     return;
                 A("aria-current=page");
-                // A list taller than its scrollport (a long sidebar nav, mostly)
-                // highlights nothing when the current row is scrolled out of it,
-                // so bring the row into view — no further than needed, and not
-                // at all when it's already visible. A row that *starts out*
-                // current arrives at the right place (a cold deep link lands
-                // with the sidebar already there); when a navigation moves the
-                // highlight later, the scroll follows it smoothly. rAF, so a
-                // fresh row is laid out before it's measured.
+                // In a list taller than its scrollport (a long sidebar nav), the current
+                // row can be scrolled out of sight; bring it back — jumping on the first
+                // run, gliding on later ones. rAF, so a fresh row is laid out first.
                 requestAnimationFrame(() => itemEl.scrollIntoView({ block: "nearest", behavior: first ? "instant" : "smooth" }));
             });
         }
         if (entry.disabled)
             A("aria-disabled=true");
+        if (entry.key)
+            A("aria-keyshortcuts=", formatKey(entry.key, true));
         A("click=", (e) => {
             if (entry.disabled) {
                 e.preventDefault();
                 return;
             }
-            onLeafSelect?.();
+            ctx.onLeafSelect?.();
             entry.click?.(e);
         });
         if (entry.icon)
             A("span.s-menu-icon", () => drawSlot(entry.icon));
         drawSlot(entry.label);
+        drawHints(entry, ctx);
     });
 }
 /**
- * The last route-derived fold state of every linked branch, keyed by the
- * branch's selection href. Module-level on purpose: the phone's full-page nav
- * (and any dropdown) mounts a fresh menu every time it opens, and per-mount
- * state would hand it three folded sections in the middle of the user's work.
- * Bounded by the number of distinct branch hrefs an app ever shows.
+ * Last route-derived fold state per linked branch, keyed by its selection href.
+ * Module-level on purpose: menus remount (the phone's full-page nav exists only
+ * while it is open), and per-mount state would refold every section mid-task.
  */
 const foldMemory = new Map();
 function setFold(href, open) {
@@ -211,35 +215,26 @@ function setFold(href, open) {
 }
 /**
  * A branch: a native `<details>` folding a sub-list of entries in and out. The
- * children stay mounted whether folded or not — closing hides them, it doesn't
- * tear them down — so a fold is a single `open` flip that the browser animates
- * itself, and nothing around it redraws.
+ * children stay mounted whether folded or not, so a fold is a single `open` flip
+ * and nothing around it redraws.
  *
- * Clicking the summary row *selects* rather than toggles when there is a page
- * to select (the branch's own `href`, or the first linked leaf below it): it
- * navigates there, and the navigation is what unfolds the branch, since a
- * linked branch is open exactly while it holds the current page. Only a branch
- * with no link anywhere below it keeps the native open/close toggle.
+ * Clicking the summary row *selects* rather than toggles when there is a page to
+ * select (the branch's own `href`, or the first linked leaf below it): it navigates,
+ * and the navigation is what unfolds the branch, since a linked branch is open
+ * exactly while it holds the current page. Only a branch with no link anywhere below
+ * it keeps the native toggle.
  */
-function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
+function drawBranch(entry, ctx) {
     const href = entry.href ?? firstLeafHref(entry.items);
-    // The route-derived fold state, as a derived boolean so the attribute scope
-    // below re-runs only when the answer flips — not on every navigation that
-    // merely moves *between* pages inside the branch. When the current page is
-    // nowhere in the menu, nothing has an opinion, and the fold simply keeps
-    // its last state — folding everything up would answer a question nobody
-    // asked with a menu that forgot where the user was.
-    //
-    // "Last state" lives in `foldMemory`, not in this closure: menus remount —
-    // the phone's full-page nav exists only while it is open — and a remount
-    // must find the state where the previous mount left it. It is keyed on the
-    // branch's selection href, so the sidebar and the phone nav (two renderings
-    // of the same items) share one truth, however often either is rebuilt.
+    // Derived, so the attribute scope below re-runs only when the fold answer flips.
+    // When the current page is nowhere in the menu, nothing has an opinion and the fold
+    // keeps its last state — kept in `foldMemory` rather than this closure, since menus
+    // remount, and keyed on the href so both renderings of the items share one truth.
     const $open = href != null
         ? A.derive(() => {
             if (containsCurrent(entry))
                 return setFold(href, true);
-            if ($menuHasCurrent == null || $menuHasCurrent.value)
+            if (ctx.$hasCurrent.value)
                 return setFold(href, false);
             return foldMemory.get(href) ?? false;
         })
@@ -253,10 +248,11 @@ function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
         A("summary.s-menu-item.s-menu-branch", entry.attrs, () => {
             if (entry.disabled)
                 A("aria-disabled=true");
+            if (entry.key)
+                A("aria-keyshortcuts=", formatKey(entry.key, true));
             A(() => {
-                // Current only on its *own* page (its `href`, or a `match` claim —
-                // pages with no row of their own): when a descendant is current, that
-                // row carries the highlight, and two highlights would read as two pages.
+                // Current only on its *own* page: when a descendant is current, that row
+                // carries the highlight, and two highlights would read as two pages.
                 if (isCurrent(entry))
                     A("aria-current=page");
             });
@@ -277,15 +273,16 @@ function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
             if (entry.icon)
                 A("span.s-menu-icon", () => drawSlot(entry.icon));
             drawSlot(entry.label);
+            drawHints(entry, ctx);
             A("span.s-menu-chevron aria-hidden=true", () => chevronRight());
         });
-        A("div.s-menu-sub", () => drawEntries(entry.items, onLeafSelect, $menuHasCurrent));
+        A("div.s-menu-sub", () => drawEntries(entry.items, ctx));
     });
 }
 /**
- * Whether a row sits inside a closed branch. A closed `<details>` hides its
- * content without unmounting it, so arrow-key navigation has to skip what the
- * user can't see — while the closed branch's own summary row stays reachable.
+ * Whether a row sits inside a closed branch. A closed `<details>` hides its content
+ * without unmounting it, so arrow-key navigation must skip it — but not the closed
+ * branch's own summary row.
  */
 function foldedAway(el) {
     for (let details = el.closest("details"); details; details = details.parentElement && details.parentElement.closest("details")) {
@@ -295,18 +292,17 @@ function foldedAway(el) {
     return false;
 }
 /**
- * Whether any item anywhere in `items` — branches, their leaves, `match`
- * claims — is the current page. The one question both the fold logic and the
- * shell's tagline rule (see `taglineFits` in main.ts) ask of a menu, exported
- * so the two can never disagree with the highlighting.
+ * Whether any item anywhere in `items` — branches, their leaves, `match` claims — is
+ * the current page. Exported because the shell's tagline rule (`taglineFits` in
+ * main.ts) must agree with the highlighting.
  */
 export function anyCurrent(items) {
     return items.some((entry) => typeof entry !== "string" && typeof entry !== "function" && !("separator" in entry) && containsCurrent(entry));
 }
 /**
- * Whether this item is the current page: its own `href` matches, or its
- * `match` claims the current path. The single test behind `aria-current`,
- * branch unfolding, and {@link anyCurrent} — one truth, three consumers.
+ * Whether this item is the current page: its own `href` matches, or its `match`
+ * claims the current path. The single test behind `aria-current`, branch unfolding
+ * and {@link anyCurrent}.
  */
 function isCurrent(entry) {
     if (entry.href != null && matchCurrent(entry.href))
@@ -343,12 +339,95 @@ function firstLeafHref(items) {
     }
     return undefined;
 }
+// ─── Keyboard shortcuts ──────────────────────────────────────────────────────
+/**
+ * A row's shortcut hint and tooltip. In a floating menu the shortcut sits at
+ * the right end of the row; a nav row keeps its label clean and tells it in
+ * its tooltip instead — under the item's own `tooltip` content, when it has
+ * one, behind a subtle hairline. See {@link MenuItem.key}.
+ */
+function drawHints(entry, ctx) {
+    const tipKey = ctx.keyHints ? undefined : entry.key;
+    // `aria-hidden`: the row already carries the shortcut as `aria-keyshortcuts`,
+    // which is what a screen reader reads out — the hint is the sighted half.
+    if (entry.key && !tipKey)
+        A("kbd.s-menu-key aria-hidden=true text=", formatKey(entry.key));
+    if (entry.tooltip == null && !tipKey)
+        return;
+    addTooltip({
+        placement: "right",
+        tip: () => {
+            drawSlot(entry.tooltip);
+            if (tipKey) {
+                if (entry.tooltip != null)
+                    A("hr.s-menu-sep");
+                A("kbd.s-menu-tt-key aria-hidden=true text=", formatKey(tipKey));
+            }
+        },
+    });
+}
+/**
+ * Bind the shortcuts of every item in a menu — see {@link MenuItem.key} — for as
+ * long as the calling scope lives. The `?` overview lists each binding under its
+ * item's label. No `aria-keyshortcuts` here — the rows announce their own.
+ *
+ * `getItems` is a function rather than the array itself, so that the read happens
+ * in this scope and not the caller's: a menu's items are often a reactive array,
+ * and subscribing the caller (`S.main()`'s whole shell, say) to it would redraw
+ * far more than the menu.
+ */
+export function registerMenuKeys(getItems, onSelect) {
+    A(() => {
+        for (const entry of withKeys(getItems(), [])) {
+            bindKey(entry.key, entry.label, (e) => {
+                // Picking a row from the keyboard is still picking a row: any menu that
+                // happens to be up steps out of the way, as it would on a click.
+                closeFloatingMenu();
+                onSelect?.();
+                entry.click?.(e);
+                if (entry.href != null)
+                    followHref(entry.href, entry.target);
+            });
+        }
+    });
+}
+/**
+ * Every item with a key worth binding, branches and their children included. A
+ * disabled one is left out rather than bound and ignored, so its combination
+ * stays free — and since `disabled` is read here, flipping it rebinds.
+ */
+function withKeys(items, out) {
+    for (const entry of items) {
+        if (typeof entry === "string" || typeof entry === "function" || "separator" in entry)
+            continue;
+        if (entry.key && !entry.disabled)
+            out.push(entry);
+        if (entry.items)
+            withKeys(entry.items, out);
+    }
+    return out;
+}
+/**
+ * Follow a row's `href` from the keyboard. The row may not even be drawn, so this
+ * can't just click it — it does what clicking it would: routing an ordinary in-app
+ * path, which lands where the row's own `data-panel=open` does (the target getting
+ * its own stack of columns, as a nav item's target does), and leaving the links
+ * Aberdeen doesn't intercept either — another target, another origin — to the
+ * browser.
+ */
+function followHref(href, target) {
+    const url = new URL(href, location.href);
+    if (target)
+        window.open(url.href, target, target === "_blank" ? "noopener" : "");
+    else if (url.origin !== location.origin)
+        location.href = url.href;
+    else
+        void go(href);
+}
 // ─── Branch navigations ──────────────────────────────────────────────────────
-// The floating menu and `S.main()`'s collapsed nav dismiss themselves when the
-// page navigates — but a branch row navigates *in order to expand*, and
-// dismissing over that would close the menu the user is in the middle of
-// opening up. So a branch click leaves a note of where it is headed, and the
-// dismiss-on-navigation checks consume it.
+// Menus dismiss themselves when the page navigates — but a branch row navigates in
+// order to expand, and dismissing over that would close the menu mid-unfold. So a
+// branch click leaves a note of where it is headed; the dismiss checks consume it.
 let branchNavPath = null;
 function noteBranchNav(href) {
     try {
@@ -414,8 +493,8 @@ function positionMenu(menuEl, rect) {
 }
 /**
  * The standard entries for the link a menu stands on (see
- * {@link FloatingMenuOptions.link}). "Open in new tab" is a real new tab, so
- * the target arrives cold, exactly as the link middle-clicked would.
+ * {@link FloatingMenuOptions.link}). "Open in new tab" is a real new tab, so the
+ * target arrives cold, exactly as the link middle-clicked would.
  */
 function linkItems(href) {
     return [
@@ -424,10 +503,9 @@ function linkItems(href) {
     ];
 }
 /**
- * Put the link's address on the clipboard, as the absolute URL someone can
- * paste anywhere — what the browser's own "Copy link" would have given them.
- * Confirmed with a toast, since a silent copy leaves you wondering; `writeText`
- * needs a secure context, so a failure says so rather than lying.
+ * Copy the link's absolute URL to the clipboard, confirmed with a toast since a
+ * silent copy leaves you wondering. `writeText` needs a secure context, so a failure
+ * says so rather than lying.
  */
 async function copyLink(href) {
     const url = new URL(href, location.href).href;
@@ -446,7 +524,7 @@ mountPortal(() => {
     const menuEl = A("div.s-menu-list.s-s.neutral.shadow create=hidden destroy=hidden", f.dropdownAttrs, () => {
         // One drawMenu call, not one per section: it owns the container's roving
         // keyboard focus, and two of them would move it twice per keypress.
-        drawMenu(f.link != null ? [...linkItems(f.link), { separator: true }, ...f.items] : f.items, closeFloating);
+        drawMenu(f.link != null ? [...linkItems(f.link), { separator: true }, ...f.items] : f.items, closeFloating, true);
     });
     // Capture-phase document handlers replace an invisible backdrop element:
     // any click outside the panel + anchor closes; Escape/Tab close.
@@ -461,11 +539,9 @@ mountPortal(() => {
             closeFloating();
         }
     };
-    // A menu is a transient overlay: whatever navigation it started, it hands over
-    // to. Items do that themselves (`closeFloating` is `drawMenu`'s `onLeafSelect`
-    // above), but custom slot content — a link in a row the menu knows nothing
-    // about — doesn't, and neither does a navigation from anywhere else. A branch
-    // row expanding is the one navigation that *isn't* a hand-over.
+    // Close on any navigation the items didn't already close for: custom slot content,
+    // or a navigation from elsewhere. A branch row expanding is the one navigation that
+    // isn't a hand-over.
     const openedAt = A.peek(currentRoute, "path");
     A(() => { if (currentRoute.path !== openedAt && !consumeBranchNav(currentRoute.path))
         closeFloating(); });
@@ -483,9 +559,8 @@ mountPortal(() => {
         // pointer location for a context menu — otherwise below the anchor.
         const rect = f.at ? { left: f.at.x, right: f.at.x, top: f.at.y, bottom: f.at.y } : f.anchor.getBoundingClientRect();
         positionMenu(menuEl, rect);
-        // Focus the active (current-page) item if there is one — so opening lands
-        // where you are — else the first focusable element (covers custom slot
-        // content, like a settings dropdown, not just `.s-menu-item`s).
+        // Focus the current-page item if there is one, else the first focusable
+        // element (covers custom slot content, not just `.s-menu-item`s).
         focusFirst(menuEl, ".s-menu-item[aria-current=page]");
     });
 });
@@ -513,13 +588,16 @@ mountPortal(() => {
  * ```
  */
 export function menu(opts) {
-    A("nav.s-menu-inline", opts.attrs, () => drawMenu(opts.items, opts.onLeafSelect));
+    A("nav.s-menu-inline", opts.attrs, () => {
+        registerMenuKeys(() => opts.items, () => opts.onLeafSelect?.());
+        drawMenu(opts.items, opts.onLeafSelect);
+    });
 }
 /**
  * Open a floating dropdown menu anchored to an element. Portals to
  * `document.body` (never clipped), positions itself (flipping up when there's
- * no room below), and closes on Escape, Tab, item selection, or any click
- * outside the panel and anchor. Returns a `close()` function.
+ * no room below), and closes on Escape, Tab, item selection, a navigation, or
+ * any click outside the panel and anchor. Returns a `close()` function.
  *
  * Menus are usually opened through {@link menuButton} or
  * {@link addContextMenu}; reach for this primitive when you need to trigger a
@@ -566,6 +644,9 @@ export function showFloatingMenu(opts) {
  * ```
  */
 export function addContextMenu(opts) {
+    // Bound here rather than where the menu is drawn: a shortcut on a context menu
+    // is meant to work without right-clicking first (see {@link MenuItem.key}).
+    registerMenuKeys(() => opts.items);
     let myEl = null;
     A.clean(() => { if ($floating.opts?.anchor === myEl)
         closeFloating(); });
@@ -573,8 +654,7 @@ export function addContextMenu(opts) {
         e.preventDefault();
         myEl = e.currentTarget;
         // Anchor at the exact click/tap point, and close on a plain click of the
-        // element (it has no toggle handler of its own). The rest of the options
-        // pass through whole, so a shared option can't be dropped on the way.
+        // element (it has no toggle handler of its own).
         showFloatingMenu({
             ...opts,
             anchor: myEl,
@@ -604,6 +684,7 @@ export function addContextMenu(opts) {
  * ```
  */
 export function menuButton(opts) {
+    registerMenuKeys(() => opts.items);
     let myEl = null;
     A.clean(() => { if ($floating.opts?.anchor === myEl)
         closeFloating(); });