staffa 0.8.0 → 0.8.1

package/README.md

@@ -172,11 +172,13 @@ Those numbers assume a nav sidebar of around 170px; without a sidebar, add that
 
 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, and never reflows what someone was reading. A lone small leaves its other half empty, and that is exactly where the next small lands. When more columns fit than the standard 1280px page holds (three smalls, say), the page itself grows, staying centred, to hold them.
 
+The panel is sized before your handler runs, so anything inside it that measures its own box — a chart, a virtualised list, a column count — gets a real one from the first frame rather than a zero-width one. A new panel starts at whatever `layout` says at that point, which is the default, so a handler that *assigns* `layout` is drawn at the medium width and reflowed immediately after. Assigning it later works too: 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.
+
 **The rest of `$page`:**
 
 - `params` and `path`: read-only.
 - `title`: shown in `document.title` while this panel is the top one.
-- `layout`: as above. It's read once, right after your handler runs, so set it there.
+- `layout`: as above, and live — set it whenever you like and the panel reflows.
 - `loading`: set it while you're fetching. A new panel waits a moment before sliding in, so it can arrive with real content instead of empty, and shows a loading indicator if the wait drags on.
 - `close()`: closes this panel, wherever it sits in the stack.
 - `requestClose`: your chance to say no. Everything that would close the panel waits for it: Escape, the panel's own ✕ or Cancel button, the browser's back button, a link that would close it, `S.panels.close()`. Return `false` to keep the panel open.
@@ -198,6 +200,8 @@ S.panels.close("/projects/7"); // that panel, wherever it is
 
 Closing the top panel goes back to whatever was underneath it. Closing one that *isn't* on top takes just that one away: the columns to its right stay where they are and keep their state, and the URL doesn't change, because the top panel didn't move. Either way it becomes a history entry, so the browser's back button brings the panel back.
 
+A closed panel is torn down at once: its `A.clean()` hooks run the moment it closes, so subscriptions, timers and requests stop there and then. Only its element hangs around, inert and frozen, for the length of the exit animation.
+
 Staffa itself contributes two things: the Escape key, which closes the top panel (and jumps to the navigation once you're at the bottom of the stack), and making the browser's back button do the right thing. Both ask `requestClose` first.
 
 <a id="ancestors"></a>
@@ -267,7 +271,7 @@ Components share naming conventions for options: `attrs` (outermost element), `c
 
 ### Layout & containers
 
-- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
+- **`S.main(opts)`**: app shell, a sticky header with `icon`, `title`, `subtitle`, `menu`; scrollable content area; footer. Set `maxWidth` to center the content. Give it a `nav` for a sidebar that collapses to a hamburger below 640 px — where the nav becomes a full page sliding in from the left, handing over to the chosen screen with a matching slide in from the right. Its `items` may be a reactive array; adding or removing one redraws just the sidebar, never the content beside it. Instead of a single `content` slot it can take a `routes` table — see [Panel-stack navigation](#panel-stack-navigation).
 - **`S.box(opts | content)`**: surface with optional `header`/`footer` and padded body. Pass a function for shorthand `{ content }`. `close: true` adds a ✕ that closes the panel the box is in (see [Panel-stack navigation](#panel-stack-navigation)); `close: fn` runs your own dismissal.
 - **`S.tabs(opts)`**: tablist with live panels and keyboard navigation. More tabs than fit make the strip scroll, with a ‹ / › button appearing at whichever end still has something to reach — so it's not just a swipe target. Selecting a tab any other way (the arrow keys, a `bind` written from elsewhere) scrolls it into view.
 - **`S.form(opts | content)`**: form aligning fields in a column or responsive grid, with an `actions` bar. Prevents the default page reload.

package/dist/components/main.d.ts

@@ -111,6 +111,11 @@ export interface MainOptions<R = Routes> {
      * mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
      * collapses to a button when the shell is too narrow — which there opens the
      * nav as a full page sliding in from the left, not as a dropdown.
+     *
+     * `items` may be a reactive array: the shell reads it inside the sidebar's own
+     * scope, so an item arriving or leaving redraws the sidebar and nothing else.
+     * The content beside it — in routed mode, the whole panel stack — is left
+     * alone.
      */
     nav?: MenuOptions;
     /**

package/dist/components/main.js

@@ -169,10 +169,14 @@ A.insertGlobalCss({
 // silently degrades to `any`. Callers that pass no `routes` are unaffected —
 // `MainOptions`'s own default kicks in there.
 export function main(opts = {}) {
+    // Whether there is a nav to show is deliberately NOT worked out here: `items`
+    // may well be a reactive array, and reading it in the shell's own scope would
+    // subscribe *the whole shell* to it — an item arriving later would redraw the
+    // lot, and in routed mode that means tearing the panel stack down and building
+    // it again from the URL. So every use below reads `nav.items` inside its own
+    // scope, and only that scope redraws.
     const nav = opts.nav;
     const navPos = opts.navPosition ?? "left";
-    const hasNav = nav != null && nav.items.length > 0;
-    const navCls = hasNav ? (navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`) : "";
     // Whether the narrow-screen full-page nav is showing. Per shell, so nested or
     // sibling `main()`s can't fight over it.
     const $nav = A.proxy({ open: false });
