modal_stack 0.1.1 → 0.3.0

data/app/javascript/modal_stack/orchestrator.js

@@ -9,12 +9,50 @@ 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
+ * `#expectedPopstates`, which lets us avoid re-entering the reducer when our
+ * own `historyBack` calls fire `popstate`.
+ *
+ * @typedef {Object} OrchestratorOptions
+ * @property {object} runtime         Instance with one method per command type
+ * @property {string} stackId
+ * @property {string} baseUrl
+ * @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();
 
-  constructor({ runtime, stackId, baseUrl, restoreFrom = null }) {
+  /** @param {OrchestratorOptions} options */
+  constructor({
+    runtime,
+    stackId,
+    baseUrl,
+    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) {
@@ -31,17 +69,34 @@ export class Orchestrator {
     return this.state.layers.length;
   }
 
+  /**
+   * Push a layer. When `html`/`fragment` are absent, the orchestrator
+   * pre-fetches the URL so `mountLayer` is a sync DOM append (no flash).
+   * @param {Partial<import("./state.js").Layer> & { id: string, url: string }} layer
+   * @param {{ html?: string|null, fragment?: DocumentFragment|null }} [options]
+   */
   async push(layer, { html = null, fragment = null } = {}) {
+    const transition = push(this.state, layer, {
+      maxDepth: this.maxDepth,
+      maxDepthStrategy: this.maxDepthStrategy,
+    });
+    if (transition.commands.length === 0) return;
+
     if (fragment == null && html == null && layer?.url) {
       fragment = await this.#prefetch(layer.url);
     }
-    return this.#dispatch(push(this.state, layer), { html, fragment });
+    return this.#dispatch(transition, { html, fragment });
   }
 
   pop() {
     return this.#dispatch(pop(this.state));
   }
 
+  /**
+   * Replace (morph) the top layer.
+   * @param {Partial<import("./state.js").Layer>} patch
+   * @param {{ html?: string|null, fragment?: DocumentFragment|null, historyMode?: "push"|"replace" }} [options]
+   */
   async replaceTop(patch, { html = null, fragment = null, ...opts } = {}) {
     if (fragment == null && html == null && patch?.url) {
       fragment = await this.#prefetch(patch.url);
@@ -51,10 +106,64 @@ export class Orchestrator {
 
   async #prefetch(url) {
     if (typeof this.runtime.fetchFragment !== "function") return null;
-    return this.runtime.fetchFragment(url);
+
+    const cached = this.#fragmentCache.get(url);
+    if (cached && Date.now() - cached.ts < this.prefetchTtlMs) {
+      return cloneFragment(cached.fragment);
+    }
+
+    const existing = this.#inflight.get(url);
+    if (existing) {
+      const entry = await existing.promise;
+      return cloneFragment(entry.fragment);
+    }
+
+    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() };
+        this.#fragmentCache.set(url, entry);
+        return entry;
+      })
+      .finally(() => {
+        this.#inflight.delete(url);
+      });
+
+    this.#inflight.set(url, { controller, promise: fetchPromise });
+    const entry = await fetchPromise;
+    return cloneFragment(entry.fragment);
+  }
+
+  // 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));
   }
 
@@ -63,6 +172,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 }),
     );
