ultimate_turbo_modal 2.0.4 → 2.1.1

data/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Ultimate Turbo Modal (UTMR) is a full-featured modal implementation for Rails applications using Turbo, Stimulus, and Hotwire. It consists of both a Ruby gem and an npm package that work together.
+
+## Project Structure
+
+- **Ruby Gem**: Main gem code in `/lib/ultimate_turbo_modal/`
+  - `base.rb`: Core modal component (Phlex-based)
+  - `configuration.rb`: Global configuration management
+  - `helpers/`: Rails helpers for views and controllers
+  - Generators in `/lib/generators/` for installation
+  
+- **JavaScript Package**: Located in `/javascript/`
+  - `modal_controller.js`: Stimulus controller for modal behavior
+  - `index.js`: Main entry point
+  - Distributed files built to `/javascript/dist/`
+
+## Common Development Commands
+
+### JavaScript Development (run from `/javascript/` directory)
+```bash
+# Install dependencies
+yarn install
+
+# Build the JavaScript package
+yarn build
+
+# Release to npm (updates version and publishes)
+yarn release
+```
+
+### Ruby Gem Development (run from root)
+```bash
+# Run tests
+bundle exec rake test
+
+# Build gem
+gem build ultimate_turbo_modal.gemspec
+
+# Release process (Ruby + JS)
+./script/build_and_release.sh
+```
+
+## Architecture & Key Concepts
+
+### Modal Options System
+Options can be set at three levels:
+1. **Global defaults** via `UltimateTurboModal.configure` in configuration.rb
+2. **Instance options** passed to the `modal` helper
+3. **Runtime values** via blocks (for title/footer)
+
+Current options: `advance`, `close_button`, `header`, `header_divider`, `padding`, `title`
+
+### Stimulus Controller Values
+The modal controller uses Stimulus values to receive configuration:
+- `advanceUrl`: URL for browser history manipulation
+- `allowedClickOutsideSelector`: CSS selectors that won't dismiss modal when clicked
+
+### Modal Lifecycle
+1. Link clicked with `data-turbo-frame="modal"`
+2. Turbo loads content into the modal frame
+3. Stimulus controller connects and shows modal
+4. Modal can be dismissed via: ESC key, close button, clicking outside, or programmatically
+
+### Adding New Configuration Options
+When adding a new option:
+
+1. Add to `Configuration` class with getter/setter methods
+2. Add to `UltimateTurboModal` delegators
+3. Add to `Base#initialize` parameters with default from configuration
+4. Pass to JavaScript via data attributes in `Base#div_dialog`
+5. Add as Stimulus value in `modal_controller.js`
+6. Update README.md options table
+
+## Testing Approach
+- JavaScript: No test framework currently set up
+- Ruby: Use standard Rails testing practices
+- Manual testing via the demo app: https://github.com/cmer/ultimate_turbo_modal-demo

data/Gemfile

@@ -7,5 +7,5 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "standard", "~> 1.3"
+gem "standard"
 gem "standard-rails"

data/Gemfile.lock

@@ -1,35 +1,17 @@
 PATH
   remote: .
   specs:
-    ultimate_turbo_modal (2.0.4)
+    ultimate_turbo_modal (2.1.1)
+      actionpack
+      activesupport
       phlex-rails
