modal_stack 0.3.0 → 0.4.2

data/app/javascript/modal_stack/runtime.js

@@ -1,8 +1,14 @@
 export const SNAPSHOT_KEY = "modalStackSnapshot";
+export const FRAME_HTML_KEY = "modalStackFrameHtml";
 export const FRAGMENT_HEADER = "X-Modal-Stack-Request";
+// Server response header that flags the just-rendered frame as stale —
+// the runtime will refetch instead of restoring from the in-memory cache
+// when the user steps back to it.
+export const STALE_HEADER = "X-Modal-Stack-Stale";
 export const SCROLLBAR_WIDTH_VAR = "--modal-stack-scrollbar-width";
 
 const LAYER_SELECTOR = '[data-modal-stack-target="layer"]';
+const FRAME_SELECTOR = "[data-modal-stack-frame]";
 // CSS variable host stylesheets set to declare their leave-transition
 // duration (e.g. "220ms"). When present, the runtime sizes its safety
 // timeout from this value; otherwise it falls back to a conservative cap.
@@ -22,11 +28,17 @@ const LEAVE_TIMEOUT_FALLBACK_MS = 600;
  * `orchestrator.test.js` for an in-memory fake).
  */
 export class BrowserRuntime {
+  // Counter: incremented per historyBack call, decremented per Turbo visit
+  // cancelled. Guards every popstate that lands on a Turbo-owned entry.
+  #suppressTurboVisitCount = 0;
+  #suppressTurboVisitTimer = null;
+
   /**
    * @param {Object} options
    * @param {HTMLDialogElement} options.dialog
    * @param {HTMLElement} [options.body]
    * @param {History} [options.history]
+   * @param {Location} [options.location]
    * @param {typeof fetch} [options.fetcher]
    * @param {Storage} [options.store]
    * @param {Document} [options.documentRef]
@@ -35,6 +47,7 @@ export class BrowserRuntime {
     dialog,
     body = globalThis.document?.body,
     history = globalThis.history,
+    location = globalThis.location,
     fetcher = globalThis.fetch?.bind(globalThis),
     store = globalThis.sessionStorage,
     documentRef = globalThis.document,
@@ -45,9 +58,52 @@ export class BrowserRuntime {
     this.dialog = dialog;
     this.body = body;
     this.history = history;
+    this.location = location;
     this.fetcher = fetcher;
     this.store = store;
     this.document = documentRef;
+    // Cached DocumentFragments for path frames, keyed by `${layerId}#${frameIndex}`.
+    // Populated by mountFrame on the way forward, drained by unmountFrame on
+    // the way back, purged on layer teardown via clearFrameCache.
+    this._frameCache = new Map();
+
+    // When our historyBack() navigates back to the original page-load history
+    // entry, that entry carries Turbo's restorationIdentifier. Turbo sees it on
+    // popstate and starts a restoration visit which replaces the body — including
+    // restoring a cached snapshot that had data-modal-stack-locked baked in,
+    // leaving the page scroll-locked after the modal closes.
+    //
+    // We intercept turbo:before-visit and cancel the *one* restoration triggered
+    // by our own historyBack. The flag is armed in historyBack and consumed (or
+    // timed out) immediately so it cannot suppress a user-initiated navigation.
+    this.#suppressTurboVisitCount = 0;
+    this._turboVisitGuard = (event) => {
+      if (this.#suppressTurboVisitCount <= 0) return;
+      this.#suppressTurboVisitCount -= 1;
+      if (this.#suppressTurboVisitCount === 0) clearTimeout(this.#suppressTurboVisitTimer);
+      event.preventDefault();
+    };
+    documentRef.addEventListener?.("turbo:before-visit", this._turboVisitGuard);
+
+    // Turbo caches a page snapshot before navigating away. If the modal is
+    // open at cache time, data-modal-stack-locked is baked into the snapshot.
+    // When Turbo later restores or morphs from that snapshot, the attribute
+    // is re-applied to body, leaving the page scroll-locked even though no
+    // modal is open. Stripping the lock before cache keeps snapshots clean.
+    this._turboBeforeCache = () => {
+      if (!this.body) return;
+      delete this.body.dataset.modalStackLocked;
+      const root = this.document?.documentElement;
+      if (root) root.style.removeProperty(SCROLLBAR_WIDTH_VAR);
+    };
+    documentRef.addEventListener?.("turbo:before-cache", this._turboBeforeCache);
+  }
+
+  // Called by the Stimulus controller on disconnect so the global listener
+  // is cleaned up if the element leaves the DOM (e.g. full page navigation).
+  destroy() {
+    this.document?.removeEventListener?.("turbo:before-visit", this._turboVisitGuard);
+    this.document?.removeEventListener?.("turbo:before-cache", this._turboBeforeCache);
   }
 
   showDialog() {
@@ -93,7 +149,10 @@ export class BrowserRuntime {
     const frag = await this.#resolveFragment({ url, html, fragment });
     const layer = this.document.createElement("div");
     this.#applyLayerAttrs(layer, { layerId, depth, variant, dismissible, size, side, width, height });
-    layer.append(...frag.childNodes);
+    this.#applyFrameDepth(layer, 0);
+    const wrapper = this.#createFrameWrapper({ frameIndex: 0 });
+    wrapper.append(...frag.childNodes);
+    layer.appendChild(wrapper);
     this.dialog.appendChild(layer);
   }
 
@@ -102,7 +161,108 @@ export class BrowserRuntime {
     const layer = this.#topLayer();
     if (!layer) return;
     this.#applyLayerAttrs(layer, { layerId, depth, variant, dismissible, size, side, width, height });
-    layer.replaceChildren(...frag.childNodes);
+    this.#applyFrameDepth(layer, 0);
+    const wrapper = this.#createFrameWrapper({ frameIndex: 0 });
+    wrapper.append(...frag.childNodes);
+    layer.replaceChildren(wrapper);
+  }
+
+  async mountFrame({ layerId, fromFrameIndex, toFrameIndex, url, html, fragment, transition }) {
+    const layer = this.#findLayer(layerId);
+    if (!layer) return;
+    const frag = await this.#resolveFragment({ url, html, fragment });
+
+    // Snapshot the outgoing frame's children for back navigation. We cache
+    // the original nodes (not clones) and detach them from the DOM — the
+    // animateOut below operates on the wrapper, which we'll throw away.
+    const oldFrame = this.#findFrame(layer, fromFrameIndex);
+    if (oldFrame) {
+      // Fire before detach so listeners can still read live form values.
+      this.#dispatchFrameEvent("modal_stack:frame-leave", {
+        layerId, frameIndex: fromFrameIndex, direction: "forward",
+      });
+      const cached = this.document.createDocumentFragment();
+      cached.append(...oldFrame.childNodes);
+      this._frameCache.set(this.#frameKey(layerId, fromFrameIndex), cached);
+    }
+
+    const newFrame = this.#createFrameWrapper({ frameIndex: toFrameIndex, transition, direction: "forward" });
+    newFrame.append(...frag.childNodes);
+    layer.appendChild(newFrame);
+    this.#applyFrameDepth(layer, toFrameIndex);
+
+    // Persist the incoming frame's HTML so it can be restored across page
+    // reloads. Frame 0 is always the layer's initial mount (accessible via
+    // GET); frames 1+ may be POST-only wizard steps that 404 on direct fetch.
+    if (toFrameIndex > 0) {
+      this.#persistFrameHtml(layerId, toFrameIndex, newFrame.innerHTML);
+    }
+
+    // Old frame is removed synchronously. Entering frames carry
+    // data-transition + data-direction so host CSS can drive the *enter*
+    // animation via @starting-style; the leaving frame would need its own
+    // overlapping layout (e.g. position: absolute) to also animate out,
+    // which we leave to the host CSS preset.
+    if (oldFrame) oldFrame.remove();
+
+    // Fire after mount so listeners can read/populate the new frame's DOM.
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId, frameIndex: toFrameIndex, direction: "forward",
+    });
+
+    // Remove transition attrs once the animation completes so the :has()
+    // rule that clips overflow doesn't persist indefinitely.
+    if (transition) this.#cleanupFrameTransition(newFrame);
+  }
+
+  async unmountFrame({ layerId, fromFrameIndex, toFrameIndex, url, stale, transition }) {
+    const layer = this.#findLayer(layerId);
+    if (!layer) return;
+
+    // Fire before detach so listeners can still read live form values.
+    this.#dispatchFrameEvent("modal_stack:frame-leave", {
+      layerId, frameIndex: fromFrameIndex, direction: "back",
+    });
+
+    const cacheKey = this.#frameKey(layerId, toFrameIndex);
+    let restored = stale ? null : this._frameCache.get(cacheKey) ?? null;
+    if (!restored) {
+      const result = await this.fetchFragment(url);
+      restored = result.fragment;
+      this._frameCache.set(cacheKey, cloneFragment(restored, this.document));
+    } else {
+      // Clone so the cache entry remains usable if we step back here again
+      // after another forward.
+      restored = cloneFragment(restored, this.document);
+    }
+
+    const newFrame = this.#createFrameWrapper({ frameIndex: toFrameIndex, transition, direction: "back" });
+    newFrame.append(...restored.childNodes);
+    layer.appendChild(newFrame);
+    this.#applyFrameDepth(layer, toFrameIndex);
+
+    // Drop cache entries for frames that are now gone (anything past the
+    // restored index — we only keep entries for frames still tracked in
+    // state).
+    this.#purgeFrameCacheAbove(layerId, toFrameIndex);
+
+    const oldFrame = this.#findFrame(layer, fromFrameIndex);
+    if (oldFrame) oldFrame.remove();
+
+    // Fire after mount so listeners can restore data into the returned frame.
+    this.#dispatchFrameEvent("modal_stack:frame-enter", {
+      layerId, frameIndex: toFrameIndex, direction: "back",
+    });
+
+    if (transition) this.#cleanupFrameTransition(newFrame);
+  }
+
+  clearFrameCache({ layerId }) {
+    const prefix = `${layerId}#`;
+    for (const key of [...this._frameCache.keys()]) {
+      if (key.startsWith(prefix)) this._frameCache.delete(key);
+    }
+    this.#removeFrameHtmlForLayer(layerId);
   }
 
   async unmountTopLayer() {
@@ -117,15 +277,25 @@ export class BrowserRuntime {
     await Promise.all(layers.map((l) => animateOut(l, timeout)));
   }
 
-  pushHistory({ url, historyState }) {
-    this.history.pushState(historyState, "", url);
+  pushHistory({ historyState }) {
+    this.history.pushState(historyState, "", this.location?.href ?? "");
   }
 
-  replaceHistory({ url, historyState }) {
-    this.history.replaceState(historyState, "", url);
+  replaceHistory({ historyState }) {
+    this.history.replaceState(historyState, "", this.location?.href ?? "");
   }
 
   historyBack({ n }) {
+    // Arm the guard before calling history.go so turbo:before-visit (which
+    // fires synchronously inside Turbo's popstate handler) can cancel the
+    // restoration visit. A safety timeout clears the flag if the popstate
+    // never triggers a Turbo visit (i.e. we landed on one of our own phantom
+    // entries that lack Turbo's restorationIdentifier).
+    this.#suppressTurboVisitCount += 1;
+    clearTimeout(this.#suppressTurboVisitTimer);
+    this.#suppressTurboVisitTimer = setTimeout(() => {
+      this.#suppressTurboVisitCount = 0;
+    }, 1000);
     this.history.go(-n);
   }
 
@@ -149,6 +319,7 @@ export class BrowserRuntime {
     if (!this.store) return;
     try {
       this.store.removeItem(SNAPSHOT_KEY);
+      this.store.removeItem(FRAME_HTML_KEY);
     } catch {
       // ignore
     }
@@ -163,6 +334,60 @@ export class BrowserRuntime {
     }
   }
 
+  // Preloads _frameCache from sessionStorage so wizard frames saved across
+  // reloads can be restored via pathTo without re-fetching their URLs.
+  restoreFrameCacheFromStorage() {
+    const map = this.#readFrameHtmlMap();
+    for (const [key, html] of Object.entries(map)) {
+      this._frameCache.set(key, parseFragment(html, this.document));
+    }
+  }
+
+  // Returns the cached fragment for a specific frame (used during restoration).
+  getFrameFragment(layerId, frameIndex) {
+    return this._frameCache.get(this.#frameKey(layerId, frameIndex)) ?? null;
+  }
+
+  #persistFrameHtml(layerId, frameIndex, html) {
+    if (!this.store) return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      map[`${layerId}#${frameIndex}`] = html;
+      this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+    } catch {
+      // sessionStorage full or unavailable — best effort
+    }
+  }
+
+  #readFrameHtmlMap() {
+    try {
+      const raw = this.store?.getItem(FRAME_HTML_KEY);
+      return raw ? JSON.parse(raw) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  #removeFrameHtmlForLayer(layerId) {
+    if (!this.store) return;
+    try {
+      const map = this.#readFrameHtmlMap();
+      const prefix = `${layerId}#`;
+      let changed = false;
+      for (const key of Object.keys(map)) {
+        if (key.startsWith(prefix)) { delete map[key]; changed = true; }
+      }
+      if (!changed) return;
+      if (Object.keys(map).length === 0) {
+        this.store.removeItem(FRAME_HTML_KEY);
+      } else {
+        this.store.setItem(FRAME_HTML_KEY, JSON.stringify(map));
+      }
+    } catch {
+      // ignore
+    }
+  }
+
   // Reads --modal-stack-duration from the dialog's computed style and
   // returns 1.5× that as the safety timeout (in ms). Cached after the
   // first successful read since the variable is host-CSS-defined and
@@ -197,6 +422,63 @@ export class BrowserRuntime {
     );
   }
 
+  #findFrame(layer, frameIndex) {
+    return layer.querySelector(
+      `${FRAME_SELECTOR}[data-frame-index="${escapeAttr(String(frameIndex))}"]`,
+    );
+  }
+
+  #frameKey(layerId, frameIndex) {
+    return `${layerId}#${frameIndex}`;
+  }
+
+  #dispatchFrameEvent(name, detail) {
+    this.dialog.dispatchEvent(
+      new CustomEvent(name, { bubbles: true, detail }),
+    );
+  }
+
+  #purgeFrameCacheAbove(layerId, frameIndex) {
+    const prefix = `${layerId}#`;
+    for (const key of [...this._frameCache.keys()]) {
+      if (!key.startsWith(prefix)) continue;
+      const idx = Number(key.slice(prefix.length));
+      if (Number.isFinite(idx) && idx > frameIndex) {
+        this._frameCache.delete(key);
+      }
+    }
+  }
+
+  // Removes [data-transition] and [data-direction] from a frame once its
+  // enter animation ends. This restores overflow-y:auto on the layer (the
+  // :has([data-transition]) rule in the CSS preset keeps overflow:hidden
+  // while the animation runs to clip off-screen slide frames).
+  #cleanupFrameTransition(frameEl) {
+    let done = false;
+    const cleanup = () => {
+      if (done) return;
+      done = true;
+      frameEl.removeAttribute("data-transition");
+      frameEl.removeAttribute("data-direction");
+    };
+    frameEl.addEventListener("transitionend", cleanup, { once: true });
+    setTimeout(cleanup, this.#leaveTimeoutMs());
+  }
+
+  #createFrameWrapper({ frameIndex, transition = null, direction = null }) {
+    const el = this.document.createElement("div");
+    el.dataset.modalStackFrame = "";
+    el.dataset.frameIndex = String(frameIndex);
+    if (transition) el.dataset.transition = transition;
+    if (direction) el.dataset.direction = direction;
+    return el;
+  }
+
+  #applyFrameDepth(layer, topFrameIndex) {
+    layer.dataset.frameIndex = String(topFrameIndex);
+    layer.dataset.frameDepth = String(topFrameIndex + 1);
+  }
+
   #topLayer() {
     const layers = this.dialog.querySelectorAll(LAYER_SELECTOR);
     return layers[layers.length - 1] ?? null;
@@ -241,13 +523,15 @@ export class BrowserRuntime {
       throw new Error(`modal_stack: fetch ${url} → ${resp.status}`);
     }
     const html = await resp.text();
-    return parseFragment(html, this.document);
+    const stale = parseStaleHeader(resp);
+    return { fragment: parseFragment(html, this.document), stale };
   }
 
   async #resolveFragment({ url, html, fragment }) {
     if (fragment) return fragment;
     if (html != null) return parseFragment(html, this.document);
-    return this.fetchFragment(url);
+    const result = await this.fetchFragment(url);
+    return result.fragment;
   }
 }
 
@@ -259,6 +543,28 @@ function parseFragment(html, doc) {
   return fragment;
 }
 
+function parseStaleHeader(resp) {
+  const headers = resp?.headers;
+  const value =
+    typeof headers?.get === "function"
+      ? headers.get(STALE_HEADER) ?? headers.get(STALE_HEADER.toLowerCase())
+      : null;
+  if (!value) return false;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "true" || normalized === "1";
+}
+
+function cloneFragment(fragment, doc) {
+  if (typeof fragment?.cloneNode === "function") {
+    return fragment.cloneNode(true);
+  }
+  const clone = doc.createDocumentFragment();
+  if (fragment?.childNodes) {
+    for (const node of fragment.childNodes) clone.appendChild(node.cloneNode(true));
+  }
+  return clone;
+}
+
 // Marks the layer with [data-leaving] so the host CSS can transition it
 // out, then awaits transitionend (with a hard timeout) before removing
 // the element from the DOM.  If the host CSS doesn't define an exit
@@ -294,5 +600,6 @@ function escapeAttr(value) {
   if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
     return CSS.escape(value);
   }
-  return String(value).replace(/["\\]/g, "\\$&");
+  // Fallback: escape chars that break CSS attribute selectors ([attr="val"])
+  return String(value).replace(/["\\[\]]/g, "\\$&");
 }

data/app/javascript/modal_stack/runtime.test.js

@@ -4,6 +4,7 @@ import {
   FRAGMENT_HEADER,
   SCROLLBAR_WIDTH_VAR,
   SNAPSHOT_KEY,
+  STALE_HEADER,
 } from "./runtime.js";
 
 function fakeStore() {
@@ -96,20 +97,21 @@ describe("snapshot storage", () => {
 });
 
 describe("history wiring", () => {
-  test("pushHistory / replaceHistory / historyBack delegate to history", () => {
+  test("pushHistory / replaceHistory always use current location.href, ignoring the modal url", () => {
     const calls = [];
     const history = {
       pushState: (s, t, u) => calls.push(["push", s, t, u]),
       replaceState: (s, t, u) => calls.push(["replace", s, t, u]),
       go: (n) => calls.push(["go", n]),
     };
-    const rt = new BrowserRuntime(noopRuntimeArgs({ history }));
-    rt.pushHistory({ url: "/a", historyState: { x: 1 } });
-    rt.replaceHistory({ url: "/b", historyState: { y: 2 } });
+    const location = { href: "http://example.com/origin" };
+    const rt = new BrowserRuntime(noopRuntimeArgs({ history, location }));
+    rt.pushHistory({ url: "/modal-a", historyState: { x: 1 } });
+    rt.replaceHistory({ url: "/modal-b", historyState: { y: 2 } });
     rt.historyBack({ n: 3 });
     expect(calls).toEqual([
-      ["push", { x: 1 }, "", "/a"],
-      ["replace", { y: 2 }, "", "/b"],
+      ["push", { x: 1 }, "", "http://example.com/origin"],
+      ["replace", { y: 2 }, "", "http://example.com/origin"],
       ["go", -3],
     ]);
   });
@@ -268,4 +270,86 @@ describe("fetch headers", () => {
     expect(captured.opts.headers.Accept).toContain("text/html");
     expect(captured.opts.credentials).toBe("same-origin");
   });
+
+  test("fetchFragment returns { fragment, stale } from response header", async () => {
+    withFakeDOMParser(async () => {
+      const fetcher = () =>
+        Promise.resolve(
+          new Response("<p>frame</p>", {
+            status: 200,
+            headers: { [STALE_HEADER]: "true" },
+          }),
+        );
+      const documentRef = fakeDocument();
+      const rt = new BrowserRuntime(noopRuntimeArgs({ fetcher, documentRef }));
+      const result = await rt.fetchFragment("/x");
+      expect(result.stale).toBe(true);
+      expect(result.fragment).toBeTruthy();
+    });
+  });
+
+  test("fetchFragment.stale is false when header is missing or '0'", async () => {
+    await withFakeDOMParser(async () => {
+      const cases = [
+        new Response("", { status: 200 }),
+        new Response("", { status: 200, headers: { [STALE_HEADER]: "0" } }),
+        new Response("", { status: 200, headers: { [STALE_HEADER]: "false" } }),
+      ];
+      for (const resp of cases) {
+        const documentRef = fakeDocument();
+        const rt = new BrowserRuntime(
+          noopRuntimeArgs({ fetcher: () => Promise.resolve(resp), documentRef }),
+        );
+        const result = await rt.fetchFragment("/x");
+        expect(result.stale).toBe(false);
+      }
+    });
+  });
+});
+
+function fakeDocument() {
+  return {
+    createDocumentFragment: () => {
+      const children = [];
+      return {
+        childNodes: children,
+        append: (...nodes) => children.push(...nodes),
+        appendChild: (n) => children.push(n),
+      };
+    },
+  };
+}
+
+async function withFakeDOMParser(fn) {
+  const original = globalThis.DOMParser;
+  globalThis.DOMParser = class {
+    parseFromString() {
+      return { body: { childNodes: [] } };
+    }
+  };
+  try {
+    return await fn();
+  } finally {
+    if (original) globalThis.DOMParser = original;
+    else delete globalThis.DOMParser;
+  }
+}
+
+describe("frame cache", () => {
+  test("clearFrameCache removes only entries for the given layerId", () => {
+    const rt = new BrowserRuntime(noopRuntimeArgs());
+    rt._frameCache.set("L1#0", "a");
+    rt._frameCache.set("L1#1", "b");
+    rt._frameCache.set("L2#0", "c");
+    rt._frameCache.set("L11#0", "d"); // verify prefix is anchored on `#`
+    rt.clearFrameCache({ layerId: "L1" });
+    expect([...rt._frameCache.keys()].sort()).toEqual(["L11#0", "L2#0"]);
+  });
+
+  test("clearFrameCache is a no-op for unknown layerId", () => {
+    const rt = new BrowserRuntime(noopRuntimeArgs());
+    rt._frameCache.set("L1#0", "a");
+    rt.clearFrameCache({ layerId: "Lz" });
+    expect([...rt._frameCache.keys()]).toEqual(["L1#0"]);
+  });
 });