modal_stack 0.1.1

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

@@ -0,0 +1,219 @@
+/*
+ * modal_stack — Vanilla preset
+ *
+ * Pure CSS, no framework dependency. Override any of the
+ * --modal-stack-* tokens on :root to retheme.
+ *
+ * Variants:    [data-variant="modal" | "drawer" | "bottom_sheet" | "confirmation"]
+ * Drawer side: [data-side="left" | "right"]
+ * Sizes:       [data-modal-stack-size="sm" | "md" | "lg" | "xl"]
+ */
+
+:root {
+  --modal-stack-z-base: 1000;
+  --modal-stack-duration: 220ms;
+  --modal-stack-ease: cubic-bezier(0.16, 1, 0.3, 1);
+  --modal-stack-radius: 8px;
+  --modal-stack-bg: #ffffff;
+  --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;
+  --modal-stack-panel-padding: 20px;
+  --modal-stack-size-sm: 320px;
+  --modal-stack-size-md: 480px;
+  --modal-stack-size-lg: 720px;
+  --modal-stack-size-xl: 960px;
+  --modal-stack-drawer-width: 400px;
+}
+
+body[data-modal-stack-locked] {
+  overflow: hidden;
+  padding-right: var(--modal-stack-scrollbar-width, 0);
+}
+
+#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(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));
+}
+
+@starting-style {
+  #modal-stack-root[open]::backdrop {
+    background: rgba(0, 0, 0, 0);
+    backdrop-filter: blur(0);
+  }
+}
+
+[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),
+    filter 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;
+  filter: blur(0.5px);
+}
+
+[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); }
+
+[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);
+}
+
+[data-modal-stack-target="layer"][data-variant="drawer"] {
+  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;
+}
+
+@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="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="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%);
+}
+
+[data-modal-stack-target="layer"][data-variant="confirmation"] {
+  width: var(--modal-stack-size-sm);
+}
+
+.modal-stack__panel {
+  padding: var(--modal-stack-panel-padding);
+  display: grid;
+  gap: 12px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  #modal-stack-root,
+  #modal-stack-root::backdrop,
+  [data-modal-stack-target="layer"] {
+    transition-duration: 1ms !important;
+  }
+}

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

