staffa 0.7.4 → 0.8.1

package/README.md

@@ -77,7 +77,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:
@@ -111,6 +111,114 @@ 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 panel is sized before your handler runs, so anything inside it that measures its own box — a chart, a virtualised list, a column count — gets a real one from the first frame rather than a zero-width one. A new panel starts at whatever `layout` says at that point, which is the default, so a handler that *assigns* `layout` is drawn at the medium width and reflowed immediately after. Assigning it later works too: the panel reflows to its new width without being redrawn, so nothing in it is rebuilt or loses its state, and the columns beside it move over.
+
+**The rest of `$page`:**
+
+- `params` and `path`: read-only.
+- `title`: shown in `document.title` while this panel is the top one.
+- `layout`: as above, and live — set it whenever you like and the panel reflows.
+- `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.
+
+A closed panel is torn down at once: its `A.clean()` hooks run the moment it closes, so subscriptions, timers and requests stop there and then. Only its element hangs around, inert and frozen, for the length of the exit animation.
+
+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. 
@@ -163,9 +271,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. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. 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
@@ -220,6 +328,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"
   }
 }
@@ -267,7 +377,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.
 
@@ -276,8 +386,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
 ```

package/dist/components/box.d.ts

@@ -5,6 +5,22 @@ export interface BoxOptions extends ContentOptions {
     header?: Slot;
     /** Footer content, drawn in a styled bar below the body. */
     footer?: Slot;
+    /**
+     * Draws a small ✕ button in the box's top-right corner: in the header row when
+     * there is a {@link BoxOptions.header | header}, floating over the body when
+     * there isn't.
+     *
+     * `true` closes the panel the box is drawn in, which is how a screen of a
+     * routed `S.main()` gives the user a way back (the shell draws no back
+     * arrows or ✕ of its own). Which panel that is gets worked out from the DOM
+     * when it's clicked, so the box needs no `$page` handed to it and works from
+     * any column, top of the stack or not. A box in a column further left closes
+     * just that column and leaves the others alone. Outside a routed shell it
+     * does nothing but warn.
+     *
+     * Pass a function to run that instead, for a dismissal of your own.
+     */
+    close?: boolean | (() => void);
     /** Aberdeen attr/style string applied to the body (content-holding) element. */
     contentAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the header bar. */
@@ -22,6 +38,9 @@ export interface BoxOptions extends ContentOptions {
  *
  * Shortcut: pass a function to use it directly as the body content.
  *
+ * {@link BoxOptions.close | `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()`.
+ *
  * @example
  * ```ts
  * const $user = A.proxy({name: "Kvothe"});
@@ -29,6 +48,7 @@ export interface BoxOptions extends ContentOptions {
  *   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
  * ```
  */
 export declare function box(opts?: BoxOptions | Slot): void;

package/dist/components/box.js

@@ -1,5 +1,6 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
+import { closeContainingPanel } from "./panels.js";
 // The box itself is a `.neutral` surface; its header/footer are `.neutral` surfaces
 // too — nested one level deeper, so they pick up the next elevation shade
 // automatically. Colours and borders come from the contextual tokens, so a box
@@ -11,11 +12,22 @@ import { drawSlot } from "../core.js";
 // single divider.
 A.insertGlobalCss({
     ".s-box": {
-        "&": "display:flex flex-direction:column overflow:hidden r: $s-radius-lg;",
+        // position:relative so a headerless box can hang its ✕ in the corner.
+        "&": "display:flex flex-direction:column overflow:hidden r: $s-radius-lg; position:relative",
         "&:not(:first-child)": "margin-top: $3",
         "> header": "display:flex align-items:center gap:$2 padding: $2 $3; border:0 border-bottom: 1px solid $s-faint; r:0 font-weight:600",
         "> footer": "display:flex align-items:center justify-content:flex-end gap:$2 padding: $2 $3; border:0 border-top: 1px solid $s-faint; r:0",
         "> div": "p:$3 gap:$3",
+        // The ✕: quiet until you're near it, and drawn in the surface's own tokens
+        // so it works on whatever the box was recoloured to. `margin-left:auto`
+        // parks it at the far end of the header's flex row.
+        ".s-box-close": "flex-shrink:0 margin-left:auto display:flex align-items:center justify-content:center " +
+            "width:1.6rem height:1.6rem p:0 border:0 background:transparent cursor:pointer " +
+            "fg:$s-muted font-size:0.95rem line-height:1 r:$s-radius-sm " +
+            "transition: color 0.12s, background 0.12s;",
+        ".s-box-close:hover": "fg:$s-text background: color-mix(in srgb, $s-text 8%, transparent);",
+        // Without a header there is no row to sit in, so it floats over the body.
+        "> .s-box-close": "position:absolute top:$2 right:$2 z-index:1",
     },
 });
 /**
@@ -28,6 +40,9 @@ A.insertGlobalCss({
  *
  * Shortcut: pass a function to use it directly as the body content.
  *
+ * {@link BoxOptions.close | `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()`.
+ *
  * @example
  * ```ts
  * const $user = A.proxy({name: "Kvothe"});
@@ -35,6 +50,7 @@ A.insertGlobalCss({
  *   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
  * ```
  */
 export function box(opts = {}) {
@@ -43,8 +59,16 @@ export function box(opts = {}) {
         // Header and footer get their own scopes so toggling them doesn't recreate
         // the body (which may hold focused inputs / lots of content).
         A(() => {
-            if (o.header != null)
-                A("header.s-s.neutral", o.headerAttrs, () => drawSlot(o.header));
+            if (o.header != null) {
+                A("header.s-s.neutral", o.headerAttrs, () => {
+                    drawSlot(o.header);
+                    if (o.close)
+                        drawCloseButton(o.close);
+                });
+            }
+            else if (o.close) {
+                drawCloseButton(o.close);
+            }
         });
         A("div", o.contentAttrs, () => {
             drawSlot(o.content);
@@ -55,3 +79,19 @@ export function box(opts = {}) {
         });
     });
 }
+/**
+ * The box's ✕. With `close: true` the panel to close is resolved from the DOM at
+ * click time — so one box can close whichever column it happens to be drawn in,
+ * and a box outside a routed shell simply warns.
+ */
+function drawCloseButton(close) {
+    A("button.s-box-close type=button aria-label=Close", () => {
+        A("click=", (e) => {
+            if (typeof close === "function")
+                close();
+            else
+                void closeContainingPanel(e.currentTarget);
+        });
+        A("span aria-hidden=true #✕");
+    });
+}

package/dist/components/layers.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Routed, multi-column "layer stack" navigation for {@link main}.
+ *
+ * An app designs every screen ("layer") as a narrow column. On a phone exactly
+ * one layer is visible — classic push/pop stack navigation. On a wider screen as
+ * many *top-of-stack* layers as fit are shown side by side, left-to-right =
+ * shallow-to-deep. Same code, no media queries in the app.
+ *
+ * Navigation is URL-driven through `aberdeen/route`: the URL carries the *top*
+ * layer, while the layers beneath it live in the history entry's state — so the
+ * browser's back/forward buttons walk an undo history of whole stack snapshots,
+ * and a reload (or a shared link) reproduces the columns exactly.
+ */
+/** Flattens an intersection into a single object type, so hovers read nicely. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * The params contributed by a single path-template segment: `:x` a string,
+ * `:x(num)` a number, `*x` the remaining segments as `string[]`.
+ */
+export type SegParams<S extends string> = S extends `:${infer Name}(num)` ? {
+    [K in Name]: number;
+} : S extends `:${infer Name}` ? {
+    [K in Name]: string;
+} : S extends `*${infer Name}` ? {
+    [K in Name]: string[];
+} : {};
+/**
+ * The params object described by a path template, e.g.
+ * `PathParams<"/projects/:id/tasks/:taskId(num)">` is
+ * `{ id: string; taskId: number }`.
+ */
+export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
+/** A layer draw function: it receives the layer's {@link Page} and draws into the current scope. */
+export type RouteHandler<P = any> = (page: Page<P>) => void;
+/**
+ * A route table: path templates mapped to layer 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.
+ */
+export type Routes = Record<string, RouteHandler>;
+/**
+ * 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.
+ */
+export type RouteTable<R> = {
+    [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
+};
+/**
+ * The per-layer state object, an Aberdeen proxy passed to the route handler as
+ * its only argument. The handler draws inside the layer's own reactive scope, so
+ * mutating the page (a `title` arriving with the data, `loading` flipping off)
+ * updates the shell in place.
+ *
+ * Search params and the hash belong to the **top** layer only — a layer that is
+ * pushed under another one keeps only its path, so anything a layer needs to
+ * redraw itself must live in that path.
+ */
+export interface Page<P = Record<string, string | number | string[]>> {
+    /**
+     * The params matched from this layer's path, typed per its route key:
+     * `:x` is a `string`, `:x(num)` a `number`, `*x` a `string[]`. Read-only.
+     */
+    readonly params: P;
+    /** This layer's path, e.g. `"/projects/7"`. Read-only. */
+    readonly path: string;
+    /** Shown in `document.title` while this layer is top-most. */
+    title?: string;
+    /**
+     * How much room this layer asks for.
+     *
+     * - `"medium"` (the default) fills the standard content area exactly — the
+     *   room a 1280px page leaves beside the sidebar.
+     * - `"small"` is half of that content area (minus a gutter) whenever the
+     *   screen is wide enough for two columns. A lone small leaves its other
+     *   half open — which is exactly where the next pushed small lands, without
+     *   anything on screen moving. On a screen too narrow for two columns it
+     *   fills the whole content area, like a medium.
+     * - `"large"` takes as much room as the window has: while it is the visible
+     *   layer the whole shell (top bar, body, footer) stretches to the screen
+     *   edges instead of the standard 1280px page.
+     *
+     * As many top-of-stack layers as the window fits are shown side by side; on
+     * a wide enough screen the page stretches beyond its standard 1280px —
+     * staying centred — to hold them (three smalls, a medium and a small, ...).
+     *
+     * Widths depend only on the window — never on what else is open — so a
+     * layer is never resized except when the window itself is. Read **once**,
+     * right after the handler's synchronous run: set it in the handler, because
+     * later changes are ignored.
+     */
+    layout?: "small" | "medium" | "large";
+    /**
+     * Set `true` while the layer is still fetching what it needs, and back to
+     * `false` when done. A freshly pushed layer that is `loading` briefly holds
+     * its enter animation so it can slide in with real content; if the fetch
+     * drags on it slides in anyway and shows a built-in loading indicator until
+     * the flag clears. Presentation only — the stack, the URL and the close
+     * guards are never delayed by it.
+     */
+    loading?: boolean;
+    /**
+     * Close guard. Called — and awaited — whenever anything would remove this
+     * layer: Escape, this page's own close affordances ({@link Page.close}, a box
+     * with `close: true`), browser back, a link that truncates past it, or
+     * {@link layers}.`close()`. Return `false` to veto. Typical use: a dirty check
+     * plus {@link confirm}.
+     */
+    requestClose?: () => boolean | Promise<boolean>;
+    /**
+     * Guarded close of **this** layer, wherever it sits in the stack. The top
+     * layer pops (back to the snapshot beneath it); a layer that isn't on top is
+     * *spliced* out — the columns above it keep their place, their DOM and their
+     * state, and the URL doesn't change. Either way it is recorded as a history
+     * entry, so the browser's back button restores the closed column.
+     *
+     * Resolves `false` when {@link Page.requestClose} vetoed (or when the layer is
+     * the only one on the stack, and so has nothing to close back to). The shell
+     * draws no close chrome of its own, so this — or `S.box`'s `close` option — is
+     * how a page provides its way out.
+     *
+     * @example
+     * ```ts
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * ```
+     */
+    close(): Promise<boolean>;
+}
+/** Options the layer stack needs from its shell. */
+export interface LayerStackOptions {
+    routes: Routes;
+    notFound?: RouteHandler<{}>;
+    /** Set `false` to show only the top layer, however much room there is. */
+    stacking?: boolean;
+    /** The shell's own title, used as the suffix of `document.title`. */
+    title?: unknown;
+}
+export declare class LayerController {
+    private compiled;
+    private opts;
+    /** The live stack, shallow-to-deep. Closing layers are no longer part of it. */
+    private live;
+    private byId;
+    private nextId;
+    /** Drives rendering: layer id → its `order` (used only as the sort key). */
+    $ids: Record<string, number>;
+    /**
+     * The live stack's paths and its top layer, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling and `S.layers.stack`.
+     */
+    $state: {
+        paths: string[];
+        topId: number;
+    };
+    private containerEl?;
+    /** The body width at the last layout; a change means a window resize → snap. */
+    private lastBodyW;
+    private layoutQueued;
+    private timers;
+    constructor(opts: LayerStackOptions);
+    /** Resolve a path to its route handler + params, falling back to `notFound`. */
+    private resolve;
+    private matches;
+    /**
+     * The one derivation rule for origin-less navigation (§2.8): probe every
+     * prefix of the path against the route table; the matching prefixes become
+     * the stack. Prefixes without a route are simply skipped, so an app that
+     * doesn't want one screen stacked under another just doesn't route that
+     * prefix. The path itself is always the top layer, matched or not.
+     */
+    deriveStack(path: string): string[];
+    /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
+    private targetFor;
+    /** The stack the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
+    /**
+     * The route guard (see `route.setGuard` in the constructor): asked before any
+     * route change lands, wherever it came from. Runs the {@link Page.requestClose}
+     * guard of every layer the new route's stack would remove — a set defined by
+     * the target (the commit reconciles by path), so a derived stack that shares
+     * nothing with the live one still asks exactly the layers that are closing.
+     */
+    private checkChange;
+    private paths;
+    /** The live layers a target stack drops — by path, so a splice removes only its own column. */
+    private removedBy;
+    /**
+     * Adopt a stack proposed by the URL. Close guards have already been run (and
+     * have passed) by the time a route change is visible here — `checkChange` is
+     * consulted by the router itself, before anything is applied.
+     */
+    private propose;
+    /**
+     * Apply a target stack: unmount what's gone, mount what's new, animate the
+     * difference.
+     *
+     * Reconciliation is BY PATH (a stack can't hold the same path twice, so that's
+     * well-defined): a layer present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a layer be spliced out of the middle
+     * (§7) without disturbing the columns above it. A common-prefix diff would
+     * remount every one of them, throwing away exactly the scroll and form state
+     * rule 5 promises to keep.
+     */
+    private commit;
+    private createEntry;
+    /**
+     * Start a layer's exit: it lingers in the DOM, inert and fading, and is dropped
+     * only when the fade itself ends. Removing it on a fixed timer instead would
+     * race the transition — pull the element a frame early and the layer appears to
+     * fade half-way and then vanish. The timeout is just a fallback for when no
+     * `transitionend` is coming at all (transitions off, or an element that never
+     * got placed).
+     */
+    private beginClose;
+    /**
+     * Navigate back to a stack that is a truncation of the current one — the shared
+     * implementation of Escape, a page closing itself, return-links and
+     * `S.layers.close()`. `route.back()` prefers the history entry where that
+     * layer was on top (with its scroll state intact); when there is no such entry
+     * it replaces the current one, carrying the snapshot passed as the fallback.
+     * Either way the route guard asks the closing layers first, and the returned
+     * promise reports its verdict.
+     */
+    private goBackTo;
+    /** Close every layer above `index` (guarded). Resolves `false` when vetoed. */
+    closeDownTo(index: number): Promise<boolean>;
+    /** Guarded close of the top layer. */
+    closeTop(): Promise<boolean>;
+    /**
+     * Guarded close of the layer at `index`, top of the stack or not — what a
+     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     *
+     * The top layer pops back to the snapshot beneath it. Any other layer is
+     * *spliced* out: its guard runs, the columns above it keep their place and
+     * state (the commit reconciles by path), and the URL doesn't change, since the
+     * top layer didn't. That still gets its own history entry, so the browser's
+     * back button restores the closed column like any other snapshot — which is
+     * why it goes through `route.go` here rather than through `navigate()`, whose
+     * "link to the layer we're already on" check would see a no-op.
+     */
+    closeLayerAt(index: number): Promise<boolean>;
+    /** Guarded close of whichever layer `path` is open as. False when it isn't open. */
+    closeByPath(path: string): Promise<boolean>;
+    /** Guarded close of the layer whose `.s-layer` element this is. */
+    closeLayerEl(el: HTMLElement): Promise<boolean>;
+    /**
+     * Navigate to `href`. `originIndex` is the depth of the layer the link lives
+     * in (−1 when it has none — a nav item or a programmatic call, which derives
+     * the whole stack instead). `replace` swaps the originating layer rather than
+     * stacking on top of it.
+     */
+    navigate(href: string, originIndex: number, replace?: boolean): void;
+    /** Programmatic push/replace, with the top layer as the implied origin. */
+    pushPath(path: string, replace: boolean): void;
+    /**
+     * Link handling through `route.interceptLinks()`, whose handler hook hands us
+     * the anchor so we can decide what the click *means*: the originating
+     * `.s-layer` (which decides what the click truncates), `data-layer=replace`,
+     * and return-to-an-open-layer semantics. The exclusion rules (targets,
+     * downloads, modified clicks, external URLs) live in Aberdeen; the close
+     * guards run in `checkChange` when our navigation reaches the router.
+     */
+    private interceptLinks;
+    /** `"<page title> · <app title>"`, kept in sync with the top layer. */
+    private watchTitle;
+    /**
+     * Draw the layer viewport into the current element. Called by `main()`.
+     *
+     * There is deliberately no close chrome here — no back rail, no ←: pages
+     * provide their own way out (see {@link Page.close} and `S.box`'s `close`
+     * option). The shell contributes Escape and the browser's own back button.
+     */
+    drawStack(): void;
+    private drawLayer;
+    scheduleLayout(): void;
+    /**
+     * Size and position every layer, and publish the width of the whole ensemble
+     * (sidebar + separator + columns) for the shell to centre itself on.
+     *
+     * This is everything CSS can't work out for itself: which layers exist, which
+     * of them are visible, how wide each one is and where it sits. All the motion
+     * between two of these arrangements is CSS's job.
+     */
+    private layout;
+    /** Let a `loading` layer's enter animation wait — but not indefinitely. */
+    private holdEnter;
+}
+/**
+ * Programmatic navigation for the routed `S.main()` shell — for acts that aren't
+ * link clicks, such as pushing the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already an open
+ * layer *returns* to it instead of duplicating it, and anything that would
+ * remove a layer asks its {@link Page.requestClose} guard first.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.layers.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export declare const layers: {
+    /** Push `path` on top of the current top layer. */
+    push(path: string): void;
+    /** Replace the current top layer with `path`. */
+    replace(path: string): void;
+    /**
+     * Guarded close: of the top layer, or — given a `path` — of whichever layer is
+     * open at it, which is *spliced* out when it isn't on top (the columns above it
+     * stay exactly as they are). Resolves `false` when a guard vetoed, or when
+     * `path` isn't an open layer.
+     */
+    close(path?: string): Promise<boolean>;
+    /** The current stack of paths, shallow-to-deep. Reactive: safe to read in a scope. */
+    readonly stack: readonly string[];
+};
+/**
+ * Guarded close of the layer `el` sits in, resolved from the DOM — which is what
+ * lets a close affordance work without any page context, from any column,
+ * whether or not it is on top. Used by `S.box`'s `close: true`.
+ *
+ * Outside a routed shell (or outside any layer — a box in a dialog, say) there is
+ * nothing to close: it warns and resolves `false`.
+ */
+export declare function closeContainingLayer(el: Element | null | undefined): Promise<boolean>;
+export {};