@@ -182,19 +186,32 @@ export function main(opts = {}) {
     }
     // The panel stack owns the routing, so it starts observing (and building its
     // stack from) the URL before any of the shell is drawn — the top bar's back
-    // button already needs to know how deep we are.
-    const ctl = routes ? new PanelController({ ...opts, routes, title: opts.title }) : null;
+    // button already needs to know how deep we are. Its options are listed one by
+    // one rather than spread from `opts`: a spread reads every key, which on a
+    // proxied options object subscribes this scope to all of them.
+    const ctl = routes
+        ? new PanelController({ routes, notFound: opts.notFound, stacking: opts.stacking, title: opts.title })
+        : null;
     // Routed mode caps the shell to the ensemble width the layout engine publishes,
     // rather than to `maxWidth`.
     const capWidth = ctl ? null : opts.maxWidth;
-    const root = A(`div.s-main${navCls}${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
+    const root = A(`div.s-main${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
+        // Which nav mode the shell is in — sidebar or button — as a class on the
+        // shell, for the CSS below to hang the responsive collapse off. Its own
+        // scope (see `nav` above), so a nav appearing or emptying out only retags
+        // the shell rather than redrawing it.
+        A(() => {
+            if (nav == null || !nav.items.length)
+                return;
+            A(navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`);
+        });
         // Top bar.
         A(() => {
             const hasBar = opts.title != null ||
                 opts.subtitle != null ||
                 opts.icon != null ||
                 opts.menu != null ||
-                hasNav;
+                (nav != null && nav.items.length > 0);
             if (!hasBar)
                 return;
             A("header.s-s.neutral", opts.topbarAttrs, () => {
@@ -206,7 +223,7 @@ export function main(opts = {}) {
                     });
                     // Nav trigger button — visible when sidebar is hidden (button mode or narrow viewport).
                     A(() => {
-                        if (!hasNav)
+                        if (nav == null || !nav.items.length)
                             return;
                         // .s-nav-trigger: CSS toggles display based on sidebar visibility.
                         A("div.s-nav-trigger", () => drawNavTrigger(nav, $nav));
@@ -240,17 +257,21 @@ export function main(opts = {}) {
                     if (capWidth != null)
                         A("max-width:", capWidth);
                 });
-                if (hasNav && navPos !== "button") {
+                // The sidebar, in its own scope so a changing item list redraws just
+                // it — never the content area beside it (see `nav` above).
+                A(() => {
+                    if (nav == null || !nav.items.length || navPos === "button")
+                        return;
                     A(`nav.s-nav-panel.s-nav-${navPos}`, opts.navAttrs, () => {
                         drawMenu(nav.items);
                     });
                     A("div.s-nav-sep aria-hidden=true");
-                }
+                });
                 drawMainContent(opts, ctl);
             });
             // The narrow-screen nav page, laid over the body it slides across.
             A(() => {
-                if (hasNav && $nav.open)
+                if (nav != null && nav.items.length && $nav.open)
                     drawNavPage(nav, opts.navPageAttrs, $nav);
             });
         });
@@ -275,7 +296,7 @@ export function main(opts = {}) {
     // shell width calls for), which focuses its current item. Listens on
     // `document` so it works wherever focus is, but bows out while another overlay
     // (a dialog, or an already-open menu) is up — those handle Escape themselves.
-    if (hasNav || ctl) {
+    if (nav != null || ctl) {
         const onKey = (e) => {
             if (e.key !== "Escape" || e.defaultPrevented)
                 return;
@@ -298,8 +319,9 @@ export function main(opts = {}) {
                 void ctl.closeTop();
                 return;
             }
-            if (!hasNav)
-                return;
+            // Whether there is a nav at all is asked of the DOM, not of `nav.items`:
+            // a subscription here would be one on the shell's own scope again, and
+            // an empty nav simply has neither of the two elements below.
             // `offsetParent` is null when the sidebar is hidden (display:none).
             const panel = root.querySelector(".s-nav-panel");
             if (panel?.offsetParent != null) {

package/dist/components/panels.d.ts

@@ -101,8 +101,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";
     /**
@@ -169,6 +180,8 @@ 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;
@@ -220,14 +233,24 @@ 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;
     /**
      * 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
@@ -289,6 +312,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.