staffa 0.12.0 → 0.12.1

package/README.md

@@ -190,7 +190,7 @@ Navigating faster than the shell can settle is fine: closing travels through the
 
 Below the width two columns need, everything takes the whole content area whatever it asked for. Those numbers assume a nav sidebar of around 170px; without one, add that back. Nothing fits beside a `"full"` on a standard 1280px page, but on a wide enough window a `"half"` still can, and the page grows past 1280px to hold both.
 
-A column'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, and never reflows what someone was reading. A lone `"half"` leaves its other half empty, and that is exactly where the next one lands. When more columns fit than the standard 1280px page holds (three halves, say), the page itself grows, staying centred, to hold them.
+A column'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, and never reflows what someone was reading. A lone `"half"` leaves its other half empty, and that is exactly where the next one lands. When more columns fit than the standard 1280px page holds (three halves, say), the page itself grows, staying centred, to hold them — though the top bar and footer keep to the standard width, so the chrome holds still while the columns come and go.
 
 Columns tile that area, separated by a hairline and no gutter — a column brings its own padding, so their contents stay comfortably apart regardless.
 

package/dist/components/main.js

@@ -8,7 +8,7 @@ import { drawMenu, isFloatingMenuOpen, consumeBranchNav, anyCurrent } from "./me
 import { menu as menuIcon, x as closeIcon } from "../icons.js";
 import { iconButton } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
