ultimate_turbo_modal 2.1.2 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17d0eab498c9c828467bea1e33c1250763a8361595847a29a421bedc84947f06
-  data.tar.gz: 41ab99f7579857ccd65d7c549d8626d2566fb952cabb5c97b7f8193e7930fa44
+  metadata.gz: 8076c3d9802abd28ef2ff1858b7268f730455c69a214dfb2f8e04d3695c8f68f
+  data.tar.gz: fa211158221a41661229457a63874690eac7e07fb19159045362eb0341d4ccee
 SHA512:
-  metadata.gz: e4925980e51ac9f8fc7e08245e8d79e3a73faca356e44ae45bedfd089e3ec3d2de17e2a5ab264f57dcae0c79b91a53e37ee3661dcb57541b422b563f3e2a8ff1
-  data.tar.gz: 93f0bb944adfcc54e844ce3d2d3438bdfdaabb3cd648bb22b87937a6b8267a46e842db622ffc7c04c7b9a2a578da3ea1c4c411742f44821368c4fd299a1c411f
+  metadata.gz: 9414a16b2a0de555727b258403230d5a65564e1158b95c61904cca0fd0b9280fe5433eaeb156962b1dbb1bbcdfe25a86d1ec7b1a65c03209211e5b97abb2fde7
+  data.tar.gz: 783c9c2af43c3b31e8e974642545ac094e2c5faf1925c84947186e215ba809daac4a6236afa7fc1e24768379f1a12376515982a48cd08350274a9a8a2230fc7b

data/.tool-versions

