modal_stack 0.1.1

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

@@ -0,0 +1,260 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { Orchestrator } from "./orchestrator.js";
+import { snapshot } from "./state.js";
+
+const STACK_ID = "stack-abc";
+const BASE_URL = "/projects";
+
+function recordingRuntime() {
+  const calls = [];
+  const handlerNames = [
+    "showDialog",
+    "lockScroll",
+    "inertLayer",
+    "mountLayer",
+    "morphTopLayer",
+    "unmountTopLayer",
+    "unmountAllLayers",
+    "closeDialog",
+    "unlockScroll",
+    "pushHistory",
+    "replaceHistory",
+    "historyBack",
+    "rebuildFromSnapshot",
+    "persistSnapshot",
+    "clearSnapshot",
+  ];
+  const runtime = { _calls: calls };
+  for (const name of handlerNames) {
+    runtime[name] = (cmd) => {
+      calls.push({ type: name, ...cmd });
+    };
+  }
+  return runtime;
+}
+
+let runtime;
+let orchestrator;
+
+beforeEach(() => {
+  runtime = recordingRuntime();
+  orchestrator = new Orchestrator({
+    runtime,
+    stackId: STACK_ID,
+    baseUrl: BASE_URL,
+  });
+});
+
+describe("constructor", () => {
+  test("requires runtime", () => {
+    expect(() => new Orchestrator({ stackId: "x", baseUrl: "/" })).toThrow(
+      /runtime required/,
+    );
+  });
+
+  test("starts empty", () => {
+    expect(orchestrator.layers).toEqual([]);
+    expect(orchestrator.depth).toBe(0);
+  });
+
+  test("restoreFrom seeds state when valid", async () => {
+    const seed = new Orchestrator({
+      runtime,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await seed.push({ id: "L1", url: "/x" });
+    const json = snapshot(seed.state);
+
+    const restored = new Orchestrator({
+      runtime: recordingRuntime(),
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+      restoreFrom: json,
+    });
+    expect(restored.depth).toBe(1);
+    expect(restored.layers[0].id).toBe("L1");
+  });
+
+  test("restoreFrom is ignored when stackId mismatches", async () => {
+    const seed = new Orchestrator({
+      runtime,
+      stackId: STACK_ID,
+      baseUrl: BASE_URL,
+    });
+    await seed.push({ id: "L1", url: "/x" });
+    const json = snapshot(seed.state);
+
+    const restored = new Orchestrator({
+      runtime: recordingRuntime(),
+      stackId: "other",
+      baseUrl: BASE_URL,
+      restoreFrom: json,
+    });
+    expect(restored.depth).toBe(0);
+  });
+});
+
+describe("push", () => {
+  test("dispatches commands in order, persists snapshot last", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "mountLayer",
+      "showDialog",
+      "lockScroll",
+      "pushHistory",
+      "persistSnapshot",
+    ]);
+  });
+
+  test("persistSnapshot receives serialized state", async () => {
+    let captured = null;
+    runtime.persistSnapshot = (json) => {
+      captured = json;
+    };
+    await orchestrator.push({ id: "L1", url: "/x" });
+    expect(typeof captured).toBe("string");
+    const parsed = JSON.parse(captured);
+    expect(parsed.layers).toHaveLength(1);
+    expect(parsed.layers[0].id).toBe("L1");
+  });
+
+  test("throws when runtime is missing a handler", async () => {
+    delete runtime.mountLayer;
+    await expect(orchestrator.push({ id: "L1", url: "/x" })).rejects.toThrow(
+      /mountLayer/,
+    );
+  });
+});
+
+describe("pop", () => {
+  test("guards the popstate that history.back triggers", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    await orchestrator.pop();
+
+    const popCalls = runtime._calls.map((c) => c.type);
+    expect(popCalls).toContain("historyBack");
+
+    runtime._calls.length = 0;
+    await orchestrator.onPopstate({
+      historyState: null,
+      locationHref: BASE_URL,
+    });
+    expect(runtime._calls).toEqual([]);
+  });
+
+  test("subsequent popstate (not from us) is processed normally", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    await orchestrator.pop();
+    await orchestrator.onPopstate({
+      historyState: null,
+      locationHref: BASE_URL,
+    });
+
+    runtime._calls.length = 0;
+    await orchestrator.push({ id: "L2", url: "/y" });
+    runtime._calls.length = 0;
+    await orchestrator.onPopstate({
+      historyState: null,
+      locationHref: BASE_URL,
+    });
+
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toContain("closeDialog");
+  });
+});
+
+describe("replaceTop", () => {
+  test("default replaces history without consuming guard", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    runtime._calls.length = 0;
+
+    await orchestrator.replaceTop({ url: "/x/y" });
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "morphTopLayer",
+      "replaceHistory",
+      "persistSnapshot",
+    ]);
+  });
+
+  test("historyMode push emits pushHistory and updates layer id", async () => {
+    await orchestrator.push({ id: "L1", url: "/wizard/1" });
+    runtime._calls.length = 0;
+
+    await orchestrator.replaceTop(
+      { id: "L1b", url: "/wizard/2" },
+      { historyMode: "push" },
+    );
+
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "morphTopLayer",
+      "pushHistory",
+      "persistSnapshot",
+    ]);
+    expect(orchestrator.layers[0].id).toBe("L1b");
+  });
+});
+
+describe("closeAll", () => {
+  test("clears layers and increments guard once for the historyBack call", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    await orchestrator.push({ id: "L2", url: "/y" });
+    runtime._calls.length = 0;
+
+    await orchestrator.closeAll();
+    expect(orchestrator.depth).toBe(0);
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "unmountAllLayers",
+      "closeDialog",
+      "unlockScroll",
+      "historyBack",
+      "clearSnapshot",
+    ]);
+
+    runtime._calls.length = 0;
+    await orchestrator.onPopstate({
+      historyState: null,
+      locationHref: BASE_URL,
+    });
+    expect(runtime._calls).toEqual([]);
+  });
+});
+
+describe("onPopstate", () => {
+  test("forward navigation requests rebuild from snapshot", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    runtime._calls.length = 0;
+
+    await orchestrator.onPopstate({
+      historyState: { stackId: STACK_ID, layerId: "L2", depth: 2 },
+      locationHref: "/y",
+    });
+
+    const rebuild = runtime._calls.find((c) => c.type === "rebuildFromSnapshot");
+    expect(rebuild).toMatchObject({ targetDepth: 2, targetLayerId: "L2" });
+  });
+
+  test("popstate from a different stack tears down without history changes", async () => {
+    await orchestrator.push({ id: "L1", url: "/x" });
+    runtime._calls.length = 0;
+
+    await orchestrator.onPopstate({
+      historyState: { stackId: "other", layerId: "Z", depth: 9 },
+      locationHref: "/elsewhere",
+    });
+
+    const types = runtime._calls.map((c) => c.type);
+    expect(types).toEqual([
+      "unmountAllLayers",
+      "closeDialog",
+      "unlockScroll",
+      "clearSnapshot",
+    ]);
+    expect(types).not.toContain("historyBack");
+  });
+});
+

