ultimate_turbo_modal 2.1.2 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17d0eab498c9c828467bea1e33c1250763a8361595847a29a421bedc84947f06
-  data.tar.gz: 41ab99f7579857ccd65d7c549d8626d2566fb952cabb5c97b7f8193e7930fa44
+  metadata.gz: f48f99a3169d751eb02f9efe0f357aa70b285097e03438e2d1b27d1693b9b59c
+  data.tar.gz: c333e8c524f3c2967d1ddc484aab887165f574e0969bdd1b1aa6d1a48752b7ba
 SHA512:
-  metadata.gz: e4925980e51ac9f8fc7e08245e8d79e3a73faca356e44ae45bedfd089e3ec3d2de17e2a5ab264f57dcae0c79b91a53e37ee3661dcb57541b422b563f3e2a8ff1
-  data.tar.gz: 93f0bb944adfcc54e844ce3d2d3438bdfdaabb3cd648bb22b87937a6b8267a46e842db622ffc7c04c7b9a2a578da3ea1c4c411742f44821368c4fd299a1c411f
+  metadata.gz: be4aa9c324429196062c98fd8845b484eb2f14f76e96ee2581063b05568f287e3e4f1961e55a5e6d11a2043a3785af13ebaaf1d9f6594abeb3750f785621f631
+  data.tar.gz: aaad99d25ccbd2bceb518a1a85ecf2e28a7e768e61ff478fddfc723aad170ef06cd7f325fc012e405008799f43f90600440cff93e29528c81cfcbb07b8c94184

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,14 @@
+## [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.1)
       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.1

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();
     });
@@ -122,7 +126,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();

data/javascript/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate_turbo_modal",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "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/templates/flavors/custom.rb

@@ -4,9 +4,9 @@
 # TODO: define the classes for each HTML element.
 module UltimateTurboModal::Flavors
   class Custom < UltimateTurboModal::Base
-    DIV_DIALOG_CLASSES = ""
+    DIV_MODAL_CONTAINER_CLASSES = ""
     DIV_OVERLAY_CLASSES = ""
-    DIV_OUTER_CLASSES = ""
+    DIV_DIALOG_CLASSES = ""
     DIV_INNER_CLASSES = ""
     DIV_CONTENT_CLASSES = ""
     DIV_MAIN_CLASSES = ""
@@ -18,5 +18,32 @@ module UltimateTurboModal::Flavors
     BUTTON_CLOSE_SR_ONLY_CLASSES = ""
     CLOSE_BUTTON_TAG_CLASSES = ""
     ICON_CLOSE_CLASSES = ""
+
+    TRANSITIONS = {
+      overlay: {
+        enter: {
+          animation: "",
+          start: "",
+          end: ""
+        },
+        leave: {
+          animation: "",
+          start: "",
+          end: ""
+        }
+      },
+      dialog: {
+        enter: {
+          animation: "",
+          start: "",
+          end: ""
+        },
+        leave: {
+          animation: "",
+          start: "",
+          end: ""
+        }
+      }
+    }
   end
 end

data/lib/generators/ultimate_turbo_modal/templates/flavors/tailwind.rb

@@ -3,9 +3,9 @@
 # Tailwind CSS v4
 module UltimateTurboModal::Flavors
   class Tailwind < UltimateTurboModal::Base
-    DIV_DIALOG_CLASSES = "relative group z-50"
-    DIV_OVERLAY_CLASSES = "fixed inset-0 bg-gray-900/70 transition-opacity dark:bg-gray-900/80"
-    DIV_OUTER_CLASSES = "fixed inset-0 overflow-y-auto sm:max-w-[80%] md:max-w-3xl sm:mx-auto m-4"
+    DIV_MODAL_CONTAINER_CLASSES = "relative group z-50"
+    DIV_OVERLAY_CLASSES = "fixed inset-0 bg-gray-900/70 transition-opacity dark:bg-gray-900/80 opacity-0"
+    DIV_DIALOG_CLASSES = "fixed inset-0 overflow-y-auto sm:max-w-[80%] md:max-w-3xl sm:mx-auto m-4 opacity-0"
     DIV_INNER_CLASSES = "flex min-h-full items-start justify-center pt-[10vh] sm:p-4"
     DIV_CONTENT_CLASSES = "relative transform max-h-screen overflow-hidden rounded-lg bg-white text-left shadow-lg transition-all sm:my-8 sm:max-w-3xl dark:bg-gray-800 dark:text-white"
     DIV_MAIN_CLASSES = "group-data-[padding=true]:p-4 group-data-[padding=true]:pt-2 overflow-y-auto max-h-[75vh]"
@@ -17,5 +17,32 @@ module UltimateTurboModal::Flavors
     BUTTON_CLOSE_SR_ONLY_CLASSES = "sr-only"
     CLOSE_BUTTON_TAG_CLASSES = "text-gray-400 bg-transparent hover:bg-gray-200 hover:text-gray-900 rounded-lg text-sm p-1.5 ml-auto inline-flex items-center dark:hover:bg-gray-600 dark:hover:text-white"
     ICON_CLOSE_CLASSES = "w-5 h-5"
