ultimate_turbo_modal 2.2.2 → 3.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8076c3d9802abd28ef2ff1858b7268f730455c69a214dfb2f8e04d3695c8f68f
-  data.tar.gz: fa211158221a41661229457a63874690eac7e07fb19159045362eb0341d4ccee
+  metadata.gz: 5e555f71c3c4e4ca7af4849d73ab342a1641da8cc3e102d5dafb1048d45b7462
+  data.tar.gz: 8783d6e1d459a6bd02443bb1ff4bbf6b4c1581efe31b9483e7feb9cbb842e99d
 SHA512:
-  metadata.gz: 9414a16b2a0de555727b258403230d5a65564e1158b95c61904cca0fd0b9280fe5433eaeb156962b1dbb1bbcdfe25a86d1ec7b1a65c03209211e5b97abb2fde7
-  data.tar.gz: 783c9c2af43c3b31e8e974642545ac094e2c5faf1925c84947186e215ba809daac4a6236afa7fc1e24768379f1a12376515982a48cd08350274a9a8a2230fc7b
+  metadata.gz: 650f91e9d8eaa38eb5b92bf8a2a090ae7f470ecdb7aca6ae0017adca6967bf973a36b50e4b6acec3aacac0b8fb46dd5022ac453deda60fccecfb868a57234bae
+  data.tar.gz: b93f9c24991c4b8940b4dd13e107de4b4839a5ba7c652d859824effaca64c1135eaab7f63d967eaff81b34fe8e115a61f2265acd59ca9c68e89c5c88935e21ac

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 4.0
 
 require:
   - standard

data/.ruby-version

@@ -1 +1 @@
-ruby-3.2.0
+ruby-4.0.1

data/.standard.yml

@@ -1,9 +1,9 @@
-ruby_version: 3.2.0
+ruby_version: 4.0.0
 parallel: true
 formatter: progress
 plugins:
   - standard-rails:
-      target_rails_version: 7.0
+      target_rails_version: 8.0
 
 ignore:
   - 'vendor/**/*'

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [3.0.0] - Unreleased
+
+- **BREAKING**: Replaced div-based modal with native HTML `<dialog>` element. 
+- **BREAKING**: If you customized the look and feel of a flavor, you'll need to reapply your customizations since the underlying markup has changed.
+- **BREAKING**: Removed Tailwind v3 flavor. Use the `tailwind` flavor (Tailwind v4+) or `custom` to define your own classes.
+- **BREAKING**: Configuration options are now split between `config.modal` and `config.drawer` blocks instead of flat on the config object. See UPGRADING.md for migration details.
+- **BREAKING**: Rails 8+ now required.
+- Added support for slide-out drawers with separate default configuration.
+- Smooth redirect behavior: same-page redirects morph content behind modal/drawer before closing; different-page redirects close modal/drawer with animation before navigating.
+- Removed `el-transition` and `focus-trap` npm dependencies.
+- ... plus a million tweaks, optimizations, refactors, etc.
+
 ## [2.2.2] - 2026-03-12
 
 - Added `close` function on Stimulus Controller. Thanks @bendangelo

data/Gemfile.lock

@@ -1,11 +1,11 @@
 PATH
   remote: .
   specs:
-    ultimate_turbo_modal (2.2.2)
-      actionpack
-      activesupport
-      phlex-rails
-      railties
+    ultimate_turbo_modal (3.0.0.beta.2)
+      actionpack (>= 8.0)
+      activesupport (>= 8.0)
+      phlex-rails (>= 2.0)
+      railties (>= 8.0)
       stimulus-rails
       turbo-rails
 
