jet_ui 0.2.10 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: debfc83f3c33c58716e876a43bab280d430a94fc4682de9b89b0cb605c8359d4
-  data.tar.gz: 5ad38cb1116cb06dfd0b1516ba282213af3a0759e3a3947e548113cf5a24c2d4
+  metadata.gz: aaa259d3afc97d0f95133cdb1f0f4a5ab4ecdb8e202cc3e2915adf675747e8e3
+  data.tar.gz: e67258fe470b32b455ff87ff3c3d2121eba46f5b549cdce377c105e8f9485d9a
 SHA512:
-  metadata.gz: 1cba15b76863db3147f4881a443ecbd2bbf69a4cf5b3f21e05be6987767ae2934e0dfe1700865f659de4b25d2c8c07bc412bf2092be1d63f980244d6670feab5
-  data.tar.gz: 9f336006021e46d6209e1e36c233cf1d44750a893b99945bb7ea6a62bf5a874abfd85ab2fd215cd69a66cc81c068ec4a785f55f18e26accbfb489680fa75f1f1
+  metadata.gz: a4eeb23778ec35b7df6d67d73185851f34bd261d930251159abf6977ed09a2c6deb19adc3112f8f506266d460fea28353a2974db2fb575e33179f109ad10e521
+  data.tar.gz: d6a945c029554f92578e4f32e9cd7c834d8a2d72d1f43497a179d0b92f4a2b7694f8538f093cce1c381f3d93a9ca4ff032f291a9059cb9b5c9d3ad77fb0fe670

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-11
+
+### Added
+- `Dialog` component — unifies `Modal` and `Drawer` into a single component built on the native `<dialog>` element, with five positions (`:center`, `:left`, `:right`, `:top`, `:bottom`) and unlimited nesting of stacked dialogs
+- `Dialogs` mount point component — renders the dialog stack root and the sentinel Turbo Frame that async dialog opens adopt
+- ViewComponent previews for `Alert`, `Badge`, `Group`, and `Stat`
+- `docs/vite.md` — setup and troubleshooting guide for the Vite/npm install path
+
+### Changed
+- README `Installation` section reorganized with a comparison table so Importmap and Vite get equal visual weight, instead of Vite being a subordinate "Alternative:" section
+- Dropped the `Ruby >=`/`Rails >=` badges from the README — duplicated info already in `## Requirements`, and not a pattern followed by comparable Ruby gems
+
+### Deprecated
+- `Modal` and `Drawer` — now thin shims delegating to `Dialog` with `position: :center`/`:right`; emit an `ActiveSupport::Deprecation` warning and will be removed in the next major version. Existing `data: { turbo_frame: :modal }`/`:drawer` links keep working automatically. See [docs/components/dialog.md](docs/components/dialog.md#migrating-from-modaldrawer) for the full migration path
+
+## [0.2.11] - 2026-09-07
+
+### Fixed
+- Rails 7.x test suite broken by Capybara 3.40+ (`quirks_mode` keyword incompatibility) — pin Capybara to `~> 3.36` and JSON to `< 3.0` in development dependencies
+- Gemspec no longer pins an exact Rails development version — the previous exact pin caused a hard `Bundler::GemfileError` against the CI matrix gemfiles on newer Bundler versions
+- Flash component's Stimulus data attributes now use hyphenated keys for Rails 7.1 compatibility
+
+### Added
+- JetUI logo to README
+
 ## [0.2.10] - 2026-08-22
 
 ### Changed

data/README.md

@@ -1,11 +1,10 @@
-# JetUi
+![JetUI Logo](app/assets/images/logo.svg)
 
 [![Gem Version](https://img.shields.io/gem/v/jet_ui)](https://rubygems.org/gems/jet_ui)
 [![Checks](https://img.shields.io/github/actions/workflow/status/jetrockets/jet_ui/ci.yml?label=checks&logo=github)](https://github.com/jetrockets/jet_ui/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE.md)
 [![Downloads](https://img.shields.io/gem/dt/jet_ui)](https://rubygems.org/gems/jet_ui)
-[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D)](https://rubygems.org/gems/jet_ui)
-[![Rails](https://img.shields.io/badge/rails-%3E%3D%207.0-CC0000)](https://rubygems.org/gems/jet_ui)
+[![Stars](https://img.shields.io/github/stars/jetrockets/jet_ui?style=social)](https://github.com/jetrockets/jet_ui/stargazers)
 
 ViewComponent-based UI library for Rails applications, matching the design system at [ui.jetrockets.com](https://ui.jetrockets.com).
 
@@ -18,40 +17,47 @@ ViewComponent-based UI library for Rails applications, matching the design syste
 
 ## Installation
 
-Add to your Gemfile:
+Add the gem to your Gemfile, then run the install generator — it detects how your app manages
+JavaScript and wires jet_ui up accordingly, no flags needed:
 
 ```ruby
 gem "jet_ui"
 ```
 
-Run the install generator:
-
 ```bash
 bundle install
 rails generate jet_ui:install
 ```
 
-The generator:
-- Detects your Tailwind CSS source file and injects a single import covering all component stylesheets
-- Registers JetUi Stimulus controllers in your app's controllers index
+|              | Importmap                                                        | Vite                                                                          |
+|--------------|-------------------------------------------------------------------|---------------------------------------------------------------------------------|
+| **Detected by**  | `config/importmap.rb` present                                  | a Vite config, or `vite` in `package.json`                                      |
+| **JS wiring**    | Automatic — controllers auto-register                          | Manual — you `import` and `application.register(...)` the ones you use          |
+| **CSS wiring**   | Automatic — injected into your Tailwind source                 | Manual — `@import "@jetrockets/jet_ui/css"` in your CSS entry point             |
+| **npm install**  | None needed — the gem ships the controllers itself              | Done for you by the generator (`yarn add @jetrockets/jet_ui`, or your package manager's equivalent) |
 
-When the gem is updated, both CSS and JS are picked up automatically — no further changes needed. Safe to re-run after upgrades.
+Full walkthrough and troubleshooting for the Vite path: [docs/vite.md](docs/vite.md).
 
-### Alternative: npm package (Vite)
+### Importmap
 
-The above (importmap) setup needs no npm install — the gem ships the controllers itself. If your app bundles JavaScript with Vite instead, run the install generator: it detects Vite, **installs the `@jetrockets/jet_ui` npm package** for you (running `yarn add @jetrockets/jet_ui`, or the npm/pnpm/bun equivalent it detects), and prints the wiring steps:
+The generator detects your Tailwind CSS source file and injects a single import covering all
+component stylesheets, and registers JetUi Stimulus controllers in your app's controllers index.
+When the gem is updated, both CSS and JS are picked up automatically — no further changes needed.
+Safe to re-run after upgrades.
 
-```bash
-rails generate jet_ui:install
-# detects Vite → runs: yarn add @jetrockets/jet_ui
-```
+### Vite
+
+The generator detects Vite and installs the `@jetrockets/jet_ui` npm package for you. Vite apps
+own their JS/CSS entry points, so those are not modified automatically — wire up the two pieces
+yourself:
 
-Then register the controllers you use (`@hotwired/stimulus` is a peer dependency):
+Register the controllers you use (`@hotwired/stimulus` is a peer dependency):
 
 ```javascript
-import { ModalController } from "@jetrockets/jet_ui"
+import { DialogController, DialogsController } from "@jetrockets/jet_ui"
 
-application.register("modal", ModalController)
+application.register("dialog", DialogController)
+application.register("dialogs", DialogsController)
 ```
 
 Import the component styles in your Tailwind/CSS entry point:
@@ -67,6 +73,8 @@ import "@jetrockets/jet_ui/css"          // all component styles
 import "@jetrockets/jet_ui/css/btn.css"  // a single component
 ```
 
+See [docs/vite.md](docs/vite.md) for detection details and troubleshooting.
+
 ## Usage
 
 The `jet_ui` helper is available in all views:
@@ -112,8 +120,9 @@ Subcomponents follow the `namespace_subcomponent` naming convention (`card_heade
 | Sidebar | [docs/components/sidebar.md](docs/components/sidebar.md) |
 | Header | [docs/components/header.md](docs/components/header.md) |
 | Navbar | [docs/components/navbar.md](docs/components/navbar.md) |
-| Modal ⚡ | [docs/components/modal.md](docs/components/modal.md) |
-| Drawer ⚡ | [docs/components/drawer.md](docs/components/drawer.md) |
+| Dialog ⚡ | [docs/components/dialog.md](docs/components/dialog.md) |
+| Modal ⚡ (deprecated, use Dialog) | [docs/components/modal.md](docs/components/modal.md) |
+| Drawer ⚡ (deprecated, use Dialog) | [docs/components/drawer.md](docs/components/drawer.md) |
 | Dropdown ⚡ | [docs/components/dropdown.md](docs/components/dropdown.md) |
 | Tooltip ⚡ | [docs/components/tooltip.md](docs/components/tooltip.md) |
 | Popover ⚡ | [docs/components/popover.md](docs/components/popover.md) |

data/app/assets/images/logo.svg

@@ -0,0 +1,25 @@
+<svg width="179" height="58" viewBox="0 0 179 58" fill="none" xmlns="http://www.w3.org/2000/svg">
+<style>
+  @media (prefers-color-scheme: dark) {
+    path { fill: white !important; stroke: white !important; }
+    path[fill="#FF5B1F"] { fill: #FF5B1F !important; }
+  }
+  @media (prefers-color-scheme: light) {
+    path { fill: #1A1A1A !important; stroke: #1A1A1A !important; }
+    path[fill="#FF5B1F"] { fill: #FF5B1F !important; }
+  }
+</style>
+<g clip-path="url(#clip0_18891_31745)">
+<path d="M12 2H46C51.5228 2 56 6.47715 56 12V46C56 51.5228 51.5228 56 46 56H12C6.47715 56 2 51.5228 2 46V12C2 6.47715 6.47715 2 12 2Z" stroke="#1A1A1A" stroke-width="4"/>
+<path d="M21 11H11C9.34315 11 8 12.3431 8 14V24C8 25.6569 9.34315 27 11 27H21C22.6569 27 24 25.6569 24 24V14C24 12.3431 22.6569 11 21 11Z" fill="#1A1A1A"/>
+<path d="M47.375 11H31.625C30.1753 11 29 11.8954 29 13V15C29 16.1046 30.1753 17 31.625 17H47.375C48.8247 17 50 16.1046 50 15V13C50 11.8954 48.8247 11 47.375 11Z" fill="#1A1A1A"/>
+<path opacity="0.4" d="M40.4545 21H31.5455C30.1396 21 29 21.8954 29 23V25C29 26.1046 30.1396 27 31.5455 27H40.4545C41.8604 27 43 26.1046 43 25V23C43 21.8954 41.8604 21 40.4545 21Z" fill="#1A1A1A"/>
+<path d="M46.5 31H11.5C9.567 31 8 32.3431 8 34V44C8 45.6569 9.567 47 11.5 47H46.5C48.433 47 50 45.6569 50 44V34C50 32.3431 48.433 31 46.5 31Z" fill="#FF5B1F"/>
+<path d="M83.214 42.588C80.19 42.588 77.782 41.762 75.99 40.11C74.226 38.458 73.344 36.148 73.344 33.18V30.408H78.888V33.18C78.888 34.496 79.252 35.532 79.98 36.288C80.708 37.016 81.73 37.38 83.046 37.38C84.278 37.38 85.23 37.016 85.902 36.288C86.602 35.56 86.952 34.524 86.952 33.18V17.64H81.912V12.6H95.856V17.64H92.496V33.18C92.496 36.232 91.67 38.57 90.018 40.194C88.366 41.79 86.098 42.588 83.214 42.588ZM108.467 42.588C106.395 42.588 104.561 42.154 102.965 41.286C101.397 40.39 100.165 39.144 99.2692 37.548C98.4012 35.924 97.9672 34.02 97.9672 31.836V31.332C97.9672 29.148 98.4012 27.258 99.2692 25.662C100.137 24.038 101.355 22.792 102.923 21.924C104.491 21.028 106.311 20.58 108.383 20.58C110.427 20.58 112.205 21.042 113.717 21.966C115.229 22.862 116.405 24.122 117.245 25.746C118.085 27.342 118.505 29.204 118.505 31.332V33.138H103.343C103.399 34.566 103.931 35.728 104.939 36.624C105.947 37.52 107.179 37.968 108.635 37.968C110.119 37.968 111.211 37.646 111.911 37.002C112.611 36.358 113.143 35.644 113.507 34.86L117.833 37.128C117.441 37.856 116.867 38.654 116.111 39.522C115.383 40.362 114.403 41.09 113.171 41.706C111.939 42.294 110.371 42.588 108.467 42.588ZM103.385 29.19H113.129C113.017 27.986 112.527 27.02 111.659 26.292C110.819 25.564 109.713 25.2 108.341 25.2C106.913 25.2 105.779 25.564 104.939 26.292C104.099 27.02 103.581 27.986 103.385 29.19ZM130.498 42C129.126 42 128.006 41.58 127.138 40.74C126.298 39.872 125.878 38.724 125.878 37.296V25.536H120.67V21.168H125.878V14.7H131.17V21.168H136.882V25.536H131.17V36.372C131.17 37.212 131.562 37.632 132.346 37.632H136.378V42H130.498ZM152.844 42.588C150.436 42.588 148.364 42.154 146.628 41.286C144.92 40.39 143.604 39.13 142.68 37.506C141.784 35.854 141.336 33.908 141.336 31.668V12.6H146.88V31.836C146.88 33.628 147.384 35.042 148.392 36.078C149.428 37.114 150.912 37.632 152.844 37.632C154.776 37.632 156.246 37.114 157.254 36.078C158.29 35.042 158.808 33.628 158.808 31.836V12.6H164.352V31.668C164.352 33.908 163.89 35.854 162.966 37.506C162.07 39.13 160.754 40.39 159.018 41.286C157.31 42.154 155.252 42.588 152.844 42.588ZM169.723 42V12.6H175.267V42H169.723Z" fill="#1A1A1A"/>
+</g>
+<defs>
+<clipPath id="clip0_18891_31745">
+<rect width="179" height="58"/>
+</clipPath>
+</defs>
+</svg>

data/app/assets/javascripts/jet_ui/dialog_controller.js

@@ -0,0 +1,95 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Per-dialog behaviour: backdrop click / swipe-to-dismiss / Esc handling for a single
+// <dialog>. Opening, stacking and DOM cleanup are owned by DialogsController — this
+// controller only reacts to interactions on an already-mounted dialog.
+export default class DialogController extends Controller {
+  static targets = ["panel"]
+
+  static values = {
+    position: { type: String, default: "center" },
+    dismissible: { type: Boolean, default: true },
+    swipe: { type: Boolean, default: false },
+    swipeThreshold: { type: Number, default: 100 }
+  }
+
+  #touchStart = 0
+
+  connect() {
+    this.element.addEventListener("click", this.#handleBackdropClick)
+    this.element.addEventListener("cancel", this.#handleCancel)
+
+    if (this.swipeValue) {
+      this.element.addEventListener("touchstart", this.#handleTouchStart, { passive: true })
+      this.element.addEventListener("touchmove", this.#handleTouchMove, { passive: true })
+      this.element.addEventListener("touchend", this.#handleTouchEnd, { passive: true })
+    }
+  }
+
+  disconnect() {
+    this.element.removeEventListener("click", this.#handleBackdropClick)
+    this.element.removeEventListener("cancel", this.#handleCancel)
+    this.element.removeEventListener("touchstart", this.#handleTouchStart)
+    this.element.removeEventListener("touchmove", this.#handleTouchMove)
+    this.element.removeEventListener("touchend", this.#handleTouchEnd)
+  }
+
+  close() {
+    try {
+      this.element.close()
+    } catch (e) {}
+  }
+
+  #handleBackdropClick = (event) => {
+    if (event.target === this.element && this.dismissibleValue) {
+      this.close()
+    }
+  }
+
+  #handleCancel = (event) => {
+    if (!this.dismissibleValue) event.preventDefault()
+  }
+
+  #axis() {
+    return this.positionValue === "top" || this.positionValue === "bottom" ? "y" : "x"
+  }
+
+  // Sign of the direction that counts as "swiping the panel away".
+  #sign() {
+    return { left: -1, right: 1, top: -1, bottom: 1 }[this.positionValue] ?? 1
+  }
+
+  #coordinate(touch) {
+    return this.#axis() === "x" ? touch.clientX : touch.clientY
+  }
+
+  #translate(value, unit) {
+    return this.#axis() === "x" ? `translateX(${value}${unit})` : `translateY(${value}${unit})`
+  }
+
+  #handleTouchStart = (event) => {
+    if (!this.hasPanelTarget) return
+    this.#touchStart = this.#coordinate(event.touches[0])
+    this.panelTarget.style.transition = "none"
+  }
+
+  #handleTouchMove = (event) => {
+    if (!this.hasPanelTarget) return
+    const delta = (this.#coordinate(event.touches[0]) - this.#touchStart) * this.#sign()
+    const clamped = Math.max(0, delta)
+    this.panelTarget.style.transform = this.#translate(clamped * this.#sign(), "px")
+  }
+
+  #handleTouchEnd = (event) => {
+    if (!this.hasPanelTarget) return
+    const delta = (this.#coordinate(event.changedTouches[0]) - this.#touchStart) * this.#sign()
+    this.panelTarget.style.transition = "transform 0.2s ease-out"
+
+    if (delta > this.swipeThresholdValue) {
+      this.panelTarget.style.transform = this.#translate(this.#sign() * 100, "%")
+      this.panelTarget.addEventListener("transitionend", () => this.close(), { once: true })
+    } else {
+      this.panelTarget.style.transform = this.#translate(0, "px")
+    }
+  }
+}

data/app/assets/javascripts/jet_ui/dialogs_controller.js

@@ -0,0 +1,248 @@
+import { Controller } from "@hotwired/stimulus"
+
+const FRAME_ID = "dialog"
+const DEFAULT_POSITION = "center"
+const DEFAULT_SIZE = "2xl"
+const HORIZONTAL_POSITIONS = ["top", "bottom"]
+
+// Legacy `data-turbo-frame` values kept working after the Modal/Drawer → Dialog unification.
+// Each alias presets a position and is rewritten to the real frame id ("dialog") before Turbo
+// resolves it, so existing async links need no edits — see docs/components/dialog.md.
+const FRAME_ALIASES = {
+  dialog: DEFAULT_POSITION,
+  modal: "center",
+  drawer: "right"
+}
+
+// Stack manager for every <dialog> on the page — sync (declared inline with an `id`) and
+// remote (opened via a link/form with data-turbo-frame="dialog", or the deprecated "modal"/
+// "drawer" aliases). Unlimited nesting works because the manager, not any single dialog, owns
+// depth tracking, the flash portal and the "sentinel" <turbo-frame id="dialog"> that every
+// async open adopts.
+export default class DialogsController extends Controller {
+  static targets = ["root", "sentinel", "dialog"]
+
+  #stack = []
+  #frameCounter = 0
+
+  connect() {
+    window.addEventListener("click", this.#interceptTrigger, { capture: true })
+    window.addEventListener("submit", this.#interceptTrigger, { capture: true })
+    document.addEventListener("turbo:frame-load", this.#handleFrameLoad)
+    document.addEventListener("turbo:frame-missing", this.#handleFrameMissing)
+    document.addEventListener("turbo:fetch-request-error", this.#handleFrameMissing)
+    document.addEventListener("turbo:before-visit", this.closeAll)
+    document.addEventListener("turbo:before-cache", this.closeAll)
+    document.addEventListener("turbo:before-render", this.#handleBeforeRender)
+    document.addEventListener("turbo:render", this.#handleRender)
+  }
+
+  disconnect() {
+    window.removeEventListener("click", this.#interceptTrigger, { capture: true })
+    window.removeEventListener("submit", this.#interceptTrigger, { capture: true })
+    document.removeEventListener("turbo:frame-load", this.#handleFrameLoad)
+    document.removeEventListener("turbo:frame-missing", this.#handleFrameMissing)
+    document.removeEventListener("turbo:fetch-request-error", this.#handleFrameMissing)
+    document.removeEventListener("turbo:before-visit", this.closeAll)
+    document.removeEventListener("turbo:before-cache", this.closeAll)
+    document.removeEventListener("turbo:before-render", this.#handleBeforeRender)
+    document.removeEventListener("turbo:render", this.#handleRender)
+  }
+
+  // Sync open — data-action="click->dialogs#open" data-id="myDialog" on the trigger.
+  open(event) {
+    const id = event.currentTarget.dataset.id
+    const dialog = this.dialogTargets.find((d) => d.id === id)
+    if (!dialog || this.#stack.includes(dialog)) return
+
+    this.#push(dialog, { remote: false })
+  }
+
+  closeAll = () => {
+    // Copy first: closing dispatches 'close' synchronously, which mutates #stack.
+    ;[...this.#stack].reverse().forEach((dialog) => dialog.close())
+  }
+
+  // --- async open: adopt the sentinel frame before Turbo navigates it ---------------------
+
+  #interceptTrigger = (event) => {
+    const frameName = this.#resolveFrameName(event)
+    if (!(frameName in FRAME_ALIASES)) return
+    if (!this.hasSentinelTarget) return
+    if (this.#opensInNewTab(event)) return
+
+    const sentinel = this.sentinelTarget
+    if (sentinel.dataset.pending === "true") return // already adopted, let Turbo re-navigate it
+
+    const trigger = this.#resolveTrigger(event)
+    const position = trigger?.dataset.dialogPosition || FRAME_ALIASES[frameName]
+    const size = trigger?.dataset.dialogSize || DEFAULT_SIZE
+    const dismissible = trigger?.dataset.dialogDismissible !== "false"
+
+    // Deprecated aliases ("modal"/"drawer") point at a frame id that no longer exists in the
+    // DOM — only the "dialog" sentinel does. Rewrite the trigger before Turbo reads it (we run
+    // first, same capture phase) so its own getElementById(frameName) lookup still finds it.
+    // Persist the resolved position on the trigger too: once data-turbo-frame becomes "dialog"
+    // it no longer carries the alias, so without this a second click on the same trigger would
+    // resolve to the "dialog" default position instead of the alias's preset.
+    if (frameName !== FRAME_ID) {
+      this.#rewriteFrameName(event, trigger)
+      if (trigger && !trigger.dataset.dialogPosition) trigger.dataset.dialogPosition = position
+    }
+
+    sentinel.dataset.pending = "true"
+
+    const shell = this.#buildShell({ position, size, dismissible })
+    shell.append(sentinel)
+    this.rootTarget.append(shell)
+
+    this.#push(shell, { remote: true })
+  }
+
+  // A modified click (Cmd/Ctrl/Shift/Alt, middle-click) or a link with target/download makes
+  // the browser open a new tab/window instead of navigating in place — Turbo itself ignores
+  // these clicks and lets the browser handle them, so we must too, or we'd adopt the sentinel
+  // and show an overlay for a navigation that never actually happens on this page.
+  #opensInNewTab(event) {
+    if (event.type !== "click") return false
+    if (event.button !== 0) return true
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return true
+
+    const trigger = this.#resolveTrigger(event)
+    const target = trigger?.getAttribute?.("target")
+    if (target && target !== "_self") return true
+
+    return trigger?.hasAttribute?.("download") ?? false
+  }
+
+  #resolveFrameName(event) {
+    if (event.type === "submit") {
+      const form = event.target
+      return event.submitter?.dataset.turboFrame || form?.dataset.turboFrame || null
+    }
+
+    const trigger = event.target?.closest?.("[data-turbo-frame]")
+    return trigger?.dataset.turboFrame || null
+  }
+
+  #resolveTrigger(event) {
+    if (event.type === "submit") {
+      return event.submitter?.dataset.turboFrame ? event.submitter : event.target
+    }
+
+    return event.target?.closest?.("[data-turbo-frame]") || null
+  }
+
+  #rewriteFrameName(event, trigger) {
+    if (!trigger) return
+    trigger.dataset.turboFrame = FRAME_ID
+  }
+
+  #buildShell({ position, size, dismissible }) {
+    const horizontal = HORIZONTAL_POSITIONS.includes(position)
+    const edge = position !== DEFAULT_POSITION
+
+    const dialog = document.createElement("dialog")
+    dialog.tabIndex = -1
+    dialog.className = `dialog dialog-${position} ${horizontal ? "h" : "w"}-${size}`
+    dialog.dataset.controller = "dialog"
+    dialog.dataset.dialogPositionValue = position
+    dialog.dataset.dialogDismissibleValue = String(dismissible)
+    dialog.dataset.dialogSwipeValue = String(edge)
+    return dialog
+  }
+
+  #handleFrameLoad = (event) => {
+    const frame = event.target
+    if (frame?.tagName !== "TURBO-FRAME") return
+    if (frame.id !== FRAME_ID) return
+
+    delete frame.dataset.pending
+    delete frame.dataset.dialogsTarget
+    frame.id = `${FRAME_ID}-${++this.#frameCounter}`
+
+    this.#respawnSentinel()
+    this.#portalFlash()
+  }
+
+  #handleFrameMissing = (event) => {
+    const frame = event.target
+    if (frame?.tagName !== "TURBO-FRAME") return
+    if (!new RegExp(`^${FRAME_ID}(-\\d+)?$`).test(frame.id)) return
+
+    const shell = frame.closest("dialog.dialog")
+    if (!shell) return
+
+    if (frame.id === FRAME_ID) this.#respawnSentinel()
+    shell.close()
+  }
+
+  #respawnSentinel() {
+    const sentinel = document.createElement("turbo-frame")
+    sentinel.id = FRAME_ID
+    sentinel.dataset.dialogsTarget = "sentinel"
+    this.rootTarget.append(sentinel)
+  }
+
+  // --- stack bookkeeping -------------------------------------------------------------------
+
+  #push(dialog, { remote }) {
+    dialog.dataset.remote = String(remote)
+    this.#stack.push(dialog)
+    this.#renumber()
+
+    dialog.addEventListener("close", this.#handleDialogClosed, { once: true })
+    dialog.showModal()
+
+    this.#portalFlash()
+    dialog.dispatchEvent(new CustomEvent("jet-ui:dialog:opened", {
+      bubbles: true,
+      detail: { depth: this.#stack.indexOf(dialog), position: dialog.dataset.dialogPositionValue }
+    }))
+  }
+
+  #handleDialogClosed = (event) => {
+    const dialog = event.target
+    const index = this.#stack.indexOf(dialog)
+    if (index === -1) return
+
+    this.#stack.splice(index, 1)
+    this.#renumber()
+
+    dialog.dispatchEvent(new CustomEvent("jet-ui:dialog:closed", { bubbles: true }))
+
+    if (dialog.dataset.remote === "true") dialog.remove()
+
+    this.#portalFlash()
+  }
+
+  #renumber() {
+    this.#stack.forEach((dialog, index) => { dialog.dataset.depth = String(index) })
+  }
+
+  // --- flash portal --------------------------------------------------------------------------
+  // The topmost open dialog is promoted to the browser's top layer, which makes everything
+  // outside it inert — a flash frame left in <body> would be invisible and unclickable.
+  // We move #flash into the topmost dialog's .dialog__flash-slot instead (see dialog.css).
+
+  #portalFlash = () => {
+    const flashFrame = document.getElementById("flash")
+    if (!flashFrame) return
+
+    const top = this.#stack.at(-1)
+    const target = top ? top.querySelector(".dialog__flash-slot") : document.body
+    if (target && flashFrame.parentElement !== target) target.append(flashFrame)
+  }
+
+  // #dialogs is data-turbo-permanent so open dialogs survive a morph refresh — but that also
+  // means Turbo won't merge a fresh #flash into a copy that is currently portaled inside it.
+  // Pull it back out to <body> before every render, then re-portal it after.
+  #handleBeforeRender = () => {
+    const flashFrame = document.getElementById("flash")
+    if (flashFrame && flashFrame.parentElement !== document.body) document.body.append(flashFrame)
+  }
+
+  #handleRender = () => {
+    this.#portalFlash()
+  }
+}

data/app/assets/javascripts/jet_ui/drawer_controller.js

@@ -1,5 +1,11 @@
 import { Controller } from "@hotwired/stimulus"
 
+// @deprecated Only the async (Turbo Frame) dialog markup rendered by JetUi::Dialog::Component
+// still uses "modal"/"drawer" as data-turbo-frame aliases — those keep working automatically,
+// handled by DialogsController. This standalone controller matches the pre-Dialog async drawer
+// markup and is no longer wired up by JetUi::Drawer::Component. Kept only for apps with custom
+// markup still registering it directly. Migrate to the "dialog" controller. Removed in the
+// next major version.
 export default class DrawerController extends Controller {
   static values = {
     swipeThreshold: { type: Number, default: 100 }

data/app/assets/javascripts/jet_ui/drawers_controller.js

@@ -1,5 +1,10 @@
 import { Controller } from "@hotwired/stimulus"
 
+// @deprecated JetUi::Drawer::Component's sync-mode markup now targets
+// data-dialogs-target="dialog" (see JetUi::Dialog::Component), not
+// data-drawers-target="dialog" — this controller no longer matches it. Migrate your
+// data-controller="drawers" wrapper and click->drawers#open actions to "dialogs" /
+// click->dialogs#open. Removed in the next major version.
 export default class DrawersController extends Controller {
   static targets = ["dialog"]
   static values = {

data/app/assets/javascripts/jet_ui/modal_controller.js

@@ -1,5 +1,11 @@
 import { Controller } from "@hotwired/stimulus"
 
+// @deprecated Only the async (Turbo Frame) dialog markup rendered by JetUi::Dialog::Component
+// still uses "modal"/"drawer" as data-turbo-frame aliases — those keep working automatically,
+// handled by DialogsController. This standalone controller matches the pre-Dialog async modal
+// markup and is no longer wired up by JetUi::Modal::Component. Kept only for apps with custom
+// markup still registering it directly. Migrate to the "dialog" controller. Removed in the
+// next major version.
 export default class ModalController extends Controller {
   connect() {
     this.element.addEventListener("click", this.#closeOnBackdropClick.bind(this))

data/app/assets/javascripts/jet_ui/modals_controller.js

@@ -1,5 +1,10 @@
 import { Controller } from "@hotwired/stimulus"
 
+// @deprecated JetUi::Modal::Component's sync-mode markup now targets
+// data-dialogs-target="dialog" (see JetUi::Dialog::Component), not
+// data-modals-target="dialog" — this controller no longer matches it. Migrate your
+// data-controller="modals" wrapper and click->modals#open actions to "dialogs" /
+// click->dialogs#open. Removed in the next major version.
 export default class ModalsController extends Controller {
   static targets = ["dialog"]