+
+    TRANSITIONS = {
+      overlay: {
+        enter: {
+          animation: "ease-out duration-300",
+          start: "opacity-0",
+          end: "opacity-100"
+        },
+        leave: {
+          animation: "ease-in duration-200",
+          start: "opacity-100",
+          end: "opacity-0"
+        }
+      },
+      dialog: {
+        enter: {
+          animation: "ease-out duration-300",
+          start: "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95",
+          end: "opacity-100 translate-y-0 sm:scale-100"
+        },
+        leave: {
+          animation: "ease-in duration-200",
+          start: "opacity-100 translate-y-0 sm:scale-100",
+          end: "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"
+        }
+      }
+    }
   end
 end

data/lib/generators/ultimate_turbo_modal/templates/flavors/tailwind3.rb

@@ -3,9 +3,9 @@
 # Tailwind CSS v3
 module UltimateTurboModal::Flavors
   class Tailwind3 < UltimateTurboModal::Base
-    DIV_DIALOG_CLASSES = "relative z-50"
+    DIV_MODAL_CONTAINER_CLASSES = "relative z-50"
     DIV_OVERLAY_CLASSES = "fixed inset-0 bg-gray-900 bg-opacity-70 transition-opacity dark:bg-gray-900 dark:bg-opacity-80"
-    DIV_OUTER_CLASSES = "fixed inset-0 overflow-y-auto sm:max-w-[80%] md:max-w-3xl sm:mx-auto m-4"
+    DIV_DIALOG_CLASSES = "fixed inset-0 overflow-y-auto sm:max-w-[80%] md:max-w-3xl sm:mx-auto m-4"
     DIV_INNER_CLASSES = "flex min-h-full items-start justify-center pt-[10vh] sm:p-4"
     DIV_CONTENT_CLASSES = "relative transform max-h-screen overflow-hidden rounded-lg bg-white text-left shadow-xl transition-all sm:my-8 sm:max-w-3xl dark:bg-gray-800 dark:text-white"
     DIV_MAIN_CLASSES = "p-4 pt-2 overflow-y-auto max-h-[75vh]"
@@ -17,5 +17,32 @@ module UltimateTurboModal::Flavors
     BUTTON_CLOSE_SR_ONLY_CLASSES = "sr-only"
     CLOSE_BUTTON_TAG_CLASSES = "text-gray-400 bg-transparent hover:bg-gray-200 hover:text-gray-900 rounded-lg text-sm p-1.5 ml-auto inline-flex items-center dark:hover:bg-gray-600 dark:hover:text-white"
     ICON_CLOSE_CLASSES = "w-5 h-5"
+
+    TRANSITIONS = {
+      overlay: {
+        enter: {
+          animation: "ease-out duration-300",
+          start: "opacity-0",
+          end: "opacity-100"
+        },
+        leave: {
+          animation: "ease-in duration-200",
+          start: "opacity-100",
+          end: "opacity-0"
+        }
+      },
+      dialog: {
+        enter: {
+          animation: "ease-out duration-300",
+          start: "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95",
+          end: "opacity-100 translate-y-0 sm:scale-100"
+        },
+        leave: {
+          animation: "ease-in duration-200",
+          start: "opacity-100 translate-y-0 sm:scale-100",
+          end: "opacity-0 translate-y-4 sm:translate-y-0 sm:scale-95"
+        }
+      }
+    }
   end
 end

data/lib/generators/ultimate_turbo_modal/templates/flavors/vanilla.rb

@@ -3,9 +3,10 @@
 # Vanilla CSS
 module UltimateTurboModal::Flavors
   class Vanilla < UltimateTurboModal::Base
-    DIV_DIALOG_CLASSES = "modal-container"
-    DIV_OVERLAY_CLASSES = "modal-overlay"
-    DIV_OUTER_CLASSES = "modal-outer"
+    DIV_MODAL_CONTAINER_CLASSES = "modal-container"
+    # Include enter-start classes so initial paint is hidden and transitions can animate smoothly
+    DIV_OVERLAY_CLASSES = "modal-overlay modal-transition-overlay-enter-start"
+    DIV_DIALOG_CLASSES = "modal-outer modal-transition-dialog-enter-start"
     DIV_INNER_CLASSES = "modal-inner"
     DIV_CONTENT_CLASSES = "modal-content"
     DIV_MAIN_CLASSES = "modal-main"
@@ -17,5 +18,32 @@ module UltimateTurboModal::Flavors
     BUTTON_CLOSE_SR_ONLY_CLASSES = "sr-only"
     CLOSE_BUTTON_TAG_CLASSES = "modal-close-button"
     ICON_CLOSE_CLASSES = "modal-close-icon"
+    
+    TRANSITIONS = {
+      overlay: {
+        enter: {
+          animation: "modal-transition-overlay-enter-animation",
+          start: "modal-transition-overlay-enter-start",
+          end: "modal-transition-overlay-enter-end"
+        },
+        leave: {
+          animation: "modal-transition-overlay-leave-animation",
+          start: "modal-transition-overlay-leave-start",
+          end: "modal-transition-overlay-leave-end"
+        }
+      },
+      dialog: {
+        enter: {
+          animation: "modal-transition-dialog-enter-animation",
+          start: "modal-transition-dialog-enter-start",
+          end: "modal-transition-dialog-enter-end"
+        },
+        leave: {
+          animation: "modal-transition-dialog-leave-animation",
+          start: "modal-transition-dialog-leave-start",
+          end: "modal-transition-dialog-leave-end"
+        }
+      }
+    }
   end
 end