data/app/javascript/modal_stack/runtime.js

@@ -0,0 +1,217 @@
+export const SNAPSHOT_KEY = "modalStackSnapshot";
+export const FRAGMENT_HEADER = "X-Modal-Stack-Request";
+
+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;
+
+export class BrowserRuntime {
+  constructor({
+    dialog,
+    body = globalThis.document?.body,
+    history = globalThis.history,
+    fetcher = globalThis.fetch?.bind(globalThis),
+    store = globalThis.sessionStorage,
+    documentRef = globalThis.document,
+  } = {}) {
+    if (!dialog) throw new Error("BrowserRuntime: dialog element required");
+    if (!fetcher) throw new Error("BrowserRuntime: fetch implementation required");
+    if (!documentRef) throw new Error("BrowserRuntime: document reference required");
+    this.dialog = dialog;
+    this.body = body;
+    this.history = history;
+    this.fetcher = fetcher;
+    this.store = store;
+    this.document = documentRef;
+  }
+
+  showDialog() {
+    if (!this.dialog.open) this.dialog.showModal();
+  }
+
+  closeDialog() {
+    if (this.dialog.open) this.dialog.close();
+  }
+
+  lockScroll() {
+    if (this.body) this.body.dataset.modalStackLocked = "";
+  }
+
+  unlockScroll() {
+    if (this.body) delete this.body.dataset.modalStackLocked;
+  }
+
+  inertLayer({ layerId, value }) {
+    const layer = this.#findLayer(layerId);
+    if (!layer) return;
+    if (value) layer.setAttribute("inert", "");
+    else layer.removeAttribute("inert");
+  }
+
+  async mountLayer({ layerId, url, depth, variant, dismissible, size, side, width, height, html, fragment }) {
+    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.dialog.appendChild(layer);
+  }
+
+  async morphTopLayer({ layerId, url, depth, variant, dismissible, size, side, width, height, html, fragment }) {
+    const frag = await this.#resolveFragment({ url, html, fragment });
+    const layer = this.#topLayer();
+    if (!layer) return;
+    this.#applyLayerAttrs(layer, { layerId, depth, variant, dismissible, size, side, width, height });
+    layer.replaceChildren(...frag.childNodes);
+  }
+
+  async unmountTopLayer() {
+    const layer = this.#topLayer();
+    if (!layer) return;
+    await animateOut(layer);
+  }
+
+  async unmountAllLayers() {
+    const layers = [...this.dialog.querySelectorAll(LAYER_SELECTOR)];
+    await Promise.all(layers.map(animateOut));
+  }
+
+  pushHistory({ url, historyState }) {
+    this.history.pushState(historyState, "", url);
+  }
+
+  replaceHistory({ url, historyState }) {
+    this.history.replaceState(historyState, "", url);
+  }
+
+  historyBack({ n }) {
+    this.history.go(-n);
+  }
+
+  rebuildFromSnapshot() {
+    // Forward navigation reconstruction is M2 territory (nested deep-linking).
+    this.dialog.dispatchEvent(
+      new CustomEvent("modal_stack:rebuild-requested", { bubbles: true }),
+    );
+  }
+
+  persistSnapshot(json) {
+    if (!this.store) return;
+    try {
+      this.store.setItem(SNAPSHOT_KEY, json);
+    } catch {
+      // sessionStorage may be full or unavailable (private mode, quota) — best effort.
+    }
+  }
+
+  clearSnapshot() {
+    if (!this.store) return;
+    try {
+      this.store.removeItem(SNAPSHOT_KEY);
+    } catch {
+      // ignore
+    }
+  }
+
+  readSnapshot() {
+    if (!this.store) return null;
+    try {
+      return this.store.getItem(SNAPSHOT_KEY);
+    } catch {
+      return null;
+    }
+  }
+
+  #findLayer(layerId) {
+    return this.dialog.querySelector(
+      `${LAYER_SELECTOR}[data-layer-id="${escapeAttr(layerId)}"]`,
+    );
+  }
+
+  #topLayer() {
+    const layers = this.dialog.querySelectorAll(LAYER_SELECTOR);
+    return layers[layers.length - 1] ?? null;
+  }
+
+  #applyLayerAttrs(layer, { layerId, depth, variant, dismissible, size, side, width, height }) {
+    layer.dataset.modalStackTarget = "layer";
+    layer.dataset.layerId = layerId;
+    layer.dataset.depth = String(depth);
+    layer.dataset.variant = variant;
+    layer.dataset.dismissible = String(dismissible);
+    if (size) layer.dataset.modalStackSize = size;
+    else delete layer.dataset.modalStackSize;
+    if (side) layer.dataset.side = side;
+    else delete layer.dataset.side;
+    if (width) {
+      layer.dataset.modalStackWidth = width;
+      layer.style.width = width;
+    } else {
+      delete layer.dataset.modalStackWidth;
+      layer.style.removeProperty("width");
+    }
+    if (height) {
+      layer.dataset.modalStackHeight = height;
+      layer.style.height = height;
+    } else {
+      delete layer.dataset.modalStackHeight;
+      layer.style.removeProperty("height");
+    }
+  }
+
+  async fetchFragment(url) {
+    const resp = await this.fetcher(url, {
+      headers: {
+        Accept: "text/html, text/vnd.turbo-stream.html",
+        [FRAGMENT_HEADER]: "1",
+      },
+      credentials: "same-origin",
+    });
+    if (!resp.ok) {
+      throw new Error(`modal_stack: fetch ${url} → ${resp.status}`);
+    }
+    const html = await resp.text();
+    return parseFragment(html, this.document);
+  }
+
+  async #resolveFragment({ url, html, fragment }) {
+    if (fragment) return fragment;
+    if (html != null) return parseFragment(html, this.document);
+    return this.fetchFragment(url);
+  }
+}
+
+function parseFragment(html, doc) {
+  const parser = new DOMParser();
+  const parsed = parser.parseFromString(html, "text/html");
+  const fragment = doc.createDocumentFragment();
+  fragment.append(...parsed.body.childNodes);
+  return fragment;
+}
+
+// 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
+// transition, the timeout still fires and the layer is removed cleanly.
+function animateOut(layer) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      layer.removeEventListener("transitionend", finish);
+      layer.remove();
+      resolve();
+    };
+    layer.addEventListener("transitionend", finish, { once: true });
+    layer.dataset.leaving = "";
+    setTimeout(finish, LEAVE_TIMEOUT_MS);
+  });
+}
+
+function escapeAttr(value) {
+  if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
+    return CSS.escape(value);
+  }
+  return String(value).replace(/["\\]/g, "\\$&");
+}

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

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import { BrowserRuntime, FRAGMENT_HEADER, SNAPSHOT_KEY } from "./runtime.js";
+
+function fakeStore() {
+  const map = new Map();
+  return {
+    map,
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    setItem: (k, v) => map.set(k, v),
+    removeItem: (k) => map.delete(k),
+  };
+}
+
+function noopRuntimeArgs(overrides = {}) {
+  return {
+    dialog: {},
+    fetcher: () => Promise.resolve(new Response("")),
+    documentRef: {},
+    ...overrides,
+  };
+}
+
+describe("BrowserRuntime constructor", () => {
+  test("requires dialog", () => {
+    expect(() => new BrowserRuntime(noopRuntimeArgs({ dialog: null }))).toThrow(
+      /dialog/,
+    );
+  });
+
+  test("requires fetcher", () => {
+    expect(
+      () => new BrowserRuntime(noopRuntimeArgs({ fetcher: null })),
+    ).toThrow(/fetch/);
+  });
+
+  test("requires document", () => {
+    expect(
+      () => new BrowserRuntime(noopRuntimeArgs({ documentRef: null })),
+    ).toThrow(/document/);
+  });
+});
+
+describe("snapshot storage", () => {
+  test("persistSnapshot writes under SNAPSHOT_KEY", () => {
+    const store = fakeStore();
+    const rt = new BrowserRuntime(noopRuntimeArgs({ store }));
+    rt.persistSnapshot('{"hello":1}');
+    expect(store.map.get(SNAPSHOT_KEY)).toBe('{"hello":1}');
+  });
+
+  test("clearSnapshot removes the key", () => {
+    const store = fakeStore();
+    store.map.set(SNAPSHOT_KEY, "x");
+    const rt = new BrowserRuntime(noopRuntimeArgs({ store }));
+    rt.clearSnapshot();
+    expect(store.map.has(SNAPSHOT_KEY)).toBe(false);
+  });
+
+  test("readSnapshot returns the stored value or null", () => {
+    const store = fakeStore();
+    const rt = new BrowserRuntime(noopRuntimeArgs({ store }));
+    expect(rt.readSnapshot()).toBeNull();
+    store.map.set(SNAPSHOT_KEY, "{}");
+    expect(rt.readSnapshot()).toBe("{}");
+  });
+
+  test("storage failures are swallowed (best-effort)", () => {
+    const failing = {
+      getItem: () => {
+        throw new Error("quota");
+      },
+      setItem: () => {
+        throw new Error("quota");
+      },
+      removeItem: () => {
+        throw new Error("quota");
+      },
+    };
+    const rt = new BrowserRuntime(noopRuntimeArgs({ store: failing }));
+    expect(() => rt.persistSnapshot("x")).not.toThrow();
+    expect(() => rt.clearSnapshot()).not.toThrow();
+    expect(rt.readSnapshot()).toBeNull();
+  });
+
+  test("operates as a no-op when no store is provided", () => {
+    const rt = new BrowserRuntime(noopRuntimeArgs({ store: null }));
+    expect(() => rt.persistSnapshot("x")).not.toThrow();
+    expect(() => rt.clearSnapshot()).not.toThrow();
+    expect(rt.readSnapshot()).toBeNull();
+  });
+});
+
+describe("history wiring", () => {
+  test("pushHistory / replaceHistory / historyBack delegate to history", () => {
+    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 } });
+    rt.historyBack({ n: 3 });
+    expect(calls).toEqual([
+      ["push", { x: 1 }, "", "/a"],
+      ["replace", { y: 2 }, "", "/b"],
+      ["go", -3],
+    ]);
+  });
+});
+
+describe("fetch headers", () => {
+  test("sends Accept and X-Modal-Stack-Request headers", async () => {
+    let captured = null;
+    const fetcher = (url, opts) => {
+      captured = { url, opts };
+      return Promise.resolve(new Response("", { status: 500 }));
+    };
+    const rt = new BrowserRuntime(noopRuntimeArgs({ fetcher }));
+    await expect(
+      rt.mountLayer({
+        layerId: "L",
+        url: "/x",
+        depth: 1,
+        variant: "modal",
+        dismissible: true,
+      }),
+    ).rejects.toThrow(/500/);
+    expect(captured.opts.headers[FRAGMENT_HEADER]).toBe("1");
+    expect(captured.opts.headers.Accept).toContain("text/html");
+    expect(captured.opts.credentials).toBe("same-origin");
+  });
+});