staffa 0.8.0 → 0.9.0

package/dist/components/panels.d.ts

@@ -55,6 +55,21 @@ export type Routes = Record<string, RouteHandler>;
 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 panel it is drawing. It's an Aberdeen proxy, so
@@ -101,8 +116,19 @@ export interface Page<P = Record<string, string | number | string[]>> {
      *
      * A panel's width depends only on the size of the window, never on what else
      * is open, so opening or closing a panel never resizes the ones already on
-     * screen. This is read **once**, right after your handler runs, so set it
-     * there; later changes are ignored.
+     * screen.
+     *
+     * 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.
+     *
+     * 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.
      */
     layout?: "small" | "medium" | "large";
     /**
@@ -146,6 +172,8 @@ export interface Page<P = Record<string, string | number | string[]>> {
 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. */
     stacking?: boolean;
     /** The shell's own title, used as the suffix of `document.title`. */
@@ -153,6 +181,8 @@ export interface PanelStackOptions {
 }
 export declare class PanelController {
     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;
@@ -169,22 +199,46 @@ export declare class PanelController {
         topId: 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 stack 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: PanelStackOptions);
     /** 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 panel, matched or not.
+     * The stack for origin-less navigation: a cold deep link, a nav item, a
+     * `route.go()` — anything arriving without a panel to build on and without a
+     * snapshot to restore.
+     *
+     * The app's {@link PanelStackOptions.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 is always the top panel, matched or not.
      */
     deriveStack(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 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. */
@@ -220,14 +274,47 @@ export declare class PanelController {
     private commit;
     private createEntry;
     /**
-     * Start a panel'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 panel 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).
+     * Take a panel out of the shell. The *scope* goes now: its cleaners run this
+     * tick, so whatever the panel registered with `A.clean` — subscriptions,
+     * timers, an open portal — is torn down when the panel closes, not when its
+     * animation is over. Only the element lingers, to play that animation, which
+     * is what the `destroy=` hook in `drawPanel` is for: Aberdeen hands the
+     * element to {@link playExit} instead of removing it.
      */
     private beginClose;
+    /**
+     * A closed panel's send-off, run by Aberdeen once the panel'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 panel 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 stack 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.
+     */
+    private intended;
+    /**
+     * 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.
+     */
+    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
@@ -243,8 +330,9 @@ export declare class PanelController {
     /** Guarded close of the top panel. */
     closeTop(): Promise<boolean>;
     /**
-     * Guarded close of the panel at `index`, top of the stack or not — what a
-     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     * 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.
      *
      * 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
@@ -254,20 +342,21 @@ export declare class PanelController {
      * 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.
      */
-    closePanelAt(index: number): Promise<boolean>;
-    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-    closeByPath(path: string): Promise<boolean>;
+    closePath(path: string): Promise<boolean>;
     /** Guarded close of the panel whose `.s-panel` element this is. */
     closePanelEl(el: HTMLElement): Promise<boolean>;
     /**
-     * Navigate to `href`. `originIndex` is the depth of the panel 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 panel rather than
-     * stacking on top of it.
+     * 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.
      */
-    navigate(href: string, originIndex: number, replace?: boolean): void;
+    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;
     /**
      * Link handling through `route.interceptLinks()`, whose handler hook hands us
      * the anchor so we can decide what the click *means*: the originating
@@ -289,6 +378,26 @@ export declare class PanelController {
     drawStack(): void;
     private drawPanel;
     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
+     * 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 panels 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 panel of this layout 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
      * (sidebar + separator + columns) for the shell to centre itself on.
@@ -325,6 +434,23 @@ export declare const panels: {
      * {@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