staffa 0.7.3 → 0.8.0

package/skill/MainOptions.md

@@ -2,6 +2,10 @@
 
 Options for `main`.
 
+**Type Parameters:**
+
+- `R = Routes`
+
 ### mainOptions.attrs · member
 
 Aberdeen attr/style string applied to the outermost shell element.
@@ -35,9 +39,86 @@ Action area on the right of the top bar (buttons, menu, ...).
 ### mainOptions.content · member
 
 The scrollable page content. A string is rendered as rich text.
+Mutually exclusive with `MainOptions.routes`.
 
 **Type:** `Slot`
 
+### mainOptions.routes · member
+
+Paths mapped to the functions that draw them, which hands navigation over
+to the shell. Each route draws one screen of your app, called a panel, and
+as many panels as fit are shown at a time: one at a time on a phone,
+several side by side on a wider screen. Mutually exclusive with
+`MainOptions.content`.
+
+A segment wrapped in brackets is a param: `[name]` matches one segment as
+a string, `[name=integer]` matches one segment as a number, and a trailing
+`[...name]` matches the rest of the path as one raw (still percent-encoded)
+string, so it has to come last and needs at least one segment to match.
+The first key that matches wins, a segment a param refuses falls through
+to a later route (or to `MainOptions.notFound`), and each handler's
+`$page.params` is typed from its own key.
+
+`integer` accepts only spellings that survive a round trip back to the
+same URL, so `/tasks/0042` is not a second path for `/tasks/42`. Ids that
+aren't safe integers, such as snowflakes, want a plain `[id]`.
+
+Navigating is just links: the shell handles the clicks itself, so do *not*
+also call Aberdeen's `interceptLinks()`. A link opens its target on top of
+the panel it sits in, closing anything that was above it first, unless it
+carries `data-panel=replace`, which replaces its own panel instead. A link
+to something already open goes back to it rather than opening it twice.
+From code, use `panels` (`S.panels.push()` and friends): navigating
+with `aberdeen/route`'s own `go()` works and still asks the panels'
+`Page.requestClose`, but builds the whole stack from the path. A
+navigation guard the app registered before mounting (an auth redirect,
+say) keeps working: the shell asks it first, and puts it back when the
+shell goes away.
+
+The shell draws no back arrows and no ✕ of its own: **every panel provides
+its own way out**, with `S.box`'s `close` option for a ✕, or
+`Page.close` behind a Cancel button. Escape and the browser's back
+button are the shell's contribution.
+
+Only one routed shell can be mounted at a time (a second one throws),
+which is what lets `panels` be a plain module-level object. Each
+handler still gets its own `$page` rather than there being one global
+"current page", since several panels are alive at once. It's that argument
+that carries the per-route typing of `params`.
+
+**Type:** `R`
+
+**Examples:**
+
+```ts
+S.main({
+  title: "Trackle",
+  nav: { items: [{ label: "Projects", href: "/projects" }] },
+  routes: {
+    "/projects": ($page) => { $page.title = "Projects"; drawProjects(); },
+    "/projects/[id]": ($page) => drawProject($page.params.id),  // typed string
+  },
+  notFound: ($page) => S.box({ header: "Not found", content: $page.path }),
+});
+```
+
+### mainOptions.notFound · member
+
+Draws the panel for a path none of the routes match. There are no params
+to go with it, so `$page.params` is empty; the path itself is in
+`$page.path`.
+
+**Type:** `RouteHandler<{}>`
+
+### mainOptions.stacking · member
+
+Set `false` to show only the top panel, however wide the screen (the nav
+sidebar still sits beside it). Everything else behaves the same: the URL,
+the back button, `requestClose`, and the panels' own close buttons. This
+only changes how many you see. Defaults to `true`.
+
+**Type:** `boolean`
+
 ### mainOptions.footer · member
 
 Footer content, pinned below the scroll area.