-      rails
+      railties
       stimulus-rails
       turbo-rails
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actioncable (8.0.2)
-      actionpack (= 8.0.2)
-      activesupport (= 8.0.2)
-      nio4r (~> 2.0)
-      websocket-driver (>= 0.6.1)
-      zeitwerk (~> 2.6)
-    actionmailbox (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-    actionmailer (8.0.2)
-      actionpack (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activesupport (= 8.0.2)
-      mail (>= 2.8.0)
-      rails-dom-testing (~> 2.2)
     actionpack (8.0.2)
       actionview (= 8.0.2)
       activesupport (= 8.0.2)
@@ -40,34 +22,12 @@ GEM
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
       useragent (~> 0.16)
-    actiontext (8.0.2)
-      actionpack (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.6.0)
-      nokogiri (>= 1.8.5)
     actionview (8.0.2)
       activesupport (= 8.0.2)
       builder (~> 3.1)
       erubi (~> 1.11)
       rails-dom-testing (~> 2.2)
       rails-html-sanitizer (~> 1.6)
-    activejob (8.0.2)
-      activesupport (= 8.0.2)
-      globalid (>= 0.3.6)
-    activemodel (8.0.2)
-      activesupport (= 8.0.2)
-    activerecord (8.0.2)
-      activemodel (= 8.0.2)
-      activesupport (= 8.0.2)
-      timeout (>= 0.4.0)
-    activestorage (8.0.2)
-      actionpack (= 8.0.2)
-      activejob (= 8.0.2)
-      activerecord (= 8.0.2)
-      activesupport (= 8.0.2)
-      marcel (~> 1.0)
     activesupport (8.0.2)
       base64
       benchmark (>= 0.3)
@@ -82,92 +42,61 @@ GEM
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
     ast (2.4.3)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.2)
     builder (3.3.0)
     concurrent-ruby (1.3.5)
-    connection_pool (2.5.0)
+    connection_pool (2.5.3)
     crass (1.0.6)
     date (3.4.1)
-    drb (2.2.1)
+    drb (2.2.3)
+    erb (5.0.2)
     erubi (1.13.1)
-    globalid (1.2.1)
-      activesupport (>= 6.1)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    io-console (0.8.0)
+    io-console (0.8.1)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.10.2)
-    language_server-protocol (3.17.0.4)
+    json (2.13.2)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    loofah (2.24.0)
+    loofah (2.24.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    mail (2.8.1)
-      mini_mime (>= 0.1.1)
-      net-imap
-      net-pop
-      net-smtp
-    marcel (1.0.4)
-    mini_mime (1.1.5)
     minitest (5.25.5)
-    net-imap (0.5.6)
-      date
-      net-protocol
-    net-pop (0.1.2)
-      net-protocol
-    net-protocol (0.2.2)
-      timeout
-    net-smtp (0.5.1)
-      net-protocol
-    nio4r (2.7.4)
-    nokogiri (1.18.7-arm64-darwin)
+    nokogiri (1.18.9-arm64-darwin)
       racc (~> 1.4)
-    parallel (1.26.3)
-    parser (3.3.7.4)
+    parallel (1.27.0)
+    parser (3.3.9.0)
       ast (~> 2.4.1)
       racc
-    phlex (2.2.1)
+    phlex (2.3.1)
       zeitwerk (~> 2.7)
-    phlex-rails (2.2.0)
-      phlex (~> 2.2.1)
+    phlex-rails (2.3.1)
+      phlex (~> 2.3.0)
       railties (>= 7.1, < 9)
+      zeitwerk (~> 2.7)
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
     prism (1.4.0)
-    psych (5.2.3)
+    psych (5.2.6)
       date
       stringio
     racc (1.8.1)
-    rack (3.1.12)
-    rack-session (2.1.0)
+    rack (3.2.0)
+    rack-session (2.1.1)
       base64 (>= 0.1.0)
       rack (>= 3.0.0)
     rack-test (2.2.0)
       rack (>= 1.3)
     rackup (2.2.1)
       rack (>= 3)
-    rails (8.0.2)
-      actioncable (= 8.0.2)
-      actionmailbox (= 8.0.2)
-      actionmailer (= 8.0.2)
-      actionpack (= 8.0.2)
-      actiontext (= 8.0.2)
-      actionview (= 8.0.2)
-      activejob (= 8.0.2)
-      activemodel (= 8.0.2)
-      activerecord (= 8.0.2)
-      activestorage (= 8.0.2)
-      activesupport (= 8.0.2)
-      bundler (>= 1.15.0)
-      railties (= 8.0.2)
-    rails-dom-testing (2.2.0)
+    rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
       nokogiri (>= 1.6)
@@ -183,13 +112,14 @@ GEM
       thor (~> 1.0, >= 1.2.2)
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
-    rake (13.2.1)
-    rdoc (6.13.1)
+    rake (13.3.0)
+    rdoc (6.14.2)
+      erb
       psych (>= 4.0.0)
-    regexp_parser (2.10.0)
-    reline (0.6.1)
+    regexp_parser (2.11.0)
+    reline (0.6.2)
       io-console (~> 0.5)
-    rubocop (1.73.2)
+    rubocop (1.75.8)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -197,44 +127,44 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.38.0, < 2.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.0)
+    rubocop-ast (1.46.0)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-performance (1.24.0)
+    rubocop-performance (1.25.0)
       lint_roller (~> 1.1)