-import { PanelStackController } from "./panels.js";
+import { PanelStackController, SHELL_PX } from "./panels.js";
 A.insertGlobalCss({
     ".s-main": {
         // container-type so @container queries below can respond to shell width.
@@ -26,8 +26,10 @@ A.insertGlobalCss({
         // The bar reads `[leading] [title] …spacer… [trailing]`. The spacer is the
         // trailing slot's own growth: it takes the free space and right-aligns
         // itself in it, which is what lets a search box live there. When the two
-        // compete, the title truncates first — but only down to a floor, past
-        // which the trailing slot shrinks instead: a wide search box must not
+        // compete, the titles give way first: the trailing slot's near-zero
+        // shrink factor keeps a row of actions at its natural width while the
+        // crumbs absorb the squeeze — but only down to the titles' floor, past
+        // which the trailing slot shrinks after all: a wide search box must not
         // starve the titles to nothing (the crumb strip's overlay buttons would
         // escape their zero-width strip, over the ☰ beside it).
         "> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
@@ -48,13 +50,16 @@ A.insertGlobalCss({
         // which their classes then provide. (`filter:none` keeps the global
         // `a:hover` brighten off the gradient text.)
         "> header a.s-logo, > header a.s-title": "text-decoration:none filter:none cursor:pointer",
-        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 1 auto; min-width:0",
+        "> header .s-menu": "display:flex align-items:center justify-content:flex-end gap:$2 flex: 1 0.1 auto; min-width:0",
         // Body always wraps <main> (with or without a sidebar) so max-width centering
         // and scrollbar alignment work identically in both cases.
         // .s-body centres .s-body-inner; .s-body-inner caps the content to maxWidth.
         // It's also the positioning + clipping context for the narrow-screen nav panel,
-        // which slides in and out across its left edge.
-        ".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center position:relative",
+        // which slides in and out across its left edge. `overflow:clip` rather than
+        // `hidden` for the same reason as `.s-panels`: a hidden box can still be
+        // scrolled (find-in-page, an anchor, an extension), and a stray scroll here
+        // would shove the whole row — sidebar and columns — out of place for good.
+        ".s-body": "flex:1 overflow:clip display:flex flex-direction:row min-height:0 justify-content:center position:relative",
         ".s-body-inner": "flex:1 min-width:0 display:flex flex-direction:row min-height:0",
         // Put the sidebar on the right (content fills the left) for right-hand navs.
         "&.s-nav-right .s-body-inner": "flex-direction:row-reverse",
@@ -85,20 +90,24 @@ A.insertGlobalCss({
         // Routed mode takes its width from the stack instead of from
         // `maxWidth`: the layout engine publishes the ensemble width (sidebar +
         // separator + content area) as --s-shell-w — the standard 1280px page
-        // normally, the window's edges while a "screen" page is up — and the body
-        // row and the bars cap themselves to it. So the chrome lines up with the
-        // columns and the lot stays centred in the shell.
-        "&.s-routed > .s-body > .s-body-inner": "max-width: var(--s-shell-w, 100%);",
-        "&.s-routed > header > .s-bar": "max-width: var(--s-shell-w, 100%);",
-        "&.s-routed > footer > .s-bar": "max-width: var(--s-shell-w, 100%);",
-        // Changing the custom property animates the max-widths consuming it, with no
-        // JS in the loop: the chrome recentres in step with the panel whose arrival
-        // or departure moved it, over the same --s-panel-ms (see panels.ts). During
-        // a window resize (and the very first pass) the layout engine raises
-        // `.s-shell-snap` so the new width is adopted instantly instead of chasing
-        // the window through a transition.
-        "&.s-routed > .s-body > .s-body-inner, &.s-routed > header > .s-bar, &.s-routed > footer > .s-bar": "transition: max-width var(--s-panel-ms) ease;",
-        "&.s-routed.s-shell-snap > .s-body > .s-body-inner, &.s-routed.s-shell-snap > header > .s-bar, &.s-routed.s-shell-snap > footer > .s-bar": "transition:none",
+        // normally, wider while the columns outgrow it (a "screen" page, or
+        // extra columns fitting a wide window) — and the body row caps itself
+        // to it, staying centred around the columns. Changing the custom
+        // property animates the max-width consuming it, with no JS in the loop:
+        // the body recentres in step with the panel whose arrival or departure
+        // moved it, over the same --s-panel-ms (see panels.ts). During a window
+        // resize (and the very first pass) the layout engine raises
+        // `.s-shell-snap` so the new width is adopted instantly instead of
+        // chasing the window through a transition.
+        "&.s-routed > .s-body > .s-body-inner": "max-width: var(--s-shell-w, 100%); transition: max-width var(--s-panel-ms) ease;",
+        "&.s-routed.s-shell-snap > .s-body > .s-body-inner": "transition:none",
+        // The bars don't follow the ensemble past the standard page: a header
+        // stretching to the window's edges and back with every "screen" panel
+        // reads as the whole app flexing, so the chrome holds still and only
+        // the columns grow. (Below the standard width the ensemble is simply
+        // the window, which only a resize changes — so the bars never animate,
+        // and take no part in the transition above.)
+        [`&.s-routed > header > .s-bar, &.s-routed > footer > .s-bar`]: `max-width:${SHELL_PX}px`,
     },
     // Sidebar nav panel. Items reuse the shared `.s-menu-item` /
     // `.s-menu-sep` styles from menu.ts, so the sidebar and the floating

package/dist/components/panels.d.ts

@@ -161,13 +161,19 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      *   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.
+     *   dashboards. While one is open the columns stretch to the screen edges
+     *   instead of stopping at the standard 1280px page; the top bar and
+     *   footer hold the standard width throughout.
      *
      * 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.
      *
+     * This is a *layout regime*, not a width guarantee: handle whatever width
+     * the bucket yields, and ask only for what your content can actually use —
+     * a screen that would cap its own content narrower than its ask is holding
+     * room that would have let another column fit beside it.
+     *
      * 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
@@ -243,7 +249,40 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      * ```
      */
     close(): Promise<boolean>;
+    /**
+     * Opens `href` exactly as a click on a link inside this panel does — the
+     * shell's own link handling runs through this very call, so the two can't
+     * drift apart. By default that is a push: the target opens on top of this
+     * panel, closing the panels after it first (pinned ones ride along
+     * beneath the new panel, unsaved ones park), and a path that is already
+     * open is returned to rather than opened twice. `how` plays the part of a
+     * link's `data-panel` attribute: `"replace"` puts the target in this
+     * panel's place, `"open"` leaves the panel behind and gives the target
+     * its own stack, and omitting it follows the shell's
+     * {@link MainOptions.linkNavigation}, like a link without the attribute.
+     *
+     * This is the one for navigation that can't be a link: a row's click
+     * handler, a keyboard shortcut acting on this screen. The stack's
+     * {@link PanelStack.pushPanel} builds on the *current* panel instead — a
+     * different panel exactly when the interaction happened in a column
+     * beside it, where it would pile the new panel on top of the open detail
+     * rather than pruning back to this one.
+     *
+     * @example
+     * ```ts
+     * A("div.row click=", () => void $panel.open(`/contacts/${id}`), ...);
+     * ```
+     */
+    open(href: string, how?: "push" | "replace" | "open"): Promise<boolean>;
 }
+/**
+ * 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. The top bar and footer keep to this
+ * width even then (see main.ts), so the chrome holds still while the
+ * columns stretch.
+ */
+export declare const SHELL_PX = 1280;
 /** Options the stack needs from its shell. */
 export interface PanelStackOptions {
     routes: Routes;
@@ -315,6 +354,11 @@ export interface PanelStack {
      * 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.
+     *
+     * Note that a link builds on the panel it is *drawn in*, which is the
+     * current panel only while no column beside it has the focus. Code
+     * navigating on behalf of a particular screen — a row's click handler —
+     * wants that panel's own {@link Panel.open} instead.
      */
     pushPanel(path: string): Promise<boolean>;
     /**
@@ -581,11 +625,22 @@ export declare class PanelStackController implements PanelStack {
      */
     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.
+     * 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
@@ -596,18 +651,15 @@ export declare class PanelStackController implements PanelStack {
     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), 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.
      */
     private interceptLinks;
     get currentPanel(): Panel | undefined;

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.
  *
@@ -126,9 +126,11 @@ 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.
+ * page makes the shell grow past it. The top bar and footer keep to this
+ * width even then (see main.ts), so the chrome holds still while the
+ * columns stretch.
  */
-const SHELL_PX = 1280;
+export 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 +153,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 +252,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
@@ -620,9 +632,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 +651,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 +881,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 +963,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 +1016,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(() => {
@@ -1447,11 +1470,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