@@ -60,18 +60,20 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.13.2)
+    json (2.19.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
     loofah (2.24.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    minitest (5.25.5)
-    nokogiri (1.18.9-arm64-darwin)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    nokogiri (1.19.2-arm64-darwin)
       racc (~> 1.4)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.2)
       ast (~> 2.4.1)
       racc
     phlex (2.3.1)
@@ -83,7 +85,7 @@ GEM
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
-    prism (1.4.0)
+    prism (1.9.0)
     psych (5.2.6)
       date
       stringio
@@ -116,10 +118,10 @@ GEM
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
-    regexp_parser (2.11.0)
+    regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
-    rubocop (1.75.8)
+    rubocop (1.84.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -127,16 +129,16 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.46.0)
+    rubocop-ast (1.49.1)
       parser (>= 3.3.7.2)
-      prism (~> 1.4)
-    rubocop-performance (1.25.0)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rails (2.31.0)
       activesupport (>= 4.2.0)
       lint_roller (~> 1.1)
@@ -145,18 +147,18 @@ GEM
       rubocop-ast (>= 1.38.0, < 2.0)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    standard (1.50.0)
+    standard (1.54.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.75.5)
+      rubocop (~> 1.84.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.8.0)
+    standard-performance (1.9.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.25.0)
+      rubocop-performance (~> 1.26.0)
     standard-rails (1.4.0)
       lint_roller (~> 1.0)
       rubocop-rails (~> 2.31.0)
@@ -169,9 +171,9 @@ GEM
       railties (>= 7.1.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.1.4)
-      unicode-emoji (~> 4.0, >= 4.0.4)
-    unicode-emoji (4.0.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
     uri (1.0.3)
     useragent (0.16.11)
     zeitwerk (2.7.3)
@@ -180,6 +182,7 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  arm64-darwin-25
 
 DEPENDENCIES
   rake (~> 13.0)

data/LLM/UPGRADE-TO-VERSION-3.md

@@ -0,0 +1,38 @@
+  # Upgrading a Ruby on Rails application from Ultimate Turbo Modal (UTMR) version 2 to version 3.
+
+  ## Minimum requirements
+
+  - Ruby 3.2 and above.
+  - Rails 8 and above.
+  - If the application uses Tailwind CSS, version 4 is now required. Tailwind 3 is deprecated. (breaking change)
+  - `ultimate_turbo_modal` should be present in the host application's Gemfile. Otherwise, it hasn't been installed yet. User should follow installation steps instead.
+
+  ## Important notes
+
+  - Before starting with the upgrade, run `bundle exec rails runner "puts UltimateTurboModal.flavor"` to detect which flavor the host application is using. `tailwind3` is now deprecated. If the host application is using `tailwind3`, inform the user that it is no longer supported, and that the host application should upgrade to TailwindCSS 4 first.
+  - If the flavor is different from the built-in `tailwind` or `vanilla`, they should be informed that they will need to reapply their custom styling changes manually since the HTML markup for UTMR has changed significantly.
+  - If the application is using the `tailwind` or `vanilla`, no manual styling changes are required. The upgrade will be seamless.
+
+  ## Steps to follow
+
+  1. Change the version number for `ultimate_turbo_modal` in Gemfile to `~> 3.0`.
+  2. If the application uses a Javascript package manager (npm, yarn, bun), change the version number for `ultimate_turbo_modal` in package.json to `^3.0.0`. Otherwise, if the application uses importmaps, update the `pin "ultimate_turbo_modal"` entry in `config/importmap.rb` to reference version `^3.0.0` (or run `bin/importmap pin ultimate_turbo_modal@^3.0.0`).
+  3. Run `bundle install`.
+  4. Run `bundle exec rails generate ultimate_turbo_modal:update` to align the npm package version with the Rubygem, and to copy the flavor file over. Note: this copies the flavor file (e.g. `config/initializers/ultimate_turbo_modal_tailwind.rb`) which defines CSS classes. It does **not** modify the configuration initializer (`config/initializers/ultimate_turbo_modal.rb`) which contains the `UltimateTurboModal.configure` block — that file must be migrated manually in step 6.
+  5. Run `yarn install` or `npm install` or `bun install` if using a Javascript package manager.
+  6. Migrate the configuration block in `config/initializers/ultimate_turbo_modal.rb` (this is the file with the `UltimateTurboModal.configure` block, not the flavor file). If this file does not exist, skip this step — the user was using defaults and no migration is needed. The objective is to replicate the same behavior the user had in v2, using the new v3 syntax. To do this:
+
+    a. Retrieve the v3 configuration template by running: `cat $(bundle info ultimate_turbo_modal --path)/lib/generators/ultimate_turbo_modal/templates/ultimate_turbo_modal.rb`. This template contains the new v3 format with all options commented out at their defaults. Note: the template contains a `FLAVOR` placeholder on the `config.flavor` line that will need to be replaced with the flavor symbol from the user's v2 file (e.g. `:tailwind`).
+
+    b. Read the user's existing `config/initializers/ultimate_turbo_modal.rb` and note any options that differ from the v3 defaults. If all the user's v2 options match these defaults, you will not need to change any of the configurations in the next step.
+
+    c. Use the template as the base for the new file. Uncomment and set only the options that differ from the v3 defaults. The mapping is:
+      - `config.flavor` and `config.allowed_click_outside_selector` remain top-level (unchanged).
+      - `config.advance` → `m.advance` inside `config.modal` block (advance only applies to modals, not drawers).
+      - `config.close_button`, `config.header`, `config.header_divider`, `config.footer_divider`, `config.padding` → `m.<option>` inside `config.modal` block.
+      - Leave the `config.drawer` block commented out (use defaults) since drawers is a new feature and was never previously configured.
+      - Setting old-style flat options directly on `config` (e.g. `config.close_button = false`) will raise a `NoMethodError` in v3.
+
+    d. Overwrite `config/initializers/ultimate_turbo_modal.rb` with the result. In addition to the modified configuration options, the output should include all commented-out configuration options from the template file. This makes it easier for the user to modify options in the future.
+
+  7. Instruct the user to restart their Rails application server for the changes to be picked up.

data/README.md

@@ -1,12 +1,13 @@
 # The Ultimate Turbo Modal for Rails (UTMR)
 
-There are MANY Turbo/Hotwire/Stimulus modal dialog implementations out there, and it seems like everyone goes about it a different way. However, as you may have learned the hard way, the majority fall short in different, often subtle ways. They generally cover the basics quite well, but do not check all the boxes for real-world use.
+There are MANY Turbo/Hotwire/Stimulus modal dialog implementations out there. However, as you may have learned, the majority fall short in different, often subtle ways. They generally cover the basics quite well, but do not check all the boxes for real-world use.
 
 UTMR aims to be the be-all and end-all of Turbo Modals. I believe it is the best (only?) full-featured implementation and checks all the boxes. It is feature-rich, yet extremely easy to use.
 
-Under the hood, it uses [Stimulus](https://stimulus.hotwired.dev), [Turbo](https://turbo.hotwired.dev/), [el-transition](https://github.com/mmccall10/el-transition), and [Idiomorph](https://github.com/bigskysoftware/idiomorph).
+Under the hood, it uses [Stimulus](https://stimulus.hotwired.dev), [Turbo](https://turbo.hotwired.dev/), the native HTML [`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element, and [Idiomorph](https://github.com/bigskysoftware/idiomorph).
+
+It ships in two flavors: Tailwind (v4+) and vanilla CSS. It is easy to create your own flavor to suit your needs.
 
-It currently ships in a three flavors: Tailwind v3, Tailwind v4 and regular, vanilla CSS. It is easy to create your own variant to suit your needs.
 
 ## Installation
 
@@ -15,6 +16,7 @@ $ bundle add ultimate_turbo_modal
 $ bundle exec rails g ultimate_turbo_modal:install
 ```
 
+
 ## Usage
 
 1. Wrap your view inside a `modal` block as follow:
@@ -35,6 +37,8 @@ Clicking on the link will automatically open the content of the view inside a mo
 
 This is really all you should need to do for most use cases.
 
+**Please note:** The generator automatically adds `<turbo-frame id="modal"></turbo-frame>` to your application layout. If you need to open modals or drawers in another layout, please add this HTML snippet manually.
+
 ### Setting Title and Footer
 
 You can set a custom title and footer by passing a block. For example:
@@ -76,15 +80,51 @@ If you need to do something a little bit more advanced when the view is shown ou
 &nbsp;
 ## Options
 
-Do not get overwhelmed with all the options. The defaults are sensible.
+Do not get overwhelmed with all the options. The defaults are sensible. You can change the defaults with an initializer:
+
+```ruby
+# config/initializers/ultimate_turbo_modal.rb
+
+UltimateTurboModal.configure do |config|
+  config.flavor = :tailwind
+  config.allowed_click_outside_selector = []
+
+  config.modal do |m|
+    m.advance = false
+    m.close_button = true
+    m.header = true
+    m.header_divider = true
+    m.footer_divider = true
+    m.padding = true
+    m.overlay = true
+  end
+
+  config.drawer do |d|
+    d.position = :right
+    d.close_button = true
+    d.header = true
+    d.header_divider = false
+    d.footer_divider = true
+    d.padding = true
+    d.overlay = true
+    d.size = :md
+  end
+end
+```
+
+Per-instance options passed to `modal()` or `drawer()` override the defaults.
 
-| name | default value | description |
-|------|---------------|-------------|
-| `advance` | `true` | When opening the modal, the URL in the URL bar will change to the URL of the view being shown in the modal. The Back button dismisses the modal and navigates back. If a URL is specified as a string (e.g. `advance: "/other-path"), the browser history will advance, and the URL shown in the URL bar will be replaced with the value specified. |
+### Modal Options
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `advance` | `false` | When opening the modal, the URL in the URL bar will change to the URL of the view being shown in the modal. The Back button dismisses the modal and navigates back. If a URL is specified as a string (e.g. `advance: "/other-path"`), the browser history will advance, and the URL shown in the URL bar will be replaced with the value specified. |
 | `close_button` | `true` | Shows or hide a close button (X) at the top right of the modal. |
 | `header` | `true` | Whether to display a modal header. |
 | `header_divider` | `true` | Whether to display a divider below the header. |
+| `footer_divider` | `true` | Whether to display a divider above the footer. |
 | `padding` | `true` | Adds padding inside the modal. |
+| `overlay` | `true` | Whether to show a backdrop overlay. |
 | `title` | `nil` | Title to display in the modal header. Alternatively, you can set the title with a block. |
 
 ### Example usage with options
@@ -101,9 +141,62 @@ Do not get overwhelmed with all the options. The defaults are sensible.
 <% end %>
 ```
 
+## Drawers
+
+UTMR includes built-in drawer (slide-out panel) support. Drawers share the same `<dialog>` element and Stimulus controller as modals — no additional JavaScript required.
+
+### Basic Usage
+
+Use the `drawer` helper instead of `modal`:
+
+```erb
+<%= drawer do %>
+  Drawer content here!
+<% end %>
+```
+
+Link to it the same way as a modal:
+
+```erb
+<%= link_to "Open Drawer", "/settings", data: { turbo_frame: "modal" } %>
+```
+
+### Drawer Options
+
+| Name | Default | Description |
+|------|---------|-------------|
+| `position` | `:right` | Which edge the drawer slides from. `:right` or `:left`. |
+| `size` | `:md` | Width of the drawer. One of `:xs`, `:sm`, `:md`, `:lg`, `:xl`, `:"2xl"`, `:full`, or a CSS string (e.g. `"500px"`). |
+| `overlay` | `true` | Whether to show a backdrop overlay behind the drawer. |
+| `close_button` | `true` | Shows or hide a close button (X). |
+| `header` | `true` | Whether to display a header. |
+| `header_divider` | `false` | Whether to display a divider below the header. |
+| `footer_divider` | `true` | Whether to display a divider above the footer. |
+| `padding` | `true` | Adds padding inside the drawer. |
+| `title` | `nil` | Title to display in the drawer header. |
+
+```erb
+<%= drawer(position: :left, size: :lg, overlay: false, title: "Settings") do %>
+  <p>Drawer content</p>
+<% end %>
+```
+
+### Drawer Size Reference
+
+| Size | Max Width |
+|------|-----------|
+| `:sm` | 24rem (384px) |
+| `:md` | 28rem (448px) |
+| `:lg` | 42rem (672px) |
+| `:xl` | 56rem (896px) |
+| `:full` | Full viewport width minus a small gutter |
+| CSS string | Custom value, e.g. `"500px"` or `"50vw"` |
+
+
 ## Features and capabilities
 
 - Extremely easy to use
+- Built-in drawer (slide-out panel) support with left/right positioning and configurable sizes
 - Fully responsive
 - Does not break if a user navigates directly to a page that is usually shown in a modal
 - Opening a modal in a new browser tab (ie: right click) gracefully degrades without having to code a modal and non-modal version of the same page
@@ -112,14 +205,14 @@ Do not get overwhelmed with all the options. The defaults are sensible.
 - Seamless support for multi-page navigation within the modal
 - Seamless support for forms with validations
 - Seamless support for Rails flash messages
-- Enter/leave animation (fade in/out)
 - Support for long, scrollable modals
 - Properly locks the background page when scrolling a long modal
 - Click outside the modal to dismiss
-- Option to whitelist CSS selectors that won't dismiss the modal when clicked outside the modal (ie: datepicker)
+- Option to whitelist CSS selectors that won't dismiss the modal when clicked outside the modal (see [body-appended widgets guide](docs/body-appended-widgets.md) for datepickers and similar popups)
 - Keyboard control; ESC to dismiss
 - Automatic (or not) close button
-- Focus trap for improved accessibility (Tab and Shift+Tab cycle through focusable elements within the modal only)
+- Native focus trapping via the `<dialog>` element for improved accessibility (Tab and Shift+Tab cycle through focusable elements within the modal only)
+- Smooth redirects: form submissions that redirect back to the same page morph the content behind the modal before closing; redirects to a different page close the modal with animation first, then navigate
 
 
 ## Demo Video
@@ -134,15 +227,6 @@ The repository includes a demo application in the `demo-app` directory that show
 # Navigate to the demo app directory
 cd demo-app
 
-# Install Ruby dependencies
-bundle install
-
-# Create and setup the database
-bin/rails db:create db:migrate db:seed
-
-# Install JavaScript dependencies
-yarn install
-
 # Start the development server
 bin/dev
 
@@ -150,38 +234,11 @@ bin/dev
 open http://localhost:3000
 ```
 
-The demo app provides examples of:
-- Basic modal usage
-- Different modal configurations
-- Custom styling options
-- Various trigger methods
-- Advanced features like scrollable content and custom footers
-
-## Updating between minor versions
-
-To upgrade within the same major version (for example 2.1 → 2.2):
-
-1. Change the UTMR gem version in your `Gemfile`:
-
-   ```ruby
-   gem "ultimate_turbo_modal", "~> 2.2"
-   ```
-
-2. Install updated dependencies:
-
-   ```sh
-   bundle install
-   ```
-
-3. Run the update generator:
 
-   ```sh
-   bundle exec rails g ultimate_turbo_modal:update
-   ```
+## Upgrading
 
-## Upgrading from 1.x
+Please see the [Upgrading Guide](UPGRADING.md) for detailed instructions on upgrading between versions.
 
-Please see the [Upgrading Guide](UPGRADING.md) for detailed instructions on how to upgrade from version 1.x.
 
 ## Thanks
 

data/UPGRADING.md

@@ -1,8 +1,53 @@
-# Upgrading from 1.x to 2.x
+# Upgrading
 
-Version 2.0 of Ultimate Turbo Modal introduces some significant changes to simplify the setup and usage. Follow these steps to upgrade from a 1.x version.
+## Updating between minor versions
 
-## 1. Gem and Package Update
+To upgrade within the same major version (for example 3.0 → 3.1):
+
+1. Change the UTMR gem version in your `Gemfile`:
+
+   ```ruby
+   gem "ultimate_turbo_modal", "~> 3.0"
+   ```
+
+2. Install updated dependencies:
+
+   ```sh
+   bundle install
+   ```
+
+3. Run the update generator:
+
+   ```sh
+   bundle exec rails g ultimate_turbo_modal:update
+   ```
+
+## Upgrading from 2.x to 3.0
+
+**Tell your favorite LLM agent to upgrade UTMR for you!** Use this prompt:
+
+```
+Retrieve and follow the instructions at https://raw.githubusercontent.com/cmer/ultimate_turbo_modal/main/LLM/UPGRADE-TO-VERSION-3.md to upgrade this application's "Ultimate Turbo Modal" dependency from v2 to v3. 
+```
+
+v3.0 includes a few breaking changes. See [CHANGELOG.md](CHANGELOG.md) for a complete list of changes.
+
+- **Native `<dialog>` element**: The modal now uses the native HTML `<dialog>` element instead of custom `<div>`-based markup. This provides native focus trapping and improved accessibility, removing the need for the `el-transition` and `focus-trap` JavaScript dependencies.
+- **Simplified HTML structure**: The modal markup has been reduced from 6 nested containers to 3 (`dialog` + `inner` + `content`).
+- **Tailwind v3 flavor removed**: Only Tailwind v4+ is supported via the `tailwind` flavor. Use `custom` if you need to define your own classes.
+- **Custom flavor update required**: The flavor constants `DIV_MODAL_CONTAINER_CLASSES`, `DIV_OVERLAY_CLASSES`, `DIV_DIALOG_CLASSES`, and `TRANSITIONS` have been replaced by `DIALOG_CLASSES`. If you have a custom flavor, you must update it to use the new constants.
+- **Configuration restructured**: Configuration options are now split between `config.modal` and `config.drawer` blocks instead of being flat on the config object. This allows modals and drawers to have different defaults.
+
+### Upgrading like a cavemen
+
+If you're old school and prefer to upgrade manually, without an LLM, it's pretty easy. Just follow the instructions at [LLM/UPGRADE-TO-VERSION-3.md].
+
+
+## Upgrading from 1.x to 2.x (LEGACY VERSIONS)
+
+Version 2.0 of Ultimate Turbo Modal introduced some significant changes to simplify the setup and usage. Follow these steps to upgrade from a 1.x version.
+
+### 1. Gem and Package Update
 
 1.  Update the gem in your `Gemfile`:
     ```ruby
@@ -14,24 +59,24 @@ Version 2.0 of Ultimate Turbo Modal introduces some significant changes to simpl
     ```
 3.  Run `bundle install` and `yarn install` (or `npm install`).
 
-## 2. JavaScript Changes
+### 2. JavaScript Changes
 
-The biggest change in v2 is the removal of the `setupUltimateTurboModal` initializer. The modal controller now handles everything automatically.
+The biggest change in v2 was the removal of the `setupUltimateTurboModal` initializer. The modal controller now handles everything automatically.
 
-### Remove Initializer
+#### Remove Initializer
 
 - Remove the two `setupUltimateTurboModal`-related lines from `app/javascript/controllers/index.js`.
 
 Your `index.js` should no longer import `setupUltimateTurboModal` or call it. The Stimulus controller will be automatically loaded.
 
-### Remove Idiomorph Tweaks (if you used them)
+#### Remove Idiomorph Tweaks (if you used them)
 
 If you were using the optional Idiomorph tweaks for better morphing, you can remove them as this is now handled differently.
 
 - Remove `<script src="https://unpkg.com/idiomorph"></script>` from your application layout.
 - Remove the `turbo:before-frame-render` event listener from your `application.js`.
 
-## 3. Tailwind CSS Changes
+### 3. Tailwind CSS Changes
 
 - Remove any `ultimate_turbo_modal` specific paths from your `tailwind.config.js`. The modal's classes are now self-contained and don't require scanning the gem's view files.
 
@@ -47,9 +92,3 @@ module.exports = {
   ]
 }
 ```
-
-## 4. Review Usage
-
-Version 2.0 aims for backward compatibility in how you render modals from your Rails views and controllers. However, it's always a good idea to test your modals after upgrading to ensure they behave as expected.
-
-That's it! You should now be running on version 2.0.

data/VERSION

@@ -1 +1 @@
-2.2.2
+3.0.0.beta.2

data/docs/body-appended-widgets.md

@@ -0,0 +1,124 @@
+# Body-Appended Widgets Inside Modals and Drawers
+
+## The Problem
+
+Many JavaScript libraries (datepickers, dropdown menus, rich text editors, color pickers, etc.) append their popup/overlay elements directly to `<body>` rather than inside the triggering element. Examples include Flatpickr, Tippy.js, Select2, and Floating UI-based components.
+
+UTMR v3 uses the native `<dialog>` element opened with `showModal()`. When a dialog is open in this mode, the browser automatically marks **everything outside the dialog** as [inert](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inert) — meaning those elements cannot receive focus, clicks, or any other user interaction. This is a browser-level behavior and cannot be overridden with CSS or JavaScript.
+
+As a result, if a widget inside your modal triggers a popup that gets appended to `<body>` (outside the `<dialog>`), that popup will be inert and un-clickable.
+
+**Note:** The `allowed_click_outside_selector` configuration option does not solve this problem. It only prevents the modal from *dismissing* when clicking matching elements — it cannot make inert elements interactive again.
+
+## Solutions
+
+### Option 1: Configure the widget to render inside the dialog
+
+Most popup libraries accept a `container` or `appendTo` option. Set it to the dialog element or a container inside it.
+
+**Flatpickr example:**
+
+The UTMR demo app uses [stimulus-flatpickr](https://www.npmjs.com/package/stimulus-flatpickr) with a custom controller that moves the calendar inside the dialog after initialization. See the full implementation at [`demo-app/app/javascript/controllers/flatpickr_controller.js`](../demo-app/app/javascript/controllers/flatpickr_controller.js):
+
+```javascript
+import Flatpickr from "stimulus-flatpickr"
+
+export default class extends Flatpickr {
+  connect() {
+    super.connect()
+
+    const dialog = this.element.closest("dialog")
+    if (dialog && this.fp?.calendarContainer) {
+      dialog.appendChild(this.fp.calendarContainer)
+    }
+  }
+}
+```
+
+If you're using Flatpickr directly (without the Stimulus wrapper), you can use the `appendTo` option instead:
+
+```javascript
+import flatpickr from "flatpickr"
+
+const dialog = element.closest("dialog")
+flatpickr(element, {
+  appendTo: dialog || undefined,
+})
+```
+
+**Tippy.js example:**
+
+```javascript
+tippy(element, {
+  appendTo: element.closest("dialog") || document.body,
+})
+```
+
+**Floating UI example:**
+
+When using Floating UI directly, render the floating element inside the dialog rather than appending it to `<body>`.
+
+### Option 2: Move elements into the dialog with a MutationObserver
+
+If you cannot configure the library's append target, you can observe `<body>` for newly added elements and relocate them into the dialog automatically.
+
+```javascript
+// Stimulus controller that relocates a widget's popups into the dialog
+import { Controller } from "@hotwired/stimulus"
+
+export default class extends Controller {
+  static values = { selector: String } // e.g. ".flatpickr-calendar"
+
+  connect() {
+    this.dialog = this.element.closest("dialog")
+    if (!this.dialog) return
+
+    this.relocated = []
+    this.observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of mutation.addedNodes) {
+          if (node.nodeType !== Node.ELEMENT_NODE) continue
+          if (this.dialog.contains(node)) continue
+          if (node.matches(this.selectorValue)) {
+            this.#relocate(node)
+          }
+        }
+      }
+    })
+
+    this.observer.observe(document.body, { childList: true })
+  }
+
+  disconnect() {
+    this.observer?.disconnect()
+    for (const { element, placeholder } of this.relocated) {
+      placeholder.parentNode?.insertBefore(element, placeholder)
+      placeholder.remove()
+    }
+    this.relocated = []
+  }
+
+  #relocate(element) {
+    const placeholder = document.createComment("utmr-relocated")
+    element.parentNode.insertBefore(placeholder, element)
+    this.dialog.appendChild(element)
+    this.relocated.push({ element, placeholder })
+  }
+}
+```
+
+Usage in your view:
+
+```erb
+<div data-controller="relocate-widget" data-relocate-widget-selector-value=".flatpickr-calendar">
+  <input data-controller="flatpickr" type="text">
+</div>
+```
+
+### Option 3: Use `<dialog>`-aware libraries
+
+Some newer UI libraries are aware of the `<dialog>` top layer and handle this correctly out of the box. When choosing new dependencies, check whether they support rendering inside `<dialog>` elements opened with `showModal()`.
+
+## Background
+
+This is not specific to UTMR — it affects **any** use of the native `<dialog>` element with `showModal()`. The [HTML spec](https://html.spec.whatwg.org/multipage/interactive-elements.html#dom-dialog-showmodal) requires that content outside the top-layer dialog be made inert. This is the same mechanism that provides native focus trapping and accessibility benefits.