-      rubocop (>= 1.72.1, < 2.0)
+      rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
-    rubocop-rails (2.26.2)
+    rubocop-rails (2.31.0)
       activesupport (>= 4.2.0)
+      lint_roller (~> 1.1)
       rack (>= 1.1)
-      rubocop (>= 1.52.0, < 2.0)
-      rubocop-ast (>= 1.31.1, < 2.0)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    standard (1.47.0)
+    standard (1.50.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.73.0)
+      rubocop (~> 1.75.5)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.7)
+      standard-performance (~> 1.8)
     standard-custom (1.0.2)
       lint_roller (~> 1.0)
       rubocop (~> 1.50)
-    standard-performance (1.7.0)
+    standard-performance (1.8.0)
       lint_roller (~> 1.1)
-      rubocop-performance (~> 1.24.0)
-    standard-rails (1.2.0)
+      rubocop-performance (~> 1.25.0)
+    standard-rails (1.4.0)
       lint_roller (~> 1.0)
-      rubocop-rails (~> 2.26.0)
+      rubocop-rails (~> 2.31.0)
     stimulus-rails (1.3.4)
       railties (>= 6.0.0)
-    stringio (3.1.6)
-    thor (1.3.2)
-    timeout (0.4.3)
-    turbo-rails (2.0.13)
+    stringio (3.1.7)
+    thor (1.4.0)
+    turbo-rails (2.0.16)
       actionpack (>= 7.1.0)
       railties (>= 7.1.0)
     tzinfo (2.0.6)
@@ -244,11 +174,7 @@ GEM
     unicode-emoji (4.0.4)
     uri (1.0.3)
     useragent (0.16.11)
-    websocket-driver (0.7.7)
-      base64
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.5)
-    zeitwerk (2.7.2)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   arm64-darwin-22
@@ -257,7 +183,7 @@ PLATFORMS
 
 DEPENDENCIES
   rake (~> 13.0)
-  standard (~> 1.3)
+  standard
   standard-rails
   ultimate_turbo_modal!
 

data/README.md

@@ -8,10 +8,6 @@ Under the hood, it uses [Stimulus](https://stimulus.hotwired.dev), [Turbo](https
 
 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
 
 ```
@@ -19,38 +15,6 @@ $ bundle add ultimate_turbo_modal
 $ bundle exec rails g ultimate_turbo_modal:install
 ```
 
- 
- 
-
-## Features and capabilities
-
-- Extremely easy to use
-- 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
-- Automatically handles URL history (ie: pushState) for shareable URLs
-- pushState URL optionally overrideable
-- 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)
-- Keyboard control; ESC to dismiss
-- Automatic (or not) close button
-
-
- 
- 
-## Demo
-
-A demo application can be found at https://github.com/cmer/ultimate_turbo_modal-demo. A video demo can be seen here: [https://youtu.be/BVRDXLN1I78](https://youtu.be/BVRDXLN1I78).
-
-
- 
- 
 ## Usage
 
 1. Wrap your view inside a `modal` block as follow:
@@ -69,6 +33,33 @@ A demo application can be found at https://github.com/cmer/ultimate_turbo_modal-
 
 Clicking on the link will automatically open the content of the view inside a modal. If you open the link in a new tab, it will render normally outside of the modal. Nothing to do!
 
+This is really all you should need to do for most use cases.
+
+### Setting Title and Footer
+
+You can set a custom title and footer by passing a block. For example:
+
+```erb
+<%= modal do |m| %>
+  <% m.title do %>
+    <div>My Title</div>
+  <% end %>
+
+  <p>Your modal body</p>
+  <%= form_with url: "#", html: { id: "myform" } do |f| %>
+    <p>..</p>
+  <% end %>
+
+  <% m.footer do %>
+    <input type="submit" form="myform">Submit</input>
+  <% end %>
+<% end %>
+```
+
+You can also set a title with options (see below).
+
+### Detecting modal at render time
+
 If you need to do something a little bit more advanced when the view is shown outside of a modal, you can use the `#inside_modal?` method as such:
 
 ```erb
@@ -79,44 +70,22 @@ If you need to do something a little bit more advanced when the view is shown ou
 <% end %>
 ```
 
+
+
 &nbsp;
 &nbsp;
 ## Options
 
