staffa 0.12.0 → 0.13.0

package/README.md

@@ -180,17 +180,19 @@ Navigations settle asynchronously (closes travel through the browser's history),
 
 Navigating faster than the shell can settle is fine: closing travels through the browser's history, so it takes a moment to land, and anything asked for in the meantime waits for it rather than being dropped. Two quick Escapes (or back gestures) peel two panels, each aimed at the stack the one before it was heading for.
 
-**Every panel must work at 360–540px**, because that is what it gets whenever two columns fit. `$panel.maxWidth` says how much *more* it can usefully take. The content area is the page, at most 1280px wide, minus the nav sidebar:
+**Every panel must work at 360–540px**, because that is what it gets whenever two columns fit. `$panel.maxWidth` says how much *more* it can usefully take. The content area is what `S.main()`'s `fullWidth` says it is — 1080px by default:
 
 | `maxWidth` | How wide the panel gets | Good for |
 | --- | --- | --- |
 | `"half"` | Half the content area: 360 to 540px. | lists, detail forms — anything that reads well at phone width |
-| `"full"` (default) | The whole content area: up to ~1100px. | ordinary screens; the safe default |
-| `"screen"` | The whole window, no upper limit: ~1750px on a 1920px screen. | boards, wide tables, dense dashboards |
+| `"full"` (default) | The whole content area: up to 1080px. | ordinary screens; the safe default |
+| `"screen"` | The whole window, no upper limit: ~1720px on a 1920px screen. | boards, wide tables, dense dashboards |
 
-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.
+Below the width two columns need, everything takes the whole content area whatever it asked for. Nothing fits beside a `"full"` on a standard page, but on a wide enough window a `"half"` still can, and the page grows 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.
+The standard page is those 1080px plus the nav sidebar's 200 — the 1280px an app is usually seen at, though neither figure is fixed: `S.main({ navWidth, fullWidth })` sets both, and everything above follows from 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 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.d.ts

@@ -217,6 +217,20 @@ export interface MainOptions<R = Routes> {
      * themselves up with them.
      */
     maxWidth?: string;
+    /**
+     * How wide a `"full"` panel gets, in pixels — and with it the whole content
+     * area, since a `"full"` fills it exactly. A `"half"` gets half of this, and
+     * a `"screen"` ignores it and takes the window. Defaults to 1080; the window
+     * caps it when there is less room than that. Routed mode only.
+     *
+     * This plus {@link MainOptions.navWidth} is the app's standard page — see
+     * there.
+     *
+     * Live, like {@link MainOptions.columns}: pass a proxied options object (or
+     * make this field a getter) and a change is adopted in one layout pass,
+     * every panel keeping its state.
+     */
+    fullWidth?: number;
     /** Aberdeen attr/style string applied to the content area. */
     contentAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the top bar. */
@@ -243,6 +257,17 @@ export interface MainOptions<R = Routes> {
      * chrome goes assumes they are one.
      */
     navPosition?: "left" | "right";
+    /**
+     * How wide the nav sidebar column is, in pixels — its hairline included.
+     * Defaults to 200.
+     *
+     * Together with {@link MainOptions.fullWidth} this is the app's *standard
+     * page*: the width the top bar and footer keep to, and the width the
+     * columns settle back to. The defaults come to the familiar 1280px.
+     *
+     * Live, like {@link MainOptions.fullWidth}.
+     */
+    navWidth?: number;
     /** Aberdeen attr/style string applied to the sidebar nav panel. */
     navAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the narrow-screen full-page nav. */

package/dist/components/main.js

@@ -9,6 +9,15 @@ 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";
+/**
+ * The default nav column (hairline included) and the default width of a
+ * `"full"` panel — see {@link MainOptions.navWidth} and
+ * {@link MainOptions.fullWidth}. Side by side they come to the 1280px page the
+ * shell is usually seen as, but that figure lives nowhere: the browser adds
+ * these two up, and an app that changes either simply gets a different page.
+ */
+const NAV_W = 200;
+const FULL_W = 1080;
 A.insertGlobalCss({
     ".s-main": {
         // container-type so @container queries below can respond to shell width.
@@ -26,8 +35,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 +59,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",
@@ -84,21 +98,25 @@ A.insertGlobalCss({
         ".s-body main.s-scroll-y": "margin-right:$3",
         // 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",
+        // separator + content area) as --s-shell-w — the standard page
+        // 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: calc(var(--s-nav-w) + var(--s-full-w))",
     },
     // Sidebar nav panel. Items reuse the shared `.s-menu-item` /
     // `.s-menu-sep` styles from menu.ts, so the sidebar and the floating
@@ -109,7 +127,10 @@ A.insertGlobalCss({
         // The generous horizontal padding is what keeps the rows clear of the content
         // separator on one side and the shell edge on the other; the vertical scroll
         // (overflow-y:auto, which also clips overflow-x) leaves no room to bleed past it.
-        "&": "display:flex flex-direction:column overflow-y:auto flex-shrink:0 max-width:228px padding:$3 gap:$1",
+        // `--s-nav-w` measures the whole column, hairline included, so the panel
+        // itself gives that 1px back — and the app's two widths then add up to
+        // exactly the page the bars above and below keep to.
+        "&": "display:flex flex-direction:column overflow-y:auto flex-shrink:0 width: calc(var(--s-nav-w) - 1px); padding:$3 gap:$1",
     },
     // The narrow-screen nav: a full "panel" that slides in over the content from the
     // left, rather than a dropdown — on a phone a nav is a screenful of UI, not a
@@ -187,6 +208,9 @@ export function main(opts = {}) {
             notFound: opts.notFound,
             ancestors: opts.ancestors,
             title: opts.title,
+            // Corrected below, and on every change, from the app's own option:
+            // read here it would subscribe the whole shell to it.
+            fullWidth: FULL_W,
             $shell,
         })
         : null;
@@ -198,6 +222,7 @@ export function main(opts = {}) {
         // the new link default. Nothing else of the shell is touched.
         A(() => ctl.setColumns(opts.columns));
         A(() => ctl.setLinkNavigation(opts.linkNavigation));
+        A(() => ctl.setFullWidth(opts.fullWidth ?? FULL_W));
     }
     // Where the brand mark and the app's name link — or nowhere, when the app
     // said `home: null` (a title slot holding a control of its own, say).
@@ -206,13 +231,22 @@ export function main(opts = {}) {
     // rather than to `maxWidth`.
     const capWidth = ctl ? null : opts.maxWidth;
     const root = A(`div.s-main${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
-        // Which side the sidebar is on, as a class on the shell for the CSS above to
-        // hang off. Its own scope (see `nav` above), so a nav appearing or emptying
-        // out only retags the shell rather than redrawing it.
+        // The two widths the CSS above works from, and with them the standard page
+        // the bars keep to. Each sits in a scope of its own — one that draws
+        // nothing, so re-running it is a single style write: an app that changes
+        // either on a proxied options object resizes the shell in place, panels
+        // and their state untouched.
+        A(() => A(`--s-full-w: ${opts.fullWidth ?? FULL_W}px`));
+        // `--s-nav-w` is the sidebar's whole column, and nothing at all when there
+        // is no sidebar to give it to — a shell without one lines its bars up with
+        // the content. This scope also tags the shell with the side the sidebar is
+        // on, for the CSS above to hang off (see `nav` above: reading `nav.items`
+        // here subscribes this scope alone, never the shell entire).
         A(() => {
             if (nav == null || !nav.items.length)
-                return;
-            A(`.s-nav-${navPos}`);
+                A("--s-nav-w: 0px");
+            else
+                A(`.s-nav-${navPos}`, `--s-nav-w: ${opts.navWidth ?? NAV_W}px`);
         });
         // Top bar: `[leading] [identity] …spacer… [trailing]`, where each slot's
         // contents depend on how much room the shell has and — in routed mode — on

package/dist/components/panels.d.ts

@@ -157,17 +157,25 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      * 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.
+     * - `"half"` — nothing more. Half the content area (360px up to half of
+     *   {@link MainOptions.fullWidth}), so a second column fits beside it. For
+     *   lists and detail forms.
+     * - `"full"` (the default) — the whole content area, which is exactly
+     *   {@link MainOptions.fullWidth}: 1080px unless the app says otherwise.
      * - `"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 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,6 +251,31 @@ 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>;
 }
 /** Options the stack needs from its shell. */
 export interface PanelStackOptions {
@@ -254,6 +287,8 @@ export interface PanelStackOptions {
     columns?: "auto" | "single";
     /** What a bare link does. See {@link MainOptions.linkNavigation}. */
     linkNavigation?: "push" | "replace" | "open";
+    /** How wide a `"full"` panel gets, in px. See {@link MainOptions.fullWidth}. */
+    fullWidth: number;
     /** The shell's own title, used as the suffix of `document.title`. */
     title?: unknown;
     /**
@@ -315,6 +350,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>;
     /**
@@ -411,8 +451,8 @@ export declare class PanelStackController implements PanelStack {
     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;
+    /** The measurements the last layout ran on; a change in them → snap. */
+    private lastGeom?;
     private layoutQueued;
     private timers;
     /** The arrangement the navigation in flight is heading for; see {@link intended}. */
@@ -581,11 +621,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 +647,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;
@@ -621,6 +669,12 @@ export declare class PanelStackController implements PanelStack {
     setColumns(columns: "auto" | "single" | undefined): void;
     /** Adopt a changed `linkNavigation` default; the next click reads it. */
     setLinkNavigation(mode: "push" | "replace" | "open" | undefined): void;
+    /**
+     * 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: number): void;
     /**
      * 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