@@ -53,6 +134,10 @@ sidebar) — cap to this width and centre horizontally. When unset, everything
 fills the available width. Either way the content shares the page surface —
 it is not boxed.
 
+Ignored when you pass `MainOptions.routes`: there the open panels
+decide the width (see `Page.layout`), and the header and footer line
+themselves up with them.
+
 **Type:** `string`
 
 ### mainOptions.contentAttrs · member
@@ -71,7 +156,8 @@ Aberdeen attr/style string applied to the top bar.
 
 Navigation menu. When provided, renders a sidebar (in `"left"` / `"right"`
 mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
-collapses to button mode when the shell is too narrow.
+collapses to a button when the shell is too narrow — which there opens the
+nav as a full page sliding in from the left, not as a dropdown.
 
 **Type:** `MenuOptions`
 
@@ -79,8 +165,12 @@ collapses to button mode when the shell is too narrow.
 
 Where to render the nav. Defaults to `"left"`.
 - `"left"` / `"right"`: sidebar next to the content area; collapses to a
-  button+dropdown in the top bar when the shell width drops below 640 px.
-- `"button"`: always a button+dropdown, never a sidebar.
+  button in the top bar when the shell width drops below 640 px.
+- `"button"`: always a button, never a sidebar.
+
+The button opens a dropdown on a wide shell, and — below 640 px — a
+full-page nav that slides in from the left, handing over to the chosen
+screen with a matching slide in from the right.
 
 **Type:** `"button" | "left" | "right"`
 
@@ -89,3 +179,9 @@ Where to render the nav. Defaults to `"left"`.
 Aberdeen attr/style string applied to the sidebar nav panel.
 
 **Type:** `string`
+
+### mainOptions.navPageAttrs · member
+
+Aberdeen attr/style string applied to the narrow-screen full-page nav.
+
+**Type:** `string`

package/skill/Page.md

@@ -0,0 +1,108 @@
+## Page · interface
+
+What a route handler gets: the params from its route, plus everything the
+shell needs to know about the panel it is drawing. It's an Aberdeen proxy, so
+you can set things later, such as a `title` that arrives with your data or
+`loading` going back to `false`, and the shell keeps up.
+
+Search params and the `#hash` belong to the top panel only. A panel with
+another one on top of it keeps just its path, so anything a panel needs in
+order to redraw itself has to live in that path.
+
+**Type Parameters:**
+
+- `P = Record<string, string | number | string[]>`
+
+### page.params · member
+
+The params matched from this panel's path, typed per its route key:
+`[x]` is a `string`, `[x=integer]` a `number`, `[...x]` a `string`.
+Read-only.
+
+**Type:** `P`
+
+### page.path · member
+
+This panel's path, e.g. `"/projects/7"`. Read-only.
+
+**Type:** `string`
+
+### page.title · member
+
+Shown in `document.title` while this panel is top-most.
+
+**Type:** `string`
+
+### page.layout · member
+
+How much room this panel takes. The content area is the page, at most
+1280px wide, minus the nav sidebar; the widths below assume a sidebar of
+around 170px, so without one add that back.
+
+- `"small"` is 360 to 540px once two panels fit side by side, which is
+  what makes it right for lists, detail forms, and anything else that
+  reads well at phone width. Below that it takes the whole content area
+  (so up to ~730px), like a medium does. A lone small leaves its other
+  half empty, and that is exactly where the next small lands, without
+  anything on screen moving.
+- `"medium"` (the default) takes the whole content area: up to ~1100px,
+  and the screen width on a phone. The safe default for ordinary screens.
+  Nothing fits beside a medium on a standard 1280px page, though on a wide
+  enough window a small still can.
+- `"large"` takes the whole window, with no upper limit (~1750px on a
+  1920px screen): for boards, wide tables and dense dashboards. While it's
+  open the whole shell (top bar, content and footer) stretches to the
+  screen edges rather than stopping at 1280px.
+
+When more columns fit than the standard page holds (three smalls, or a
+medium and a small) the page itself grows, staying centred, to hold them.
+
+A panel's width depends only on the size of the window, never on what else
+is open, so opening or closing a panel never resizes the ones already on
+screen. This is read **once**, right after your handler runs, so set it
+there; later changes are ignored.
+
+**Type:** `"small" | "medium" | "large"`
+
+### page.loading · member
+
+Set this while you're fetching what the panel needs, and back to `false`
+when you're done. A new panel waits a moment before sliding in, so it can
+arrive with real content instead of empty; if the wait drags on it slides
+in anyway and shows a loading indicator until the flag clears. It only
+affects the animation; the stack, the URL and `requestClose` never wait
+for it.
+
+**Type:** `boolean`
+
+### page.requestClose · member
+
+Your chance to say no. Everything that would close this panel waits for
+it: Escape, the panel's own ✕ or Cancel button (`Page.close`, or a
+box with `close: true`), the browser's back button, a link that would
+close it, and `panels`.`close()`. Return `false` to keep the panel
+open, usually after a dirty check and a `confirm`.
+
+**Type:** `() => boolean | Promise<boolean>`
+
+### page.close · member
+
+Closes **this** panel, wherever it sits in the stack. The top panel goes
+back to whatever was underneath it; any other panel is taken out on its
+own, leaving the columns to its right where they are, with their state,
+and the URL alone, since the top panel didn't move. Either way it
+becomes a history entry, so the browser's back button brings it back.
+
+Resolves `false` if the panel didn't close: `Page.requestClose` said
+no, it was the only panel on the stack (so there's nothing to go back to),
+or another navigation got there first. The shell draws no back arrows or
+✕ of its own, so this (or `S.box`'s `close` option) is how a panel gives
+the user a way out.
+
+**Type:** `() => Promise<boolean>`
+
+**Examples:**
+
+```ts
+S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+```

package/skill/PathParams.md

@@ -0,0 +1,7 @@
+## PathParams · type
+
+The params object described by a path template, e.g.
+`PathParams<"/projects/[id]/tasks/[taskId=integer]">` is
+`{ id: string; taskId: number }`.
+
+**Type:** `P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>`

package/skill/SKILL.md

@@ -82,7 +82,7 @@ S.box({ header: "See the [docs](/docs)", content: () => { ... } });
 
 Staffa builds on **surfaces**: elements marked with `.s-s` that have their own background and derived text/border tokens. There are two families:
 
-- **Neutral surfaces** — `.neutral` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (page → panel → raised, capped). Use them for cards, bars, popovers — anything that just holds content. No variants.
+- **Neutral surfaces** — `.neutral` (and the implicit page at `:root`). A calm neutral whose shade steps automatically with nesting depth (each level a step away from the page colour, up to a cap). Use them for cards, bars, popovers — anything that just holds content. No variants.
 - **Accent surfaces** — `.primary`, `.danger`, `.success`, `.warning`, `.link` (a bare `.s-s` defaults to primary). A bright fill with white ink, painted as a subtle single-colour gradient. They take a **variant**: `.filled` (default), `.tonal`, or `.outlined`. A surface nested *inside* an accent surface is always rendered filled, so it can't bleed into the vivid parent.
 
 Components are built from these (`S.button` is a `.s-s.primary`, `S.box` a `.s-s.neutral`, etc.). Because component options include an optional `attrs` string, which has Aberdeen `A()` string semantics, you can easily override it:
@@ -116,6 +116,110 @@ S.setDarkMode(undefined);  // follow OS
 
 *Hint:* A `buttonChooser` is probably the right component for a color scheme selector.
 
+### Panel-stack navigation
+
+Give `S.main()` a `routes` table instead of a `content` slot, and it takes over navigation for you. Each route draws one screen of your app. Staffa calls those screens **panels**, and it shows as many of them at a time as comfortably fit.
+
+On a phone that means one panel at a time: a link opens a new panel on top of it, and closing that one brings the previous back, the way most mobile apps work. On a wider screen, panels that would have covered each other sit side by side instead. Pick a project from a list and it opens *beside* the list; pick another and it takes the first one's place. Your code doesn't know the difference.
+
+```ts
+S.main({
+  title: "Trackle",
+  nav: { items: [{ label: "Projects", href: "/projects" }] },
+  routes: {
+    "/projects": drawProjectList,
+    "/projects/[projectId]": drawProject,
+    "/projects/[projectId]/tasks/[taskId=integer]": drawProjectTask,
+  },
+  notFound: ($page) => S.box({ header: "Not found", content: $page.path }),
+});
+
+function drawProject($page: S.Page<{ projectId: string }>) {
+  const { projectId } = $page.params;    // typed from the route key
+  A(`a href=/projects/${projectId}/tasks/1 #Open the first task`);
+}
+
+// Etc..
+```
+
+Each handler gets a `$page` object holding the params from its route, along with the things Staffa needs to know about the panel: its title, how much room it wants, whether it's still loading. It's an Aberdeen proxy, so you can set those later (when your data arrives, say) and the shell keeps up.
+
+**Route keys.** A segment wrapped in brackets is a param:
+
+- `[name]` matches one segment, as a string.
+- `[name=integer]` matches one segment, as a number.
+- `[...name]` matches the rest of the path, as a string. It has to be the last thing in the key, and it needs at least one segment to match.
+
+The first key that matches wins, and a segment a param refuses simply doesn't match, so it falls through to a later route, or to `notFound`. TypeScript reads each key and types that handler's `$page.params` from it, so `params.taskId` above really is a `number`.
+
+`integer` only accepts spellings that survive a round trip back to the same URL: `42` and `-7` and `0`, but not `007`, `1.5`, `0x10`, `-0` or anything past `Number.MAX_SAFE_INTEGER`. Otherwise `/tasks/42` and `/tasks/0042` would be two different paths for one record, and could sit open in two panels at once. For ids that aren't safe integers, such as snowflakes, use a plain `[id]` and keep them as strings.
+
+`[...name]` hands you the remaining path exactly as it appears in the URL, still percent-encoded. Decoding it for you would be lossy: an encoded slash inside a segment would come back looking just like a separator. When you want the pieces, `name.split("/").map(decodeURIComponent)` gives them to you. (Single-segment params have no such ambiguity, so those *are* decoded.)
+
+**Navigating is just links.** Write ordinary `<a href="/...">` links; Staffa handles the clicks (so don't also call Aberdeen's `interceptLinks()`).
+
+- A link inside a panel opens its target on top of that panel, closing anything that was above it first. That's why clicking a second project replaces the open project instead of adding a third column.
+- Add `data-panel=replace` and the link replaces the panel it sits in, rather than opening on top of it. That's what you want for prev/next buttons.
+- A link to something that's already open goes back to it instead of opening it twice. The same path is never in the stack twice.
+- A link that isn't inside a panel (a nav item, or one in a dialog) has no panel to build on, so it replaces the stack as a whole: the page you asked for, with its ancestor pages opened beneath it (see [below](#ancestors)). Panels that the new stack also contains stay as they are, so clicking the nav item for the section you're already in won't reset it. Clicking a nav item and opening that same URL in a fresh tab therefore give you the same columns.
+
+From code, `S.panels.push(path)` opens a panel on top of the top one, `.replace(path)` opens one in place of the top one, and `.close(path?)` closes the top panel (or a named one). `S.panels.stack` is the list of open paths.
+
+**How much room a panel takes** is up to `$page.layout`. The content area is the page, at most 1280px wide, minus the nav sidebar:
+
+| `layout` | How wide the panel gets | Good for |
+| --- | --- | --- |
+| `"small"` | 360 to 540px once two fit side by side. Below that, the whole content area (so up to ~730px). | lists, detail forms, anything that reads well at phone width |
+| `"medium"` (default) | The whole content area: up to ~1100px, and the screen width on a phone. | ordinary screens; the safe default |
+| `"large"` | The whole window, with no upper limit: ~1750px on a 1920px screen. | boards, wide tables, dense dashboards |
+
+Those numbers assume a nav sidebar of around 170px; without a sidebar, add that back (a medium then reaches the full 1280px). Nothing fits beside a medium on a standard 1280px page, but on a wide enough window a small still can, and the page grows past 1280px to hold both.
+
+A panel's width depends only on the size of the window, never on what else is open. So opening or closing a panel never resizes the ones already on screen, and never reflows what someone was reading. A lone small leaves its other half empty, and that is exactly where the next small lands. When more columns fit than the standard 1280px page holds (three smalls, say), the page itself grows, staying centred, to hold them.
+
+**The rest of `$page`:**
+
+- `params` and `path`: read-only.
+- `title`: shown in `document.title` while this panel is the top one.
+- `layout`: as above. It's read once, right after your handler runs, so set it there.
+- `loading`: set it while you're fetching. A new panel waits a moment before sliding in, so it can arrive with real content instead of empty, and shows a loading indicator if the wait drags on.
+- `close()`: closes this panel, wherever it sits in the stack.
+- `requestClose`: your chance to say no. Everything that would close the panel waits for it: Escape, the panel's own ✕ or Cancel button, the browser's back button, a link that would close it, `S.panels.close()`. Return `false` to keep the panel open.
+
+```ts
+$page.requestClose = async () => !$task.dirty || await S.confirm("Discard unsaved changes?");
+```
+
+**Every panel provides its own way out.** Staffa draws no back arrows and no ✕ of its own, because a panel knows better than the shell does what leaving it should look like: Cancel and Save buttons, or a ✕ in the corner of a box. So say it yourself:
+
+```ts
+S.box({ header: "Task 42", close: true, content: drawTask });   // a ✕ in the box's corner
+S.button({ content: "Cancel", attrs: ".neutral", click: () => $page.close() });
+S.panels.close();              // the top panel
+S.panels.close("/projects/7"); // that panel, wherever it is
+```
+
+`S.box`'s `close: true` works out for itself which panel it's in, so the same code closes the right thing whether it's one column of several or a whole phone screen. (Pass a function instead if you'd rather do something else.)
+
+Closing the top panel goes back to whatever was underneath it. Closing one that *isn't* on top takes just that one away: the columns to its right stay where they are and keep their state, and the URL doesn't change, because the top panel didn't move. Either way it becomes a history entry, so the browser's back button brings the panel back.
+
+Staffa itself contributes two things: the Escape key, which closes the top panel (and jumps to the navigation once you're at the bottom of the stack), and making the browser's back button do the right thing. Both ask `requestClose` first.
+
+<a id="ancestors"></a>
+
+**The back button, and links from elsewhere.** The URL holds the top panel; the rest of the stack is stored beside it in the browser's history entry. So back and forward step through whole arrangements of columns, and a reload brings the same columns back.
+
+A URL that arrives without any of that (a shared link, a bookmark, a new tab) has nothing to restore, so Staffa builds the stack from the path: it walks the parent paths and opens each one you have a route for. With the routes above, `/projects/7/tasks/42` opens as three panels: the project list, project 7, and task 42. A parent path you have no route for is skipped, so if you don't want one screen appearing under another, just don't give it a route.
+
+Search params and the `#hash` belong to the top panel only. Anything a panel deeper in the stack needs in order to redraw itself has to live in its path.
+
+**A few more things.**
+
+- `stacking: false` shows only the top panel, however wide the screen. Everything else behaves the same: the URL, the back button, `requestClose`, and the panels' own close buttons.
+- Only one routed `S.main()` can be mounted at a time; a second one throws. That's what lets `S.panels` be a plain module-level object. Each handler still gets its own `$page` rather than there being one global "current page", since several panels are alive at once.
+- Navigating with `aberdeen/route`'s own `go()` works and still asks `requestClose`, but, like a link from outside a panel, it builds the whole stack from the path. So prefer `S.panels`. If your app registered its own navigation guard before mounting (an auth redirect, say), it keeps working: Staffa asks it first, and puts it back when the shell goes away.
+- 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.
+
 ### CSS reset
 
 Staffa includes a lightweight CSS reset that makes bare semantic HTML look a bit better but unsurprising without additional styling. 
@@ -168,9 +272,9 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 ### Layout & containers
 
-- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content.
-- **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`.
-- **`S.tabs(opts)`**: tablist with live panels and keyboard navigation.
+- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; 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. 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: true` adds a ✕ that closes the panel the box is in (see [Panel-stack navigation](#panel-stack-navigation)); `close: fn` runs your own dismissal.
+- **`S.tabs(opts)`**: tablist with live panels and keyboard navigation. More tabs than fit make the strip scroll, with a ‹ / › button appearing at whichever end still has something to reach — so it's not just a swipe target. Selecting a tab any other way (the arrow keys, a `bind` written from elsewhere) scrolls it into view.
 - **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with an `actions` bar. Prevents the default page reload.
 
 ### Form fields
@@ -225,6 +329,8 @@ Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form f
 {
   "imports": {
     "aberdeen": "https://cdn.jsdelivr.net/npm/aberdeen/dist/src/aberdeen.js",
+    "aberdeen/route": "https://cdn.jsdelivr.net/npm/aberdeen/dist/src/route.js",
+    "aberdeen/transitions": "https://cdn.jsdelivr.net/npm/aberdeen/dist/src/transitions.js",
     "staffa/all.js": "https://cdn.jsdelivr.net/npm/staffa/dist/staffa.esm.js"
   }
 }
@@ -272,7 +378,7 @@ The previous section is good advice for any project-specific custom, but should
 2. Define `<Name>Options` extending `ContentOptions`, `FieldOptions`, or a plain interface. Add TSDoc on every option.
 3. Add a TSDoc `@example` on the function.
 4. Register in `src/index.ts` (the `S` object + type re-export).
-5. Extend `smoke.mjs` to render it. Run `npm run smoke` and `npm run build`.
+5. Add it to the demo, cover it in the visual tests (`tests/*.spec.ts`), and run `npm run build` and `npm run typecheck`.
 
 See `src/components/button.ts` and `src/components/dialog.ts` for examples.
 
@@ -281,8 +387,8 @@ See `src/components/button.ts` and `src/components/dialog.ts` for examples.
 ```sh
 npm run build      # compile TypeScript to dist/
 npm run typecheck  # check types
-npm run smoke      # render every component in jsdom
-npx http-server    # allows demo to be viewed at http://localhost:8080/demo
+npx http-server -P "http://localhost:8080/demo/index.html?"   # demo at http://localhost:8080/demo
+                   # (-P is the SPA fallback the demo's routed URLs need)
 npx shotest test   # visual tests: click through the demo, screenshotting every step
 npx shotest review # review/accept the visual changes against the baseline
 ```
@@ -418,11 +524,59 @@ top bar (icon, title, subtitle, action menu), a scrollable content area, and a
 footer. With `MainOptions.maxWidth` the content area is centred and its
 width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
 menu button below 640 px, or always a button with `navPosition: "button"`).
+Below 640 px that button opens the nav as a full page sliding in from the
+left; picking an item slides it away as the chosen screen enters from the
+right.
 
 ## [MainOptions](MainOptions.md) · interface
 
 Options for `main`.
 
+## [panels](panels.md) · constant
+
+Navigating the routed `S.main()` shell from code, for the times it isn't a
+link click, such as opening the screen for a record you just created.
+
+## [Page](Page.md) · interface
+
+What a route handler gets: the params from its route, plus everything the
+shell needs to know about the panel it is drawing. It's an Aberdeen proxy, so
+you can set things later, such as a `title` that arrives with your data or
+`loading` going back to `false`, and the shell keeps up.
+
+## Routes · type
+
+A route table: path templates mapped to panel draw functions. Used as the
+loose (non-inferred) type; `S.main()` infers a more precise type from the
+literal you pass, so each handler's `$page.params` is typed per its key.
+
+**Type:** `Record<string, RouteHandler>`
+
+## RouteHandler · type
+
+A panel draw function: it receives the panel's `Page` and draws into the current scope.
+
+**Type:** `(page: Page<P>) => void`
+
+## RouteTable · type
+
+The shape `S.main()`'s `routes` option is checked against: every key types its
+own handler's `params`. Used as a self-referential generic constraint, which
+is what makes `$page.params` infer from the route key.
+
+**Type:** `{ [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void }`
+
+## [PathParams](PathParams.md) · type
+
+The params object described by a path template, e.g.
+`PathParams<"/projects/[id]/tasks/[taskId=integer]">` is
+`{ id: string; taskId: number }`.
+
+## [SegParams](SegParams.md) · type
+
+The params contributed by a single path-template segment: `[x]` a string,
+`[x=integer]` a number, `[...x]` the rest of the path as one raw string.
+
 ## [menuButton](menuButton.md) · function
 
 A button that opens a | floating dropdown menu on
@@ -443,6 +597,24 @@ via `A` so a | floating menu opens (instead of
 the browser's own menu) on right-click or long-press. The menu is anchored to
 the element and closes on Escape, Tab, item selection, or any click outside.
 
+## [isFloatingMenuOpen](isFloatingMenuOpen.md) · function
+
+Whether a floating menu is currently open. Reflects live state (cleared the
+instant it closes), unlike the DOM — the panel lingers briefly while its
+`destroy=` transition plays out.
+
+## closeFloatingMenu · function
+
+Close the open floating menu (if any), returning focus to its anchor. With an
+`anchor`, only closes when the open menu belongs to it, so dismissing your own
+menu can't steal someone else's.
+
+**Signature:** `(anchor?: HTMLElement) => void`
+
+**Parameters:**
+
+- `anchor?: HTMLElement`
+
 ## [MenuOptions](MenuOptions.md) · interface
 
 Options for `menuButton` and `MainOptions.nav`.
@@ -502,6 +674,12 @@ Shows a confirmation dialog with Cancel and OK buttons. Returns a
 Shows a prompt dialog with a text input. Returns a `Promise<string | null>` —
 the entered string if the user confirmed, or `null` if cancelled.
 
+## isDialogOpen · function
+
+Whether any dialog is currently open (live state, not the lingering DOM).
+
+**Signature:** `() => boolean`
+
 ## [DialogOptions](DialogOptions.md) · interface
 
 Options for `dialog`.

package/skill/SegParams.md

@@ -0,0 +1,8 @@
+## SegParams · type
+
+The params contributed by a single path-template segment: `[x]` a string,
+`[x=integer]` a number, `[...x]` the rest of the path as one raw string.
+
+**Type:** `S extends `[...${infer Name}]` ? { [K in Name]: string } :
+	S extends `[${infer Name}=${infer Matcher}]` ? { [K in Name]: MatcherType<Matcher> } :
+	S extends `[${infer Name}]` ? { [K in Name]: string } : {}`

package/skill/box.md

@@ -9,6 +9,9 @@ out as a flex container.
 
 Shortcut: pass a function to use it directly as the body content.
 
+| `close: true` adds a ✕ that closes the panel the box
+is drawn in: the usual way back out of a screen in a routed `S.main()`.
+
 **Signature:** `(opts?: BoxOptions | Slot) => void`
 
 **Parameters:**
@@ -23,4 +26,5 @@ S.box({ header: "Profile", contentAttrs: "display:flex flex-direction:column", c
   S.textline({ label: "Name", bind: A.ref($user, "name") });
 }});
 S.box(() => A("p#Just some content"));   // shorthand
+S.box({ header: "Task 42", close: true, content: drawTask });  // ✕ closes this panel
 ```

package/skill/isFloatingMenuOpen.md

@@ -0,0 +1,12 @@
+## isFloatingMenuOpen · function
+
+Whether a floating menu is currently open. Reflects live state (cleared the
+instant it closes), unlike the DOM — the panel lingers briefly while its
+`destroy=` transition plays out.
+
+**Signature:** `(anchor?: HTMLElement) => boolean`
+
+**Parameters:**
+
+- `anchor?: HTMLElement` - When given, only reports `true` for a menu opened from *this*
+anchor — so a component can ask about its own menu rather than any menu.

package/skill/main.md

@@ -5,12 +5,24 @@ top bar (icon, title, subtitle, action menu), a scrollable content area, and a
 footer. With `MainOptions.maxWidth` the content area is centred and its
 width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
 menu button below 640 px, or always a button with `navPosition: "button"`).
+Below 640 px that button opens the nav as a full page sliding in from the
+left; picking an item slides it away as the chosen screen enters from the
+right.
 
-**Signature:** `(opts?: MainOptions) => void`
+Instead of a single `content` slot, pass `MainOptions.routes` and the
+shell takes over navigation: each route draws one screen, called a panel,
+and as many panels as fit are shown at a time, side by side on a wide screen
+and one at a time on a phone. See `MainOptions.routes` and `Page`.
+
+**Signature:** `<R extends RouteTable<R>>(opts?: MainOptions<R>) => void`
+
+**Type Parameters:**
+
+- `R extends RouteTable<R>`
 
 **Parameters:**
 
-- `opts: MainOptions` (optional)
+- `opts: MainOptions<R>` (optional)
 
 **Examples:**
 

package/skill/panels.md

@@ -0,0 +1,10 @@
+## panels · constant
+
+Navigating the routed `S.main()` shell from code, for the times it isn't a
+link click, such as opening the screen for a record you just created.
+
+The same rules as a link click apply: pushing a path that is already open
+goes back to it rather than opening it twice, and anything that would close a
+panel asks its `Page.requestClose` first.
+
+**Value:** `{ push(path: string): void; replace(path: string): void; close(path?: string): Promise<boolean>; readonly stack: readonly string[]; }`

package/skill/tabs.md

@@ -3,6 +3,11 @@
 A tabbed view. Renders an ARIA `tablist` of buttons and a single live panel
 for the selected tab. Supports keyboard navigation (left/right/home/end).
 
+More tabs than fit make the strip scroll sideways, with a ‹ / › button
+appearing over whichever end still has something to reach — a bare scroll area
+says nothing about itself to a mouse. Selecting a tab that's out of view
+(arrow keys, or a `bind` written from elsewhere) scrolls it back in.
+
 **Signature:** `(opts: TabsOptions) => void`
 
 **Parameters:**

package/src/components/autocomplete.ts

@@ -261,8 +261,14 @@ export function autocomplete(opts: AutocompleteOptions): void {
 				$st.open = false;
 			}
 		} else if (e.key === "Escape") {
-			$st.open = false;
-			if (!opts.multi) $st.query = labelFor(selectedValues()[0] ?? "");
+			// Only consume Escape while the list is showing: it dismisses the
+			// innermost layer, so a surrounding dialog must not also close. With the
+			// list already closed, let it pass through to the dialog/nav handlers.
+			if ($st.open) {
+				e.preventDefault();
+				$st.open = false;
+				if (!opts.multi) $st.query = labelFor(selectedValues()[0] ?? "");
+			}
 		} else if (e.key === "Backspace" && opts.multi && $st.query === "") {
 			const sel = selectedValues();
 			if (sel.length) remove(sel[sel.length - 1]!);