-### `padding`, default: `true`
-
-Adds padding inside the modal.
-
-### `close_button`, default: `true`
-
-Shows or hide a close button (X) at the top right of the modal.
-
-### `advance`, default: `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, the browser history will advance, and the URL shown in the URL bad will be replaced by the URL specified.
-
-### `title`, default: `nil`
-
-Title to display in the modal header. Alternatively, you can set the title with a block.
-
-### `header`, default: `true`
-
-Whether to display a modal header.
-
-### `header_divider`, default: `true`
-
-Whether to display a divider below the header.
-
-### `footer_divider`, default: `true`
+Do not get overwhelmed with all the options. The defaults are sensible.
 
-Whether to display a divider above the footer. The divider will not appear if no footer was specified.
-
-### `allowed_click_outside_selector`, default: `nil`
-
-A string of CSS selectors that can be clicked outside of the modal without dismissing the modal. Useful for elements
-such as datepickers.
+| 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. |
+| `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. |
+| `padding` | `true` | Adds padding inside the modal. |
+| `title` | `nil` | Title to display in the modal header. Alternatively, you can set the title with a block. |
 
 ### Example usage with options
 
@@ -132,50 +101,45 @@ such as datepickers.
 <% end %>
 ```
 
-### Title and Footer
-
-You can set a custom title and footer by passing a block. For example
-
-```erb
-<%= modal do |m| %>
-  <% m.title do %>
-    <div>My Title</div>
-  <% end %>
-
-  Modal body
+## Features and capabilities
 
-  <% m.footer do %>
-    <input type="submit" form="myform">Submit</input>
-  <% end %>
-<% end %>
-```
+- Extremely easy to use
+- 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
+- Automatically handles URL history (ie: pushState) for shareable URLs
+- pushState URL optionally overrideable
+- 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)
+- 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)
 
-&nbsp;
-&nbsp;
 
-## Upgrading from version 1.x
+## Demo
 
-- Remove the two `setupUltimateTurboModal`-related lines from `app/javascript/controllers/index.js`:
+A demo application can be found at https://github.com/cmer/ultimate_turbo_modal-demo. A video demo can be seen here: [https://youtu.be/BVRDXLN1I78](https://youtu.be/BVRDXLN1I78).
 
-- Remove anything UTMR-specific in `tailwind.config.js`.
+## Upgrading from 1.x
 
-- Remove the optional Idiomorph tweaks:
-  - `<script src="https://unpkg.com/idiomorph"></script>` from your HTML
-  - `addEventListener("turbo:before-frame-render", (event) => {...` from `application.js`
-- Update the gem to the newest version and follow the installation instructions above.
+Please see the [Upgrading Guide](UPGRADING.md) for detailed instructions on how to upgrade from version 1.x.
 
 ## Thanks
 
 Thanks to [@joeldrapper](https://github.com/joeldrapper) and [@konnorrogers](https://github.com/KonnorRogers) for all the help!
 
-&nbsp;
-&nbsp;
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/cmer/ultimate_turbo_modal.
 
-&nbsp;
-&nbsp;
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/UPGRADING.md

@@ -0,0 +1,55 @@
+# Upgrading from 1.x to 2.x
+
+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.
+
+## 1. Gem and Package Update
+
+1.  Update the gem in your `Gemfile`:
+    ```ruby
+    gem 'ultimate_turbo_modal', '~> 2.0'
+    ```
+2.  Update the npm package in your `package.json`:
+    ```json
+    "ultimate-turbo-modal": "^2.0"
+    ```
+3.  Run `bundle install` and `yarn install` (or `npm install`).
+
+## 2. JavaScript Changes
+
+The biggest change in v2 is the removal of the `setupUltimateTurboModal` initializer. The modal controller now handles everything automatically.
+
+### 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)
+
+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
+
+- 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.
+
+A typical `tailwind.config.js` in a Rails app should have its `content` array look something like this, without mentioning the gem:
+
+```js
+module.exports = {
+  content: [
+    './app/views/**/*.html.erb',
+    './app/helpers/**/*.rb',
+    './app/assets/stylesheets/**/*.css',
+    './app/javascript/**/*.js'
+  ]
+}
+```
+
+## 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.0.4
+2.1.1

data/demo-app/.gitattributes

@@ -0,0 +1,7 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored