staffa 0.12.0 → 0.13.0

package/dist/components/panels.js

@@ -112,7 +112,7 @@ function matchRoute(r, segments) {
 /**
  * The one duration every bit of shell motion shares: the enter/exit fades, the
  * `left` moves of columns shifting sideways, the ensemble-width transition the
- * chrome follows (see `--s-shell-w` in main.ts), and the narrow-screen nav
+ * body row follows (see `--s-shell-w` in main.ts), and the narrow-screen nav
  * panel's slide. Published as the `--s-panel-ms` custom property below, so CSS
  * and JS can't drift apart.
  *
@@ -123,12 +123,6 @@ function matchRoute(r, segments) {
 const PAGE_MS = 250;
 /** How long a freshly pushed `loading` panel holds its enter animation. */
 const LOADING_HOLD_MS = 300;
-/**
- * The standard page width: sidebar plus content area, capped by the window.
- * `"full"` fills the content-area part of this exactly; only a `"screen"`
- * page makes the shell grow past it.
- */
-const SHELL_PX = 1280;
 /** Don't pair smalls when half the content area would be narrower than this. */
 const PAIR_MIN_PX = 360;
 /**
@@ -151,7 +145,12 @@ A.insertGlobalCss({
     // The region paints the panel's sheen over its own box, and every panel shows
     // a slice of that same gradient (see `.s-panel` below), so the columns and
     // the ground beside them are one continuous surface.
-    ".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden isolation:isolate " +
+    // `overflow:clip`, not `hidden`: a hidden box is still a scroll container,
+    // and anything that ever scrolls it — find-in-page reaching for text in a
+    // parked column, an in-page anchor, an extension — shifts every column
+    // sideways, permanently, because nothing here would ever scroll it back.
+    // `clip` clips without being scrollable at all, closing the whole class.
+    ".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:clip isolation:isolate " +
         SURFACE_SHEEN,
     ".s-panel": {
         // A panel rests at a plain `left` offset and carries no transform: a
@@ -245,13 +244,18 @@ A.insertGlobalCss({
         // the weight change alone is ambiguous in a short crumb, the colour alone
         // too subtle. No padding of its own — the first crumb has to start on the
         // same pixel as the app's name above it, and the gap below spaces the row.
-        // `flex-shrink:0` because the crumbs are the strip's flex items and carry
-        // `overflow:hidden`, which resolves their automatic minimum size to zero:
-        // left to shrink they would ellipsise themselves down to stubs rather than
-        // overflow, and the stack would never scroll. One long title still caps at
-        // 14rem — that is this crumb's own business, not the row running out.
-        "&": "flex-shrink:0 font-size:0.85em line-height:1.5 fg:$s-muted text-decoration:none " +
-            "white-space:nowrap max-width:14rem overflow:hidden text-overflow:ellipsis " +
+        // The flex is how a tight row is shared out. Every crumb grows from the
+        // same 4rem basis in equal shares, freezing at its own text
+        // (`max-width:max-content`) — so with room to spare every title shows in
+        // full, and under pressure it is the *longest* crumbs that give way
+        // first, equalising downward while short ones keep every character. No
+        // crumb drops below min(its text, 4rem) though: `flex-shrink:0`, so past
+        // that point the row overflows and the strip scrolls — which is what
+        // keeps a deep stack on a phone readable. (Crumbs allowed to shrink
+        // would ellipsise to a row of stubs instead, and the stack would never
+        // scroll.)
+        "&": "flex: 1 0 4rem; font-size:0.85em line-height:1.5 fg:$s-muted text-decoration:none " +
+            "white-space:nowrap max-width:max-content overflow:hidden text-overflow:ellipsis " +
             "transition: color 0.12s;",
         "&.s-crumb-on": "font-weight:600 fg:$s-text",
         // The same hover treatment as a menu item. The panel you are on is a plain
@@ -349,8 +353,8 @@ export class PanelStackController {
     containerEl;
     /** The shell's measurements, shared by everything drawn since they were taken. */
     geom;
-    /** The body width at the last layout; a change means a window resize → snap. */
-    lastBodyW = -1;
+    /** The measurements the last layout ran on; a change in them → snap. */
+    lastGeom;
     layoutQueued = false;
     timers = new Set();
     /** The arrangement the navigation in flight is heading for; see {@link intended}. */
@@ -620,9 +624,12 @@ export class PanelStackController {
             maxWidth: "full",
             width: 0,
         };
-        // `close` closes *this* panel, current or not. It resolves the panel's
-        // place in the stack at call time, so it keeps working after a splice has
-        // moved it — and quietly resolves false once the panel is gone.
+        // `close` closes *this* panel, current or not, and `open` navigates
+        // *from* it, through the very implementation a link click uses (see
+        // `navigate`). Both resolve the panel's place in the stack at call
+        // time, so they keep working after a splice has moved it; an `open`
+        // from a panel that has since closed falls back to a derived stack,
+        // like a link from nowhere.
         //
         // `visible` starts at what the panel's place implies: shown when it sits
         // at or before the current panel (a pushed panel always does), hidden when
@@ -636,6 +643,7 @@ export class PanelStackController {
             visible,
             pinned: pinned || undefined,
             close: () => this.closePath(entry.path),
+            open: (href, how) => this.navigate(href, { from: entry.path, how }),
         });
         return entry;
     }
