RubyGems - ultimate_turbo_modal - Versions diffs - 3.2.1 → 3.4.0 - Mend

ultimate_turbo_modal 3.2.1 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +13 -0
data/Gemfile.lock +1 -1
data/README.md +248 -0
data/VERSION +1 -1
data/app/assets/stylesheets/ultimate_turbo_modal.css +610 -0
data/lib/generators/ultimate_turbo_modal/base.rb +44 -0
data/lib/generators/ultimate_turbo_modal/install_generator.rb +8 -0
data/lib/generators/ultimate_turbo_modal/templates/flavors/custom.rb +10 -1
data/lib/generators/ultimate_turbo_modal/templates/flavors/tailwind.rb +78 -4
data/lib/generators/ultimate_turbo_modal/templates/flavors/vanilla.rb +14 -1
data/lib/generators/ultimate_turbo_modal/templates/ultimate_turbo_modal.rb +18 -0
data/lib/generators/ultimate_turbo_modal/update_generator.rb +2 -0
data/lib/ultimate_turbo_modal/base.rb +172 -26
data/lib/ultimate_turbo_modal/configuration.rb +45 -5
data/lib/ultimate_turbo_modal/helpers/view_helper.rb +31 -0
data/lib/ultimate_turbo_modal/railtie.rb +23 -0
data/lib/ultimate_turbo_modal.rb +4 -0
metadata +2 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0c59204e8c87cee87fc85083ef4147930a7a493b5d9c6a8ddf7e1ac76f04359
-  data.tar.gz: 92c975e4676ec8ae2ae953be97f6beea70d2aa3d90b6403564af08950710a058
+  metadata.gz: e8449cf081c6d1dfc2b84106cc16b316fb6a15b25031a2a9dc94c2ce4bf99b35
+  data.tar.gz: b1067b8a6ef21a15e9556bee1e8a0ceb45fdb453ff8fa772eda0ad5191b7d669
 SHA512:
-  metadata.gz: 918fac0dfe7519413443eac794e82b31d8014ecdbaae3279baeb0474fa00f2445b59c57f249ff35f7e5bcc0ab6c3dd6f91fecdaf3e30e34c78326b2d02e25082
-  data.tar.gz: 6cf8a3e810da824c8bb2cf6eb1f5c4fc9ef75671dbae67486289a927599c2c3984fa5d046fa2ac17562e78db63635145016bb4a0f1d46441b26e44c7b2d44b53
+  metadata.gz: 86b485906013944b475e4f0aece1ee980dd226aa160b8daed3628fb84b8b7cbbea8b015086310372f2fceab89d34372a18acd0b4cd76720dbf5af0cd18574f74
+  data.tar.gz: 5e6753fa5decf7401e07a2bda70dcef18a25fe56c2c487f0eb76e66dc010b556b52a2d7893201de73815431bd95600a80861de94e7758d863d3e98949d67783f

data/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,18 @@
 ## [Unreleased]
+## [3.4.0] - 2026-09-10
+- Added optional Turbo Confirm support: `data-turbo-confirm` prompts can now render as a UTMR dialog instead of the browser's `window.confirm`.
+- Fixed `<%= m.title do %>` and `<%= m.footer do %>` printing a `Proc` into the modal body. Both forms now work, with or without the `=`.
+## [3.3.0] - 2026-09-05
+- Added `close_on_submit`, which keeps a modal or drawer open after a successful form submission. Individual forms can override it with `data-modal-close-on-submit`.
+- Drawers now support the `advance` option to push their URL to browser history, matching modals. Defaults to `false`.
+- Fixed modals disappearing during in-frame updates that morph an already-open dialog.
+- Fixed stale close cleanup interfering with a newer modal opened in the same frame.
+- Fixed the vanilla flavor loading no styles on apps without a JavaScript bundler. The stylesheet now ships with the gem and can be included with `stylesheet_link_tag "ultimate_turbo_modal"`.
 ## [3.2.1] - 2026-05-07
 - Fixed drawers closing abruptly when pressing Escape after dismissing a modal opened from inside the drawer.

