modal_stack 0.2.0 → 0.3.0

data/app/assets/stylesheets/modal_stack/tailwind_v4.css

@@ -0,0 +1,311 @@
+/*
+ * modal_stack — Tailwind v4 preset
+ *
+ * Tailwind v4 exposes its design tokens as native CSS variables via the
+ * `@theme` directive (`--color-*`, `--radius-*`, `--shadow-*`,
+ * `--ease-*`, `--container-*`, …). This preset chains on those so the
+ * modal stack picks up your theme automatically. Fallbacks match the
+ * Tailwind v4 defaults, so the preset still renders correctly when a
+ * project hasn't redefined `@theme` (or isn't running v4 yet).
+ *
+ * Override `--modal-stack-*` on `:root` for modal-specific tweaks
+ * without touching the gem.
+ *
+ * Variants:    [data-variant="modal" | "drawer" | "bottom_sheet" | "confirmation"]
+ * Drawer side: [data-side="left" | "right" | "top" | "bottom"]
+ * Sizes:       [data-modal-stack-size="sm" | "md" | "lg" | "xl"]
+ *
+ * Entry / exit transitions:
+ *   - @starting-style + transition-behavior: allow-discrete (Chrome 117+,
+ *     Safari 17.4+, Firefox 129+).
+ *   - The runtime sets [data-leaving] before unmounting a layer so the
+ *     same transition rules apply on exit.
+ */
+
+:root {
+  --modal-stack-z-base: 1000;
+  --modal-stack-duration: 220ms;
+  --modal-stack-ease: var(--ease-out, cubic-bezier(0.16, 1, 0.3, 1));
+  --modal-stack-radius: var(--radius-2xl, 14px);
+  --modal-stack-bg: var(--color-white, #ffffff);
+  --modal-stack-fg: var(--color-slate-900, #0f172a);
+  --modal-stack-shadow: var(--shadow-2xl, 0 30px 60px -20px rgba(15, 23, 42, 0.35));
+  --modal-stack-backdrop: rgba(15, 23, 42, 0.55);
+  /* `none` by default — `backdrop-filter: blur()` even at radius 0
+   * still allocates a filter layer on the compositor, and animating
+   * a non-zero radius costs ~190ms/frame on Hi-DPI displays. Opt in
+   * with `:root { --modal-stack-backdrop-filter: blur(8px); }` —
+   * the filter is applied statically when the dialog opens (no
+   * per-frame compositor cost). */
+  --modal-stack-backdrop-filter: none;
+  --modal-stack-panel-padding: 24px;
+  --modal-stack-size-sm: var(--container-sm, 24rem);   /* 384px */
+  --modal-stack-size-md: 34rem;                        /* 544px — no v4 container alias */
+  --modal-stack-size-lg: var(--container-3xl, 48rem);  /* 768px */
+  --modal-stack-size-xl: var(--container-5xl, 64rem);  /* 1024px */
+  --modal-stack-drawer-width: var(--container-md, 28rem); /* 448px */
+  --modal-stack-drawer-height: 22rem; /* 352px */
+}
+
+/* --- Body lock when the stack is open ------------------------------- */
+
+body[data-modal-stack-locked] {
+  overflow: hidden;
+  /* Compensate for the scrollbar width to avoid a layout shift. */
+  padding-right: var(--modal-stack-scrollbar-width, 0);
+}
+
+/* --- The single dialog root ---------------------------------------- */
+
+#modal-stack-root {
+  position: fixed;
+  inset: 0;
+  width: 100vw;
+  height: 100vh;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  max-width: none;
+  max-height: none;
+  overflow: visible;
+  z-index: var(--modal-stack-z-base);
+  opacity: 0;
+  transition:
+    opacity var(--modal-stack-duration) var(--modal-stack-ease),
+    overlay var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete,
+    display var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete;
+}
+
+#modal-stack-root[open] {
+  opacity: 1;
+}
+
+@starting-style {
+  #modal-stack-root[open] {
+    opacity: 0;
+  }
+}
+
+#modal-stack-root::backdrop {
+  background: rgba(15, 23, 42, 0);
+  transition:
+    background var(--modal-stack-duration) var(--modal-stack-ease),
+    overlay var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete,
+    display var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete;
+}
+
+#modal-stack-root[open]::backdrop {
+  background: var(--modal-stack-backdrop);
+  /* Static (not in the transition list above). Default is `none` so
+   * Chrome skips the filter pass entirely. Override --modal-stack-
+   * backdrop-filter to opt in. */
+  backdrop-filter: var(--modal-stack-backdrop-filter);
+}
+
+@starting-style {
+  #modal-stack-root[open]::backdrop {
+    background: rgba(15, 23, 42, 0);
+  }
+}
+
+/* --- Layer (one per modal, vertically stacked Z-axis) -------------- */
+
+[data-modal-stack-target="layer"] {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: var(--modal-stack-size-md);
+  max-width: 92vw;
+  max-height: min(85vh, 720px);
+  overflow-y: auto;
+  background: var(--modal-stack-bg);
+  color: var(--modal-stack-fg);
+  border-radius: var(--modal-stack-radius);
+  box-shadow: var(--modal-stack-shadow);
+  padding: 0;
+  transform: translate(-50%, -50%);
+  transition:
+    transform var(--modal-stack-duration) var(--modal-stack-ease),
+    opacity var(--modal-stack-duration) var(--modal-stack-ease);
+}
+
+@starting-style {
+  [data-modal-stack-target="layer"] {
+    opacity: 0;
+    transform: translate(-50%, -44%) scale(0.97);
+  }
+}
+
+[data-modal-stack-target="layer"][data-leaving] {
+  opacity: 0;
+  transform: translate(-50%, -56%) scale(0.97);
+  pointer-events: none;
+}
+
+[data-modal-stack-target="layer"][inert] {
+  opacity: 0.5;
+}
+
+/* --- Sizes via [data-modal-stack-size] ----------------------------- */
+
+[data-modal-stack-target="layer"][data-modal-stack-size="sm"] { width: var(--modal-stack-size-sm); }
+[data-modal-stack-target="layer"][data-modal-stack-size="md"] { width: var(--modal-stack-size-md); }
+[data-modal-stack-target="layer"][data-modal-stack-size="lg"] { width: var(--modal-stack-size-lg); }
+[data-modal-stack-target="layer"][data-modal-stack-size="xl"] { width: var(--modal-stack-size-xl); }
+
+/* --- Subtle depth offset for stacked layers ----------------------- */
+
+[data-modal-stack-target="layer"][data-depth="2"] {
+  transform: translate(-50%, -53%) scale(1.015);
+}
+
+[data-modal-stack-target="layer"][data-depth="3"] {
+  transform: translate(-50%, -56%) scale(1.03);
+}
+
+[data-modal-stack-target="layer"][data-depth="4"] {
+  transform: translate(-50%, -59%) scale(1.045);
+}
+
+/* --- Drawer ------------------------------------------------------- */
+
+[data-modal-stack-target="layer"][data-variant="drawer"] {
+  left: 0;
+  top: 0;
+  max-width: 100vw;
+  max-height: 100vh;
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="right"],
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="left"] {
+  top: 0;
+  height: 100vh;
+  max-height: none;
+  width: var(--modal-stack-drawer-width);
+  max-width: 90vw;
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="right"] {
+  left: auto;
+  right: 0;
+  transform: translateX(0);
+  border-radius: var(--modal-stack-radius) 0 0 var(--modal-stack-radius);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="left"] {
+  left: 0;
+  transform: translateX(0);
+  border-radius: 0 var(--modal-stack-radius) var(--modal-stack-radius) 0;
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="top"] {
+  left: 0;
+  top: 0;
+  width: 100vw;
+  max-width: none;
+  height: var(--modal-stack-drawer-height);
+  max-height: 85vh;
+  transform: translateY(0);
+  border-radius: 0 0 var(--modal-stack-radius) var(--modal-stack-radius);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="bottom"] {
+  left: 0;
+  top: auto;
+  bottom: 0;
+  width: 100vw;
+  max-width: none;
+  height: var(--modal-stack-drawer-height);
+  max-height: 85vh;
+  transform: translateY(0);
+  border-radius: var(--modal-stack-radius) var(--modal-stack-radius) 0 0;
+}
+
+@starting-style {
+  [data-modal-stack-target="layer"][data-variant="drawer"][data-side="right"] {
+    opacity: 0;
+    transform: translateX(100%);
+  }
+  [data-modal-stack-target="layer"][data-variant="drawer"][data-side="left"] {
+    opacity: 0;
+    transform: translateX(-100%);
+  }
+  [data-modal-stack-target="layer"][data-variant="drawer"][data-side="top"] {
+    opacity: 0;
+    transform: translateY(-100%);
+  }
+  [data-modal-stack-target="layer"][data-variant="drawer"][data-side="bottom"] {
+    opacity: 0;
+    transform: translateY(100%);
+  }
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="right"][data-leaving] {
+  opacity: 0;
+  transform: translateX(100%);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="left"][data-leaving] {
+  opacity: 0;
+  transform: translateX(-100%);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="top"][data-leaving] {
+  opacity: 0;
+  transform: translateY(-100%);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"][data-side="bottom"][data-leaving] {
+  opacity: 0;
+  transform: translateY(100%);
+}
+
+/* --- Bottom sheet ------------------------------------------------- */
+
+[data-modal-stack-target="layer"][data-variant="bottom_sheet"] {
+  top: auto;
+  bottom: 0;
+  left: 0;
+  width: 100vw;
+  max-width: none;
+  transform: translate(0, 0);
+  border-radius: var(--modal-stack-radius) var(--modal-stack-radius) 0 0;
+  max-height: 90vh;
+}
+
+@starting-style {
+  [data-modal-stack-target="layer"][data-variant="bottom_sheet"] {
+    opacity: 0;
+    transform: translateY(100%);
+  }
+}
+
+[data-modal-stack-target="layer"][data-variant="bottom_sheet"][data-leaving] {
+  opacity: 0;
+  transform: translateY(100%);
+}
+
+/* --- Confirmation ------------------------------------------------- */
+
+[data-modal-stack-target="layer"][data-variant="confirmation"] {
+  width: var(--modal-stack-size-sm);
+}
+
+/* --- Panel slot (the modal_stack_container output) --------------- */
+
+.modal-stack__panel {
+  padding: var(--modal-stack-panel-padding);
+  display: grid;
+  gap: 14px;
+}
+
+/* --- Reduced motion ---------------------------------------------- */
+
+@media (prefers-reduced-motion: reduce) {
+  #modal-stack-root,
+  #modal-stack-root::backdrop,
+  [data-modal-stack-target="layer"] {
+    transition-duration: 1ms !important;
+  }
+}

