modal_stack 0.1.1 → 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

@@ -6,6 +6,8 @@ export class ModalStackController extends Controller {
   static values = {
     stackId: String,
     baseUrl: String,
+    maxDepth: { type: Number, default: 0 },
+    maxDepthStrategy: { type: String, default: "warn" },
   };
 
   connect() {
@@ -20,6 +22,10 @@ export class ModalStackController extends Controller {
       stackId,
       baseUrl,
       restoreFrom: snapshot,
+      // 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) =>
@@ -73,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;
@@ -89,28 +99,57 @@ export class ModalStackController extends Controller {
     }
     const StreamActions = Turbo.StreamActions || (Turbo.StreamActions = {});
     const orchestrator = this.orchestrator;
-
-    StreamActions.modal_push = function modalPush() {
-      orchestrator.push(layerFromStreamElement(this), {
+    const dialog = this.element;
+
+    // Wraps a stream-action body so a malformed payload (bad data-*, fetch
+    // 500, etc.) doesn't bubble up and break the page. The error is logged
+    // and re-emitted as `modal_stack:error` so apps can surface UI feedback.
+    const guarded = (action, fn) =>
+      function guardedStreamAction() {
+        try {
+          const result = fn.call(this, orchestrator);
+          if (result && typeof result.catch === "function") {
+            result.catch((err) => emitStreamError(dialog, action, err));
+          }
+        } catch (err) {
+          emitStreamError(dialog, action, err);
+        }
+      };
+
+    StreamActions.modal_push = guarded("modal_push", function (orch) {
+      return orch.push(layerFromStreamElement(this), {
         fragment: this.templateContent.cloneNode(true),
       });
-    };
+    });
 
-    StreamActions.modal_pop = function modalPop() {
-      orchestrator.pop();
-    };
+    StreamActions.modal_pop = guarded("modal_pop", function (orch) {
+      return orch.pop();
+    });
 
-    StreamActions.modal_replace = function modalReplace() {
-      orchestrator.replaceTop(layerPatchFromStreamElement(this), {
+    StreamActions.modal_replace = guarded("modal_replace", function (orch) {
+      return orch.replaceTop(layerPatchFromStreamElement(this), {
         fragment: this.templateContent.cloneNode(true),
         historyMode: this.dataset.historyMode || "replace",
       });
-    };
+    });
 
-    StreamActions.modal_close_all = function modalCloseAll() {
-      orchestrator.closeAll();
-    };
+    StreamActions.modal_close_all = guarded("modal_close_all", function (orch) {
+      return orch.closeAll();
+    });
+  }
+}
+
+function emitStreamError(dialog, action, error) {
+  if (typeof console !== "undefined" && console.error) {
+    console.error(`[modal_stack] stream action "${action}" failed:`, error);
   }
+  dialog.dispatchEvent(
+    new CustomEvent("modal_stack:error", {
+      bubbles: true,
+      cancelable: false,
+      detail: { action, error },
+    }),
+  );
 }
 
 function layerFromStreamElement(el) {

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() {