data/Gemfile.lock CHANGED Viewed

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    ultimate_turbo_modal (3.2.1)
+    ultimate_turbo_modal (3.4.0)
       actionpack (>= 8.0)
       activesupport (>= 8.0)
       phlex-rails (>= 2.0)

data/README.md CHANGED Viewed

@@ -26,6 +26,30 @@ $ bundle add ultimate_turbo_modal
 $ bundle exec rails g ultimate_turbo_modal:install
 ```
+### Stylesheet
+The `tailwind` and `custom` flavors are styled entirely by the classes in their flavor
+file, so they need no stylesheet.
+The `vanilla` flavor ships its styles as a CSS file. The install generator adds it to
+`app/views/layouts/application.html.erb` for you; if you need to add it by hand, put this
+in your layout's `<head>`:
+```erb
+<%= stylesheet_link_tag "ultimate_turbo_modal", "data-turbo-track": "reload" %>
+```
+The gem puts the stylesheet on the asset pipeline's load path, so this works with
+Propshaft and Sprockets whether you use importmaps or a JavaScript bundler. Keep it
+*before* your own stylesheets: where the two collide at equal specificity the later one
+wins, so loading the defaults first is what lets your own styles override them.
+If you would rather pull the CSS through your bundler, the npm package also ships it:
+```css
+@import 'ultimate_turbo_modal/dist/vanilla.css';
+```
 ## Usage
@@ -102,6 +126,7 @@ UltimateTurboModal.configure do |config|
   config.modal do |m|
     m.advance = false
     m.close_button = true
+    m.close_on_submit = true
     m.header = true
     m.header_divider = true
     m.footer_divider = true
@@ -111,7 +136,9 @@ UltimateTurboModal.configure do |config|
   config.drawer do |d|
     d.position = :right
+    d.advance = false
     d.close_button = true
+    d.close_on_submit = true
     d.header = true
     d.header_divider = false
     d.footer_divider = true
@@ -119,6 +146,14 @@ UltimateTurboModal.configure do |config|
     d.overlay = true
     d.size = :md
   end
+  # Only used when Turbo Confirm support is enabled.
+  # See https://github.com/cmer/ultimate_turbo_modal#turbo-confirm
+  config.confirm do |c|
+    c.title = "Are you sure?"
+    c.accept_label = "OK"
+    c.cancel_label = "Cancel"
+  end
 end
 ```
@@ -130,6 +165,7 @@ Per-instance options passed to `modal()` or `drawer()` override the defaults.
 |------|---------|-------------|
 | `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. |
+| `close_on_submit` | `true` | Whether a successful form submission dismisses the modal. See [Closing on form submission](#closing-on-form-submission). |
 | `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. |
@@ -177,8 +213,10 @@ Link to it the same way as a modal:
 |------|---------|-------------|
 | `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"`). |
+| `advance` | `false` | When opening the drawer, the URL in the URL bar will change to the URL of the view being shown in the drawer. The Back button dismisses the drawer 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. |
 | `overlay` | `true` | Whether to show a backdrop overlay behind the drawer. |
 | `close_button` | `true` | Shows or hide a close button (X). |
