staffa 0.8.1 → 0.9.0

package/dist/components/panels.js

@@ -33,11 +33,12 @@ function splitPath(path) {
     return p === "/" ? [] : p.slice(1).split("/");
 }
 /**
- * Turn a route key into segment tokens, throwing on malformed templates. A
+ * Turn a path template into segment tokens, throwing on malformed ones. A
  * segment is a param only when it is *entirely* a bracket group, so a literal
- * segment that merely contains brackets (`/v[1]beta`) stays literal.
+ * segment that merely contains brackets (`/v[1]beta`) stays literal. Used for
+ * both tables keyed by a path template: `routes` and `ancestors`.
  */
-function compileRoute(key, draw) {
+function compileKey(key) {
     const parts = splitPath(key);
     const segs = parts.map((part, i) => {
         if (!part.startsWith("[") || !part.endsWith("]"))
@@ -57,7 +58,7 @@ function compileRoute(key, draw) {
         }
         return { kind: "param", name, matcher };
     });
-    return { key, segs, draw };
+    return { key, segs };
 }
 /** Percent-decode a path segment, leaving it alone when it isn't valid encoding. */
 function decodeSeg(value) {
@@ -218,6 +219,8 @@ A.insertGlobalCss({
 let active = null;
 export class PanelController {
     compiled;
+    /** The `ancestors` table, compiled like the routes it is keyed by. */
+    ancestors;
     opts;
     /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
     live = [];
@@ -237,13 +240,22 @@ export class PanelController {
     lastBodyW = -1;
     layoutQueued = false;
     timers = new Set();
+    /** The stack the navigation in flight is heading for; see {@link intended}. */
+    intent = null;
+    /** The navigation the router hasn't settled yet, if any. */
+    settling = null;
+    /** The one navigation waiting behind it; see {@link issue}. */
+    queued = null;
     constructor(opts) {
         if (active) {
             throw new Error("Staffa: only one routed S.main() (one with `routes`) can be active at a time");
         }
         active = this;
         this.opts = opts;
-        this.compiled = Object.entries(opts.routes).map(([key, draw]) => compileRoute(key, draw));
+        this.compiled = Object.entries(opts.routes).map(([key, draw]) => ({ ...compileKey(key), draw }));
+        this.ancestors = Object.entries(opts.ancestors ?? {})
+            .filter((entry) => entry[1] != null)
+            .map(([key, fn]) => ({ ...compileKey(key), fn }));
         // The router consults this guard before any navigation is applied — ours,
         // a link's, browser back/forward, even a direct route.go() by app code —
         // so every panel the change would remove gets its requestClose asked,
@@ -274,6 +286,10 @@ export class PanelController {
             for (const t of this.timers)
                 clearTimeout(t);
             this.timers.clear();
+            // Nothing is going to navigate a shell that isn't there: whatever was
+            // waiting its turn is answered rather than left hanging.
+            this.queued?.settle(false);
+            this.queued = null;
             route.setGuard(appGuard);
             if (active === this)
                 active = null;
@@ -295,23 +311,54 @@ export class PanelController {
         return this.compiled.some((r) => matchRoute(r, segments) != null);
     }
     /**
-     * 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) {
-        const segments = splitPath(path);
+        const top = normalizePath(path);
+        const asked = this.askAncestors(top);
+        const beneath = asked ? asked.map(normalizePath) : this.prefixesOf(top);
         const stack = [];
-        for (let i = 1; i < segments.length; i++) {
-            const prefix = "/" + segments.slice(0, i).join("/");
-            if (this.matches(prefix))
-                stack.push(prefix);
+        for (const ancestor of beneath) {
+            if (ancestor !== top && !stack.includes(ancestor) && this.matches(ancestor))
+                stack.push(ancestor);
         }
-        stack.push(normalizePath(path));
+        stack.push(top);
         return stack;
     }
+    /**
+     * 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.
+     */
+    askAncestors(path) {
+        const segments = splitPath(path);
+        for (const entry of this.ancestors) {
+            const params = matchRoute(entry, segments);
+            if (params)
+                return entry.fn(params, path) ?? undefined;
+        }
+        return undefined;
+    }
+    /** Every prefix of `path` that has a route, shallowest first. */
+    prefixesOf(path) {
+        const segments = splitPath(path);
+        const found = [];
+        for (let i = 1; i < segments.length; i++)
+            found.push("/" + segments.slice(0, i).join("/"));
+        return found;
+    }
     /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
     targetFor(path, snapshot) {
         if (Array.isArray(snapshot))
@@ -413,7 +460,7 @@ export class PanelController {
         entry.$page = A.proxy({
             params,
             path,
-            close: () => this.closePanelAt(this.live.indexOf(entry)),
+            close: () => this.closePath(entry.path),
         });
         return entry;
     }
@@ -468,6 +515,58 @@ export class PanelController {
         this.timers.add(timer);
     }
     // ── Navigation ─────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    intended() {
+        return this.intent ?? this.paths();
+    }
+    /**
+     * 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.
+     */
+    issue(target, run) {
+        this.intent = target;
+        if (this.settling) {
+            this.queued?.settle(false);
+            return new Promise((settle) => { this.queued = { run, settle }; });
+        }
+        return this.start(run);
+    }
+    start(run) {
+        const done = (ok) => {
+            this.settling = null;
+            const next = this.queued;
+            this.queued = null;
+            // The router applies a change (and runs Aberdeen's queue, so our own
+            // commit has happened) before it settles us, which is what lets the next
+            // one go straight out: it asks the guards of the panels it removes from
+            // the stack as it stands now, not the one it was queued against.
+            if (ok && next)
+                this.start(next.run).then(next.settle, () => next.settle(false));
+            else {
+                this.intent = null;
+                next?.settle(false);
+            }
+            return ok;
+        };
+        const settling = Promise.resolve(run()).then(done, (e) => { console.error(e); return done(false); });
+        this.settling = settling;
+        return settling;
+    }
     /**
      * 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
@@ -478,21 +577,23 @@ export class PanelController {
      * promise reports its verdict.
      */
     goBackTo(target) {
-        return route.back({ path: target[target.length - 1] }, { state: { panels: target.slice(0, -1) } });
+        return this.issue(target, () => route.back({ path: target[target.length - 1] }, { state: { panels: target.slice(0, -1) } }));
     }
     /** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
     closeDownTo(index) {
-        if (index < 0 || index >= this.live.length - 1)
+        const paths = this.intended();
+        if (index < 0 || index >= paths.length - 1)
             return Promise.resolve(false);
-        return this.goBackTo(this.paths().slice(0, index + 1));
+        return this.goBackTo(paths.slice(0, index + 1));
     }
     /** Guarded close of the top panel. */
     closeTop() {
-        return this.closeDownTo(this.live.length - 2);
+        return this.closeDownTo(this.intended().length - 2);
     }
     /**
-     * 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
@@ -502,13 +603,15 @@ export 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) {
-        if (index < 0 || index >= this.live.length)
+    closePath(path) {
+        const paths = this.intended();
+        const index = paths.indexOf(normalizePath(path));
+        if (index < 0)
             return Promise.resolve(false);
-        if (index === this.live.length - 1)
-            return this.closeTop();
-        const target = this.paths().filter((_, i) => i !== index);
-        return Promise.resolve(route.go({
+        if (index === paths.length - 1)
+            return this.closeDownTo(index - 1);
+        const target = paths.filter((_, i) => i !== index);
+        return this.issue(target, () => route.go({
             path: target[target.length - 1],
             // The top panel keeps its search params and hash: it isn't going
             // anywhere, and `go()` would otherwise default them away.
@@ -517,22 +620,19 @@ export class PanelController {
             state: { panels: target.slice(0, -1) },
         }));
     }
-    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
-    closeByPath(path) {
-        const wanted = normalizePath(path);
-        return this.closePanelAt(this.live.findIndex((entry) => entry.path === wanted));
-    }
     /** Guarded close of the panel whose `.s-panel` element this is. */
     closePanelEl(el) {
-        return this.closePanelAt(this.live.findIndex((entry) => entry.el === el));
+        const entry = this.live.find((e) => e.el === el);
+        return entry ? this.closePath(entry.path) : Promise.resolve(false);
     }
     /**
-     * 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, originIndex, replace = false) {
+    navigate(href, origin, replace = false, beneath) {
         let url;
         try {
             url = new URL(href, location.href);
@@ -543,21 +643,22 @@ export class PanelController {
         const path = normalizePath(url.pathname);
         const search = Object.fromEntries(new URLSearchParams(url.search));
         const hash = url.hash;
+        const paths = this.intended();
         // A link to a panel that is already open is a return, not a navigation —
         // so a stack can never hold the same path twice.
-        const open = this.live.findIndex((e) => e.path === path);
-        if (open >= 0 && open < this.live.length - 1) {
+        const open = paths.indexOf(path);
+        if (open >= 0 && open < paths.length - 1 && !beneath) {
             void this.closeDownTo(open);
             return;
         }
-        if (open >= 0) {
+        if (open >= 0 && !beneath) {
             // The target is the panel we're already on. Going nowhere — but the link
             // may still carry a different search or hash, which belong to the top
             // panel: record that as a history entry, leaving the stack alone (the
             // panel reconciles by path, so it isn't even redrawn).
             if (url.search === location.search && (url.hash || "") === (location.hash || ""))
                 return;
-            route.go({ path, search, hash, state: { panels: this.paths().slice(0, -1) } });
+            void this.issue(paths, () => route.go({ path, search, hash, state: { panels: paths.slice(0, -1) } }));
             return;
         }
         // Without an originating panel there is no stack to build on, so derive
@@ -565,14 +666,22 @@ export class PanelController {
         // The route guard (checkChange) asks every panel this removes — a set
         // defined by the target stack, wherever those panels happen to sit —
         // before the change is applied; a veto leaves everything untouched.
-        const beneath = originIndex < 0
-            ? this.deriveStack(path).slice(0, -1)
-            : this.paths().slice(0, replace ? originIndex : originIndex + 1);
-        route.go({ path, search, hash, state: { panels: beneath } });
+        const originIndex = origin == null ? -1 : paths.indexOf(origin);
+        const under = beneath
+            ? beneath.map(normalizePath).filter((p) => p !== path)
+            : originIndex < 0
+                ? this.deriveStack(path).slice(0, -1)
+                : paths.slice(0, replace ? originIndex : originIndex + 1);
+        void this.issue([...under, path], () => route.go({ path, search, hash, state: { panels: under } }));
     }
     /** Programmatic push/replace, with the top panel as the implied origin. */
     pushPath(path, replace) {
-        this.navigate(path, this.live.length - 1, replace);
+        const paths = this.intended();
+        this.navigate(path, paths[paths.length - 1] ?? null, replace);
+    }
+    /** Programmatic open-as-a-whole-stack: `beneath` as given, or derived. */
+    openPath(path, beneath) {
+        this.navigate(path, null, false, beneath);
     }
     // ── Link interception ──────────────────────────────────────────────────
     /**
@@ -586,8 +695,8 @@ export class PanelController {
     interceptLinks() {
         route.interceptLinks((url, anchor) => {
             const panel = anchor.closest(".s-panel");
-            const originIndex = panel ? this.live.findIndex((entry) => entry.el === panel) : -1;
-            this.navigate(url.href, originIndex, anchor.getAttribute("data-panel") === "replace");
+            const origin = panel ? this.live.find((entry) => entry.el === panel) : undefined;
+            this.navigate(url.href, origin?.path ?? null, anchor.getAttribute("data-panel") === "replace");
             return true;
         });
     }
@@ -991,6 +1100,25 @@ export const panels = {
     replace(path) {
         requireActive().pushPath(path, true);
     },
+    /**
+     * 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, beneath) {
+        requireActive().openPath(path, beneath);
+    },
     /**
      * 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
@@ -1001,7 +1129,7 @@ export const panels = {
      */
     close(path) {
         const ctl = requireActive();
-        return path == null ? ctl.closeTop() : ctl.closeByPath(path);
+        return path == null ? ctl.closeTop() : ctl.closePath(path);
     },
     /** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
     get stack() {

package/dist/index.d.ts

@@ -37,8 +37,8 @@ export { buttonChooser, type ButtonChooserOptions } from "./components/buttonCho
 export { buttonGroup, type ButtonGroupOptions } from "./components/buttonGroup.js";
 export { checkbox, type CheckboxOptions } from "./components/checkbox.js";
 export { form, type FormOptions } from "./components/form.js";
-export { main, type MainOptions } from "./components/main.js";
-export { panels, type Page, type Routes, type RouteHandler, type RouteTable, type PathParams, type SegParams } from "./components/panels.js";
+export { main, closeNav, type MainOptions } from "./components/main.js";
+export { panels, type Page, type Routes, type RouteHandler, type RouteTable, type AncestorsHandler, type AncestorTable, type PathParams, type SegParams } from "./components/panels.js";
 export { menuButton, showFloatingMenu, addContextMenu, isFloatingMenuOpen, closeFloatingMenu, type MenuOptions, type MenuEntry, type MenuItem, type MenuSeparator, type FloatingMenuOptions, type ContextMenuOptions } from "./components/menu.js";
 export { dialog, alert, confirm, prompt, isDialogOpen, type DialogOptions } from "./components/dialog.js";
 export { select, type SelectOptions, type SelectOptionInput } from "./components/select.js";

package/dist/index.js

@@ -40,7 +40,7 @@ export { buttonChooser } from "./components/buttonChooser.js";
 export { buttonGroup } from "./components/buttonGroup.js";
 export { checkbox } from "./components/checkbox.js";
 export { form } from "./components/form.js";
-export { main } from "./components/main.js";
+export { main, closeNav } from "./components/main.js";
 export { panels } from "./components/panels.js";
 export { menuButton, showFloatingMenu, addContextMenu, isFloatingMenuOpen, closeFloatingMenu } from "./components/menu.js";
 export { dialog, alert, confirm, prompt, isDialogOpen } from "./components/dialog.js";