staffa 0.10.1 → 0.12.0

package/README.md

@@ -210,7 +210,7 @@ function drawTask($panel: S.Panel<{ taskId: number }>) {
 
 On a wide screen the title becomes the stack's last crumb and the Save button sits in a quiet strip at the top of the column. On a phone the crumb is still there and Save moves into the top bar, where the app menu was. Nothing in your code measures the viewport, and no screen is written twice.
 
-**The breadcrumbs are the navigation.** The top bar's second line writes the open panels out as breadcrumbs — `Projects / Trackle / Task 42` — with the panels currently on screen in bold. Clicking an earlier crumb goes back to it *without closing anything*: the panels right of it stay open, parked just past the viewport's right edge, and clicking their crumbs brings them back. Browsing the stack is free — it's opening a *new* panel that closes the panels after the one it came from. The app's name and logo link to the app's home (the `home` option, `/` by default), going back to it when it's already open and opening it when it isn't. A stack too long for the bar scrolls sideways, in an `S.scrollStrip` like the tab strip's.
+**The breadcrumbs are the navigation.** The top bar's second line writes the open panels out as breadcrumbs — `Projects / Trackle / Task 42` — with the panels currently on screen in bold. Clicking an earlier crumb goes back to it *without closing anything*: the panels right of it stay open, parked just past the viewport's right edge, and clicking their crumbs brings them back. Browsing the stack is free — it's opening a *new* panel that closes the panels after the one it came from. The app's name and logo link to the app's home (the `home` option, `/` by default; `null` links neither), going back to it when it's already open and opening it when it isn't. A stack too long for the bar scrolls sideways, in an `S.scrollStrip` like the tab strip's.
 
 That line is the `subtitle`'s while the stack has nothing to add: one panel open, reachable from a nav item that is already highlighted in a visible sidebar. Otherwise the stack takes it, since it is then the only thing naming the screen.
 
@@ -221,7 +221,7 @@ A crumb can also wear a **●**: the panel holds unsaved work, and nothing will
 | `$panel` | what it does |
 | --- | --- |
 | `title` | Names the screen: its breadcrumb, and `document.title` while it's the current panel. A panel that sets none borrows the first line of text in its own body — good enough for a crumb, but say it yourself. |
-| `actions` | The screen's buttons or menu. In the column's chrome while several columns fit; in the top bar (taking the app `menu`'s place) once the shell is narrow. |
+| `actions` | The screen's buttons or menu. In the column's chrome while several columns fit; in the top bar (taking the app `menu`'s place) once the shell is narrow. A link among them builds on this panel at both widths. |
 
 Two deliberate rules there. `actions` are the screen's *verbs* — Save, Delete, Share, a menu — not a second way out: going back is the crumbs' job, at every width, and there is no back button even on a phone. And **`title` names the screen; it does not draw a heading** — a screen that wants its name in its own body writes it there, where it owns the typography.
 
@@ -291,7 +291,9 @@ Search params and the `#hash` belong to the current panel only. Anything another
 
 **A few more things.**
 
-- `stacking: false` shows only the current panel, however wide the screen. Everything else behaves the same: the URL, the back button, unsaved panels, and the panels' own close buttons.
+- `columns: "single"` shows only the current panel, however wide the screen — the phone experience at every size. Only the display changes: the URL, the back button, unsaved panels and the panels' own close buttons all behave the same.
+- `linkNavigation` sets what a link *without* a `data-panel` attribute does: `"push"` (the default), `"replace"`, or `"open"`. With `"open"` every click replaces the content as a whole — which, with flat routes, is the conventional sidebar-and-content app: one pane, swapped on every click, the crumb line simply naming it.
+- Both are live: pass a proxied options object (or make the field a getter) and a change is adopted in place, every open panel keeping its state.
 - Only one routed `S.main()` can be mounted at a time; a second one throws — the URL is global, so two of them would fight over it. Nothing else is global: the stack belongs to its shell, and each handler gets its own `$panel`, since several panels are alive at once.
 - Navigating with `aberdeen/route`'s own `go()` works — an unsaved panel survives it too — but, like a link from outside a panel, it builds the whole stack from the path. So prefer the stack's own methods. A navigation guard your app registered with `route.setGuard` (an auth redirect, say) keeps working untouched: Staffa registers none of its own.
 - Deep links need your static server to serve the app for unknown paths (the usual SPA fallback). For `http-server` that's `-P`, as in the demo command below.
@@ -348,7 +350,7 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 ### Layout & containers
 
-- **`S.main(opts)`**: app shell, a sticky header with `logo`, `title`, `subtitle`, `menu` — plus, in routed mode, the breadcrumbs of the open panels; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. An item with `items` of its own becomes a collapsible submenu: only the branch holding the current page stays unfolded, and clicking a branch selects its first leaf (expanding a branch doesn't dismiss the phone's full-page nav — only picking a leaf does). A sidebar taller than the window scrolls, and follows the highlighted item: navigating to a page whose item sits past the fold scrolls it back into view. A navigation dismisses the collapsed nav by itself, links in your own custom rows included; `S.closeNav()` does it for the rows that *don't* navigate. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
+- **`S.main(opts)`**: app shell, a sticky header with `logo`, `title`, `subtitle`, `menu` — plus, in routed mode, the breadcrumbs of the open panels; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. An item with `items` of its own becomes a collapsible submenu: only the branch holding the current page stays unfolded, and clicking a branch selects its first leaf (expanding a branch doesn't dismiss the phone's full-page nav — only picking a leaf does). A page the menu holds nowhere leaves every fold as it was. An item can also `match` pages beyond its own `href` — a path prefix, or a `(path) => boolean` — claiming the detail screens that have no row of their own: it is then highlighted, and the branches above it stay unfolded, cold deep links included. A sidebar taller than the window scrolls, and follows the highlighted item: navigating to a page whose item sits past the fold scrolls it back into view. A navigation dismisses the collapsed nav by itself, links in your own custom rows included; `S.closeNav()` does it for the rows that *don't* navigate. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
 - **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`. `close: fn` adds a ✕ that runs your dismissal — in the header row, or floating over the body when there is no header. (It is plain furniture: a routed screen gets its own way out from the shell, see [Panel-declared chrome](#chrome).)
 - **`S.tabs(opts)`**: tablist with live tab panels and keyboard navigation. More tabs than fit make the strip scroll (see `S.scrollStrip`); selecting a tab any other way (the arrow keys, a `bind` written from elsewhere) scrolls it into view.
 - **`S.scrollStrip(opts)`**: a horizontal row that scrolls once its content outgrows it, with a ‹ / › button appearing over whichever end still has something to reach — so it isn't just a swipe target. Its own scrollbar is hidden. `S.tabs` and the routed shell's breadcrumbs are built on it; reach for it for any row of chrome that can outgrow its space. `S.revealInStrip(el)` scrolls one of its children into view.

package/dist/components/main.d.ts

@@ -41,9 +41,11 @@ export interface MainOptions<R = Routes> {
      * when your home screen lives elsewhere. It's an ordinary link, so the
      * usual rules apply: a home that is already open in the stack — its first
      * panel, usually — is returned to, closing nothing, and one that isn't is
-     * opened the way a nav item would be. Routed mode only.
+     * opened the way a nav item would be. Pass `null` to link neither — for a
+     * `title` or `logo` slot holding interactive content of its own, which
+     * can't sit inside a link. Routed mode only.
      */
-    home?: string;
+    home?: string | null;
     /**
      * The app's own chrome, at the trailing end of the top bar: an account
      * button, a global search box, a settings menu. It may grow into the bar's
@@ -175,12 +177,31 @@ export interface MainOptions<R = Routes> {
      */
     ancestors?: AncestorTable<NoInfer<R>>;
     /**
-     * Set `false` to show only the current panel, however wide the screen (the
-     * nav sidebar still sits beside it). Everything else behaves the same: the
-     * URL, the back button, unsaved panels, and the panels' own close buttons.
-     * This only changes how many you see. Defaults to `true`.
+     * How many panels are *shown* at a time. `"auto"` (the default) shows as
+     * many columns, side by side, as comfortably fit, ending at the current
+     * panel; `"single"` shows only the current panel, however wide the screen
+     * — the phone experience at every size (the nav sidebar still sits beside
+     * it). Only the display differs: the stack, the breadcrumbs, the URL,
+     * Escape and the back button behave identically in both. Routed mode only.
+     *
+     * Live: pass a proxied options object (or make this field a getter) and a
+     * change is adopted in place — one layout pass, every panel keeping its
+     * state.
+     */
+    columns?: "auto" | "single";
+    /**
+     * What a link *without* a `data-panel` attribute does — the per-link
+     * attribute always wins. `"push"` (the default) opens the target on top of
+     * the panel the link sits in; `"replace"` opens it in that panel's place;
+     * `"open"` gives it its own stack, the way a nav item does. With `"open"`
+     * every click replaces the content as a whole — which, with flat routes,
+     * is the conventional sidebar-and-content app: one pane, swapped on every
+     * click, the crumb line simply naming it. Routed mode only.
+     *
+     * Live, like {@link MainOptions.columns}: change it and the next click
+     * uses the new default.
      */
-    stacking?: boolean;
+    linkNavigation?: "push" | "replace" | "open";
     /** Footer content, pinned below the scroll area. */
     footer?: Slot;
     /**

package/dist/components/main.js

@@ -1,7 +1,7 @@
 import A from "aberdeen";
-import { current as currentRoute, matchCurrent } from "aberdeen/route";
+import { current as currentRoute } from "aberdeen/route";
 import { drawSlot, focusFirst, NARROW_PX } from "../core.js";
-import { drawMenu, isFloatingMenuOpen, consumeBranchNav } from "./menu.js";
+import { drawMenu, isFloatingMenuOpen, consumeBranchNav, anyCurrent } from "./menu.js";
 // The shell's own chrome glyphs, from the same Lucide set an app draws with —
 // so a nav trigger sits beside app icons as an equal. Named imports, so a
 // bundler keeps these two and tree-shakes the other ~1950 away.
@@ -25,9 +25,11 @@ A.insertGlobalCss({
         "> footer": "border-top: 1px solid $s-faint; fg:$s-muted",
         // The bar reads `[leading] [title] …spacer… [trailing]`. The spacer is the
         // trailing slot's own growth: it takes the free space and right-aligns
-        // itself in it, which is what lets a search box live there. It doesn't
-        // shrink, and the title does — so the title is what truncates when the two
-        // compete, and the app's chrome stays usable.
+        // itself in it, which is what lets a search box live there. When the two
+        // compete, the title truncates first — but only down to a floor, past
+        // which the trailing slot shrinks instead: a wide search box must not
+        // starve the titles to nothing (the crumb strip's overlay buttons would
+        // escape their zero-width strip, over the ☰ beside it).
         "> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
         "> header .s-logo, > header .s-nav-trigger": "display:flex align-items:center flex-shrink:0",
         // The ☰ is a glyph in a 2rem hit area, so it carries ~6px of its own
@@ -35,7 +37,7 @@ A.insertGlobalCss({
         // up with the bar's edge and with the stack below.
         "> header .s-nav-trigger": "margin-left:-0.375rem",
         "> header .s-logo": "font-size:1.4em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent;",
-        "> header .s-titles": "display:flex flex-direction:column min-width:0 flex: 0 1 auto;",
+        "> header .s-titles": "display:flex flex-direction:column min-width:5rem flex: 0 1 auto;",
         // Same font-size and line-height as `.s-crumb`, because in routed mode the
         // two take turns on this line (see `drawSecondLine`): a different height
         // would jog the whole bar as they swap.
@@ -46,7 +48,7 @@ A.insertGlobalCss({
         // which their classes then provide. (`filter:none` keeps the global
         // `a:hover` brighten off the gradient text.)
         "> header a.s-logo, > header a.s-title": "text-decoration:none filter:none cursor:pointer",
-        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 0 auto;",
+        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 1 auto; min-width:0",
         // Body always wraps <main> (with or without a sidebar) so max-width centering
         // and scrollbar alignment work identically in both cases.
         // .s-body centres .s-body-inner; .s-body-inner caps the content to maxWidth.
@@ -122,10 +124,12 @@ A.insertGlobalCss({
         // body starts below the bar), but the bar should still win if they ever do.
         "position:absolute inset:0 z-index:5 display:flex flex-direction:column " +
             "overflow-y:auto overscroll-behavior:contain border:0 r:0 padding:$2 gap:$1 " +
-            "transition: transform var(--s-panel-ms) ease;",
+            "transition: transform var(--s-panel-ms) ease, visibility var(--s-panel-ms);",
         // Parked one screen to the left: the state the `create=`/`destroy=` hooks
-        // transition out of and back into.
-        "&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none",
+        // transition out of and back into. `visibility` flips at the slide's end
+        // (see `.s-menu-list` in menu.ts): the dismissed page lingers off screen
+        // until Aberdeen's removal timer, and mustn't stay reachable meanwhile.
+        "&.s-nav-page-off": "transform:translateX(-100%) pointer-events:none visibility:hidden",
         // Roomier rows than the dropdown's: this is the whole screen, and every row
         // is a thumb target.
         ".s-menu-item": "padding: $2 $3; min-height:3rem font-size:1.05em gap:$3",
@@ -182,11 +186,22 @@ export function main(opts = {}) {
             routes,
             notFound: opts.notFound,
             ancestors: opts.ancestors,
-            stacking: opts.stacking,
             title: opts.title,
             $shell,
         })
         : null;
+    if (ctl) {
+        // `columns` and `linkNavigation` are live: each is read in a scope of
+        // its own, so when the options object is a proxy (or the field a
+        // getter), a change re-runs just that scope — the columns relayout in
+        // place with every panel's state intact, and the next click picks up
+        // the new link default. Nothing else of the shell is touched.
+        A(() => ctl.setColumns(opts.columns));
+        A(() => ctl.setLinkNavigation(opts.linkNavigation));
+    }
+    // Where the brand mark and the app's name link — or nowhere, when the app
+    // said `home: null` (a title slot holding a control of its own, say).
+    const homeHref = ctl && opts.home !== null ? opts.home ?? "/" : null;
     // Routed mode caps the shell to the ensemble width the layout engine publishes,
     // rather than to `maxWidth`.
     const capWidth = ctl ? null : opts.maxWidth;
@@ -242,9 +257,9 @@ export function main(opts = {}) {
                         // twinned with the app's name beside it — a real link, so it
                         // has an address to hover, middle-click and copy, and a click
                         // runs the shell's usual link rules.
-                        A(ctl ? "a.s-logo aria-label=Home" : "div.s-logo", () => {
-                            if (ctl)
-                                A("href=", opts.home ?? "/");
+                        A(homeHref != null ? "a.s-logo aria-label=Home" : "div.s-logo", () => {
+                            if (homeHref != null)
+                                A("href=", homeHref);
                             drawSlot(opts.logo);
                         });
                     });
@@ -257,9 +272,9 @@ export function main(opts = {}) {
                         A(() => {
                             if (opts.title == null)
                                 return;
-                            A(ctl ? "a.s-title" : "div.s-title", () => {
-                                if (ctl)
-                                    A("href=", opts.home ?? "/");
+                            A(homeHref != null ? "a.s-title" : "div.s-title", () => {
+                                if (homeHref != null)
+                                    A("href=", homeHref);
                                 drawSlot(opts.title);
                             });
                         });
@@ -267,11 +282,14 @@ export function main(opts = {}) {
                     });
                     // Trailing: on a narrow shell the screen's own verbs win the space,
                     // and a screen with none of its own leaves the app's chrome up.
+                    // Promoted actions are marked as the current panel's own chrome
+                    // (`.s-panel-origin`), so a link among them still builds on that
+                    // panel — see `interceptLinks` in panels.ts.
                     A(() => {
                         const actions = $shell.narrow ? ctl?.currentPanel?.actions : undefined;
                         const slot = actions ?? opts.menu;
                         if (slot != null)
-                            A("div.s-menu", () => drawSlot(slot));
+                            A(`div.s-menu${actions != null ? ".s-panel-origin" : ""}`, () => drawSlot(slot));
                     });
                 });
             });
@@ -434,24 +452,20 @@ function drawSecondLine(opts, ctl, nav, $shell) {
 }
 /**
  * Whether the stack would only be saying what the sidebar already says: a
- * single panel open, the sidebar on screen, and that panel being one of the nav's
- * own rows.
+ * single panel open, the sidebar on screen, and that panel being one of the
+ * nav's own rows — a leaf inside a submenu counts, since the sidebar shows it
+ * highlighted (inside its unfolded branch) all the same.
  *
- * The row test is {@link matchCurrent} — the very thing that marks a row
- * `aria-current=page` — so "the crumb is redundant" and "the sidebar has it
- * highlighted" can never come apart. It compares whole paths, so it is true
- * only for a nav item's own screen, never for one opened beneath it.
+ * The row test is the menu's own {@link anyCurrent} — the very thing that
+ * marks a row `aria-current=page` — so "the crumb is redundant" and "the
+ * sidebar has it highlighted" can never come apart.
  */
 function taglineFits(ctl, nav, $shell) {
     if ($shell.narrow || nav == null)
         return false;
     if (ctl.panels.length > 1)
         return false;
-    return nav.items.some((entry) => typeof entry !== "string" &&
-        typeof entry !== "function" &&
-        !("separator" in entry) &&
-        entry.href != null &&
-        matchCurrent(entry.href));
+    return anyCurrent(nav.items);
 }
 /**
  * Track whether the shell is narrow, for everything that has to agree about it.

package/dist/components/menu.d.ts

@@ -26,6 +26,17 @@ export interface MenuItem {
      * `attrs: "data-panel=push"` for a row that should stack instead.
      */
     href?: string;
+    /**
+     * Pages this item claims *beyond* its own `href`: a string claims that path
+     * and everything under it (`"/mail"` claims `/mail/…`, not `/mailbox`), a
+     * function is asked with the current path. While a claimed page is current,
+     * the item is highlighted and the branches above it stay unfolded — for the
+     * detail screens a menu has no row of their own: the `/thread/[id]` a
+     * notification lands on, an icon's page under the gallery's row. Claims
+     * work from the very first paint, so they also cover cold deep links,
+     * which no amount of fold-state keeping can.
+     */
+    match?: string | ((path: string) => boolean);
     /** `target` for the link (`_blank`, etc.). Only meaningful with `href`. */
     target?: string;
     /** Disables the item. */
@@ -34,11 +45,13 @@ export interface MenuItem {
     attrs?: Attributes;
     /**
      * Child entries, which turn the item into a collapsible **branch** of a
-     * tree. Only the branch holding the current page is expanded; navigate away
-     * and it folds back up. Clicking a branch *selects* rather than toggles: it
-     * follows the item's own `href`, or failing that the first linked leaf
-     * below it — which is what expands it. A branch with no link anywhere below
-     * it falls back to plain open/close toggling.
+     * tree. Only the branch holding the current page is expanded; navigate to
+     * another page in the menu and it folds back up. (Navigating to a page the
+     * menu doesn't hold *anywhere* leaves every fold as it was: there is no
+     * better answer to fold up to.) Clicking a branch *selects* rather than
+     * toggles: it follows the item's own `href`, or failing that the first
+     * linked leaf below it — which is what expands it. A branch with no link
+     * anywhere below it falls back to plain open/close toggling.
      *
      * Expanding is not selecting: a branch click never counts as picking an
      * item (see `onLeafSelect` on {@link menu}), so on a phone the nav stays up
@@ -135,6 +148,13 @@ export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor" | "at" | "cl
  *   not a selection, so it doesn't run this.
  */
 export declare function drawMenu(items: MenuEntry[], onLeafSelect?: () => void): void;
+/**
+ * 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.
+ */
+export declare function anyCurrent(items: MenuEntry[]): boolean;
 /**
  * Whether the navigation that just landed on `path` was a branch row expanding
  * (consuming the note it left). Internal — used by the floating menu below and

package/dist/components/menu.js

@@ -9,11 +9,16 @@ import { button } from "./button.js";
 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.
     ".s-menu-list": "position:fixed z-index:350 min-width:10rem display:flex flex-direction:column p:$1 " +
         "r:$s-radius-lg " +
         "overflow-y:auto max-height:min(80vh,28rem) " +
-        "transition: opacity 0.15s, transform 0.15s;",
-    ".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px)",
+        "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
@@ -114,9 +119,15 @@ export function drawMenu(items, onLeafSelect) {
                     (cur + dir + els.length) % els.length;
         els[next].focus();
     });
-    drawEntries(items, onLeafSelect);
+    // 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);
 }
-function drawEntries(items, onLeafSelect) {
+function drawEntries(items, onLeafSelect, $menuHasCurrent) {
     for (const entry of items) {
         if (typeof entry === "string" || typeof entry === "function") {
             drawSlot(entry);
@@ -127,7 +138,7 @@ function drawEntries(items, onLeafSelect) {
             continue;
         }
         if (entry.items)
-            drawBranch(entry, onLeafSelect);
+            drawBranch(entry, onLeafSelect, $menuHasCurrent);
         else
             drawLeaf(entry, onLeafSelect);
     }
@@ -152,7 +163,7 @@ function drawLeaf(entry, onLeafSelect) {
             A(() => {
                 const first = !drawn;
                 drawn = true;
-                if (!matchCurrent(entry.href))
+                if (!isCurrent(entry))
                     return;
                 A("aria-current=page");
                 // A list taller than its scrollport (a long sidebar nav, mostly)
@@ -181,6 +192,18 @@ function drawLeaf(entry, onLeafSelect) {
         drawSlot(entry.label);
     });
 }
+/**
+ * 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.
+ */
+const foldMemory = new Map();
+function setFold(href, open) {
+    foldMemory.set(href, open);
+    return 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
@@ -193,12 +216,29 @@ function drawLeaf(entry, onLeafSelect) {
  * 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.
  */
-function drawBranch(entry, onLeafSelect) {
+function drawBranch(entry, onLeafSelect, $menuHasCurrent) {
     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.
-    const $open = href != null ? A.derive(() => containsCurrent(entry)) : null;
+    // 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.
+    const $open = href != null
+        ? A.derive(() => {
+            if (containsCurrent(entry))
+                return setFold(href, true);
+            if ($menuHasCurrent == null || $menuHasCurrent.value)
+                return setFold(href, false);
+            return foldMemory.get(href) ?? false;
+        })
+        : null;
     A("details.s-menu-details", () => {
         // For a no-link branch this scope has no subscriptions and never re-runs,
         // which is exactly what leaves the native toggle alone.
@@ -209,9 +249,10 @@ function drawBranch(entry, onLeafSelect) {
             if (entry.disabled)
                 A("aria-disabled=true");
             A(() => {
-                // Current only on its *own* page: when a descendant is current, that
+                // 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.
-                if (entry.href != null && matchCurrent(entry.href))
+                if (isCurrent(entry))
                     A("aria-current=page");
             });
             A("click=", (e) => {
@@ -233,7 +274,7 @@ function drawBranch(entry, onLeafSelect) {
             drawSlot(entry.label);
             A("span.s-menu-chevron aria-hidden=true", () => chevronRight());
         });
-        A("div.s-menu-sub", () => drawEntries(entry.items, onLeafSelect));
+        A("div.s-menu-sub", () => drawEntries(entry.items, onLeafSelect, $menuHasCurrent));
     });
 }
 /**
@@ -248,10 +289,36 @@ function foldedAway(el) {
     }
     return false;
 }
-/** Whether `entry`'s own page, or any page linked below it, is the current one. */
-function containsCurrent(entry) {
+/**
+ * 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.
+ */
+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.
+ */
+function isCurrent(entry) {
     if (entry.href != null && matchCurrent(entry.href))
         return true;
+    const m = entry.match;
+    if (m == null)
+        return false;
+    const path = currentRoute.path;
+    if (typeof m === "function")
+        return m(path);
+    const claim = m.replace(/\/+$/, "") || "/";
+    return path === claim || path.startsWith(claim === "/" ? "/" : claim + "/");
+}
+/** Whether `entry` is the current page itself, or holds it anywhere below. */
+function containsCurrent(entry) {
+    if (isCurrent(entry))
+        return true;
     for (const child of entry.items ?? []) {
         if (typeof child === "string" || typeof child === "function" || "separator" in child)
             continue;

package/dist/components/panels.d.ts

@@ -250,8 +250,10 @@ export interface PanelStackOptions {
     notFound?: RouteHandler<{}>;
     /** What to open beneath a path that arrives cold. See {@link MainOptions.ancestors}. */
     ancestors?: Record<string, AncestorsHandler | undefined>;
-    /** Set `false` to show only the current panel, however much room there is. */
-    stacking?: boolean;
+    /** How many panels are shown at a time. See {@link MainOptions.columns}. */
+    columns?: "auto" | "single";
+    /** What a bare link does. See {@link MainOptions.linkNavigation}. */
+    linkNavigation?: "push" | "replace" | "open";
     /** The shell's own title, used as the suffix of `document.title`. */
     title?: unknown;
     /**
@@ -601,9 +603,11 @@ export declare class PanelStackController implements PanelStack {
      * close guards run in `checkChange` when our navigation reaches the router.
      *
      * `data-panel` names which of the three {@link PanelStack} navigations the
-     * click is: `push` (the default), `replace`, or `open`, which drops the
+     * click is: `push`, `replace`, or `open`, which drops the
      * originating panel so the target arrives with its own stack beneath it,
-     * exactly as a nav item's link does. An unrecognised value is a `push`.
+     * exactly as a nav item's link does. A link that doesn't say gets the
+     * shell's {@link PanelStackOptions.linkNavigation} (`push` by default);
+     * an unrecognised value is a `push`.
      */
     private interceptLinks;
     get currentPanel(): Panel | undefined;
@@ -613,6 +617,10 @@ export declare class PanelStackController implements PanelStack {
     replacePanel(path: string): Promise<boolean>;
     openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
     closePanel(path?: string): Promise<boolean>;
+    /** Adopt a changed `columns` setting: one layout pass, nothing redrawn. */
+    setColumns(columns: "auto" | "single" | undefined): void;
+    /** Adopt a changed `linkNavigation` default; the next click reads it. */
+    setLinkNavigation(mode: "push" | "replace" | "open" | undefined): void;
     /**
      * The breadcrumb stack, drawn by `main()` into the top bar: every open
      * panel, oldest first, the ones on screen right now in bold, pinned ones

package/dist/components/panels.js

@@ -946,16 +946,30 @@ export class PanelStackController {
      * close guards run in `checkChange` when our navigation reaches the router.
      *
      * `data-panel` names which of the three {@link PanelStack} navigations the
-     * click is: `push` (the default), `replace`, or `open`, which drops the
+     * click is: `push`, `replace`, or `open`, which drops the
      * originating panel so the target arrives with its own stack beneath it,
-     * exactly as a nav item's link does. An unrecognised value is a `push`.
+     * exactly as a nav item's link does. A link that doesn't say gets the
+     * shell's {@link PanelStackOptions.linkNavigation} (`push` by default);
+     * an unrecognised value is a `push`.
      */
     interceptLinks() {
         route.interceptLinks((url, anchor) => {
-            const mode = anchor.getAttribute("data-panel");
-            const panel = mode === "open" ? null : anchor.closest(".s-panel");
-            const origin = panel ? this.$state.live.find((entry) => entry.el === panel) : undefined;
-            void this.navigate(url.href, origin?.path ?? null, mode === "replace");
+            const mode = anchor.getAttribute("data-panel") ?? this.opts.linkNavigation;
+            let origin = null;
+            if (mode !== "open") {
+                const panel = anchor.closest(".s-panel");
+                if (panel) {
+                    origin = this.$state.live.find((entry) => entry.el === panel)?.path ?? null;
+                }
+                else if (anchor.closest(".s-panel-origin")) {
+                    // The current panel's actions, promoted into the top bar on a
+                    // narrow shell (see main.ts), sit outside every `.s-panel` — but
+                    // they are still the current panel's own chrome, so a link among
+                    // them builds on that panel, exactly as it does at full width.
+                    origin = this.$state.live[this.$state.focus]?.path ?? null;
+                }
+            }
+            void this.navigate(url.href, origin, mode === "replace");
             return true;
         });
     }
@@ -987,6 +1001,23 @@ export class PanelStackController {
             return this.closePath(path ?? arr.stack[arr.focus] ?? "");
         });
     }
+    // ── Live settings ──────────────────────────────────────────────────────
+    // `main()` keeps these fed from small reactive scopes of their own, so an
+    // app that reads them off a proxy (or through a getter) can change them at
+    // runtime and the shell adapts in place — nothing is redrawn, no panel
+    // loses its state. Not {@link PanelStack} API: the app talks to `main()`'s
+    // options; these are how `main()` talks to the stack.
+    /** Adopt a changed `columns` setting: one layout pass, nothing redrawn. */
+    setColumns(columns) {
+        if (this.opts.columns === columns)
+            return;
+        this.opts.columns = columns;
+        this.scheduleLayout();
+    }
+    /** Adopt a changed `linkNavigation` default; the next click reads it. */
+    setLinkNavigation(mode) {
+        this.opts.linkNavigation = mode;
+    }
     /**
      * The breadcrumb stack, drawn by `main()` into the top bar: every open
      * panel, oldest first, the ones on screen right now in bold, pinned ones
@@ -1375,7 +1406,7 @@ export class PanelStackController {
         const geom = this.geometry();
         if (!geom)
             return;
-        const stacking = this.opts.stacking !== false;
+        const stacking = this.opts.columns !== "single";
         // A window resize (or the very first pass) must be adopted instantly —
         // geometry tracking the window through a 450ms transition reads as lag,
         // and a shell animating itself into place on load reads as a glitch.