+| `close_on_submit` | `true` | Whether a successful form submission dismisses the drawer. See [Closing on form submission](#closing-on-form-submission). |
 | `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. |
@@ -203,6 +241,215 @@ Link to it the same way as a modal:
 | CSS string | Custom value, e.g. `"500px"` or `"50vw"` |
+## Closing on form submission
+By default, a form submitted inside a modal or drawer dismisses it once the
+submission succeeds. Set `close_on_submit: false` to keep it open instead —
+useful for chat composers, image uploaders, inline "add another" forms, and
+anything else where the user is expected to submit repeatedly:
+```erb
+<%= drawer(title: "Messages", close_on_submit: false) do %>
+  <%= render "messages/list" %>
+  <%= form_with model: Message.new do |f| %>
+    <%= f.text_field :body %>
+    <%= f.submit "Send" %>
+  <% end %>
+<% end %>
+```
+Respond with a Turbo Stream to update the contents in place, and send
+`turbo_stream.modal(:close)` from the server on the submissions that *should*
+dismiss it.
+Two things are worth calling out:
+- **Failed submissions never dismiss.** A 422 rendering validation errors leaves
+  the modal open regardless of this setting, so errors are shown in place.
+- **Redirects still dismiss.** If the server redirects to a page that doesn't
+  contain the modal frame, the browser is navigating away and the modal closes
+  (smoothly) even with `close_on_submit: false`.
+### Per-form overrides
+`data-modal-close-on-submit` on a form overrides the setting for that form
+alone, so a single modal can mix both behaviors:
+```erb
+<%= drawer(title: "Messages", close_on_submit: false) do %>
+  <%# Stays open — inherits close_on_submit: false %>
+  <%= form_with model: Message.new do |f| %>
+    <%= f.text_field :body %>
+    <%= f.submit "Send" %>
+  <% end %>
+  <%# Dismisses the drawer, despite close_on_submit: false %>
+  <%= form_with model: @conversation, method: :delete,
+                data: { modal_close_on_submit: true } do |f| %>
+    <%= f.submit "Delete conversation" %>
+  <% end %>
+<% end %>
+```
+It works in both directions: `data: { modal_close_on_submit: false }` on a form
+inside a default modal keeps that one form from dismissing it. Placing the
+attribute on a wrapping element applies it to every form inside; the nearest
+one wins.
+## Turbo Confirm
+Optional, opt-in. Once enabled, Turbo's `data-turbo-confirm` prompts render as
+UTMR dialogs in your app's flavor instead of the browser's `window.confirm`.
+Enabling it is one line in your layout:
+```erb
+<%= modal_confirm_template %>
+```
+That's the whole opt-in — no JavaScript changes. The helper renders an inert
+`<template>`, and its presence on the page is the switch: with it, UTMR handles
+confirmations; without it, Turbo falls back to `window.confirm` exactly as
+before. Remove the line to turn the feature off.
+You can also flip it from the initializer, which is handy for toggling per
+environment without touching the layout:
+```ruby
+UltimateTurboModal.configure do |config|
+  config.confirm do |c|
+    c.enabled = false
+  end
+end
+```
+### Basic usage
+Nothing changes about how you write confirmations:
+```erb
+<%= button_to "Delete", post_path(post), method: :delete,
+      form: { data: { turbo_confirm: "This can't be undone." } } %>
+```
+The message becomes the dialog body; the title and button labels come from your
+configured defaults.
+> [!NOTE]
+> Turbo only runs confirmations for form submissions. A plain `<a>` needs
+> `data-turbo-method` (or `data-turbo-stream`) for `data-turbo-confirm` to fire
+> at all — that is Turbo's behavior, not UTMR's.
+### Customizing a single confirmation
+For anything beyond the message, use the `modal_confirm` helper. It builds the
+`data` attributes for you:
+```erb
+<%= link_to "Delete", post_path(post), data: modal_confirm(
+      "This can't be undone.",
+      title: "Delete post?",
+      accept: "Delete",
+      variant: :danger,
+      turbo_method: :delete) %>
+```
+| Option | Description |
+|--------|-------------|
+| `body` | First positional argument. The message. |
+| `title` | Dialog heading. |
+| `accept` | Label for the confirming button. |
+| `cancel` | Label for the dismissing button. |
+| `variant` | `:danger` styles the accept button destructively and moves the initial focus to Cancel. |
+| `native` | `true` uses the browser's own `window.confirm` for this one prompt. |
+Any option you leave out keeps its configured default.
+You can also write the attributes by hand, which is convenient on forms:
+```erb
+<%= button_to "Delete", post_path(post), method: :delete, form: { data: {
+      turbo_confirm: "This can't be undone.",
+      turbo_confirm_title: "Delete post?",
+      turbo_confirm_accept: "Delete",
+      turbo_confirm_variant: "danger" } } %>
+```
+`data-turbo-confirm` itself has to be on the form or on the submit button:
+Turbo looks nowhere else, and a prompt written on a wrapping element is simply
+never triggered. The `data-turbo-confirm-*` options are read once the prompt has
+fired, so those may also sit on a wrapping element. The submitter wins when both
+it and the form carry the same option.
+> [!IMPORTANT]
+> On a **link**, use `modal_confirm`. Sibling `data-turbo-confirm-*` attributes
+> do not survive: Turbo rewrites a link carrying `data-turbo-method` into a
+> hidden form and copies only a fixed set of attributes across, so they are gone
+> before UTMR is called. The helper's JSON payload rides inside
+> `data-turbo-confirm` itself, which always survives. On forms, either style
+> works.
+### Defaults
+```ruby
+UltimateTurboModal.configure do |config|
+  config.confirm do |c|
+    c.enabled = true
+    c.title = "Are you sure?"
+    c.accept_label = "OK"
+    c.cancel_label = "Cancel"
+    c.close_button = false   # a confirm has its own Cancel button
+    c.header_divider = false # dividers chop up one or two lines of text
+    c.footer_divider = false
+    c.header = true
+    c.padding = true
+    c.overlay = true
+  end
+end
+```
+The confirm dialog is deliberately plainer than a modal: no close button and no
+dividers by default, and a set width (floor `20rem`, cap `28rem`) so a one-word
+prompt and a three-line one come out the same size. Adjust it by overriding
+`CONFIRM_CONTENT_CLASSES` in your flavor file.
+### Behavior
+- The dialog is appended to `<body>`, so it layers above an open modal or drawer without any extra setup.
+- **ESC** and the Cancel button both cancel — the action does not run.
+- Clicking the backdrop does nothing. A confirm has to be answered, so a stray click never decides it.
+- The confirming button is focused on open, so Enter accepts. `variant: :danger` focuses Cancel instead.
+- Accepting waits for the close animation to finish before the request is sent.
+- `window.modal` keeps pointing at the modal underneath, so `turbo_stream.modal(:close)` still addresses the right dialog.
+- `data-turbo-confirm-native` on a form or submitter opts that one confirmation back out to `window.confirm`. On a link, pass `native: true` to `modal_confirm` instead, for the same reason the other options have to travel in the payload.
+- If something else in your app assigns `Turbo.config.forms.confirm` after UTMR loads, it wins. Import `enableModalConfirm` from the package and call it afterwards to take the hook back.
+### Styling
+The dialog is cloned from the template, so it shares your flavor's dialog,
+backdrop and transition classes. Every slot falls back to its `MODAL_*` class
+unless the flavor defines a `CONFIRM_*` override, so you only need to define
+what should differ:
+| Constant | Falls back to |
+|----------|---------------|
+| `CONFIRM_INNER_CLASSES` | `MODAL_INNER_CLASSES` |
+| `CONFIRM_CONTENT_CLASSES` | `MODAL_CONTENT_CLASSES` |
+| `CONFIRM_HEADER_CLASSES` | `MODAL_HEADER_CLASSES` |
+| `CONFIRM_TITLE_CLASSES` | `MODAL_TITLE_CLASSES` |
+| `CONFIRM_TITLE_H_CLASSES` | `MODAL_TITLE_H_CLASSES` |
+| `CONFIRM_MAIN_CLASSES` | `MODAL_MAIN_CLASSES` |
+| `CONFIRM_FOOTER_CLASSES` | `MODAL_FOOTER_CLASSES` |
+| `CONFIRM_BODY_CLASSES` | — (confirm only) |
+| `CONFIRM_ACTIONS_CLASSES` | — (confirm only) |
+| `CONFIRM_ACCEPT_CLASSES` | — (confirm only) |
+| `CONFIRM_CANCEL_CLASSES` | — (confirm only) |
+Upgrading from an earlier version? Run
+`rails generate ultimate_turbo_modal:update` to refresh your flavor file — until
+you do, the confirm dialog falls back to the modal's classes and the four
+confirm-only slots render unstyled rather than raising.
 ## Opening a Modal from a Drawer
 You don't need to do anything special. Use `data-turbo-frame="modal"` like you would anywhere else, and UTMR handles the rest:
@@ -262,6 +509,7 @@ For a full lifecycle walkthrough and edge-case notes, see [docs/modal-from-drawe
 - Automatic (or not) close button
 - 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
+- Optional Turbo Confirm support: `data-turbo-confirm` prompts render as a styled dialog instead of the browser's `window.confirm`
 ### Running the Demo Application

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 3.2.1
1	+ 3.4.0