npm - staffa - Versions diffs - 0.9.0 → 0.10.0 - Mend

staffa 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (60) hide show

package/README.md +106 -48
package/dist/components/autocomplete.js +1 -1
package/dist/components/box.d.ts +8 -16
package/dist/components/box.js +21 -27
package/dist/components/button.d.ts +40 -0
package/dist/components/button.js +85 -12
package/dist/components/buttonChooser.js +1 -1
package/dist/components/checkbox.js +3 -3
package/dist/components/field.js +3 -3
package/dist/components/main.d.ts +134 -71
package/dist/components/main.js +245 -174
package/dist/components/menu.d.ts +72 -14
package/dist/components/menu.js +231 -34
package/dist/components/pages.d.ts +638 -0
package/dist/components/pages.js +1510 -0
package/dist/components/panels.d.ts +448 -225
package/dist/components/panels.js +819 -435
package/dist/components/tabs.d.ts +37 -0
package/dist/components/tabs.js +128 -69
package/dist/core.d.ts +1 -1
package/dist/core.js +1 -1
package/dist/glyphs.d.ts +24 -0
package/dist/glyphs.js +25 -0
package/dist/index.d.ts +4 -4
package/dist/index.js +3 -4
package/dist/staffa.esm.js +1 -1
package/dist/theme.d.ts +67 -0
package/dist/theme.js +12 -2
package/package.json +2 -2
package/skill/BoxOptions.md +7 -12
package/skill/IconButtonOptions.md +41 -0
package/skill/MainOptions.md +106 -58
package/skill/MenuItem.md +16 -1
package/skill/MenuListOptions.md +24 -0
package/skill/MenuOptions.md +3 -2
package/skill/Panel.md +190 -0
package/skill/PanelStack.md +106 -0
package/skill/SKILL.md +172 -64
package/skill/ScrollStripOptions.md +21 -0
package/skill/box.md +1 -4
package/skill/closeNav.md +3 -3
package/skill/iconButton.md +27 -0
package/skill/main.md +13 -9
package/skill/menu.md +29 -0
package/skill/scrollStrip.md +28 -0
package/src/components/autocomplete.ts +1 -1
package/src/components/box.ts +29 -39
package/src/components/button.ts +109 -8
package/src/components/buttonChooser.ts +1 -1
package/src/components/checkbox.ts +3 -3
package/src/components/field.ts +3 -3
package/src/components/main.ts +381 -188
package/src/components/menu.ts +265 -37
package/src/components/panels.ts +1136 -526
package/src/components/tabs.ts +134 -68
package/src/core.ts +1 -1
package/src/index.ts +4 -4
package/src/theme.ts +14 -3
package/skill/Page.md +0 -119
package/skill/panels.md +0 -10

package/dist/components/panels.d.ts CHANGED Viewed

