ultimate_turbo_modal 3.0.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e411c9c81c6a9d66e510bec9419320098ffe600585b40c7dfb2030be2a5850d9
-  data.tar.gz: 6d96129a3bc0c1df07c42e3fc590a4fb9fcc33d3b52ebb07b36c0746f5337e04
+  metadata.gz: 4006bd50ba1693d0d012a648cf4a8d500082f9f58ba02c00d828233d3437b46a
+  data.tar.gz: e7377b811456a99d875a0d0450690d63c4e1dec41e1e8e21dfe5110210e529a5
 SHA512:
-  metadata.gz: 4a1946c9a3238294a9c4ea52a1459ea9e6e220eee55e3e4ed3717e1bae5840922c52c6d9b01dc42d8b08450b0c36ee51090854cad36057d39e7d06f7943f5955
-  data.tar.gz: f82213efb17b0a364e06d1e131684466e9b5f6e35f2cdf0166ecab10b191469e1b96fc035955e5fb612259e30d05f5bbc16cf515c646fbf1e65b1b8ca1d791c4
+  metadata.gz: 85529b5b0438d441e75bb50ecc58733d938a3e4486b8935273c57bc7f3a5bb82e99a263a92a5ccb7618ddfd860ad84be3cd1de7d9f3146d9eba07977dff7a6c0
+  data.tar.gz: d2d481a1a9713e6adec93a679c3f59ad285eb7acd6c866a01d45cf496fa82422ea0c84fe2c060439af41950276645d889f216404714ead27df185b890bcff743

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [3.0.2] - 2026-03-22
+
+- Fixed npm package not being found on JSPM, which prevented `bin/importmap pin` from working ([#46](https://github.com/cmer/ultimate_turbo_modal/issues/46)).
+
+## [3.0.1] - 2026-03-21
+
+- Fixed missing bottom padding on vanilla flavor drawer header when header divider is enabled.
+
 ## [3.0.0] - 2026-03-21
 
 Upgrading is easy! See [UPGRADING.md](UPGRADING.md)

data/Gemfile.lock

@@ -1,12 +1,13 @@
 PATH
   remote: .
   specs:
-    ultimate_turbo_modal (3.0.0)
+    ultimate_turbo_modal (3.0.2)
       actionpack (>= 8.0)
       activesupport (>= 8.0)
       phlex-rails (>= 2.0)
       railties (>= 8.0)
       stimulus-rails
+      tsort
       turbo-rails
 
 GEM
@@ -166,6 +167,7 @@ GEM
       railties (>= 6.0.0)
     stringio (3.1.7)
     thor (1.4.0)
+    tsort (0.2.0)
     turbo-rails (2.0.16)
       actionpack (>= 7.1.0)
       railties (>= 7.1.0)

data/README.md

@@ -2,12 +2,22 @@
 
 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.
+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. Its purpose is to make it as easy as possible to have polished Turbo-backed modals and drawers.
 
 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.
 
+## Screenshots & Demo Video
+
+[![Demo Video](/screenshots/light-showcase-play.webp "Demo Video")](https://youtu.be/qXoeyxuyn7w)
+
+|  |  |
+|:-------------------------:|:-------------------------:|
+| ![Light Modal Form](/screenshots/light-modal-form.webp "Light Modal Form") | ![Light Long Scrollable Modal](/screenshots/light-long-scrollable-modal.webp "Light Long Scrollable  Modal") |
+| ![Light Drawer with Footer](/screenshots/light-drawer-with-footer.webp "Light Drawer with Footer") | ![Dark Modal Form](/screenshots/dark-modal-form.webp "Dark Modal Form") |
+|  |  |
+
 
 ## Installation
 
@@ -215,10 +225,6 @@ Link to it the same way as a modal:
 - 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
-
-A video demo can be seen here: [https://youtu.be/qXoeyxuyn7w](https://youtu.be/qXoeyxuyn7w).
-
 ### Running the Demo Application
 
 The repository includes a demo application in the `demo-app` directory that showcases all the features of Ultimate Turbo Modal. To run it locally:

data/UPGRADING.md

@@ -1,5 +1,26 @@
 # Upgrading
 
+## 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](LLM/UPGRADE-TO-VERSION-3.md).
+
+
 ## Updating between minor versions
 
 To upgrade within the same major version (for example 3.0 → 3.1):
@@ -22,26 +43,6 @@ To upgrade within the same major version (for example 3.0 → 3.1):
    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)
 

data/VERSION

@@ -1 +1 @@
-3.0.0
+3.0.2

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ultimate_turbo_modal
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.2
 platform: ruby
 authors:
 - Carl Mercier
@@ -79,6 +79,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: turbo-rails
   requirement: !ruby/object:Gem::Requirement
@@ -111,12 +125,10 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- LLM/UPGRADE-TO-VERSION-3.md
 - README.md
 - Rakefile
 - UPGRADING.md
 - VERSION
-- docs/body-appended-widgets.md
 - lib/generators/ultimate_turbo_modal/base.rb
 - lib/generators/ultimate_turbo_modal/install_generator.rb
 - lib/generators/ultimate_turbo_modal/templates/flavors/custom.rb
@@ -135,7 +147,6 @@ files:
 - lib/ultimate_turbo_modal/railtie.rb
 - lib/ultimate_turbo_modal/version.rb
 - mise.toml
-- script/build_and_release.sh
 - sig/ultimate_turbo_modal.rbs
 - yarn.lock
 homepage: https://github.com/cmer/ultimate_turbo_modal

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

@@ -1,38 +0,0 @@
-  # 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/docs/body-appended-widgets.md

@@ -1,124 +0,0 @@
-# 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.

data/script/build_and_release.sh

@@ -1,61 +0,0 @@
-#!/bin/bash
-set -e
-cd $(dirname $0)/..
-
-if [ "$1" == "--help" ]; then
-  echo "Usage: $0 [--skip-gem] [--skip-js]"
-  echo ""
-  echo "Options:"
-  echo "  --skip-gem   Skip building and releasing the gem."
-  echo "  --skip-js    Skip building and releasing the JavaScript."
-  echo "  --help       Show this help message."
-  exit 0
-fi
-
-# Check for uncommitted changes
-if ! git diff --quiet; then
-  echo "There are uncommitted changes. Aborting."
-  exit 1
-fi
-
-
-if [ "$1" != "--skip-gem" ]; then
-  echo "Building and releasing gem..."
-  bundle exec rake build
-
-  # Update demo app with latest gem and JavaScript
-  echo "Updating demo app with latest code..."
-  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-  DEMO_APP_DIR="$SCRIPT_DIR/../demo-app"
-
-  # Build JavaScript package first
-  echo "Building ultimate_turbo_modal JavaScript package..."
-  (cd "$SCRIPT_DIR/../javascript" && npm run build)
-
-  # Update demo app dependencies
-  echo "Installing latest ultimate_turbo_modal in demo app..."
-  (cd "$DEMO_APP_DIR" && bundle install)
-  (cd "$DEMO_APP_DIR" && npm install)
-
-  # Check if Gemfile.lock or demo-app files are git dirty
-  if ! git diff --quiet Gemfile.lock demo-app/Gemfile.lock demo-app/package-lock.json; then
-    echo "Lock files are dirty. Adding, committing, and pushing."
-    git add Gemfile.lock demo-app/Gemfile.lock demo-app/package-lock.json
-    git commit -m "Update lock files for demo app"
-  fi
-
-  bundle exec rake build
-  bundle exec rake release
-else
-  echo "Skipping gem build and release..."
-fi
-
-if [ "$1" != "--skip-js" ]; then
-  echo "Building JavaScript..."
-  cd javascript
-  ./scripts/release-npm.sh
-else
-  echo "Skipping JavaScript build..."
-fi
-
-echo "Done!"