modal_stack 0.2.0 → 0.4.1

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

@@ -79,6 +79,21 @@ export class ModalStackController extends Controller {
     return this.orchestrator.closeAll();
   }
 
+  prefetch(url) {
+    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;
@@ -132,6 +147,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,
+      });
+    });
   }
 }
 
@@ -182,3 +212,27 @@ function generateLayerId() {
   }
   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/controllers/modal_stack_link_controller.js

@@ -1,14 +1,21 @@
 import { Controller } from "@hotwired/stimulus";
 
 export class ModalStackLinkController extends Controller {
-  open(event) {
-    const stack = document.querySelector('[data-controller~="modal-stack"]');
-    if (!stack) return;
+  connect() {
+    if (this.element.dataset.modalStackLinkPrefetch === "false") return;
+    this._onIntent = () => this.#warm();
+    this.element.addEventListener("pointerenter", this._onIntent);
+    this.element.addEventListener("focus", this._onIntent);
+  }
 
-    const controller = this.application.getControllerForElementAndIdentifier(
-      stack,
-      "modal-stack",
-    );
+  disconnect() {
+    if (!this._onIntent) return;
+    this.element.removeEventListener("pointerenter", this._onIntent);
+    this.element.removeEventListener("focus", this._onIntent);
+  }
+
+  open(event) {
+    const controller = this.#stackController();
     if (!controller) return;
 
     event.preventDefault();
@@ -24,6 +31,21 @@ export class ModalStackLinkController extends Controller {
       dismissible: ds.modalStackLinkDismissible !== "false",
     });
   }
+
+  #warm() {
+    const controller = this.#stackController();
+    if (!controller || typeof controller.prefetch !== "function") return;
+    controller.prefetch(this.element.href);
+  }
+
+  #stackController() {
+    const stack = document.querySelector('[data-controller~="modal-stack"]');
+    if (!stack) return null;
+    return this.application.getControllerForElementAndIdentifier(
+      stack,
+      "modal-stack",
+    );
+  }
 }
 
 function generateLayerId() {

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,
@@ -9,6 +11,11 @@ import {
   snapshot,
 } from "./state.js";
 
+// How long a successful prefetch is reused before being refetched. Short
+// enough that stale server-rendered HTML doesn't linger; long enough to
+// absorb back/forward bounces and rapid double-clicks.
+const PREFETCH_TTL_MS = 30_000;
+
 /**
  * Owns the current `Stack`, calls the pure reducer, and executes the emitted
  * commands against an injected runtime. The only stateful piece is
@@ -22,9 +29,16 @@ import {
  * @property {string|null} [restoreFrom]   Serialized snapshot from sessionStorage
  * @property {number|null} [maxDepth]      null disables the cap
  * @property {"raise"|"warn"|"silent"} [maxDepthStrategy]
+ * @property {number} [prefetchTtlMs]      Override the prefetch cache TTL (testing)
  */
 export class Orchestrator {
   #expectedPopstates = 0;
+  // url → { fragment, ts }. Fragment is the canonical copy; consumers
+  // always receive a `cloneNode(true)` so the cached entry stays intact.
+  #fragmentCache = new Map();
+  // url → { controller, promise }. Lets concurrent prefetches dedupe onto
+  // the same in-flight request, and gives `closeAll` a way to cancel them.
+  #inflight = new Map();
 
   /** @param {OrchestratorOptions} options */
   constructor({
@@ -34,11 +48,13 @@ export class Orchestrator {
     restoreFrom = null,
     maxDepth = null,
     maxDepthStrategy = "warn",
+    prefetchTtlMs = PREFETCH_TTL_MS,
   }) {
     if (!runtime) throw new Error("runtime required");
     this.runtime = runtime;
     this.maxDepth = maxDepth;
     this.maxDepthStrategy = maxDepthStrategy;
+    this.prefetchTtlMs = prefetchTtlMs;
     this.state = createStack({ stackId, baseUrl });
 
     if (restoreFrom) {
@@ -90,12 +106,106 @@ 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;
-    return this.runtime.fetchFragment(url);
+    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 { fragment: cloneFragment(cached.fragment), stale: cached.stale === true };
+    }
+
+    const existing = this.#inflight.get(url);
+    if (existing) {
+      const entry = await existing.promise;
+      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((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;
+      })
+      .finally(() => {
+        this.#inflight.delete(url);
+      });
+
+    this.#inflight.set(url, { controller, promise: fetchPromise });
+    const entry = await fetchPromise;
+    return { fragment: cloneFragment(entry.fragment), stale: entry.stale === true };
+  }
+
+  // Aborts every in-flight prefetch and forgets any cached fragments.
+  // Called when we tear the stack down (closeAll / cross-stack popstate)
+  // because the URLs in flight are no longer relevant. In-flight callers
+  // see an AbortError; caller code (controllers) already wraps push/pop
+  // in try/catch via `guarded()`.
+  #invalidatePrefetch() {
+    for (const { controller } of this.#inflight.values()) {
+      try {
+        controller?.abort();
+      } catch {
+        // ignore — abort is best-effort
+      }
+    }
+    this.#inflight.clear();
+    this.#fragmentCache.clear();
+  }
+
+  // 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.
+  prefetch(url) {
+    if (!url || typeof this.runtime.fetchFragment !== "function") {
+      return Promise.resolve(null);
+    }
+    return this.#prefetch(url).catch(() => null);
   }
 
   closeAll() {
+    this.#invalidatePrefetch();
     return this.#dispatch(closeAll(this.state));
   }
 
@@ -104,6 +214,9 @@ export class Orchestrator {
       this.#expectedPopstates -= 1;
       return Promise.resolve();
     }
+    // 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 }),
     );
@@ -112,7 +225,11 @@ export class Orchestrator {
   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;
       }
@@ -145,3 +262,15 @@ export class Orchestrator {
     await handler.call(this.runtime, cmd);
   }
 }
+
+function cloneFragment(fragment) {
+  if (!fragment) return fragment;
+  if (typeof fragment.cloneNode === "function") {
+    return fragment.cloneNode(true);
+  }
+  return fragment;
+}
+
+function supportsAbort() {
+  return typeof globalThis.AbortController === "function";
+}

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" });
@@ -208,8 +298,10 @@ describe("closeAll", () => {
     expect(orchestrator.depth).toBe(0);
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
+      "clearFrameCache",
+      "clearFrameCache",
       "unlockScroll",
       "historyBack",
       "clearSnapshot",
@@ -224,6 +316,175 @@ describe("closeAll", () => {
   });
 });
 
+describe("prefetch cache + abort", () => {
+  // Each fakeFragment supports cloneNode so the orchestrator can hand out
+  // independent copies without exhausting the cached entry.
+  function fakeFragment(label) {
+    return {
+      label,
+      consumed: false,
+      cloneNode() {
+        return fakeFragment(label);
+      },
+    };
+  }
+
+  function fetchingRuntime({ delayMs = 0, fail = false } = {}) {
+    const calls = [];
+    const aborts = [];
+    const handlerNames = [
+      "showDialog",
+      "lockScroll",
+      "inertLayer",
+      "mountLayer",
+      "morphTopLayer",
+      "unmountTopLayer",
+      "unmountAllLayers",
+      "closeDialog",
+      "unlockScroll",
+      "pushHistory",
+      "replaceHistory",
+      "historyBack",
+      "rebuildFromSnapshot",
+      "persistSnapshot",
+      "clearSnapshot",
+      "mountFrame",
+      "unmountFrame",
+      "clearFrameCache",
+    ];
+    const runtime = { _calls: calls, _fetches: [], _aborts: aborts };
+    for (const name of handlerNames) {
+      runtime[name] = (cmd) => {
+        calls.push({ type: name, ...cmd });
+      };
+    }
+    runtime.fetchFragment = (url, { signal } = {}) => {
+      runtime._fetches.push(url);
+      return new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+          if (fail) reject(new Error("boom"));
+          else resolve(fakeFragment(`frag:${url}`));
+        }, delayMs);
+        if (signal) {
+          signal.addEventListener("abort", () => {
+            clearTimeout(t);
+            aborts.push(url);
+            const err = new Error("aborted");
+            err.name = "AbortError";
+            reject(err);
+          });
+        }
+      });
+    };
+    return runtime;
+  }
+
+  test("dedupes concurrent prefetches for the same url", async () => {
+    const rt = fetchingRuntime({ delayMs: 5 });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await Promise.all([
+      orch.push({ id: "L1", url: "/x" }),
+      orch.push({ id: "L2", url: "/x" }),
+    ]);
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("hits the cache on a second push to the same url", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await orch.push({ id: "L2", url: "/x" });
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("returns a fresh clone per consumer (cache survives consumption)", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    const seenFragments = [];
+    rt.mountLayer = (cmd) => {
+      seenFragments.push(cmd.fragment);
+    };
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await orch.push({ id: "L2", url: "/x" });
+    expect(seenFragments).toHaveLength(2);
+    expect(seenFragments[0]).not.toBe(seenFragments[1]);
+  });
+
+  test("TTL expires the cache and triggers a refetch", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      prefetchTtlMs: 1,
+    });
+    await orch.push({ id: "L1", url: "/x" });
+    await orch.pop();
+    await new Promise((r) => setTimeout(r, 5));
+    await orch.push({ id: "L2", url: "/x" });
+    expect(rt._fetches).toEqual(["/x", "/x"]);
+  });
+
+  test("prefetch warms the cache without dispatching commands", async () => {
+    const rt = fetchingRuntime();
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await orch.prefetch("/x");
+    expect(rt._fetches).toEqual(["/x"]);
+    expect(rt._calls).toEqual([]);
+    // Subsequent push consumes the cache, no second fetch.
+    await orch.push({ id: "L1", url: "/x" });
+    expect(rt._fetches).toEqual(["/x"]);
+  });
+
+  test("prefetch swallows errors (best-effort)", async () => {
+    const rt = fetchingRuntime({ fail: true });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await expect(orch.prefetch("/boom")).resolves.toBeNull();
+  });
+
+  test("closeAll aborts in-flight prefetches and clears the cache", async () => {
+    const rt = fetchingRuntime({ delayMs: 50 });
+    const orch = new Orchestrator({
+      runtime: rt,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    // First push completes so the cache has /x.
+    await orch.push({ id: "L1", url: "/x" });
+    // Second push starts fetching /y and stays in flight.
+    const inflight = orch.push({ id: "L2", url: "/y" });
+    await new Promise((r) => setTimeout(r, 5));
+    await orch.closeAll();
+    await expect(inflight).rejects.toThrow(/aborted/);
+    expect(rt._aborts).toContain("/y");
+    // Cache has been cleared too: re-push of /x must refetch.
+    await orch.push({ id: "L3", url: "/x" });
+    expect(rt._fetches.filter((u) => u === "/x")).toHaveLength(2);
+  });
+});
+
 describe("onPopstate", () => {
   test("forward navigation requests rebuild from snapshot", async () => {
     await orchestrator.push({ id: "L1", url: "/x" });
@@ -299,8 +560,9 @@ describe("onPopstate", () => {
 
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
+      "clearFrameCache",
       "unlockScroll",
       "clearSnapshot",
     ]);