staffa 0.8.0 → 0.8.1

package/dist/components/panels.js

@@ -122,21 +122,32 @@ const SHELL_PX = 1280;
 const GUTTER_PX = 24;
 /** Don't pair smalls when half the content area would be narrower than this. */
 const PAIR_MIN_PX = 360;
+/**
+ * Panels are layered by their depth in the stack, two `z-index` steps per panel:
+ * a panel sits on the odd layer for its depth, and a *closing* one drops to the
+ * even layer just below, where it is frozen for the length of its fade. So a
+ * panel that replaces another comes in over it, while one that closes fades out
+ * over whatever it was covering — which is the way round both should read.
+ */
+const LAYER_STEP = 2;
 // ─── Module-level styling ────────────────────────────────────────────────────
 A.insertGlobalCss({
     ":root": `--s-panel-ms:${PANEL_MS}ms`,
     // The clipping viewport that the columns slide through. Panels are absolutely
     // positioned inside it, with their width and x offset set from JS (see
-    // `layout()`), so they can animate between arrangements.
-    ".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden",
+    // `layout()`), so they can animate between arrangements. `isolation` keeps the
+    // layers they stack themselves in (see LAYER_STEP) to themselves: the region
+    // as a whole still sits under the shell's own chrome — the sticky top bar, and
+    // the nav page that slides across the body — however deep the stack gets.
+    ".s-panels": "flex:1 min-width:0 min-height:0 position:relative overflow:hidden isolation:isolate",
     ".s-panel": {
         // A panel rests at a plain `left` offset and carries no transform: a
         // transformed element is composited, which costs it subpixel text
         // antialiasing. `transform` is used only to play the enter/exit slides,
-        // where the compositing is what makes them cheap. There is deliberately
-        // no `width` transition: widths depend only on the window, change only in
-        // `.s-shell-snap` passes, and a column's content never reflows while the
-        // arrangement moves.
+        // where the compositing is what makes them cheap. There is deliberately no
+        // `width` transition: a width changes only when the window resizes or when
+        // the page itself asks for another layout, and animating one would reflow
+        // the column's content on every frame of it.
         // Every duration is `--s-panel-ms`, so a column's move, its neighbour's fade
         // and the chrome recentering around them all run as one motion. The drift
         // eases out (it should read as a slow settle) while the fade runs *linear*
@@ -144,6 +155,10 @@ A.insertGlobalCss({
         // zero, which looks like the panel vanishing rather than fading.
         // No `overflow:hidden` here: the scroll container below clips the content
         // itself, and the pair hairline sits in the gutter *outside* the panel.
+        // Layering is set from JS (`layout()` and `beginClose`) rather than left to
+        // DOM order: a closing panel is no longer part of the reactive list, so
+        // where its element sits among the live ones is Aberdeen's business, not a
+        // thing to depend on. `LAYER_*` says what the numbers mean.
         "&": "position:absolute top:0 bottom:0 left:0 display:flex flex-direction:column " +
             "visibility:visible transition: left var(--s-panel-ms) ease, transform var(--s-panel-ms) ease-out, opacity var(--s-panel-ms) linear, visibility 0s;",
         // The scroll container. Mirrors content mode's `main > .s-content`: same
@@ -163,8 +178,8 @@ A.insertGlobalCss({
         // dropped, which is what makes the panel settle instead of jumping.
         "&.s-panel-enter": "opacity:0 transition:none transform: translateX(8cqw);",
         // On its way out: fading where it stands, drifting the same short distance,
-        // and out of reach while it does. It is removed from the DOM when the fade
-        // itself ends (see `beginClose`), never part-way through it.
+        // and out of reach while it does. It leaves the DOM when the fade itself
+        // ends (see `playExit`), never part-way through it.
         "&.s-panel-closing": "opacity:0 pointer-events:none transform: translateX(8cqw);",
         // Crowded out from under the visible run. It keeps its DOM (and thus its
         // scroll position and half-typed forms), so `display:none` is out —
@@ -216,6 +231,8 @@ export class PanelController {
      */
     $state = A.proxy({ paths: [], topId: 0 });
     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;
     layoutQueued = false;
@@ -346,6 +363,9 @@ export class PanelController {
      * rule 5 promises to keep.
      */
     commit(target, nav) {
+        // The panels this commit mounts size themselves as they draw, so make them
+        // measure the shell as it is now rather than trusting the last pass's numbers.
+        this.geom = undefined;
         const existing = new Map(this.live.map((entry) => [entry.path, entry]));
         const next = [];
         for (const path of target) {
@@ -398,34 +418,53 @@ export class PanelController {
         return entry;
     }
     /**
-     * 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.
      */
     beginClose(entry) {
         entry.closing = true;
-        const el = entry.el;
-        const drop = () => {
-            if (!this.byId.has(entry.id))
-                return;
-            this.byId.delete(entry.id);
-            delete this.$ids[String(entry.id)];
-        };
-        if (el) {
-            el.classList.add("s-panel-closing");
-            el.setAttribute("inert", "");
-            el.addEventListener("transitionend", (e) => {
-                if (e.target === el && e.propertyName === "opacity")
-                    drop();
-            });
+        // Frozen one layer below where it was, which is still above everything it
+        // was covering: it fades out over the panel it uncovers, and under the one
+        // that takes its place (see LAYER_STEP). Set here, while the element is
+        // still ours — a moment later the scope, and with it `entry.el`, is gone.
+        if (entry.el)
+            entry.el.style.zIndex = String(LAYER_STEP * this.live.indexOf(entry));
+        this.byId.delete(entry.id);
+        delete this.$ids[String(entry.id)];
+    }
+    /**
+     * 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).
+     */
+    playExit(entry, el) {
+        // Only a close is worth animating. A panel being *redrawn* (a reactive
+        // dependency in its handler) replaces its element through here too, and that
+        // one simply goes, so the new one isn't drawn over a ghost of the old.
+        if (!entry.closing) {
+            el.remove();
+            return;
         }
-        const timer = setTimeout(() => {
+        el.classList.add("s-panel-closing");
+        el.setAttribute("inert", "");
+        const drop = () => {
+            clearTimeout(timer);
             this.timers.delete(timer);
-            drop();
-        }, PANEL_MS + 80);
+            el.remove();
+        };
+        el.addEventListener("transitionend", (e) => {
+            if (e.target === el && e.propertyName === "opacity")
+                drop();
+        });
+        const timer = setTimeout(drop, PANEL_MS + 80);
         this.timers.add(timer);
     }
     // ── Navigation ─────────────────────────────────────────────────────────
@@ -576,9 +615,13 @@ export class PanelController {
      */
     drawStack() {
         const container = A("div.s-panels role=main", () => {
+            // Published before the first panel draws, rather than from the return
+            // value below: a panel sizes itself from the shell's measurements (see
+            // `measure`), and the first ones do that while this very call is still
+            // running. `A()` without arguments is "the element we're in".
+            this.containerEl = A();
             A.onEach(this.$ids, (_order, id) => this.drawPanel(Number(id)), (order, id) => [order, Number(id)]);
         });
-        this.containerEl = container;
         if (typeof ResizeObserver !== "undefined") {
             const ro = new ResizeObserver(() => this.layout());
             // The region *and* the body it sits in: the region alone misses a shell
@@ -597,7 +640,30 @@ export class PanelController {
         const entry = this.byId.get(id);
         if (!entry)
             return;
-        const el = A("section.s-panel", () => {
+        let el;
+        // How much room the panel wants, resolved *before* its content is drawn: an
+        // element that arrives without a width has no box for its content to measure
+        // itself against until the next frame's layout pass, which is a frame too
+        // late for anything that sizes itself from its container. So the panel is
+        // created at the width the window gives its layout — "medium" until the page
+        // says otherwise. Reactively, too: a page that changes its mind later (when
+        // its data arrives, say) reflows in place rather than being redrawn, and the
+        // columns beside it slide over to make room.
+        A(() => {
+            const asked = entry.$page.layout;
+            entry.layout = asked === "small" || asked === "large" ? asked : "medium";
+            const width = this.roomFor(entry.layout);
+            if (!width)
+                return;
+            entry.width = width;
+            // The first run has no element to put it on yet — it's created with this
+            // width, just below. Later runs are the page changing its layout.
+            if (!el)
+                return;
+            el.style.width = `${width}px`;
+            this.scheduleLayout();
+        });
+        el = A(`section.s-panel${entry.width ? ` w:${entry.width}px` : ""}`, "destroy=", (node) => this.playExit(entry, node), () => {
             const contentEl = A("div.s-content", () => {
                 entry.draw(entry.$page);
                 // After the content, so there is something to scroll when restoring.
@@ -613,17 +679,12 @@ export class PanelController {
                 A("div.s-panel-loading aria-hidden=true", () => { A("i"); A("i"); A("i"); });
             });
         });
-        // How much room the panel wants, settled right after its handler's
-        // synchronous run — deliberately once: a column that changed its mind
-        // later would reflow itself and shove its neighbours around.
-        const asked = A.peek(entry.$page, "layout");
-        entry.layout = asked === "small" || asked === "large" ? asked : "medium";
         entry.el = el;
-        // Nothing animates from the arbitrary initial position; `layout()` gives
-        // the panel its real geometry (and turns transitions back on) in the
-        // upcoming frame, before anything is painted. A redraw (a reactive
-        // dependency inside the handler) lands here too, with a brand-new element
-        // that has to be placed again before it may animate.
+        // It has its width, but nothing animates from the arbitrary initial spot;
+        // `layout()` gives the panel its place in the run (and turns transitions
+        // back on) in the upcoming frame, before anything is painted. A redraw (a
+        // reactive dependency inside the handler) lands here too, with a brand-new
+        // element that has to be placed again before it may animate.
         entry.placed = false;
         el.style.transition = "none";
         A.clean(() => { if (entry.el === el)
@@ -645,6 +706,65 @@ export class PanelController {
             this.layout();
         });
     }
+    /**
+     * 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.
+     */
+    measure() {
+        const container = this.containerEl;
+        const inner = container?.parentElement;
+        const body = inner?.parentElement;
+        if (!container || !inner || !body)
+            return undefined;
+        const total = body.getBoundingClientRect().width;
+        if (!total)
+            return undefined;
+        // Everything that sits beside the columns: the sidebar and its hairline,
+        // either of which may be display:none on a narrow shell.
+        let chrome = 0;
+        for (const child of inner.children) {
+            if (child !== container)
+                chrome += child.getBoundingClientRect().width;
+        }
+        // The standard page 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:
+        // - "medium" fills the standard content area exactly;
+        // - "small" is half of it (minus the gutter) whenever that half is still
+        //   a usable column, and the whole of it on narrower screens;
+        // - "large" ignores the standard width and takes everything the window
+        //   has — which also means nothing ever fits beside it.
+        const medium = Math.max(0, Math.min(SHELL_PX, total) - chrome);
+        const half = (medium - GUTTER_PX) / 2;
+        return {
+            total,
+            chrome,
+            small: half >= PAIR_MIN_PX ? half : medium,
+            medium,
+            large: Math.max(0, total - chrome),
+        };
+    }
+    /**
+     * 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.
+     */
+    geometry() {
+        return (this.geom ??= this.measure());
+    }
+    /** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+    roomFor(layout) {
+        return this.geometry()?.[layout] ?? 0;
+    }
     /**
      * Size and position every panel, and publish the width of the whole ensemble
      * (sidebar + separator + columns) for the shell to centre itself on.
@@ -655,10 +775,8 @@ export class PanelController {
      */
     layout() {
         const container = this.containerEl;
-        const inner = container?.parentElement;
-        const body = inner?.parentElement;
         const shell = container?.closest(".s-main");
-        if (!container || !inner || !body || !shell)
+        if (!container || !shell)
             return;
         const n = this.live.length;
         // A panel that hasn't drawn yet has no width to contribute, which would make
@@ -666,45 +784,22 @@ export class PanelController {
         // Every mount schedules another pass, so simply wait for it.
         if (!n || this.live.some((entry) => !entry.el))
             return;
-        // Measured on the *shell*, not on the region: the region's width is this
-        // function'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.
-        const total = body.getBoundingClientRect().width;
-        if (!total)
+        // This pass measures afresh — it is the one thing that runs after a resize.
+        this.geom = undefined;
+        const geom = this.geometry();
+        if (!geom)
             return;
         const stacking = this.opts.stacking !== false;
         // 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.
         // `.s-shell-snap` suppresses every standing transition for this one pass.
-        const snap = this.lastBodyW !== total;
+        const snap = this.lastBodyW !== geom.total;
         if (snap) {
-            this.lastBodyW = total;
+            this.lastBodyW = geom.total;
             shell.classList.add("s-shell-snap");
         }
-        // Everything that sits beside the columns: the sidebar and its hairline,
-        // either of which may be display:none on a narrow shell.
-        let chrome = 0;
-        for (const child of inner.children) {
-            if (child !== container)
-                chrome += child.getBoundingClientRect().width;
-        }
-        // The standard page 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 above) changes them:
-        // - "medium" fills the standard content area exactly;
-        // - "small" is half of it (minus the gutter) whenever that half is still
-        //   a usable column, and the whole of it on narrower screens;
-        // - "large" ignores the standard width and takes everything the window
-        //   has — which also means nothing ever fits beside it.
-        const stdRoom = Math.max(0, Math.min(SHELL_PX, total) - chrome);
-        const fullRoom = Math.max(0, total - chrome);
-        const halfW = (stdRoom - GUTTER_PX) / 2;
-        const smallW = halfW >= PAIR_MIN_PX ? halfW : stdRoom;
-        const width = (entry) => entry.layout === "small" ? smallW : entry.layout === "large" ? fullRoom : stdRoom;
+        const width = (entry) => geom[entry.layout];
         // The visible run: as many top-of-stack panels as the window fits, at the
         // sizes the window gives them. The top panel always shows.
         let first = n - 1;
@@ -712,7 +807,7 @@ export class PanelController {
         if (stacking) {
             for (let i = n - 2; i >= 0; i--) {
                 const sum = runSum + GUTTER_PX + width(this.live[i]);
-                if (sum > fullRoom)
+                if (sum > geom.large)
                     break;
                 runSum = sum;
                 first = i;
@@ -724,7 +819,7 @@ export class PanelController {
         // wider than the window. So the page is the familiar 1280px until extra
         // columns genuinely fit, and stretches — centred — to hold the ones that
         // do; with a "large" up that's the window's edges.
-        const area = Math.min(fullRoom, Math.max(stdRoom, runSum));
+        const area = Math.min(geom.large, Math.max(geom.medium, runSum));
         for (let i = first; i < n; i++)
             this.live[i].width = width(this.live[i]);
         // Panels that have never been visible get their would-be width too, so a
@@ -738,7 +833,7 @@ export class PanelController {
         // The consumers transition their max-width (see main.ts), so the
         // recentring plays along with the panel that caused it instead of
         // snapping.
-        shell.style.setProperty("--s-shell-w", `${chrome + area}px`);
+        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
         // mounted ones still have transitions switched off, so what we set here is
@@ -750,8 +845,10 @@ export class PanelController {
             const el = entry.el;
             const shown = i >= first;
             // Visible panels are left-aligned in the content area, a gutter apart;
-            // hidden ones park at its left edge, keeping their last width.
-            place(el, shown ? x : 0, entry.width);
+            // hidden ones park at its left edge, keeping their last width. Deeper
+            // panels layer over shallower ones, each on the odd layer for its depth
+            // (see LAYER_STEP).
+            place(el, shown ? x : 0, entry.width, LAYER_STEP * i + 1);
             if (shown)
                 x += entry.width + GUTTER_PX;
             el.classList.toggle("s-panel-sep", shown && i > first);
@@ -805,10 +902,11 @@ export class PanelController {
         this.timers.add(timer);
     }
 }
-/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide. */
-function place(el, x, width) {
+/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide, on layer `z`. */
+function place(el, x, width, z) {
     el.style.left = `${x}px`;
     el.style.width = `${width}px`;
+    el.style.zIndex = String(z);
 }
 // ─── Guards ──────────────────────────────────────────────────────────────────
 /**