data/app/assets/stylesheets/modal_stack/vanilla.css

@@ -18,7 +18,9 @@
   --modal-stack-fg: #1a1a1a;
   --modal-stack-shadow: 0 24px 60px -16px rgba(0, 0, 0, 0.32);
   --modal-stack-backdrop: rgba(0, 0, 0, 0.5);
-  --modal-stack-backdrop-blur: 0;
+  /* Default `none` so Chrome skips the filter pass. Opt in with
+   * `:root { --modal-stack-backdrop-filter: blur(8px); }`. */
+  --modal-stack-backdrop-filter: none;
   --modal-stack-panel-padding: 20px;
   --modal-stack-size-sm: 320px;
   --modal-stack-size-md: 480px;
@@ -60,23 +62,22 @@ body[data-modal-stack-locked] {
 
 #modal-stack-root::backdrop {
   background: rgba(0, 0, 0, 0);
-  backdrop-filter: blur(0);
   transition:
     background var(--modal-stack-duration) var(--modal-stack-ease),
-    backdrop-filter var(--modal-stack-duration) var(--modal-stack-ease),
     overlay var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete,
     display var(--modal-stack-duration) var(--modal-stack-ease) allow-discrete;
 }
 
 #modal-stack-root[open]::backdrop {
   background: var(--modal-stack-backdrop);
