staffa 0.9.0 → 0.10.0

package/dist/components/pages.d.ts

@@ -0,0 +1,638 @@
+import { type Slot } from "../core.js";
+/**
+ * Routed, multi-column page navigation for {@link main}.
+ *
+ * Each route draws one screen of the app, called a page. The open pages form
+ * a *trail*, and one of them is the **current** page: the one the URL names,
+ * and the rightmost column on screen. As many pages as fit are shown, ending
+ * at the current one — on a phone that is one at a time, on a wider screen the
+ * pages that would have covered each other sit side by side instead. The
+ * app's own code is the same either way.
+ *
+ * Going to a page that is already open — a breadcrumb, or any link to it —
+ * just moves the current-page cursor along the trail: pages right of it stay
+ * open, parked past the right edge of the viewport, and nothing closes.
+ * Opening a *new* page is what prunes: everything after the page it came from
+ * closes, except pages the user pinned — which ride along beneath the new page
+ * — and pages holding unsaved work, which no navigation ever tears down.
+ * Escape steps one page left, closing the page it leaves only when that page
+ * is the trail's discardable end.
+ *
+ * Navigation runs through `aberdeen/route`: the URL holds the current page,
+ * and the rest of the arrangement — the pages 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> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * What a `[name=matcher]` matcher name yields. An unrecognised name resolves to
+ * `never`, which shows up as an unusable param at the handler rather than
+ * quietly typing as `string` (the route key itself throws at mount time).
+ */
+export type MatcherType<M extends string> = M extends "integer" ? number : never;
+/**
+ * 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.
+ */
+export type SegParams<S extends string> = 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;
+} : {};
+/**
+ * The params object described by a path template, e.g.
+ * `PathParams<"/projects/[id]/tasks/[taskId=integer]">` is
+ * `{ id: string; taskId: number }`.
+ */
+export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
+/** A page draw function: it receives the page'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 page 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;
+};
+/**
+ * What belongs beneath a path that arrives cold, worked out from the params of
+ * the path itself. Return the paths shallowest first, or nothing to leave this
+ * one to the parent-path derivation.
+ */
+export type AncestorsHandler<P = any> = (params: P, path: string) => readonly string[] | undefined | void;
+/**
+ * A table of {@link AncestorsHandler}s keyed by path template, the same way
+ * `routes` is — so each one's `params` are matched and typed from its own key
+ * rather than parsed out of the path a second time. The keys are checked
+ * against the route table, so a stale one is a type error.
+ */
+export type AncestorTable<R> = {
+    [K in keyof R & string]?: (params: Prettify<PathParams<K>>, path: string) => readonly string[] | undefined | void;
+};
+/**
+ * What a route handler gets: the params from its route, plus everything the
+ * shell needs to know about the page 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 current page only. Any other
+ * page keeps just its path, so anything a page needs in order to redraw
+ * itself has to live in that path. (A page 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[]>> {
+    /**
+     * The params matched from this page's path, typed per its route key:
+     * `[x]` is a `string`, `[x=integer]` a `number`, `[...x]` a `string`.
+     * Read-only.
+     */
+    readonly params: P;
+    /** This page's path, e.g. `"/projects/7"`. Read-only. */
+    readonly path: string;
+    /**
+     * Names this screen, in the top bar's breadcrumb trail and in
+     * `document.title` while the page is current. A page that doesn't set one
+     * borrows the first line of text in its own body, so the trail 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;
+    /**
+     * This screen's own actions: a couple of buttons, a menu. The shell draws
+     * them — never the page — and *where* depends on facts only the shell has:
+     * a quiet strip at the top of this page'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 page 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 page's column actually is, in pixels — what
+     * {@link Page.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.
+     *
+     * 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 page 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.
+     *
+     * The one to hang per-page floating UI on (a FAB, a "3 selected" bar), for
+     * which "am I the current page?" is the wrong question — two columns can be
+     * visible at once, and both of them are really there.
+     */
+    readonly visible: boolean;
+    /**
+     * The widest this page can usefully be. Every page must work at 360–540px,
+     * because that is what it gets when two columns fit; this says how much
+     * *more* it can take.
+     *
+     * - `"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.
+     *
+     * 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 page never resizes another.
+     *
+     * Set it at the top of your handler and the page is already that wide when
+     * you draw (see {@link Page.width}); set it later — when your data tells you
+     * — and the page reflows without being redrawn, keeping its state, while
+     * the columns beside it move over.
+     */
+    maxWidth?: "half" | "full" | "screen";
+    /**
+     * Set this while you're fetching what the page needs, and back to `false`
+     * when you're done. A new page 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 and the URL never wait for it.
+     */
+    loading?: boolean;
+    /**
+     * Keeps this page from being closed by navigation happening *elsewhere*.
+     * Opening a new page normally closes everything after the page it came
+     * from; a pinned page survives that, staying in the trail — parked past the
+     * right edge of the viewport — slotted in beneath the new page, 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 trail's end,
+     * {@link Page.close}, the crumb menu's Close and `data-page=replace` all
+     * still close the page.
+     */
+    pinned?: boolean;
+    /**
+     * Set this while the page holds work that must not be lost — a dirty form,
+     * an upload in flight. An unsaved page 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 Page.close} and the crumb menu's Close refuse,
+     * Escape on it steps left along the trail rather than closing, and closing
+     * the browser tab runs into the browser's own are-you-sure (after which the
+     * shell brings the unsaved page back on screen).
+     *
+     * Only the app clears it; the user has no toggle. A Save or Discard button
+     * clears it and then closes:
+     *
+     * ```ts
+     * A(() => { $page.unsaved = $form.dirty || undefined; });
+     * S.button({ content: "Discard", attrs: ".neutral", click: () => {
+     *   $page.unsaved = false;   // explicitly — see below
+     *   void $page.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** page, wherever it sits in the trail. Closing the current
+     * page hands the focus to the page on its left; closing any other page
+     * 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 page back.
+     *
+     * Resolves `false` if the page didn't close: it holds
+     * {@link Page.unsaved} work, it was the only page on the trail (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() });
+     * ```
+     */
+    close(): Promise<boolean>;
+}
+/**
+ * A {@link Page} as the controller holds it: the same object the handler gets,
+ * minus the `readonly`s. `width` and `visible` are read-only *to the app* —
+ * they are facts about the page, not requests — but the shell keeps them up to
+ * date by writing them, which is what makes reading them reactive.
+ */
+type PageState = {
+    -readonly [K in keyof Page<any>]: Page<any>[K];
+};
+/** Options the trail needs from its shell. */
+export interface PageStackOptions {
+    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 current page, 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 page'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 PageController {
+    private compiled;
+    /** The `ancestors` table, compiled like the routes it is keyed by. */
+    private ancestors;
+    private opts;
+    /** The live trail, oldest first. Closing pages are no longer part of it. */
+    private live;
+    /** Index into `live` of the current page — the one the URL names. */
+    private focus;
+    private byId;
+    private nextId;
+    /** Drives rendering: page id → its `order` (used only as the sort key). */
+    $ids: Record<string, number>;
+    /**
+     * The live trail's paths and its current page, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling, the breadcrumbs,
+     * and `S.pages.stack`.
+     */
+    $state: {
+        paths: string[];
+        focus: number;
+        currentId: number;
+    };
+    private containerEl?;
+    /** The shell's measurements, shared by everything drawn since they were taken. */
+    private geom?;
+    /** The body width at the last layout; a change means a window resize → snap. */
+    private lastBodyW;
+    private layoutQueued;
+    private timers;
+    /** 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 one navigation waiting behind it; see {@link issue}. */
+    private queued;
+    constructor(opts: PageStackOptions);
+    /** Resolve a path to its route handler + params, falling back to `notFound`. */
+    private resolve;
+    private matches;
+    /**
+     * The stack for origin-less navigation: a cold deep link, a nav item, a
+     * `route.go()` — anything arriving without a page to build on and without a
+     * snapshot to restore.
+     *
+     * The app's {@link PageStackOptions.ancestors} gets first say, since only it
+     * can know what belongs under a path that doesn't spell its own context out
+     * (a `/thread/[id]` reached from a notification). Failing that — or when it
+     * has no opinion — every prefix of the path is probed against the route table
+     * 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 always ends the derived stack, matched or not.
+     */
+    deriveTrail(path: string): string[];
+    /**
+     * 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
+     * path apart itself — and `undefined` from it means "no opinion", leaving the
+     * path to the prefix derivation just as an unlisted one is.
+     */
+    private askAncestors;
+    /** Every prefix of `path` that has a route, shallowest first. */
+    private prefixesOf;
+    /**
+     * The pinned pages among `trail`, in order, minus `omit` — the ones a
+     * navigation must carry along rather than close. Pin flags live on the
+     * pages themselves, so a path without a live page can't be pinned.
+     */
+    private pinnedIn;
+    /** Whether the page open at `path` (if any) holds unsaved work. Peeked. */
+    private unsavedAt;
+    /**
+     * The arrangement a route implies: its snapshot around its path, or —
+     * without a snapshot — derived, with the new page current at the end and
+     * any pinned pages carried along beneath it.
+     */
+    private targetFor;
+    /** The arrangement the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
+    private paths;
+    /**
+     * Adopt an arrangement proposed by the URL — after repairing it: pages
+     * 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 page existed. Whatever the target drops, they stay, parked
+     * after the current page 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 arrangement: unmount what's gone, mount what's new, animate
+     * the difference.
+     *
+     * Reconciliation is BY PATH (a trail can't hold the same path twice, so that's
+     * well-defined): a page present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a page 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;
+    /**
+     * Take a page out of the shell. The *scope* goes now: its cleaners run this
+     * tick, so whatever the page registered with `A.clean` — subscriptions,
+     * timers, an open portal — is torn down when the page closes, not when its
+     * animation is over. Only the element lingers, to play that animation, which
+     * is what the `destroy=` hook in `drawPage` is for: Aberdeen hands the
+     * element to {@link playExit} instead of removing it.
+     */
+    private beginClose;
+    /**
+     * A closed page's send-off, run by Aberdeen once the page's scope is gone (so
+     * the content it shows is frozen, which is exactly what a departing column
+     * should be): it fades where it stands, inert, and leaves the DOM when the fade
+     * itself ends. Removing it on a fixed timer instead would race the transition —
+     * pull the element a frame early and the page 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 playExit;
+    /**
+     * 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: 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 page the
+     * first one is already taking away — so two quick Escapes would peel one page.
+     */
+    private intended;
+    /** The history `state` describing `arr` — exactly what `targetFor` reads back. */
+    private stateFor;
+    /**
+     * Stash the URL's search params and hash on the page they belong to — the
+     * current one — for when a crumb brings it back (see PageEntry.search).
+     * Called as a navigation is issued, just before the URL moves off it.
+     */
+    private stashQuery;
+    /**
+     * 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 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;
+    /**
+     * Make the trail's `index`th page current: the URL and the visible run move
+     * to it, while the pages 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 page — comes down to.
+     */
+    private focusAt;
+    /**
+     * One step back along the trail — what Escape does. At the trail's
+     * end this closes the current page; mid-trail — with pages parked to the
+     * right — or when the page holds {@link Page.unsaved} work, the page stays
+     * open and the focus just moves to the page on its left, parking the one
+     * it leaves. Resolves `false` at the trail's start, where there is no left
+     * to go.
+     */
+    back(): Promise<boolean>;
+    /** Close the current page (refused, like any close, while it is unsaved). */
+    closeCurrent(): Promise<boolean>;
+    /**
+     * Close whichever page is open at `path`, current or not — what
+     * {@link Page.close} and the crumb menu's Close come down to. `false` when
+     * that path isn't open, is the trail's only page, or holds
+     * {@link Page.unsaved} work — nothing may close an unsaved page; the app
+     * clears the flag first, which is its explicit "this is now discardable".
+     *
+     * Closing the current page at the trail'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 page 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 page" check
+     * would turn it into a focus move.
+     */
+    closePath(path: string): Promise<boolean>;
+    /**
+     * Navigate to `href`. `origin` is the path of the page 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 deriveTrail}). `replace` swaps the
+     * originating page rather than stacking on top of it, and `beneath` says what
+     * the stack under the target is outright, for callers that know.
+     */
+    navigate(href: string, origin: string | null, replace?: boolean, beneath?: readonly string[]): void;
+    /** Programmatic push/replace, with the current page as the implied origin. */
+    pushPath(path: string, replace: boolean): void;
+    /** Programmatic open-as-a-whole-trail: `beneath` as given, or derived. */
+    openPath(path: string, beneath?: readonly string[]): void;
+    /**
+     * Link handling through `route.interceptLinks()`, whose handler hook hands us
+     * the anchor so we can decide what the click *means*: the originating
+     * `.s-page` (which decides what the click truncates), `data-page=replace`,
+     * and return-to-an-open-page 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;
+    /**
+     * The current page's page, or `undefined` while there is none. Reactive on
+     * *which* page is current, so the bar follows every move along the trail;
+     * the fields it then reads (`title`, `actions`) are reactive in their own
+     * right, so a page that names itself when its data lands updates the bar in
+     * place.
+     */
+    currentPage(): PageState | undefined;
+    /**
+     * The breadcrumb trail, drawn by `main()` into the top bar: every open
+     * page, oldest first, the ones on screen right now in bold, pinned ones
+     * wearing their pin. Every crumb but the current page's is a plain link to
+     * that page, and a link to an open page is a focus move (see `navigate`) —
+     * so clicking along the trail closes nothing, in either direction, and the
+     * pages right of the current one wait just past the viewport's edge.
+     * Right-click (or long-press) offers pinning, and closing just that one
+     * page — the close that splices it out of the middle when it isn't last.
+     */
+    drawCrumbs(): void;
+    private drawCrumb;
+    /**
+     * Flip a page's pin (see {@link Page.pinned}). The flag lives on the page;
+     * the current history entry's snapshot is rewritten too, so a reload keeps
+     * the pin — a same-page state tweak, which the router applies unguarded.
+     */
+    private togglePin;
+    /**
+     * `"<page title> · <app title>"`, kept in sync with the current page — and
+     * prefixed `"• "` while *any* open page holds unsaved work, the way editors
+     * mark a dirty document. Any page, not just the current one: the risk of
+     * losing the work is tab-wide, so the mark on the tab is too.
+     */
+    private watchTitle;
+    /**
+     * While any open page 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 page 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()`.
+     *
+     * A column is the page's own content, plus the one bit of chrome the shell
+     * places for it: its {@link Page.actions}, in a strip on wide shells and in
+     * the top bar on narrow ones (see {@link drawActions}).
+     */
+    drawColumns(): void;
+    private drawPage;
+    /**
+     * The one bit of column chrome the shell draws: the page'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 page'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 page of each
+     * 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.
+     *
+     * `undefined` while the shell has no width to speak of (it isn't in a document
+     * yet, or it's `display:none`); the next pass tries again.
+     */
+    private measure;
+    /**
+     * The measurements this pass runs on. Taken once per layout pass and per
+     * commit, and shared with the pages drawn in between — they all size
+     * themselves against the same shell, and a `getBoundingClientRect()` each
+     * would be a forced reflow each, in the middle of building their DOM.
+     */
+    private geometry;
+    /** How wide a page asking for this is, right now; 0 while the shell can't be measured. */
+    private roomFor;
+    /**
+     * Size and position every page, 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 pages 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` page'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 — a focus move along the trail, closing nothing — rather
+ * than opening it twice, and a page holding {@link Page.unsaved} work is
+ * never closed, only parked.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.pages.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export declare const pages: {
+    /**
+     * Opens `path` in a new page on top of the current one, closing the
+     * unpinned pages that were after it (pinned ones stay, sliding in beneath
+     * the new page).
+     */
+    push(path: string): void;
+    /**
+     * Opens `path` in place of the current page, which closes. The pages
+     * 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.
+     * Pages the new arrangement also holds stay as they are; ones it drops
+     * close, except pages with {@link Page.unsaved} work, which stay, parked.
+     *
+     * @example
+     * ```ts
+     * S.pages.open(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+     * ```
+     */
+    open(path: string, beneath?: readonly string[]): void;
+    /**
+     * Closes the current page, or, given a `path`, whichever page is open at
+     * it. A page that isn't current is taken out on its own, leaving the
+     * columns around it exactly as they are.
+     *
+     * Resolves `false` if the page didn't close: it holds
+     * {@link Page.unsaved} work, `path` isn't open, or another navigation got
+     * there first.
+     */
+    close(path?: string): Promise<boolean>;
+    /** The paths of the open pages, oldest first. Reactive: safe to read in a scope. */
+    readonly trail: readonly string[];
+    /**
+     * The path of the current page: the one the URL names, and the rightmost
+     * column on screen. The pages after it in {@link pages.trail} are the
+     * ones parked past the viewport's right edge. Reactive.
+     */
+    readonly current: string | undefined;
+};
+export {};