@@ -1,2 +1,2 @@
-ruby 3.4.4
+ruby 3.3.9
 nodejs 22.14.0

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [2.2.2] - 2026-03-12
+
+- Added `close` function on Stimulus Controller. Thanks @bendangelo
+- Focus bug fix. Thanks @pasl
+- Refactor generator and fix [bug #33](https://github.com/cmer/ultimate_turbo_modal/issues/33).
+
+## [2.2.1] - 2025-08-08
+
+- Added `rails generate ultimate_turbo_modal:update` for easy updates
+- Exclude demo-app directory from gem package
+
+## [2.2.0] - 2025-08-07
+
+- BREAKING: Make sure to re-run the generator `rails generate ultimate_turbo_modal:install` after install.
+- Fixed transistions that were sometimes not showing
+- Improved demo app to make it easier to use for development
+
 ## [2.1.2] - 2025-08-06
 
 - Fixed scroll lock

data/CLAUDE.md

@@ -4,7 +4,187 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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.
+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 to provide seamless modal functionality with proper focus management, history manipulation, and customizable styling.
+
+## Architecture
+
+### High-Level Design
+
+The system follows a separation of concerns between server-side rendering (Ruby/Rails) and client-side behavior (JavaScript/Stimulus):
+
+1. **Server-Side (Ruby Gem)**: Handles HTML generation, configuration management, and Rails integration
+2. **Client-Side (JavaScript Package)**: Manages modal behavior, focus trapping, scroll locking, and Turbo interactions
+3. **Communication Layer**: Uses Turbo Frames, Turbo Streams, and data attributes to coordinate between server and client
+
+### Core Components
+
+#### Ruby Gem Architecture
+
+- **Module Structure**: `UltimateTurboModal` is the main module that delegates to configuration and instantiates modal classes
+- **Base Class**: `UltimateTurboModal::Base` extends `Phlex::HTML` for component-based HTML generation
+- **Configuration System**: Centralized configuration with validation and type checking
+- **Flavor System**: CSS framework-specific implementations (Tailwind, Vanilla, Custom) that define styling classes
+- **Rails Integration**: Via Railtie that injects helpers into ActionController and ActionView
+
+#### JavaScript Architecture
+
+- **Stimulus Controller**: `modal_controller.js` handles all modal interactions
+- **Dependencies**:
+  - `el-transition`: For smooth enter/leave animations
+  - `focus-trap`: For accessibility-compliant focus management
+  - `idiomorph`: For intelligent DOM morphing to prevent flicker
+- **Global Registration**: Modal instance exposed as `window.modal` for programmatic access
+- **Turbo Integration**: Custom stream actions and frame handling
+
+## Detailed Implementation
+
+### Ruby Components
+
+#### `UltimateTurboModal` Module (`lib/ultimate_turbo_modal.rb`)
+- Entry point for the gem
+- Factory method `new` creates modal instances
+- `modal_class` method dynamically loads flavor classes based on configuration
+- Extends self for module-level methods
+
+#### `Base` Class (`lib/ultimate_turbo_modal/base.rb`)
+- **Inheritance**: `Phlex::HTML` for HTML generation with Ruby DSL
+- **Mixins**:
+  - `Phlex::DeferredRenderWithMainContent` for content block handling
+  - Dynamic inclusion of Turbo helpers (FramesHelper, StreamsHelper)
+- **Key Methods**:
+  - `initialize`: Accepts configuration options with defaults from global config
+  - `view_template`: Main rendering method that wraps content in appropriate Turbo tags
+  - `modal`: Orchestrates HTML structure generation
+  - `div_*` methods: Generate specific HTML elements with proper classes and attributes
+- **Data Attributes**: Passes configuration to JavaScript via data attributes on the container div
+
+#### `Configuration` Class (`lib/ultimate_turbo_modal/configuration.rb`)
+- **Options with Validation**:
+  - `flavor`: Symbol/String for CSS framework (default: `:tailwind`)
+  - `close_button`: Boolean for showing close button
+  - `advance`: Boolean for browser history manipulation
+  - `padding`: Boolean or String for content padding
+  - `header`, `header_divider`, `footer_divider`: Boolean display options
+  - `allowed_click_outside_selector`: Array of CSS selectors that won't dismiss modal
+- **Type Safety**: Each setter validates input types and raises `ArgumentError` on invalid values
+
+#### Rails Helpers
+
+##### `ViewHelper` (`helpers/view_helper.rb`)
+- `modal` method: Renders modal component with current request context
+- Instantiates `UltimateTurboModal` with passed options
+
+##### `ControllerHelper` (`helpers/controller_helper.rb`)
+- `inside_modal?` method: Detects if request is within modal context
+- Uses `Turbo-Frame` header to determine modal context
+- Exposed as helper method to views
+
+##### `StreamHelper` (`helpers/stream_helper.rb`)
+- `modal` method: Generates Turbo Stream actions for modal control
+- Supports `:close` and `:hide` messages
+- Creates custom `modal` stream action with message attribute
+
+#### Flavor System
+- Located in generator templates (`lib/generators/ultimate_turbo_modal/templates/flavors/`)
+- Each flavor defines CSS class constants for modal elements:
+  - `DIV_DIALOG_CLASSES`, `DIV_OVERLAY_CLASSES`, `DIV_OUTER_CLASSES`, etc.
+- Flavors inherit from `Base` and override class constants
+- Supports Tailwind (v3 and v4), Vanilla CSS, and Custom implementations
+
+### JavaScript Components
+
+#### Modal Controller (`javascript/modal_controller.js`)
+
+##### Stimulus Configuration
+- **Targets**: `container`, `content`
+- **Values**: `advanceUrl`, `allowedClickOutsideSelector`
+- **Actions**: Responds to keyboard, click, and Turbo events
+
+##### Lifecycle Methods
+- **`connect()`**:
+  - Initializes focus trap and scroll lock variables
+  - Shows modal immediately
+  - Sets up popstate listener for browser back button
+  - Exposes controller as `window.modal`
+- **`disconnect()`**: Cleans up focus trap and global reference
+
+##### Core Functionality
+
+###### Modal Display
+- **`showModal()`**:
+  - Locks body scroll
+  - Triggers enter transition
+  - Activates focus trap after transition
+  - Pushes history state if `advance` is enabled
+- **`hideModal()`**:
+  - Prevents double-hiding with `hidingModal` flag
+  - Dispatches cancelable `modal:closing` event
+  - Deactivates focus trap
+  - Triggers leave transition
+  - Cleans up DOM and history
+  - Dispatches `modal:closed` event
+
+###### Focus Management (`#activateFocusTrap()`, `#deactivateFocusTrap()`)
+- Creates focus trap with sensible defaults
+- Finds first focusable element or focuses modal itself
+- Handles errors gracefully without breaking modal
+- Respects modal's own keyboard/click handlers
+
+###### Scroll Locking (`#lockBodyScroll()`, `#unlockBodyScroll()`)
+- Stores current scroll position
+- Sets body to `position: fixed` to prevent scroll
+- Restores original overflow and scroll position on unlock
+- Prevents layout shift during modal display
+
+###### History Management
+- Uses data attribute on body to track history state
+- `#hasHistoryAdvanced()`, `#setHistoryAdvanced()`, `#resetHistoryAdvanced()`
+- Coordinates with browser back button via popstate listener
+
+###### Event Handlers
+- **`submitEnd()`**: Closes modal on successful form submission
+- **`closeWithKeyboard()`**: ESC key handler
+- **`outsideModalClicked()`**: Dismisses modal on outside clicks unless allowed selector matches
+
+###### Version Checking
+- `#checkVersions()`: Warns about gem/npm version mismatches in development
+- Helps developers keep packages in sync
+
+#### Main Package Entry (`javascript/index.js`)
+
+##### Turbo Stream Actions
+- Registers custom `modal` stream action
+- Handles `hide` and `close` messages via `window.modal` reference
+
+##### Turbo Frame Integration
+- **`handleTurboFrameMissing`**: Escapes modal on redirects
+- **`handleTurboBeforeFrameRender`**: Uses Idiomorph for intelligent morphing
+  - Prevents flicker and unwanted animations
+  - Morphs only innerHTML to preserve modal container
+
+### Modal Lifecycle Flow
+
+1. **Trigger**: Link/form targets `data-turbo-frame="modal"`
+2. **Request**: Rails controller renders modal content
+3. **Response**:
+   - If Turbo Frame request: Wrapped in `<turbo-frame id="modal">`
+   - If Turbo Stream: Wrapped in stream action targeting modal
+4. **Client Processing**:
+   - Turbo updates modal frame content
+   - Stimulus controller connects and shows modal
+   - Focus trap activates, scroll locks
+   - History state pushed (if enabled)
+5. **Interaction**:
+   - User interacts with modal content
+   - Form submissions handled via Turbo
+   - ESC key, close button, or outside clicks trigger hiding
+6. **Dismissal**:
+   - `modal:closing` event fired (cancelable)
+   - Focus trap deactivates
+   - Leave transition plays
+   - DOM cleaned up
+   - History restored
+   - `modal:closed` event fired
 
 ## Project Structure
 
@@ -12,13 +192,19 @@ Ultimate Turbo Modal (UTMR) is a full-featured modal implementation for Rails ap
   - `base.rb`: Core modal component (Phlex-based)
   - `configuration.rb`: Global configuration management
   - `helpers/`: Rails helpers for views and controllers
+  - `railtie.rb`: Rails integration setup
   - Generators in `/lib/generators/` for installation
 
 - **JavaScript Package**: Located in `/javascript/`
   - `modal_controller.js`: Stimulus controller for modal behavior
-  - `index.js`: Main entry point
+  - `index.js`: Main entry point with Turbo integration
+  - `styles/`: CSS files for vanilla styling
   - Distributed files built to `/javascript/dist/`
 
+- **Demo Application**: Located in `/demo-app/`
+  - `Procfile.dev`: Development process file for overmind/foreman
+  - `bin/dev`: Development script for starting the demo app
+
 ## Common Development Commands
 
 ### JavaScript Development (run from `/javascript/` directory)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ultimate_turbo_modal (2.1.2)
+    ultimate_turbo_modal (2.2.2)
       actionpack
       activesupport
       phlex-rails

data/README.md

@@ -157,6 +157,28 @@ The demo app provides examples of:
 - 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 from 1.x
 
 Please see the [Upgrading Guide](UPGRADING.md) for detailed instructions on how to upgrade from version 1.x.

data/VERSION

@@ -1 +1 @@
-2.1.2
+2.2.2

data/javascript/index.js

@@ -8,10 +8,19 @@ Turbo.StreamActions.modal = function () {
   if (message == "close") window.modal?.hide();
 };
 
+// Check if the event target is one of our modal Turbo Frames
+const isModalFrameTarget = (event) => {
+  const target = event?.target;
+  return (
+    target instanceof Element &&
+    target.tagName.toLowerCase() === 'turbo-frame' &&
+    (target.id === 'modal' || target.id === 'modal-inner')
+  );
+};
+
 // Escape modal from the backend on redirects
 const handleTurboFrameMissing = (event) => {
-  if (event.detail.response.redirected &&
-    event.target == document.querySelector("turbo-frame#modal")) {
+  if (event.detail.response.redirected && isModalFrameTarget(event)) {
     event.preventDefault()
     event.detail.visit(event.detail.response)
   }
@@ -19,7 +28,7 @@ const handleTurboFrameMissing = (event) => {
 
 // Morph the innerHTML of the modal to prevent flickering and transition animations
 const handleTurboBeforeFrameRender = (event) => {
-  if (event.target.id === "modal") {
+  if (isModalFrameTarget(event)) {
     event.detail.render = (currentElement, newElement) => {
       Idiomorph.morph(currentElement, newElement, {
         morphstyle: 'innerHTML'

data/javascript/modal_controller.js

@@ -6,7 +6,7 @@ import { createFocusTrap } from 'focus-trap';
 const PACKAGE_VERSION = '__PACKAGE_VERSION__';
 
 export default class extends Controller {
-  static targets = ["container", "content"]
+  static targets = ["container", "content", "overlay", "outer"]
   static values = {
     advanceUrl: String,
     allowedClickOutsideSelector: String
@@ -48,7 +48,11 @@ export default class extends Controller {
     // Lock body scroll
     this.#lockBodyScroll();
 
-    enter(this.containerTarget).then(() => {
+    // Apply transitions to both overlay and outer elements
+    Promise.all([
+      enter(this.overlayTarget),
+      enter(this.outerTarget)
+    ]).then(() => {
       // Activate focus trap after the modal transition is complete
       this.#activateFocusTrap();
     });
@@ -92,6 +96,10 @@ export default class extends Controller {
     this.hideModal();
   }
 
+  close() {
+    this.hideModal();
+  }
+
   refreshPage() {
     window.Turbo.visit(window.location.href, { action: "replace" });
   }
@@ -122,7 +130,11 @@ export default class extends Controller {
     // Unlock body scroll
     this.#unlockBodyScroll();
     
-    leave(this.containerTarget).then(() => {
+    // Apply leave transitions to both overlay and outer elements
+    Promise.all([
+      leave(this.overlayTarget),
+      leave(this.outerTarget)
+    ]).then(() => {
       this.turboFrame.removeAttribute("src");
       this.containerTarget.remove();
       this.#resetHistoryAdvanced();
@@ -170,7 +182,7 @@ export default class extends Controller {
           initialFocus: () => {
             // Try to focus the first focusable element, or the modal itself
             const firstFocusable = this.contentTarget.querySelector(
-              'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+              'button:not([tabindex="-1"]), [href]:not([tabindex="-1"]), input:not([tabindex="-1"]), select:not([tabindex="-1"]), textarea:not([tabindex="-1"]), [tabindex]:not([tabindex="-1"])'
             );
             return firstFocusable || this.contentTarget;
           }

data/javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate_turbo_modal",
-  "version": "2.1.1",
+  "version": "2.2.1",
   "description": "The ultimate Turbo / Stimulus / Hotwire modal window for Rails",
   "main": "dist/ultimate_turbo_modal.min.js",
   "module": "dist/ultimate_turbo_modal.min.js",
@@ -10,6 +10,7 @@
   "scripts": {
     "update-version": "node scripts/update-version.js",
     "build": "yarn install && rollup -c",
+    "build:watch": "rollup -c -w",
     "release": "bash scripts/release-npm.sh"
   },
   "repository": {

data/javascript/styles/vanilla.css

@@ -1,3 +1,7 @@
+.hidden {
+  display: none
+}
+
 .dark {
   .modal-overlay {
     background-color: rgba(17, 24, 39, 0.8)
@@ -177,3 +181,85 @@
   width: 1.25rem;
   height: 1.25rem;
 }
+
+/*
+  Transition utilities for Vanilla flavor
+  These replicate the Tailwind transitions defined in tailwind.rb
+  using plain CSS classes referenced in vanilla.rb
+*/
+
+/* Overlay: Enter */
+.modal-transition-overlay-enter-animation {
+  transition-property: opacity;
+  transition-duration: 300ms; /* duration-300 */
+  transition-timing-function: ease-out; /* ease-out */
+}
+
+.modal-transition-overlay-enter-start {
+  opacity: 0; /* opacity-0 */
+}
+
+.modal-transition-overlay-enter-end {
+  opacity: 1; /* opacity-100 */
+}
+
+/* Overlay: Leave */
+.modal-transition-overlay-leave-animation {
+  transition-property: opacity;
+  transition-duration: 200ms; /* duration-200 */
+  transition-timing-function: ease-in; /* ease-in */
+}
+
+.modal-transition-overlay-leave-start {
+  opacity: 1; /* opacity-100 */
+}
+
+.modal-transition-overlay-leave-end {
+  opacity: 0; /* opacity-0 */
+}
+
+/* Dialog: Enter */
+.modal-transition-dialog-enter-animation {
+  transition-property: opacity, transform;
+  transition-duration: 300ms; /* duration-300 */
+  transition-timing-function: ease-out; /* ease-out */
+}
+
+.modal-transition-dialog-enter-start {
+  opacity: 0; /* opacity-0 */
+  transform: translateY(1rem) scale(1); /* translate-y-4 */
+}
+
+@media (min-width: 640px) {
+  .modal-transition-dialog-enter-start {
+    transform: translateY(0) scale(0.95); /* sm:translate-y-0 sm:scale-95 */
+  }
+}
+
+.modal-transition-dialog-enter-end {
+  opacity: 1; /* opacity-100 */
+  transform: translateY(0) scale(1); /* translate-y-0 scale-100 */
+}
+
+/* Dialog: Leave */
+.modal-transition-dialog-leave-animation {
+  transition-property: opacity, transform;
+  transition-duration: 200ms; /* duration-200 */
+  transition-timing-function: ease-in; /* ease-in */
+}
+
+.modal-transition-dialog-leave-start {
+  opacity: 1; /* opacity-100 */
+  transform: translateY(0) scale(1); /* translate-y-0 scale-100 */
+}
+
+.modal-transition-dialog-leave-end {
+  opacity: 0; /* opacity-0 */
+  transform: translateY(1rem) scale(1); /* translate-y-4 */
+}
+
+@media (min-width: 640px) {
+  .modal-transition-dialog-leave-end {
+    transform: translateY(0) scale(0.95); /* sm:translate-y-0 sm:scale-95 */
+  }
+}

data/lib/generators/ultimate_turbo_modal/base.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "pathname"
+
+module UltimateTurboModal
+  module Generators
+    class Base < Rails::Generators::Base
+      protected
+
+      def package_name
+        "ultimate_turbo_modal"
+      end
+
+      # Add JS dependency (for install flow)
+      def add_js_dependency
+        say "Attempting to set up JavaScript dependencies...", :yellow
+
+        version_spec = "#{package_name}@#{UltimateTurboModal::VERSION}"
+
+        if uses_importmaps?
+          say "Detected Importmaps. Pinning #{version_spec}...", :green
+          run "bin/importmap pin #{version_spec}"
+          say "✅ Pinned '#{package_name}' via importmap.", :green
+          return
+        end
+
+        if uses_javascript_bundler?
+          say "Detected jsbundling-rails (Yarn/npm/Bun). Adding #{package_name} package...", :green
+          if uses_yarn?
+            run "yarn add #{version_spec}"
+            say "✅ Added '#{package_name}' using Yarn.", :green
+          elsif uses_npm?
+            run "npm install --save #{version_spec}"
+            say "✅ Added '#{package_name}' using npm.", :green
+          elsif uses_bun?
+            run "bun add #{version_spec}"
+            say "✅ Added '#{package_name}' using Bun.", :green
+          else
+            say "Attempting to add with Yarn. If you use npm or Bun, please add manually.", :yellow
+            run "yarn add #{version_spec}"
+            say "If this failed or you use npm/bun, please run:", :yellow
+            say "npm install --save #{version_spec}", :cyan
+            say "# or", :cyan
+            say "bun add #{version_spec}", :cyan
+          end
+        else
+          say "Could not automatically detect Importmaps or jsbundling-rails.", :yellow
+          say "Please manually add the '#{package_name}' JavaScript package.", :yellow
+          say "If using Importmaps: bin/importmap pin #{version_spec}", :cyan
+          say "If using Yarn: yarn add #{version_spec}", :cyan
+          say "If using npm: npm install --save #{version_spec}", :cyan
+          say "If using Bun: bun add #{version_spec}", :cyan
+          say "Then, import it in your app/javascript/application.js:", :yellow
+          say "import '#{package_name}'", :cyan
+        end
+      end
+
+      # Install all JS dependencies (for update flow)
+      def install_all_js_dependencies
+        if uses_importmaps?
+          version_spec = "#{package_name}@#{UltimateTurboModal::VERSION}"
+          say "Detected Importmaps. Ensuring pin for #{version_spec}...", :green
+          run "bin/importmap pin #{version_spec}"
+          say "✅ Pinned '#{package_name}' via importmap.", :green
+          return
+        end
+
+        unless uses_javascript_bundler?
+          say "Could not detect Importmaps or jsbundling-rails. Skipping JS install step.", :yellow
+          return
+        end
+
+        say "Installing JavaScript dependencies...", :yellow
+        if uses_yarn?
+          run "yarn install"
+          say "✅ Installed dependencies with Yarn.", :green
+        elsif uses_npm?
+          run "npm install"
+          say "✅ Installed dependencies with npm.", :green
+        elsif uses_bun?
+          run "bun install"
+          say "✅ Installed dependencies with Bun.", :green
+        else
+          say "Attempting to install with Yarn. If you use npm or Bun, please run the appropriate command.", :yellow
+          run "yarn install"
+        end
+      end
+
+      def uses_importmaps?
+        File.exist?(rails_root_join("config", "importmap.rb"))
+      end
+
+      def uses_javascript_bundler?
+        File.exist?(rails_root_join("package.json"))
+      end
+
+      def uses_yarn?
+        File.exist?(rails_root_join("yarn.lock"))
+      end
+
+      def uses_npm?
+        File.exist?(rails_root_join("package-lock.json")) && !uses_yarn? && !uses_bun?
+      end
+
+      def uses_bun?
+        File.exist?(rails_root_join("bun.lockb"))
+      end
+
+      def rails_root_join(*args)
+        Pathname.new(destination_root).join(*args)
+      end
+    end
+  end
+end
+
+