@@ -865,17 +873,31 @@ export class PanelStackController {
         });
     }
     /**
-     * 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 to `href` — the one implementation behind a link click,
+     * {@link Panel.open} and the stack's own methods, so none of them can
+     * behave differently.
+     *
+     * `from` is the path of the panel the navigation starts from — the one
+     * the link lives in — or absent when it has none: a nav item, or a call
+     * that means the whole stack, which is then built instead (see
+     * {@link deriveStack}), or taken outright from `beneath`, for callers
+     * that know it.
+     *
+     * `how` is the link's `data-panel` attribute (or the caller's word for
+     * it): absent — like a link without the attribute — it is the shell's
+     * `linkNavigation` default, an unrecognised value is a push on top of
+     * `from`, `"replace"` swaps `from` out rather than stacking on it, and
+     * `"open"` drops `from` altogether so the target arrives with its own
+     * stack, the way a nav item's link does.
      *
      * 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, origin, replace = false, beneath) {
+    navigate(href, { from, how, beneath } = {}) {
+        const mode = how ?? this.opts.linkNavigation;
+        const origin = mode === "open" ? null : from ?? null;
+        const replace = mode === "replace";
         return A.peek(() => {
             let url;
             try {
@@ -933,43 +955,36 @@ export class PanelStackController {
     pushPath(path, replace) {
         return A.peek(() => {
             const arr = this.intended();
-            return this.navigate(path, arr.stack[arr.focus] ?? null, replace);
+            return this.navigate(path, { from: arr.stack[arr.focus], how: replace ? "replace" : "push" });
         });
     }
     // ── Link interception ──────────────────────────────────────────────────
     /**
      * 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), the `data-panel`
-     * attribute, and return-to-an-open-panel semantics. The exclusion rules
+     * the anchor so we can decide what the click *means*. 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`, `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. A link that doesn't say gets the
-     * shell's {@link PanelStackOptions.linkNavigation} (`push` by default);
-     * an unrecognised value is a `push`.
+     * A link inside a panel is that panel's {@link Panel.open}, the `data-panel`
+     * attribute as its `how` (see {@link navigate}, the shared implementation).
+     * A link that isn't inside any panel — a nav item, one in a dialog — has no
+     * panel to build on, so it replaces the stack as a whole, exactly as a cold
+     * link to the same URL would open it.
      */
     interceptLinks() {
         route.interceptLinks((url, anchor) => {
-            const mode = anchor.getAttribute("data-panel") ?? this.opts.linkNavigation;
-            let origin = null;
-            if (mode !== "open") {
-                const panel = anchor.closest(".s-panel");
-                if (panel) {
-                    origin = this.$state.live.find((entry) => entry.el === panel)?.path ?? null;
-                }
-                else if (anchor.closest(".s-panel-origin")) {
-                    // The current panel's actions, promoted into the top bar on a
-                    // narrow shell (see main.ts), sit outside every `.s-panel` — but
-                    // they are still the current panel's own chrome, so a link among
-                    // them builds on that panel, exactly as it does at full width.
-                    origin = this.$state.live[this.$state.focus]?.path ?? null;
-                }
-            }
-            void this.navigate(url.href, origin, mode === "replace");
+            const how = anchor.getAttribute("data-panel") ?? undefined;
+            // The panel the link lives in: the enclosing `.s-panel`, or — for the
+            // current panel's actions, promoted into the top bar on a narrow shell
+            // (see main.ts), outside every `.s-panel` — the current panel, whose
+            // own chrome they remain at every width.
+            const panelEl = anchor.closest(".s-panel");
+            const entry = panelEl
+                ? this.$state.live.find((e) => e.el === panelEl)
+                : anchor.closest(".s-panel-origin")
+                    ? this.$state.live[this.$state.focus]
+                    : undefined;
+            void this.navigate(url.href, { from: entry?.path, how });
             return true;
         });
     }