@@ -1,16 +1,29 @@
+import { OPAQUE } from "aberdeen";
+import { type Slot } from "../core.js";
 /**
  * Routed, multi-column panel navigation for {@link main}.
  *
- * Each route draws one screen of the app, called a panel, and as many panels as
- * fit are shown at a time. On a phone that is one, so a link opens a new panel
- * on top and closing it brings the previous one back. On a wider screen the
- * panels that would have covered each other sit side by side instead, oldest on
- * the left. The app's own code is the same either way.
+ * Each route draws one screen of the app, called a *panel*. The open panels
+ * form a **stack**, and one of them is the **current** panel: the one the URL
+ * names, and the rightmost column on screen. As many panels as fit are shown,
+ * ending at the current one — on a phone that is one at a time, on a wider
+ * screen the panels that would have covered each other sit side by side
+ * instead. The app's own code is the same either way.
  *
- * Navigation runs through `aberdeen/route`: the URL holds the top panel, and
- * the ones beneath it are stored beside it in the history entry. So back and
- * forward step through whole arrangements of columns, and a reload (or a shared
- * link) brings the same columns back.
+ * Going to a panel that is already open — a breadcrumb, or any link to it —
+ * just moves the current-panel cursor along the stack: panels right of it stay
+ * open, parked past the right edge of the viewport, and nothing closes.
+ * Opening a *new* panel is what prunes: everything after the panel it came
+ * from closes, except panels the user pinned — which ride along beneath the
+ * new panel — and panels holding unsaved work, which no navigation ever tears
+ * down. Escape steps one panel left, closing the panel it leaves only when
+ * that panel is the stack's discardable end.
+ *
+ * Navigation runs through `aberdeen/route`: the URL holds the current panel,
+ * and the rest of the arrangement — the panels before it, the ones parked
+ * after it, and which are pinned — is stored beside it in the history entry.
+ * So back and forward step through whole arrangements of columns, and a reload
+ * (or a shared link) brings the same columns back.
  */
 /** Flattens an intersection into a single object type, so hovers read nicely. */
 type Prettify<T> = {
@@ -39,21 +52,21 @@ export type SegParams<S extends string> = S extends `[...${infer Name}]` ? {
  * `{ id: string; taskId: number }`.
  */
 export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
-/** A panel draw function: it receives the panel's {@link Page} and draws into the current scope. */
-export type RouteHandler<P = any> = (page: Page<P>) => void;
+/** A panel draw function: it receives the panel's {@link Panel} and draws into the current scope. */
+export type RouteHandler<P = any> = (panel: Panel<P>) => void;
 /**
  * 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.
+ * literal you pass, so each handler's `$panel.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.
+ * is what makes `$panel.params` infer from the route key.
  */
 export type RouteTable<R> = {
-    [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
+    [K in keyof R & string]: (panel: Panel<Prettify<PathParams<K>>>) => void;
 };
 /**
  * What belongs beneath a path that arrives cold, worked out from the params of
@@ -76,128 +89,323 @@ export type AncestorTable<R> = {
  * 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.
+ * Search params and the `#hash` belong to the current panel only. Any other
+ * panel keeps just its path, so anything a panel needs in order to redraw
+ * itself has to live in that path. (A panel browsed away from does get its
+ * search and hash back when a crumb makes it current again.)
  */
-export interface Page<P = Record<string, string | number | string[]>> {
+export interface Panel<P = Record<string, string | number | string[]>> {
     /**
      * 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.
      */
     readonly params: P;
+    /**
+     * The stack this panel is in — the very object `S.main()` hands back. It is
+     * here as well because a route handler runs *while* that call is still
+     * going, so its return value isn't available to it yet; this always is.
+     */
+    readonly stack: PanelStack;
     /** This panel's path, e.g. `"/projects/7"`. Read-only. */
     readonly path: string;
-    /** Shown in `document.title` while this panel is top-most. */
+    /**
+     * Names this screen, in the top bar's breadcrumb stack and in
+     * `document.title` while the panel is current. A panel that doesn't set one
+     * borrows the first line of text in its own body, so the stack never shows a
+     * blank — but a borrowed paragraph makes a poor name, so say it yourself.
+     *
+     * It does **not** conjure a heading: naming a screen and heading its content
+     * are different jobs, and a screen that wants its name in its own body
+     * writes it there, where it owns the typography.
+     */
     title?: string;
     /**
-     * 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.
+     * This screen's own actions: a couple of buttons, a menu. The shell draws
+     * them — never the panel — and *where* depends on facts only the shell has:
+     * a quiet strip at the top of this panel's column while several columns are
+     * up, and the top bar (where they take the app's own `menu` slot) once the
+     * shell is narrow and this panel is the screen.
+     *
+     * They are drawn in exactly one of those places at a time, so crossing the
+     * threshold redraws them; anything stateful inside (the focus in a search
+     * box) is lost. Buttons and menus are fine.
+     */
+    actions?: Slot;
+    /**
+     * How wide this panel's column actually is, in pixels — what
+     * {@link Panel.maxWidth} asked for, resolved against the window. Reactive and
+     * read-only, and correct *before* your handler draws, so content that sizes
+     * itself can read it instead of measuring.
      *
-     * - `"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.
+     * You rarely need it: the shell places the chrome for you. It's for content
+     * that genuinely differs by width, such as a table that becomes a list.
+     */
+    readonly width: number;
+    /**
+     * Whether this panel is on screen right now: not crowded out from under the
+     * visible run, not parked past its right end, and not on its way out.
+     * Reactive and read-only.
      *
-     * 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.
+     * The one to hang per-panel floating UI on (a FAB, a "3 selected" bar), for
+     * which "am I the current panel?" is the wrong question — two columns can be
+     * visible at once, and both of them are really there.
+     */
+    readonly visible: boolean;
+    /**
+     * The widest this panel can usefully be. Every panel must work at 360–540px,
+     * because that is what it gets when two columns fit; this says how much
+     * *more* it can take.
      *
-     * 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.
+     * - `"half"` — nothing more. Half the content area (360–540px), so a second
+     *   column fits beside it. For lists and detail forms.
+     * - `"full"` (the default) — the whole content area, up to ~1100px.
+     * - `"screen"` — the whole window, unbounded: boards, wide tables, dense
+     *   dashboards. While one is open the shell itself stretches to the screen
+     *   edges instead of stopping at the standard 1280px page.
      *
-     * The panel is sized from this **before** your handler runs, so anything that
-     * measures its own box has a real one from the first frame. What it is sized
-     * at is whatever this says at that moment, which for a brand-new panel is the
-     * default: a handler that *assigns* `layout` is drawn at the medium width and
-     * reflowed immediately after — in time for the frame, but not for a
-     * measurement taken in the same breath.
+     * Below the width two columns need, everything takes the content area
+     * whatever it asked for. Widths depend only on the window, never on what
+     * else is open, so opening or closing a panel never resizes another.
      *
-     * Assigning it later works just as well. When your data arrives and you find
-     * you want the wide one, 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.
+     * Set it at the top of your handler and the panel is already that wide when
+     * you draw (see {@link Panel.width}); set it later — when your data tells you
+     * — and the panel reflows without being redrawn, keeping its state, while
+     * the columns beside it move over.
      */
-    layout?: "small" | "medium" | "large";
+    maxWidth?: "half" | "full" | "screen";
     /**
      * 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.
+     * affects the animation; the stack and the URL never wait for it.
      */
     loading?: boolean;
     /**
-     * Your chance to say no. Everything that would close this panel waits for
-     * it: Escape, the panel's own ✕ or Cancel button ({@link Page.close}, or a
-     * box with `close: true`), the browser's back button, a link that would
-     * close it, and {@link panels}.`close()`. Return `false` to keep the panel
-     * open, usually after a dirty check and a {@link confirm}.
+     * Keeps this panel from being closed by navigation happening *elsewhere*.
+     * Opening a new panel normally closes everything after the panel it came
+     * from; a pinned panel survives that, staying in the stack — parked past the
+     * right edge of the viewport — slotted in beneath the new panel, one crumb
+     * click away. The user toggles it from the crumb's context menu
+     * (right-click or long-press), which is also where the pin shows; setting
+     * it from code does the same thing.
+     *
+     * A pin never blocks an *explicit* close: Escape at the stack's end,
+     * {@link Panel.close}, the crumb menu's Close and `data-panel=replace` all
+     * still close the panel.
      */
-    requestClose?: () => boolean | Promise<boolean>;
+    pinned?: boolean;
     /**
-     * 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.
+     * Set this while the panel holds work that must not be lost — a dirty form,
+     * an upload in flight. An unsaved panel cannot be closed, by anything:
+     * navigation that would prune it parks it instead, past the viewport's
+     * right edge, wearing a ● in its crumb — even the browser's back button
+     * only parks it. {@link Panel.close} and the crumb menu's Close refuse,
+     * Escape on it steps left along the stack rather than closing, and closing
+     * the browser tab runs into the browser's own are-you-sure (after which the
+     * shell brings the unsaved panel back on screen).
      *
-     * Resolves `false` if the panel didn't close: {@link 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.
+     * Only the app clears it; the user has no toggle. A Save or Discard button
+     * clears it and then closes:
+     *
+     * ```ts
+     * A(() => { $panel.unsaved = $form.dirty || undefined; });
+     * S.button({ content: "Discard", attrs: ".neutral", click: () => {
+     *   $panel.unsaved = false;   // explicitly — see below
+     *   void $panel.close();
+     * }});
+     * ```
+     *
+     * The explicit `unsaved = false` before `close()` matters when the flag is
+     * kept by a reactive scope, as above: resetting the form marks that scope
+     * dirty, but it reruns *after* the running handler — after `close()` has
+     * already been refused.
+     */
+    unsaved?: boolean;
+    /**
+     * Closes **this** panel, wherever it sits in the stack. Closing the current
+     * panel hands the focus to the panel on its left; closing any other panel
+     * takes just it away, leaving the columns around it where they are, with
+     * their state. Either way it becomes a history entry, so the browser's
+     * back button brings the panel back.
+     *
+     * Resolves `false` if the panel didn't close: it holds
+     * {@link Panel.unsaved} work, it was the only panel on the stack (so
+     * there's nothing to show instead), or another navigation got there first.
+     * The shell's breadcrumbs already travel back, so reach for this when a
+     * screen wants a more explicit way out: a Cancel button, or a Save that
+     * closes.
      *
      * @example
      * ```ts
-     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $panel.close() });
      * ```
      */
     close(): Promise<boolean>;
 }
-/** Options the panel stack needs from its shell. */
+/** Options the stack needs from its shell. */
 export interface PanelStackOptions {
     routes: Routes;
     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 top panel, however much room there is. */
+    /** Set `false` to show only the current panel, however much room there is. */
     stacking?: boolean;
     /** The shell's own title, used as the suffix of `document.title`. */
     title?: unknown;
+    /**
+     * The shell's live narrow flag (see `main()`), which decides where a panel's
+     * chrome goes: in its own column, or promoted into the top bar. Shared rather
+     * than measured again here, so the bar and the columns can't disagree about
+     * which regime they are in.
+     */
+    $shell: {
+        narrow: boolean;
+    };
 }
-export declare class PanelController {
+/**
+ * The panel stack behind a routed `S.main()`, and what that call hands back:
+ * the open {@link Panel}s, which of them is current, and the four ways to
+ * change that. Everything on it is scoped to its own shell.
+ *
+ * Every navigation settles asynchronously (closes travel through the
+ * browser's history), so the methods resolve once it has: `true` when it
+ * landed, `false` when it didn't — an unsaved panel refused to close, an
+ * app-registered route guard said no, or another navigation superseded it.
+ * Ignore the promise unless you care.
+ *
+ * @example
+ * ```ts
+ * const shell = S.main({ title: "Trackle", routes: { ... } });
+ *
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   shell.pushPanel(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export interface PanelStack {
+    /**
+     * The open panels, oldest first — the stack itself, as live objects rather
+     * than a copy of it. Writing through one is how you pin a panel, or rename
+     * it, from outside its own handler. Reactive on the stack's shape; don't
+     * hold a {@link Panel} across a navigation, since a closed one is dropped
+     * here while its element plays out its exit.
+     */
+    readonly panels: readonly Panel[];
+    /** Index into {@link PanelStack.panels} of the current panel. Reactive. */
+    readonly currentPanelIndex: number;
+    /**
+     * The current panel — shorthand for `panels[currentPanelIndex]`, and
+     * `undefined` only while the stack is still empty. Reactive on *which*
+     * panel is current; the fields you then read (`title`, `actions`, …) are
+     * reactive in their own right.
+     */
+    readonly currentPanel: Panel | undefined;
+    /**
+     * Opens `path` in a new panel on top of the current one, closing the
+     * unpinned panels that were after it (pinned ones stay, sliding in beneath
+     * the new panel).
+     *
+     * The same rules as a link click apply: pushing a path that is already open
+     * goes back to it — a focus move along the stack, closing nothing — rather
+     * than opening it twice, and a panel holding {@link Panel.unsaved} work is
+     * never closed, only parked. That's what a plain link does, and what
+     * `data-panel=push` says outright.
+     */
+    pushPanel(path: string): Promise<boolean>;
+    /**
+     * Opens `path` in place of the current panel, which closes. The panels
+     * beneath it stay as they are. That's what a `data-panel=replace` link does.
+     */
+    replacePanel(path: string): Promise<boolean>;
+    /**
+     * Opens `path` as a whole stack rather than on top of what's there: the same
+     * thing a nav item or a fresh tab does. Without `beneath`, the stack under it
+     * is worked out the way a cold link's is (see {@link MainOptions.ancestors});
+     * with it, the paths you give are opened underneath, shallowest first.
+     *
+     * That's the one for a screen whose URL doesn't say where it belongs — the
+     * thread a notification opens — and for seeding a stack from code in general.
+     * Panels the new stack also holds stay as they are; ones it drops close,
+     * except panels with {@link Panel.unsaved} work, which stay, parked.
+     *
+     * A `data-panel=open` link does the same thing (without a `beneath`): it
+     * leaves the panel it sits in behind rather than stacking on it, which is
+     * what a link to somewhere else in the app wants — a search hit, a mention.
+     *
+     * @example
+     * ```ts
+     * shell.openPanelStack(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+     * ```
+     */
+    openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
+    /**
+     * Closes the current panel, or, given a `path`, whichever panel is open at
+     * it. Closing the current panel hands the focus to the panel on its left;
+     * closing any other panel takes just it away, leaving the columns around it
+     * exactly as they are, with their state. Either way it becomes a history
+     * entry, so the browser's back button brings the panel back.
+     *
+     * Resolves `false` if the panel didn't close: it holds {@link Panel.unsaved}
+     * work, `path` isn't open, it was the stack's only panel, or another
+     * navigation got there first.
+     */
+    closePanel(path?: string): Promise<boolean>;
+}
+/**
+ * The controller behind a routed shell. It implements {@link PanelStack} —
+ * the app-facing face, and the only part of it that is Staffa API — and on
+ * top of that draws the columns and the breadcrumbs for `main()`, which
+ * constructs it.
+ */
+export declare class PanelStackController implements PanelStack {
+    /**
+     * Kept out of Aberdeen's proxy wrapping: this is a class instance holding
+     * DOM nodes, timers and route handlers, and it rides inside every
+     * {@link Panel.stack}. Its reactivity doesn't need the wrapper — it comes
+     * from `$state` and the panels, which are proxies in their own right.
+     */
+    readonly [OPAQUE] = true;
     private compiled;
     /** The `ancestors` table, compiled like the routes it is keyed by. */
     private ancestors;
     private opts;
-    /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
-    private live;
-    private byId;
-    private nextId;
-    /** Drives rendering: panel id → its `order` (used only as the sort key). */
-    $ids: Record<string, number>;
-    /**
-     * The live stack's paths and its top panel, for reactive readers: the
-     * `document.title` watcher, `main()`'s Escape handling and `S.panels.stack`.
-     */
-    $state: {
-        paths: string[];
-        topId: number;
-    };
+    /**
+     * The live stack, oldest first (closing panels are no longer part of it),
+     * and which of its panels is current — the one reactive fact about the
+     * stack's *shape*. The getters, the crumbs and `document.title` subscribe
+     * to it simply by reading it; each commit publishes the next shape by
+     * assigning a fresh `live` array. The entries themselves are opaque (see
+     * {@link PanelEntry}), so the array carries their comings, goings and
+     * order — nothing deeper; a panel's own facts stay separately reactive on
+     * its `$panel`, which is what lets a panel rename itself without the
+     * stack redrawing.
+     *
+     * One rule makes this safe to touch from anywhere: **queries subscribe,
+     * commands peek**. The getters below are the queries. Every navigation
+     * entry point (`navigate`, `closePath`, `back`, …) wraps itself in
+     * `A.peek`, so an app calling one from inside a reactive scope (a
+     * redirect in a route handler, say) can't subscribe that scope to the
+     * very stack it is changing — and everything those commands call through
+     * to, `propose` and `commit` included, inherits the same guarantee and
+     * reads the stack plainly.
+     */
+    private $state;
+    /**
+     * The open panels again, keyed by path — the shape as the DOM consumes it.
+     * `drawColumns`' `onEach` mounts and unmounts panels by key, so a panel
+     * spliced out of the middle of the stack touches exactly one key, and the
+     * DOM of the retained columns — scroll positions, half-typed forms — is
+     * left alone. (Iterating `live` itself would key panels by array index,
+     * and a splice renumbers every index after it, redrawing them all.) A
+     * key's value is its entry, by reference, and is never reassigned, so a
+     * panel only ever redraws wholesale when its path closes.
+     */
+    private $open;
+    /** Feeds {@link PanelEntry.order}: one shared counter, so keys never tie. */
+    private nextOrder;
     private containerEl?;
     /** The shell's measurements, shared by everything drawn since they were taken. */
     private geom?;
@@ -205,10 +413,12 @@ export declare class PanelController {
     private lastBodyW;
     private layoutQueued;
     private timers;
-    /** The stack the navigation in flight is heading for; see {@link intended}. */
+    /** The arrangement the navigation in flight is heading for; see {@link intended}. */
     private intent;
     /** The navigation the router hasn't settled yet, if any. */
     private settling;
+    /** The route last seen by the observer, for stashing a left panel's query. */
+    private lastSeen;
     /** The one navigation waiting behind it; see {@link issue}. */
     private queued;
     constructor(opts: PanelStackOptions);
@@ -227,9 +437,9 @@ export declare class PanelController {
      * and the matching ones become the stack. Either way, a path with no route is
      * skipped rather than opened as a "not found" column, so an app that doesn't
      * want one screen stacked under another simply doesn't route it. The path
-     * itself is always the top panel, matched or not.
+     * itself always ends the derived stack, matched or not.
      */
-    deriveStack(path: string): string[];
+    private deriveStack;
     /**
      * Ask the `ancestors` table what belongs beneath `path`. The first key that
      * matches answers — with its own matched params, so it never has to take the
@@ -239,30 +449,41 @@ export declare class PanelController {
     private askAncestors;
     /** Every prefix of `path` that has a route, shallowest first. */
     private prefixesOf;
-    /** 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 panel 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 panels that are closing.
+     * The pinned panels among `stack`, in order, minus `omit` — the ones a
+     * navigation must carry along rather than close. Pin flags live on the
+     * panels themselves, so a path without a live panel can't be pinned.
+     */
+    private pinnedIn;
+    /** Whether the panel open at `path` (if any) holds unsaved work. */
+    private unsavedAt;
+    /**
+     * The arrangement a route implies: its snapshot around its path, or —
+     * without a snapshot — derived, with the new panel current at the end and
+     * any pinned panels carried along beneath it.
+     *
+     * The snapshot reads subscribe — they are the URL's, exactly what the
+     * route observer is for. The derivation is peeked instead: it reads the
+     * live stack for its pins, which is the very thing that observer rewrites,
+     * and subscribing to it would re-run the observer once per commit.
      */
-    private checkChange;
+    private targetFor;
+    /** The arrangement the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
     private paths;
-    /** The live panels 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.
+     * Adopt an arrangement proposed by the URL — after repairing it: panels
+     * holding unsaved work are never torn down by a navigation, wherever it
+     * came from — a link, a nav item, even a browser back to an entry from
+     * before the panel existed. Whatever the target drops, they stay, parked
+     * after the current panel and wearing the ● that says why. (They are
+     * deliberately not written into history entries: the work they protect
+     * lives in the page's DOM, which a reload clears anyway.)
      */
     private propose;
     /**
-     * Apply a target stack: unmount what's gone, mount what's new, animate the
-     * difference.
+     * Apply a target arrangement: 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 panel present in both stacks stays mounted *even if its
@@ -293,94 +514,158 @@ export declare class PanelController {
      */
     private playExit;
     /**
-     * The stack navigation works from: the one we're on the way to while a change
-     * is still settling, and the one on screen otherwise.
+     * The arrangement navigation works from: the one we're on the way to while a
+     * change is still settling, and the one on screen otherwise.
      *
-     * Settling takes a moment more often than it looks: an async
-     * {@link Page.requestClose}, and every `route.back()`, which travels through
-     * the browser's history and lands on a `popstate`. Working from the committed
-     * stack in that window would make a second Escape ask for the panel the first
-     * one is already taking away — so two quick Escapes would peel one panel.
+     * Settling takes a moment more often than it looks: every `route.back()`
+     * travels through the browser's history and lands on a `popstate`, and an
+     * app-registered route guard may be async. Working from the committed
+     * arrangement in that window would make a second Escape aim at the panel the
+     * first one is already taking away — so two quick Escapes would peel one panel.
      */
     private intended;
+    /** The history `state` describing `arr` — exactly what `targetFor` reads back. */
+    private stateFor;
+    /** The paths of the pinned panels — the pin list history entries persist. */
+    private pinnedPaths;
     /**
      * Put a navigation to the router, or — while one is still settling — behind
      * the one that is. Only the newest waits: each was worked out against
      * {@link intended}, so the newest is the one that means what the user last
      * asked for, and the one it displaces resolves `false`.
      *
-     * A refusal empties the queue instead of running it. A veto is a "no, keep
-     * this open", and the Escape queued behind it was aimed a panel deeper — with
-     * the veto standing, running it would close the very panel that just said no.
+     * A refusal empties the queue instead of running it: a navigation can still
+     * fail to land — an app-registered route guard vetoes it, or another one
+     * supersedes it — and what was queued behind it was worked out against the
+     * arrangement it would have produced.
      */
     private issue;
     private start;
     /**
-     * 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.panels.close()`. `route.back()` prefers the history entry where that
-     * panel 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 panels first, and the returned
-     * promise reports its verdict.
-     */
-    private goBackTo;
-    /** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
-    closeDownTo(index: number): Promise<boolean>;
-    /** Guarded close of the top panel. */
-    closeTop(): Promise<boolean>;
-    /**
-     * Guarded close of whichever panel is open at `path`, top of the stack or not
-     * — what a page's own close affordances ({@link Page.close}, a box's ✕) come
-     * down to. `false` when that path isn't open.
+     * Make the stack's `index`th panel current: the URL and the visible run move
+     * to it, while the panels right of it stay open, parked past the right edge
+     * of the viewport. Nothing closes; it is a history entry, so the browser's
+     * back button returns the focus to where it was. What a click on a
+     * breadcrumb — any link to an open panel — comes down to.
+     */
+    private focusAt;
+    /**
+     * One step back along the stack — what Escape does (`main()` calls this;
+     * it is not {@link PanelStack} API). At the stack's end this closes the
+     * current panel; mid-stack — with panels parked to the right — or when the
+     * panel holds {@link Panel.unsaved} work, the panel stays open and the
+     * focus just moves to the panel on its left, parking the one it leaves.
+     * Resolves `false` at the stack's start, where there is no left to go.
+     */
+    back(): Promise<boolean>;
+    /**
+     * Close whichever panel is open at `path`, current or not — what
+     * {@link Panel.close}, {@link PanelStack.closePanel} and the crumb menu's
+     * Close come down to. `false` when that path isn't open, is the stack's
+     * only panel, or holds {@link Panel.unsaved} work — nothing may close an
+     * unsaved panel; the app clears the flag first, which is its explicit
+     * "this is now discardable".
      *
-     * The top panel pops back to the snapshot beneath it. Any other panel 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 panel 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 panel we're already on" check would see a no-op.
-     */
-    closePath(path: string): Promise<boolean>;
-    /** Guarded close of the panel whose `.s-panel` element this is. */
-    closePanelEl(el: HTMLElement): Promise<boolean>;
+     * Closing the current panel at the stack's very end pops back through the
+     * browser's history to the entry beneath it, when it is there (restoring its
+     * scroll and search state); the arrangement is part of the match, so an
+     * entry where the closing panel was merely parked won't do. Every other
+     * close is a *splice*: the columns around the closed one keep their place
+     * and state (the commit reconciles by path). That still gets its own
+     * history entry, so the browser's back button restores the closed column
+     * like any other arrangement — which is why it goes through `route.go` here
+     * rather than through `navigate()`, whose "link to an open panel" check
+     * would turn it into a focus move.
+     */
+    private closePath;
     /**
      * Navigate to `href`. `origin` is the path of the panel the link lives in, or
      * `null` when it has none — a nav item, or a programmatic call, which builds
      * the whole stack instead (see {@link deriveStack}). `replace` swaps the
      * originating panel rather than stacking on top of it, and `beneath` says what
      * the stack under the target is outright, for callers that know.
+     *
+     * Resolves the way every {@link PanelStack} method does: `true` once the
+     * navigation lands, `false` when it doesn't (already there counts as
+     * landed).
      */
-    navigate(href: string, origin: string | null, replace?: boolean, beneath?: readonly string[]): void;
-    /** Programmatic push/replace, with the top panel as the implied origin. */
-    pushPath(path: string, replace: boolean): void;
-    /** Programmatic open-as-a-whole-stack: `beneath` as given, or derived. */
-    openPath(path: string, beneath?: readonly string[]): void;
+    private navigate;
+    /** Programmatic push/replace, with the current panel as the implied origin. */
+    private pushPath;
     /**
      * Link handling through `route.interceptLinks()`, whose handler hook hands us
      * the anchor so we can decide what the click *means*: the originating
-     * `.s-panel` (which decides what the click truncates), `data-panel=replace`,
-     * and return-to-an-open-panel 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.
+     * `.s-panel` (which decides what the click truncates), the `data-panel`
+     * attribute, and return-to-an-open-panel 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.
+     *
+     * `data-panel` names which of the three {@link PanelStack} navigations the
+     * click is: `push` (the default), `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`.
      */
     private interceptLinks;
-    /** `"<page title> · <app title>"`, kept in sync with the top panel. */
+    get currentPanel(): Panel | undefined;
+    get panels(): readonly Panel[];
+    get currentPanelIndex(): number;
+    pushPanel(path: string): Promise<boolean>;
+    replacePanel(path: string): Promise<boolean>;
+    openPanelStack(path: string, beneath?: readonly string[]): Promise<boolean>;
+    closePanel(path?: string): Promise<boolean>;
+    /**
+     * 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
+     * wearing their pin. Every crumb but the current panel's is a plain link to
+     * that panel, and a link to an open panel is a focus move (see `navigate`) —
+     * so clicking along the stack closes nothing, in either direction, and the
+     * panels right of the current one wait just past the viewport's edge.
+     * Right-click (or long-press) offers pinning, and closing just that one
+     * panel — the close that splices it out of the middle when it isn't last.
+     */
+    drawCrumbs(): void;
+    private drawCrumb;
+    /**
+     * Flip a panel's pin (see {@link Panel.pinned}). The flag lives on the panel;
+     * the current history entry's snapshot is rewritten too, so a reload keeps
+     * the pin — a same-panel state tweak, which the router applies unguarded.
+     */
+    private togglePin;
+    /**
+     * `"<panel title> · <app title>"`, kept in sync with the current panel — and
+     * prefixed `"• "` while *any* open panel holds unsaved work, the way editors
+     * mark a dirty document. Any panel, not just the current one: the risk of
+     * losing the work is tab-wide, so the mark on the tab is too.
+     */
     private watchTitle;
     /**
-     * Draw the panel viewport into the current element. Called by `main()`.
+     * While any open panel holds unsaved work, closing the tab — or navigating
+     * the whole browser away — runs into the browser's own are-you-sure. When
+     * the user stays, the unsaved panel is brought back on screen if it wasn't,
+     * so what held the tab is in front of them rather than parked out of sight.
+     */
+    private guardTabClose;
+    /**
+     * Draw the column 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.
+     * A column is the panel's own content, plus the one bit of chrome the shell
+     * places for it: its {@link Panel.actions}, in a strip on wide shells and in
+     * the top bar on narrow ones (see {@link drawActions}).
      */
-    drawStack(): void;
+    drawColumns(): void;
     private drawPanel;
+    /**
+     * The one bit of column chrome the shell draws: the panel's actions, in a
+     * quiet strip above the scroll area — and only while the shell is wide, the
+     * top bar carrying them otherwise. Everything else in a column is the panel's
+     * own content: a screen that wants a heading or a card draws them itself.
+     * Going back isn't here either — that is the breadcrumbs' job, in the bar.
+     */
+    private drawActions;
     scheduleLayout(): void;
     /**
      * Measure the shell, and with it the width the window gives a panel of each
-     * layout. Measured on the *shell*, not on the panel region: the region's width
+     * layout. Measured on the *shell*, not on the column region: the region's width
      * is the layout engine's own output, so reading it back would nail the layout
      * to whatever it happened to be a frame ago. Fractional widths throughout — a
      * rounded column edge would drift a pixel away from the chrome above it.
@@ -396,7 +681,7 @@ export declare class PanelController {
      * would be a forced reflow each, in the middle of building their DOM.
      */
     private geometry;
-    /** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+    /** How wide a panel asking for this is, right now; 0 while the shell can't be measured. */
     private roomFor;
     /**
      * Size and position every panel, and publish the width of the whole ensemble
@@ -410,66 +695,4 @@ export declare class PanelController {
     /** Let a `loading` panel's enter animation wait — but not indefinitely. */
     private holdEnter;
 }
-/**
- * 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 {@link Page.requestClose} first.
- *
- * @example
- * ```ts
- * S.button({ content: "New task", click: async () => {
- *   const task = await createTask();
- *   S.panels.push(`/tasks/${task.id}`);
- * }});
- * ```
- */
-export declare const panels: {
-    /** Opens `path` in a new panel on top of the top one. */
-    push(path: string): void;
-    /**
-     * Opens `path` in place of the top panel, which closes (asking its
-     * {@link Page.requestClose} first). The panels beneath it stay as they are.
-     */
-    replace(path: string): void;
-    /**
-     * Opens `path` as a whole arrangement rather than on top of what's there: the
-     * same thing a nav item or a fresh tab does. Without `beneath`, the stack under
-     * it is worked out the way a cold link's is (see `S.main()`'s `ancestors`);
-     * with it, the paths you give are opened underneath, shallowest first.
-     *
-     * That's the one for a screen whose URL doesn't say where it belongs — the
-     * thread a notification opens — and for seeding a stack from code in general.
-     * Panels the new arrangement also holds stay as they are, and any it drops are
-     * asked their {@link Page.requestClose} first.
-     *
-     * @example
-     * ```ts
-     * S.panels.open(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
-     * ```
-     */
-    open(path: string, beneath?: readonly string[]): void;
-    /**
-     * Closes the top panel, or, given a `path`, whichever panel is open at it,
-     * asking {@link Page.requestClose} first. A panel that isn't on top is taken
-     * out on its own, leaving the columns to its right exactly as they are.
-     *
-     * Resolves `false` if the panel didn't close: `requestClose` said no, `path`
-     * isn't open, or another navigation got there first.
-     */
-    close(path?: string): Promise<boolean>;
-    /** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
-    readonly stack: readonly string[];
-};
-/**
- * Closes the panel `el` sits in, working out which one that is from the DOM.
- * That is what lets a close button work without being handed a `$page`, from
- * any column, whether or not it is on top. Used by `S.box`'s `close: true`.
- *
- * Outside a routed shell (or outside any panel, such as a box in a dialog) there is
- * nothing to close: it warns and resolves `false`.
- */
-export declare function closeContainingPanel(el: Element | null | undefined): Promise<boolean>;
 export {};