@@ -91,8 +203,28 @@ export class Orchestrator {
 
     const handler = this.runtime[cmd.type];
     if (typeof handler !== "function") {
-      throw new Error(`runtime missing handler for "${cmd.type}"`);
+      const known = Object.getOwnPropertyNames(Object.getPrototypeOf(this.runtime))
+        .filter((name) => name !== "constructor" && typeof this.runtime[name] === "function")
+        .sort()
+        .join(", ");
+      throw new Error(
+        `[modal_stack] runtime missing handler for "${cmd.type}" ` +
+          `(stack depth=${this.depth}). ` +
+          `Known handlers: ${known || "<none>"}.`,
+      );
     }
     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

@@ -208,8 +208,8 @@ describe("closeAll", () => {
     expect(orchestrator.depth).toBe(0);
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
       "unlockScroll",
       "historyBack",
       "clearSnapshot",
@@ -224,6 +224,172 @@ 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",
+    ];
+    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" });
@@ -238,6 +404,56 @@ describe("onPopstate", () => {
     expect(rebuild).toMatchObject({ targetDepth: 2, targetLayerId: "L2" });
   });
 
+  test("missing handler error names known handlers", async () => {
+    const partialRuntime = {
+      // showDialog is missing on purpose so we can verify the error message.
+      mountLayer: () => {},
+      lockScroll: () => {},
+      pushHistory: () => {},
+      persistSnapshot: () => {},
+    };
+    Object.setPrototypeOf(partialRuntime, {
+      mountLayer: partialRuntime.mountLayer,
+      lockScroll: partialRuntime.lockScroll,
+      pushHistory: partialRuntime.pushHistory,
+      persistSnapshot: partialRuntime.persistSnapshot,
+    });
+    const orch = new Orchestrator({
+      runtime: partialRuntime,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    let caught = null;
+    try {
+      await orch.push({ id: "L1", url: "/x" });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect(caught.message).toMatch(/showDialog/);
+    expect(caught.message).toMatch(/depth=/);
+  });
+
+  test("max_depth strategy is threaded through to the reducer", async () => {
+    const orch = new Orchestrator({
+      runtime: recordingRuntime(),
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      maxDepth: 1,
+      maxDepthStrategy: "raise",
+    });
+    await orch.push({ id: "L1", url: "/x" });
+    let caught = null;
+    try {
+      await orch.push({ id: "L2", url: "/y" });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).not.toBeNull();
+    expect(caught.name).toBe("ModalStackDepthError");
+    expect(orch.depth).toBe(1);
+  });
+
   test("popstate from a different stack tears down without history changes", async () => {
     await orchestrator.push({ id: "L1", url: "/x" });
     runtime._calls.length = 0;
@@ -249,8 +465,8 @@ describe("onPopstate", () => {
 
     const types = runtime._calls.map((c) => c.type);
     expect(types).toEqual([
-      "unmountAllLayers",
       "closeDialog",
+      "unmountAllLayers",
       "unlockScroll",
       "clearSnapshot",
     ]);

data/app/javascript/modal_stack/runtime.js

@@ -1,12 +1,36 @@
 export const SNAPSHOT_KEY = "modalStackSnapshot";
 export const FRAGMENT_HEADER = "X-Modal-Stack-Request";
+export const SCROLLBAR_WIDTH_VAR = "--modal-stack-scrollbar-width";
 
 const LAYER_SELECTOR = '[data-modal-stack-target="layer"]';
-// Hard cap: never wait longer than this for an exit transition to fire,
-// even if the host CSS forgot to transition the leaving state.
-const LEAVE_TIMEOUT_MS = 600;
+// 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.
+const DURATION_CSS_VAR = "--modal-stack-duration";
+// Floor for the safety timeout — even very short CSS transitions need
+// enough headroom for transitionend to fire on slow devices.
+const LEAVE_TIMEOUT_FLOOR_MS = 300;
+// Used when no CSS variable is exposed (host CSS missing, JSDOM tests).
+const LEAVE_TIMEOUT_FALLBACK_MS = 600;
 
+/**
+ * The only file that touches `<dialog>`, `history`, `fetch`, and
+ * `sessionStorage`. Implements one method per command type emitted by the
+ * reducer in `state.js`.
+ *
+ * Tests can swap in any object that implements the same surface (see
+ * `orchestrator.test.js` for an in-memory fake).
+ */
 export class BrowserRuntime {
+  /**
+   * @param {Object} options
+   * @param {HTMLDialogElement} options.dialog
+   * @param {HTMLElement} [options.body]
+   * @param {History} [options.history]
+   * @param {typeof fetch} [options.fetcher]
+   * @param {Storage} [options.store]
+   * @param {Document} [options.documentRef]
+   */
   constructor({
     dialog,
     body = globalThis.document?.body,
@@ -35,11 +59,27 @@ export class BrowserRuntime {
   }
 
   lockScroll() {
-    if (this.body) this.body.dataset.modalStackLocked = "";
+    if (!this.body) return;
+    // Compensate for the scrollbar that disappears once <body> stops
+    // overflowing — without this, fixed elements jump rightward by the
+    // scrollbar width on lock. Host CSS reads the variable via
+    // `padding-right: var(--modal-stack-scrollbar-width, 0)`.
+    const root = this.document?.documentElement;
+    if (root) {
+      const scrollbarWidth = Math.max(
+        0,
+        (globalThis.innerWidth ?? root.clientWidth) - root.clientWidth,
+      );
+      root.style.setProperty(SCROLLBAR_WIDTH_VAR, `${scrollbarWidth}px`);
+    }
+    this.body.dataset.modalStackLocked = "";
   }
 
   unlockScroll() {
-    if (this.body) delete this.body.dataset.modalStackLocked;
+    if (!this.body) return;
+    delete this.body.dataset.modalStackLocked;
+    const root = this.document?.documentElement;
+    if (root) root.style.removeProperty(SCROLLBAR_WIDTH_VAR);
   }
 
   inertLayer({ layerId, value }) {
@@ -68,12 +108,13 @@ export class BrowserRuntime {
   async unmountTopLayer() {
     const layer = this.#topLayer();
     if (!layer) return;
-    await animateOut(layer);
+    await animateOut(layer, this.#leaveTimeoutMs());
   }
 
   async unmountAllLayers() {
     const layers = [...this.dialog.querySelectorAll(LAYER_SELECTOR)];
-    await Promise.all(layers.map(animateOut));
+    const timeout = this.#leaveTimeoutMs();
+    await Promise.all(layers.map((l) => animateOut(l, timeout)));
   }
 
   pushHistory({ url, historyState }) {
@@ -122,6 +163,34 @@ export class BrowserRuntime {
     }
   }
 
+  // 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
+  // shouldn't change at runtime. Returns LEAVE_TIMEOUT_FALLBACK_MS when
+  // getComputedStyle is unavailable (tests) or the variable is missing.
+  #leaveTimeoutMs() {
+    if (this._cachedLeaveTimeoutMs != null) return this._cachedLeaveTimeoutMs;
+
+    const get = globalThis.getComputedStyle;
+    if (typeof get !== "function" || !this.dialog?.ownerDocument) {
+      return LEAVE_TIMEOUT_FALLBACK_MS;
+    }
+
+    let parsed = NaN;
+    try {
+      const raw = get(this.dialog).getPropertyValue(DURATION_CSS_VAR);
+      parsed = parseDurationMs(raw);
+    } catch {
+      // getComputedStyle can throw in detached/foreign documents.
+    }
+
+    const ms = Number.isFinite(parsed)
+      ? Math.max(Math.ceil(parsed * 1.5), LEAVE_TIMEOUT_FLOOR_MS)
+      : LEAVE_TIMEOUT_FALLBACK_MS;
+    this._cachedLeaveTimeoutMs = ms;
+    return ms;
+  }
+
   #findLayer(layerId) {
     return this.dialog.querySelector(
       `${LAYER_SELECTOR}[data-layer-id="${escapeAttr(layerId)}"]`,
@@ -159,13 +228,14 @@ export class BrowserRuntime {
     }
   }
 
-  async fetchFragment(url) {
+  async fetchFragment(url, { signal } = {}) {
     const resp = await this.fetcher(url, {
       headers: {
         Accept: "text/html, text/vnd.turbo-stream.html",
         [FRAGMENT_HEADER]: "1",
       },
       credentials: "same-origin",
+      signal,
     });
     if (!resp.ok) {
       throw new Error(`modal_stack: fetch ${url} → ${resp.status}`);
@@ -193,7 +263,7 @@ function parseFragment(html, doc) {
 // out, then awaits transitionend (with a hard timeout) before removing
 // the element from the DOM.  If the host CSS doesn't define an exit
 // transition, the timeout still fires and the layer is removed cleanly.
-function animateOut(layer) {
+function animateOut(layer, timeoutMs = LEAVE_TIMEOUT_FALLBACK_MS) {
   return new Promise((resolve) => {
     let done = false;
     const finish = () => {
@@ -205,10 +275,21 @@ function animateOut(layer) {
     };
     layer.addEventListener("transitionend", finish, { once: true });
     layer.dataset.leaving = "";
-    setTimeout(finish, LEAVE_TIMEOUT_MS);
+    setTimeout(finish, timeoutMs);
   });
 }
 
+// Parses a CSS time token ("220ms", "0.22s", "  220 ms ") to milliseconds.
+// Returns NaN when the input is empty or unparseable so callers can fall back.
+function parseDurationMs(raw) {
+  if (typeof raw !== "string") return NaN;
+  const value = raw.trim();
+  if (!value) return NaN;
+  const num = parseFloat(value);
+  if (!Number.isFinite(num)) return NaN;
+  return /m?s$/i.test(value) && !/ms$/i.test(value) ? num * 1000 : num;
+}
+
 function escapeAttr(value) {
   if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
     return CSS.escape(value);