modal_stack 0.3.0 → 0.4.2

data/app/javascript/modal_stack/controllers/modal_stack_controller.js

@@ -1,6 +1,7 @@
 import { Controller } from "@hotwired/stimulus";
 import { Orchestrator } from "../orchestrator.js";
 import { BrowserRuntime } from "../runtime.js";
+import { restore } from "../state.js";
 
 export class ModalStackController extends Controller {
   static values = {
@@ -10,33 +11,56 @@ export class ModalStackController extends Controller {
     maxDepthStrategy: { type: String, default: "warn" },
   };
 
+  #restoring = false;
+
   connect() {
-    const stackId = this.stackIdValue || generateLayerId();
     const baseUrl = this.baseUrlValue || window.location.href;
 
     this.runtime = new BrowserRuntime({ dialog: this.element });
-    const snapshot = this.runtime.readSnapshot();
+    // Restore frame HTML cache before reading snapshot so wizard frames
+    // saved in sessionStorage are available during #restoreSnapshot.
+    this.runtime.restoreFrameCacheFromStorage();
+    const savedSnapshot = this.runtime.readSnapshot();
+
+    // Peek at the snapshot (without stackId filter) to reuse the saved
+    // stackId across page reloads — otherwise a randomly generated stackId
+    // would never match the one saved in sessionStorage.
+    const snapshotState = savedSnapshot ? restore(savedSnapshot) : null;
+    const stackId =
+      this.stackIdValue || snapshotState?.stackId || generateLayerId();
 
     this.orchestrator = new Orchestrator({
       runtime: this.runtime,
       stackId,
       baseUrl,
-      restoreFrom: snapshot,
+      // Restoration is handled below via push() so each layer gets a
+      // phantom history entry and the back button closes them one by one.
+      restoreFrom: null,
       // Stimulus Number values default to 0, but state.js treats null as
       // "no cap" — so map 0/missing to null here.
       maxDepth: this.maxDepthValue > 0 ? this.maxDepthValue : null,
       maxDepthStrategy: this.maxDepthStrategyValue || "warn",
     });
 
-    this._onPopstate = (event) =>
+    this._onPopstate = (event) => {
+      // Run in capture phase so we fire before Turbo's bubble-phase popstate
+      // handler. When the popstate was triggered by our own historyBack
+      // (expectedPopstates > 0), stop propagation immediately after processing
+      // so Turbo never sees the event and cannot start a restoration visit
+      // (which shows the loading bar and replaces the body).
+      const isOwn = this.orchestrator.expectedPopstates > 0;
       this.orchestrator.onPopstate({
         historyState: event.state,
         locationHref: window.location.href,
       });
-    window.addEventListener("popstate", this._onPopstate);
+      if (isOwn) event.stopImmediatePropagation();
+    };
+    window.addEventListener("popstate", this._onPopstate, true);
 
     this._onCancel = (event) => {
       event.preventDefault();
+      if (!this.element.open) return;
+      if (this.#restoring) return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false) return;
       this.orchestrator.pop();
@@ -45,22 +69,98 @@ export class ModalStackController extends Controller {
 
     this._onBackdropClick = (event) => {
       if (event.target !== this.element) return;
+      if (!this.element.open) return;
+      if (this.#restoring) return;
       const top = this.#topLayer();
       if (!top || top.dismissible === false) return;
       this.orchestrator.pop();
     };
     this.element.addEventListener("click", this._onBackdropClick);
 
+    // After any Turbo render (restoration, morph, stream-driven page update),
+    // re-check scroll lock. A snapshot cached while a modal was open can
+    // restore data-modal-stack-locked on body even after the modal has closed.
+    // turbo:before-cache strips the attribute before caching; this is the
+    // safety net for renders that fire from an already-stale cache.
+    this._onTurboRender = () => {
+      if (this.orchestrator.depth === 0) this.runtime.unlockScroll();
+    };
+    document.addEventListener("turbo:render", this._onTurboRender);
+
     this.#registerStreamActions();
+
+    if (snapshotState?.layers?.length > 0) {
+      this.#restoring = true;
+      this.#restoreSnapshot(snapshotState.layers)
+        .catch((err) =>
+          console.warn("[modal_stack] snapshot restore failed:", err),
+        )
+        .finally(() => {
+          this.#restoring = false;
+        });
+    }
+
     this.element.dispatchEvent(
-      new CustomEvent("modal_stack:ready", { bubbles: true, detail: { stackId } }),
+      new CustomEvent("modal_stack:ready", {
+        bubbles: true,
+        detail: { stackId },
+      }),
     );
   }
 
+  async #restoreSnapshot(layers) {
+    // Always open each layer from its first frame URL (accessible via GET).
+    const baseUrls = layers.map((l) => l.frames?.[0]?.url ?? l.url);
+
+    // Pre-fetch base frames in parallel so the push loop runs without any
+    // network await between iterations, eliminating the race window where
+    // Escape fires while this.state lags behind (only partial stack).
+    const baseFragments = await Promise.all(
+      baseUrls.map((url) => this.orchestrator.prefetch(url).catch(() => null)),
+    );
+
+    for (let i = 0; i < layers.length; i++) {
+      const layer = layers[i];
+      await this.orchestrator.push(
+        {
+          id: layer.id,
+          url: baseUrls[i],
+          variant: layer.variant,
+          dismissible: layer.dismissible,
+          size: layer.size,
+          side: layer.side,
+          width: layer.width,
+          height: layer.height,
+        },
+        { fragment: baseFragments[i] },
+      );
+
+      // Restore additional wizard frames using HTML saved to sessionStorage
+      // on the previous visit. Each frame may be a POST-only step that 404s
+      // on a direct GET — we use the cached HTML instead of re-fetching.
+      const extraFrames = (layer.frames ?? []).slice(1);
+      for (let fi = 0; fi < extraFrames.length; fi++) {
+        const frame = extraFrames[fi];
+        const frameIndex = fi + 1;
+        const cached = this.runtime.getFrameFragment(layer.id, frameIndex);
+        if (!cached) break; // Can't restore beyond this frame — stop here
+        // Warm the orchestrator's fragment cache so forward re-navigation
+        // after a back doesn't attempt a failing GET for this URL.
+        this.orchestrator.setFragmentCache(frame.url, cached.cloneNode(true));
+        await this.orchestrator.pathTo(
+          { url: frame.url, stale: frame.stale },
+          { fragment: cached.cloneNode(true) },
+        );
+      }
+    }
+  }
+
   disconnect() {
-    window.removeEventListener("popstate", this._onPopstate);
+    window.removeEventListener("popstate", this._onPopstate, true);
     this.element.removeEventListener("cancel", this._onCancel);
     this.element.removeEventListener("click", this._onBackdropClick);
+    document.removeEventListener("turbo:render", this._onTurboRender);
+    this.runtime.destroy?.();
   }
 
   push(layer, opts) {
@@ -83,6 +183,17 @@ export class ModalStackController extends Controller {
     return this.orchestrator.prefetch(url);
   }
 
+  // Stimulus action — wire up via data-action="click->modal-stack#pathBack"
+  // on any button/link inside a modal panel.
+  pathBack(event) {
+    if (event) {
+      event.preventDefault();
+      event.stopPropagation();
+    }
+    const steps = readSteps(event);
+    return this.orchestrator.pathBack({ steps });
+  }
+
   #topLayer() {
     const layers = this.orchestrator.layers;
     return layers[layers.length - 1] ?? null;
@@ -136,6 +247,21 @@ export class ModalStackController extends Controller {
     StreamActions.modal_close_all = guarded("modal_close_all", function (orch) {
       return orch.closeAll();
     });
+
+    StreamActions.modal_path_to = guarded("modal_path_to", function (orch) {
+      return orch.pathTo(frameFromStreamElement(this), {
+        fragment: this.templateContent.cloneNode(true),
+        transition: this.dataset.transition || null,
+      });
+    });
+
+    StreamActions.modal_path_back = guarded("modal_path_back", function (orch) {
+      const steps = parsePositiveInt(this.dataset.steps, 1);
+      return orch.pathBack({
+        steps,
+        transition: this.dataset.transition || null,
+      });
+    });
   }
 }
 
@@ -181,8 +307,35 @@ function layerPatchFromStreamElement(el) {
 }
 
 function generateLayerId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
     return crypto.randomUUID();
   }
   return `ms-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 }
+
+function frameFromStreamElement(el) {
+  return {
+    url: el.dataset.url || window.location.href,
+    stale: el.dataset.stale === "true" || el.dataset.stale === "1",
+  };
+}
+
+function parsePositiveInt(raw, fallback) {
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+// Steps for pathBack come from either Stimulus action params
+// (data-modal-stack-steps-param) or a plain data-steps attribute on
+// the action target, e.g. <button data-modal-stack-steps-param="2">.
+function readSteps(event) {
+  const params = event?.params;
+  if (params && Number.isFinite(params.steps) && params.steps > 0) {
+    return params.steps;
+  }
+  const target = event?.currentTarget ?? event?.target;
+  return parsePositiveInt(target?.dataset?.steps, 1);
+}

data/app/javascript/modal_stack/install.js

@@ -1,3 +1,4 @@
+import { ModalStackBackLinkController } from "./controllers/modal_stack_back_link_controller.js";
 import { ModalStackController } from "./controllers/modal_stack_controller.js";
 import { ModalStackLinkController } from "./controllers/modal_stack_link_controller.js";
 
@@ -9,7 +10,12 @@ export function install(application) {
   }
   application.register("modal-stack", ModalStackController);
   application.register("modal-stack-link", ModalStackLinkController);
+  application.register("modal-stack-back-link", ModalStackBackLinkController);
   return application;
 }
 
-export { ModalStackController, ModalStackLinkController };
+export {
+  ModalStackBackLinkController,
+  ModalStackController,
+  ModalStackLinkController,
+};

data/app/javascript/modal_stack/orchestrator.js

@@ -2,6 +2,8 @@ import {
   closeAll,
   createStack,
   handlePopstate,
+  pathBack,
+  pathTo,
   pop,
   push,
   replaceTop,
@@ -69,6 +71,10 @@ export class Orchestrator {
     return this.state.layers.length;
   }
 
+  get expectedPopstates() {
+    return this.#expectedPopstates;
+  }
+
   /**
    * Push a layer. When `html`/`fragment` are absent, the orchestrator
    * pre-fetches the URL so `mountLayer` is a sync DOM append (no flash).
@@ -104,25 +110,65 @@ export class Orchestrator {
     return this.#dispatch(replaceTop(this.state, patch, opts), { html, fragment });
   }
 
+  /**
+   * Append a frame to the top layer's path.
+   * @param {{ url: string, stale?: boolean }} frame
+   * @param {{ html?: string|null, fragment?: DocumentFragment|null, transition?: string|null }} [options]
+   */
+  async pathTo(frame, { html = null, fragment = null, transition = null } = {}) {
+    let resolvedStale = frame?.stale === true;
+    if (fragment == null && html == null && frame?.url) {
+      const meta = await this.#prefetchWithMeta(frame.url);
+      fragment = meta.fragment;
+      // The caller's explicit `stale: true` always wins; if they didn't say,
+      // honor the X-Modal-Stack-Stale response header surfaced by the runtime.
+      if (frame.stale !== true && meta.stale === true) resolvedStale = true;
+    }
+    return this.#dispatch(
+      pathTo(this.state, { url: frame.url, stale: resolvedStale }, { transition }),
+      { html, fragment },
+    );
+  }
+
+  /**
+   * Step back through frames in the top layer's path.
+   * @param {{ steps?: number, transition?: string|null }} [options]
+   */
+  pathBack({ steps = 1, transition = null } = {}) {
+    return this.#dispatch(pathBack(this.state, { steps, transition }));
+  }
+
   async #prefetch(url) {
-    if (typeof this.runtime.fetchFragment !== "function") return null;
+    const meta = await this.#prefetchWithMeta(url);
+    return meta.fragment;
+  }
+
+  async #prefetchWithMeta(url) {
+    if (typeof this.runtime.fetchFragment !== "function") {
+      return { fragment: null, stale: false };
+    }
 
     const cached = this.#fragmentCache.get(url);
     if (cached && Date.now() - cached.ts < this.prefetchTtlMs) {
-      return cloneFragment(cached.fragment);
+      return { fragment: cloneFragment(cached.fragment), stale: cached.stale === true };
     }
 
     const existing = this.#inflight.get(url);
     if (existing) {
       const entry = await existing.promise;
-      return cloneFragment(entry.fragment);
+      return { fragment: cloneFragment(entry.fragment), stale: entry.stale === true };
     }
 
     const controller = supportsAbort() ? new AbortController() : null;
     const fetchPromise = this.runtime
       .fetchFragment(url, controller ? { signal: controller.signal } : undefined)
-      .then((fragment) => {
-        const entry = { fragment, ts: Date.now() };
+      .then((result) => {
+        // BrowserRuntime returns { fragment, stale }; older test fakes
+        // (and prior behavior) returned a bare DocumentFragment — accept
+        // both so we don't lock the runtime contract too tightly.
+        const fragment = result?.fragment ?? result;
+        const stale = result?.stale === true;
+        const entry = { fragment, stale, ts: Date.now() };
         this.#fragmentCache.set(url, entry);
         return entry;
       })
@@ -132,7 +178,7 @@ export class Orchestrator {
 
     this.#inflight.set(url, { controller, promise: fetchPromise });
     const entry = await fetchPromise;
-    return cloneFragment(entry.fragment);
+    return { fragment: cloneFragment(entry.fragment), stale: entry.stale === true };
   }
 
   // Aborts every in-flight prefetch and forgets any cached fragments.
@@ -152,6 +198,18 @@ export class Orchestrator {
     this.#fragmentCache.clear();
   }
 
+  // Seed the fragment cache with a known fragment for a URL. Used during
+  // snapshot restore to ensure forward re-navigation to a POST-only wizard
+  // step reuses the cached HTML rather than attempting a failing GET fetch.
+  setFragmentCache(url, fragment) {
+    if (!url || !fragment) return;
+    this.#fragmentCache.set(url, {
+      fragment: cloneFragment(fragment),
+      stale: false,
+      ts: Date.now(),
+    });
+  }
+
   // Warm the prefetch cache for `url` without mutating the stack. Safe
   // to call repeatedly for the same URL (deduped via #inflight) and from
   // hover/focus handlers; failures are swallowed since this is best-effort.
@@ -175,15 +233,17 @@ export class Orchestrator {
     // A popstate arriving while we have prefetches in flight means the
     // user navigated away from any URL we were preloading; drop them.
     this.#invalidatePrefetch();
-    return this.#dispatch(
-      handlePopstate(this.state, { historyState, locationHref }),
-    );
+    return this.#dispatch(handlePopstate(this.state, { historyState, locationHref }));
   }
 
   async #dispatch({ state, commands }, payload = {}) {
     this.state = state;
     for (const cmd of commands) {
-      if (cmd.type === "mountLayer" || cmd.type === "morphTopLayer") {
+      if (
+        cmd.type === "mountLayer" ||
+        cmd.type === "morphTopLayer" ||
+        cmd.type === "mountFrame"
+      ) {
         if (payload.html != null) cmd.html = payload.html;
         if (payload.fragment != null) cmd.fragment = payload.fragment;
       }

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

@@ -23,6 +23,9 @@ function recordingRuntime() {
     "rebuildFromSnapshot",
     "persistSnapshot",
     "clearSnapshot",
+    "mountFrame",
+    "unmountFrame",
+    "clearFrameCache",
   ];
   const runtime = { _calls: calls };
   for (const name of handlerNames) {
@@ -198,6 +201,93 @@ describe("replaceTop", () => {
   });
 });
 
+describe("pathTo", () => {
+  test("appends a frame, dispatches mountFrame + pushHistory + persistSnapshot", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    runtime._calls.length = 0;
+
+    await orchestrator.pathTo({ url: "/wizard/2" });
+    expect(orchestrator.layers[0].frames).toHaveLength(2);
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "mountFrame",
+      "pushHistory",
+      "persistSnapshot",
+    ]);
+    const mount = runtime._calls.find((c) => c.type === "mountFrame");
+    expect(mount).toMatchObject({
+      layerId: "L1",
+      fromFrameIndex: 0,
+      toFrameIndex: 1,
+      url: "/wizard/2",
+      stale: false,
+    });
+  });
+
+  test("explicit stale: true wins over the response header", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    runtime._calls.length = 0;
+
+    await orchestrator.pathTo({ url: "/wizard/2", stale: true });
+    const mount = runtime._calls.find((c) => c.type === "mountFrame");
+    expect(mount.stale).toBe(true);
+    expect(orchestrator.layers[0].frames[1].stale).toBe(true);
+  });
+
+  test("threads transition through to the runtime", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    runtime._calls.length = 0;
+    await orchestrator.pathTo({ url: "/wizard/2" }, { transition: "fade" });
+    expect(runtime._calls.find((c) => c.type === "mountFrame")).toMatchObject({
+      transition: "fade",
+    });
+  });
+});
+
+describe("pathBack", () => {
+  test("on a single-frame layer is a noop (does not close the layer)", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    runtime._calls.length = 0;
+    await orchestrator.pathBack();
+    expect(orchestrator.layers[0].frames).toHaveLength(1);
+    expect(runtime._calls).toEqual([]);
+  });
+
+  test("steps back through frames and walks history", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    await orchestrator.pathTo({ url: "/wizard/2" });
+    await orchestrator.pathTo({ url: "/wizard/3" });
+    runtime._calls.length = 0;
+
+    await orchestrator.pathBack({ steps: 2 });
+    expect(orchestrator.layers[0].frames).toHaveLength(1);
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "unmountFrame",
+      "historyBack",
+      "persistSnapshot",
+    ]);
+    expect(runtime._calls.find((c) => c.type === "historyBack")).toEqual({
+      type: "historyBack",
+      n: 2,
+    });
+  });
+
+  test("guards the popstate that history.go triggers", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    await orchestrator.pathTo({ url: "/wizard/2" });
+    runtime._calls.length = 0;
+
+    await orchestrator.pathBack();
+    runtime._calls.length = 0;
+    await orchestrator.onPopstate({
+      historyState: { stackId: STACK_ID, layerId: "L1", depth: 1, frameIndex: 0 },
+      locationHref: "/wizard/1",
+    });
+    expect(runtime._calls).toEqual([]);
+  });
+});
+
 describe("closeAll", () => {
   test("clears layers and increments guard once for the historyBack call", async () => {
     await orchestrator.push({ id: "L1", url: "/x" });
@@ -209,10 +299,12 @@ describe("closeAll", () => {
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
       "closeDialog",
+      "clearSnapshot",
       "unmountAllLayers",
+      "clearFrameCache",
+      "clearFrameCache",
       "unlockScroll",
       "historyBack",
-      "clearSnapshot",
     ]);
 
     runtime._calls.length = 0;
@@ -256,6 +348,9 @@ describe("prefetch cache + abort", () => {
       "rebuildFromSnapshot",
       "persistSnapshot",
       "clearSnapshot",
+      "mountFrame",
+      "unmountFrame",
+      "clearFrameCache",
     ];
     const runtime = { _calls: calls, _fetches: [], _aborts: aborts };
     for (const name of handlerNames) {
@@ -466,9 +561,10 @@ describe("onPopstate", () => {
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
       "closeDialog",
+      "clearSnapshot",
       "unmountAllLayers",
+      "clearFrameCache",
       "unlockScroll",
-      "clearSnapshot",
     ]);
     expect(types).not.toContain("historyBack");
   });