@@ -0,0 +1,149 @@
+import { Controller } from "@hotwired/stimulus";
+import { Orchestrator } from "../orchestrator.js";
+import { BrowserRuntime } from "../runtime.js";
+
+export class ModalStackController extends Controller {
+  static values = {
+    stackId: String,
+    baseUrl: String,
+  };
+
+  connect() {
+    const stackId = this.stackIdValue || generateLayerId();
+    const baseUrl = this.baseUrlValue || window.location.href;
+
+    this.runtime = new BrowserRuntime({ dialog: this.element });
+    const snapshot = this.runtime.readSnapshot();
+
+    this.orchestrator = new Orchestrator({
+      runtime: this.runtime,
+      stackId,
+      baseUrl,
+      restoreFrom: snapshot,
+    });
+
+    this._onPopstate = (event) =>
+      this.orchestrator.onPopstate({
+        historyState: event.state,
+        locationHref: window.location.href,
+      });
+    window.addEventListener("popstate", this._onPopstate);
+
+    this._onCancel = (event) => {
+      event.preventDefault();
+      const top = this.#topLayer();
+      if (!top || top.dismissible === false) return;
+      this.orchestrator.pop();
+    };
+    this.element.addEventListener("cancel", this._onCancel);
+
+    this._onBackdropClick = (event) => {
+      if (event.target !== this.element) return;
+      const top = this.#topLayer();
+      if (!top || top.dismissible === false) return;
+      this.orchestrator.pop();
+    };
+    this.element.addEventListener("click", this._onBackdropClick);
+
+    this.#registerStreamActions();
+    this.element.dispatchEvent(
+      new CustomEvent("modal_stack:ready", { bubbles: true, detail: { stackId } }),
+    );
+  }
+
+  disconnect() {
+    window.removeEventListener("popstate", this._onPopstate);
+    this.element.removeEventListener("cancel", this._onCancel);
+    this.element.removeEventListener("click", this._onBackdropClick);
+  }
+
+  push(layer, opts) {
+    return this.orchestrator.push(layer, opts);
+  }
+
+  pop() {
+    return this.orchestrator.pop();
+  }
+
+  replaceTop(patch, opts) {
+    return this.orchestrator.replaceTop(patch, opts);
+  }
+
+  closeAll() {
+    return this.orchestrator.closeAll();
+  }
+
+  #topLayer() {
+    const layers = this.orchestrator.layers;
+    return layers[layers.length - 1] ?? null;
+  }
+
+  #registerStreamActions() {
+    const Turbo = globalThis.Turbo;
+    if (!Turbo) {
+      console.warn(
+        "[modal_stack] Turbo is not loaded; modal_push/pop/replace stream actions are disabled. " +
+          "Ensure turbo-rails (or @hotwired/turbo) loads before modal_stack.",
+      );
+      return;
+    }
+    const StreamActions = Turbo.StreamActions || (Turbo.StreamActions = {});
+    const orchestrator = this.orchestrator;
+
+    StreamActions.modal_push = function modalPush() {
+      orchestrator.push(layerFromStreamElement(this), {
+        fragment: this.templateContent.cloneNode(true),
+      });
+    };
+
+    StreamActions.modal_pop = function modalPop() {
+      orchestrator.pop();
+    };
+
+    StreamActions.modal_replace = function modalReplace() {
+      orchestrator.replaceTop(layerPatchFromStreamElement(this), {
+        fragment: this.templateContent.cloneNode(true),
+        historyMode: this.dataset.historyMode || "replace",
+      });
+    };
+
+    StreamActions.modal_close_all = function modalCloseAll() {
+      orchestrator.closeAll();
+    };
+  }
+}
+
+function layerFromStreamElement(el) {
+  return {
+    id: el.dataset.layerId || generateLayerId(),
+    url: el.dataset.url || window.location.href,
+    variant: el.dataset.variant || "modal",
+    side: el.dataset.side,
+    size: el.dataset.size,
+    width: el.dataset.width,
+    height: el.dataset.height,
+    dismissible: el.dataset.dismissible !== "false",
+  };
+}
+
+function layerPatchFromStreamElement(el) {
+  const patch = {};
+  if (el.dataset.layerId) patch.id = el.dataset.layerId;
+  if (el.dataset.url) patch.url = el.dataset.url;
+  if (el.dataset.variant) patch.variant = el.dataset.variant;
+  if (el.dataset.side) patch.side = el.dataset.side;
+  if (el.dataset.size) patch.size = el.dataset.size;
+  if (el.dataset.width) patch.width = el.dataset.width;
+  if (el.dataset.height) patch.height = el.dataset.height;
+  if (el.dataset.dismissible != null) {
+    patch.dismissible = el.dataset.dismissible !== "false";
+  }
+  return patch;
+}
+
+function generateLayerId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `ms-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}

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

@@ -0,0 +1,34 @@
+import { Controller } from "@hotwired/stimulus";
+
+export class ModalStackLinkController extends Controller {
+  open(event) {
+    const stack = document.querySelector('[data-controller~="modal-stack"]');
+    if (!stack) return;
+
+    const controller = this.application.getControllerForElementAndIdentifier(
+      stack,
+      "modal-stack",
+    );
+    if (!controller) return;
+
+    event.preventDefault();
+    const ds = this.element.dataset;
+    controller.push({
+      id: generateLayerId(),
+      url: this.element.href,
+      variant: ds.modalStackLinkVariant || "modal",
+      side: ds.modalStackLinkSide,
+      size: ds.modalStackLinkSize,
+      width: ds.modalStackLinkWidth,
+      height: ds.modalStackLinkHeight,
+      dismissible: ds.modalStackLinkDismissible !== "false",
+    });
+  }
+}
+
+function generateLayerId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `ms-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}

data/app/javascript/modal_stack/index.js