@@ -993,7 +1008,7 @@ export class PanelStackController {
         return this.pushPath(path, true);
     }
     openPanelStack(path, beneath) {
-        return this.navigate(path, null, false, beneath);
+        return this.navigate(path, { how: "open", beneath });
     }
     closePanel(path) {
         return A.peek(() => {
@@ -1018,6 +1033,17 @@ export class PanelStackController {
     setLinkNavigation(mode) {
         this.opts.linkNavigation = mode;
     }
+    /**
+     * Adopt a changed `fullWidth`: one layout pass, nothing redrawn. A changed
+     * `navWidth` needs no counterpart — resizing the sidebar resizes the column
+     * region, which the layout engine is already observing.
+     */
+    setFullWidth(px) {
+        if (this.opts.fullWidth === px)
+            return;
+        this.opts.fullWidth = px;
+        this.scheduleLayout();
+    }
     /**
      * 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
@@ -1345,25 +1371,21 @@ export class PanelStackController {
             if (child !== container)
                 chrome += child.getBoundingClientRect().width;
         }
-        // The standard panel is SHELL_PX wide, capped by the window; what it leaves
-        // beside the sidebar is the *standard* content area. Widths are a pure
-        // function of the window — never of what else is open — so a panel NEVER
-        // resizes because a neighbour came or went; only a window resize (the
-        // snap pass in `layout`) changes them:
+        // What the window has beside the sidebar, and within that the *standard*
+        // content area: the width the app gave a "full" panel, or all there is
+        // when the window has less. Widths are a pure function of the window —
+        // never of what else is open — so a panel NEVER resizes because a
+        // neighbour came or went; only a window resize (the snap pass in
+        // `layout`) changes them:
         // - "full" fills the standard content area exactly;
         // - "half" is half of it whenever that half is still a usable column, and
         //   the whole of it on narrower screens;
         // - "screen" ignores the standard width and takes everything the window
         //   has — which also means nothing ever fits beside it.
-        const full = Math.max(0, Math.min(SHELL_PX, total) - chrome);
+        const screen = Math.max(0, total - chrome);
+        const full = Math.min(this.opts.fullWidth, screen);
         const halved = full / 2;
-        return {
-            total,
-            chrome,
-            half: halved >= PAIR_MIN_PX ? halved : full,
-            full,
-            screen: Math.max(0, total - chrome),
-        };
+        return { total, chrome, half: halved >= PAIR_MIN_PX ? halved : full, full, screen };
     }
     /**
      * The measurements this pass runs on. Taken once per layout pass and per
@@ -1407,13 +1429,16 @@ export class PanelStackController {
         if (!geom)
             return;
         const stacking = this.opts.columns !== "single";
-        // A window resize (or the very first pass) must be adopted instantly —
-        // geometry tracking the window through a 450ms transition reads as lag,
-        // and a shell animating itself into place on load reads as a glitch.
+        // A window resize — or the app resizing the shell itself, by changing
+        // `navWidth` or `fullWidth` — must be adopted instantly: geometry tracking
+        // the window through a 450ms transition reads as lag, and a shell
+        // animating itself into place on its first pass reads as a glitch. Only
+        // what a *panel* did is worth animating, and none of those three are.
         // `.s-shell-snap` suppresses every standing transition for this one pass.
-        const snap = this.lastBodyW !== geom.total;
+        const was = this.lastGeom;
+        const snap = was == null || was.total !== geom.total || was.chrome !== geom.chrome || was.full !== geom.full;
         if (snap) {
-            this.lastBodyW = geom.total;
+            this.lastGeom = geom;
             shell.classList.add("s-shell-snap");
         }
         const width = (entry) => geom[entry.maxWidth];
@@ -1435,7 +1460,7 @@ export class PanelStackController {
         // The content area holds the run, but is never smaller than the standard
         // panel (a lone small leaves its other half open — which is exactly where
         // the next small lands, without anything on screen moving) and never
-        // wider than the window. So the panel is the familiar 1280px until extra
+        // wider than the window. So the page holds its standard width until extra
         // columns genuinely fit, and stretches — centred — to hold the ones that
         // do; with a "screen" up that's the window's edges.
         const area = Math.min(geom.screen, Math.max(geom.full, runSum));
@@ -1447,11 +1472,11 @@ export class PanelStackController {
             if (!entry.width)
                 entry.width = width(entry);
         }
-        // The chrome above and below the body caps itself to the ensemble width,
-        // keeping everything centred and aligned however far the area stretches.
-        // The consumers transition their max-width (see main.ts), so the
-        // recentring plays along with the panel that caused it instead of
-        // snapping.
+        // The body row caps itself to the ensemble width, keeping the columns
+        // centred however far the area stretches, and transitions its max-width
+        // (see main.ts) so the recentring plays along with the panel that caused
+        // it. The bars above and below don't follow — they hold at the standard
+        // page width (also main.ts).
         shell.style.setProperty("--s-shell-w", `${geom.chrome + area}px`);
         // Phase 1 — every panel's *start* state for this frame. Panels already on
         // screen simply move (their standing transition animates it); freshly