-  backdrop-filter: blur(var(--modal-stack-backdrop-blur));
+  /* Static. Default is `none` (no filter pass). Opt in with
+   * --modal-stack-backdrop-filter on :root. */
+  backdrop-filter: var(--modal-stack-backdrop-filter);
 }
 
 @starting-style {
   #modal-stack-root[open]::backdrop {
     background: rgba(0, 0, 0, 0);
-    backdrop-filter: blur(0);
   }
 }
 
@@ -96,8 +97,7 @@ body[data-modal-stack-locked] {
   transform: translate(-50%, -50%);
   transition:
     transform var(--modal-stack-duration) var(--modal-stack-ease),
-    opacity var(--modal-stack-duration) var(--modal-stack-ease),
-    filter var(--modal-stack-duration) var(--modal-stack-ease);
+    opacity var(--modal-stack-duration) var(--modal-stack-ease);
 }
 
 @starting-style {
@@ -115,7 +115,6 @@ body[data-modal-stack-locked] {
 
 [data-modal-stack-target="layer"][inert] {
   opacity: 0.5;
-  filter: blur(0.5px);
 }
 
 [data-modal-stack-target="layer"][data-modal-stack-size="sm"] { width: var(--modal-stack-size-sm); }

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

@@ -79,6 +79,10 @@ export class ModalStackController extends Controller {
     return this.orchestrator.closeAll();
   }
 
+  prefetch(url) {
+    return this.orchestrator.prefetch(url);
+  }
+
   #topLayer() {
     const layers = this.orchestrator.layers;
     return layers[layers.length - 1] ?? null;

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/orchestrator.js

@@ -9,6 +9,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 +27,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 +46,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) {
@@ -92,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));
   }
 
@@ -104,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 }),
     );
@@ -145,3 +216,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";
+}