@@ -0,0 +1,15 @@
+export {
+  VARIANTS,
+  closeAll,
+  createStack,
+  handlePopstate,
+  pop,
+  push,
+  replaceTop,
+  restore,
+  snapshot,
+  topLayer,
+} from "./state.js";
+
+export { Orchestrator } from "./orchestrator.js";
+export { BrowserRuntime, FRAGMENT_HEADER, SNAPSHOT_KEY } from "./runtime.js";

data/app/javascript/modal_stack/install.js

@@ -0,0 +1,15 @@
+import { ModalStackController } from "./controllers/modal_stack_controller.js";
+import { ModalStackLinkController } from "./controllers/modal_stack_link_controller.js";
+
+export function install(application) {
+  if (!application || typeof application.register !== "function") {
+    throw new Error(
+      "modal_stack: install(application) requires a Stimulus Application instance",
+    );
+  }
+  application.register("modal-stack", ModalStackController);
+  application.register("modal-stack-link", ModalStackLinkController);
+  return application;
+}
+
+export { ModalStackController, ModalStackLinkController };

data/app/javascript/modal_stack/orchestrator.js

@@ -0,0 +1,98 @@
+import {
+  closeAll,
+  createStack,
+  handlePopstate,
+  pop,
+  push,
+  replaceTop,
+  restore,
+  snapshot,
+} from "./state.js";
+
+export class Orchestrator {
+  #expectedPopstates = 0;
+
+  constructor({ runtime, stackId, baseUrl, restoreFrom = null }) {
+    if (!runtime) throw new Error("runtime required");
+    this.runtime = runtime;
+    this.state = createStack({ stackId, baseUrl });
+
+    if (restoreFrom) {
+      const restored = restore(restoreFrom, { stackId });
+      if (restored) this.state = restored;
+    }
+  }
+
+  get layers() {
+    return this.state.layers;
+  }
+
+  get depth() {
+    return this.state.layers.length;
+  }
+
+  async push(layer, { html = null, fragment = null } = {}) {
+    if (fragment == null && html == null && layer?.url) {
+      fragment = await this.#prefetch(layer.url);
+    }
+    return this.#dispatch(push(this.state, layer), { html, fragment });
+  }
+
+  pop() {
+    return this.#dispatch(pop(this.state));
+  }
+
+  async replaceTop(patch, { html = null, fragment = null, ...opts } = {}) {
+    if (fragment == null && html == null && patch?.url) {
+      fragment = await this.#prefetch(patch.url);
+    }
+    return this.#dispatch(replaceTop(this.state, patch, opts), { html, fragment });
+  }
+
+  async #prefetch(url) {
+    if (typeof this.runtime.fetchFragment !== "function") return null;
+    return this.runtime.fetchFragment(url);
+  }
+
+  closeAll() {
+    return this.#dispatch(closeAll(this.state));
+  }
+
+  onPopstate({ historyState, locationHref }) {
+    if (this.#expectedPopstates > 0) {
+      this.#expectedPopstates -= 1;
+      return Promise.resolve();
+    }
+    return this.#dispatch(
+      handlePopstate(this.state, { historyState, locationHref }),
+    );
+  }
+
+  async #dispatch({ state, commands }, payload = {}) {
+    this.state = state;
+    for (const cmd of commands) {
+      if (cmd.type === "mountLayer" || cmd.type === "morphTopLayer") {
+        if (payload.html != null) cmd.html = payload.html;
+        if (payload.fragment != null) cmd.fragment = payload.fragment;
+      }
+      await this.#execute(cmd);
+    }
+  }
+
+  async #execute(cmd) {
+    if (cmd.type === "historyBack") {
+      this.#expectedPopstates += 1;
+    }
+
+    if (cmd.type === "persistSnapshot") {
+      await this.runtime.persistSnapshot?.(snapshot(this.state));
+      return;
+    }
+
+    const handler = this.runtime[cmd.type];
+    if (typeof handler !== "function") {
+      throw new Error(`runtime missing handler for "${cmd.type}"`);
+    }
+    await handler.call(this.runtime, cmd);
+  }
+}