dialog-patterns

📁 majesticlabs-dev/majestic-marketplace 📅 8 days ago

总安装量

周安装量

#26350

全站排名

安装命令

npx skills add https://github.com/majesticlabs-dev/majestic-marketplace --skill dialog-patterns

Agent 安装分布

opencode 2

claude-code 2

replit 2

openhands 1

zencoder 1

Skill 文档

Native Dialog Patterns for Rails

Build accessible, modern dialog UIs using the native HTML <dialog> element with Turbo Frames and Stimulus. No JavaScript frameworks or heavy libraries required.

When to Use This Skill

Building modal dialogs for forms, confirmations, or content
Creating toast/alert notifications
Implementing confirmation dialogs (delete, destructive actions)
Any overlay UI that needs focus management and accessibility

Why Native `<dialog>`?

Feature	Native `<dialog>`	Custom Modal
Focus trapping	Built-in	Manual implementation
ESC to close	Built-in	Manual implementation
Backdrop	Built-in (`::backdrop`)	Manual overlay
Accessibility	Native `role="dialog"`	Manual ARIA
Top layer	Automatic (above all content)	z-index battles
Scroll lock	Automatic	Manual `overflow: hidden`

Zero-JavaScript Confirmation Dialogs (Recommended)

Modern browsers support the Invoker Commands API for declarative dialog controlâno JavaScript required. See resources/zero-js-patterns.md for complete examples.

Quick Reference

<%= button_tag "Delete", commandfor: "delete-#{post.id}", command: "show-modal" %>

<dialog id="delete-<%= post.id %>" closedby="any" role="alertdialog">
  <h3>Delete "<%= post.title %>"?</h3>
  <button commandfor="delete-<%= post.id %>" command="close">Cancel</button>
  <%= button_to "Delete", post, method: :delete %>
</dialog>

Key Attributes

Attribute	Purpose
`commandfor="id"`	References the dialog to control
`command="show-modal"`	Opens as modal (backdrop, focus trap)
`command="close"`	Closes the dialog
`closedby="any"`	Enables backdrop click and ESC to close

When to Use Zero-JS vs Stimulus

Scenario	Approach
Simple confirmations	Zero-JS (Invoker Commands)
Modals with async content	Stimulus + Turbo Frames
Complex multi-step dialogs	Stimulus controller
Animations	CSS `@starting-style`

Additional Patterns (see resources/)

CSS animations with @starting-style for enter/exit transitions
Turbo.config.forms.confirm to replace ugly browser dialogs
Progressive enhancement for cross-browser compatibility

Core Pattern: Async Modal with Turbo Frames

The recommended pattern for Rails modals combines three technologies:

Turbo Frame – Async content loading without page reload
Native <dialog> – Accessible modal presentation
Stimulus controller – Lifecycle management

Step 1: Layout Container

Add a modal turbo-frame to your layout:

<%# app/views/layouts/application.html.erb %>
<body>
  <%= yield %>

  <%# Modal injection point %>
  <%= turbo_frame_tag :modal %>
</body>

Step 2: Trigger Links

Target the modal frame from any link:

<%# Any view %>
<%= link_to "New Post", new_post_path, data: { turbo_frame: :modal } %>
<%= link_to "Edit", edit_post_path(@post), data: { turbo_frame: :modal } %>
<%= link_to "Confirm Delete", confirm_delete_post_path(@post), data: { turbo_frame: :modal } %>

Step 3: Modal Content View

Wrap modal content in matching turbo-frame with nested inner frame:

<%# app/views/posts/new.html.erb %>
<%= turbo_frame_tag :modal do %>
  <%# Inner frame prevents flash during form validation %>
  <%= turbo_frame_tag :modal_content do %>
    <dialog data-controller="dialog" data-action="click->dialog#clickOutside" open>
      <article>
        <header>
          <h2>New Post</h2>
          <button data-action="dialog#close" aria-label="Close">&times;</button>
        </header>

        <%= render "form", post: @post %>
      </article>
    </dialog>
  <% end %>
<% end %>

Step 4: Stimulus Controller

// app/javascript/controllers/dialog_controller.js
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    // Auto-open when content loads via Turbo
    this.element.showModal()

    // Store original scroll position
    this.scrollY = window.scrollY
  }

  disconnect() {
    // Clean up turbo-frame to prevent stale content flash
    const frame = this.element.closest("turbo-frame")
    if (frame) {
      frame.removeAttribute("src")
      // Safe DOM clearing without innerHTML
      frame.replaceChildren()
    }
  }

  close() {
    this.element.close()
  }

  clickOutside(event) {
    // Close when clicking backdrop (the dialog element itself, not content)
    if (event.target === this.element) {
      this.close()
    }
  }

  // Handle ESC key (native behavior, but can customize)
  keydown(event) {
    if (event.key === "Escape") {
      this.close()
    }
  }
}

Step 5: Styling

/* app/assets/stylesheets/components/dialog.css */
dialog {
  border: none;
  border-radius: 0.5rem;
  padding: 0;
  max-width: 32rem;
  width: 90vw;
  box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);
}

dialog::backdrop {
  background: rgb(0 0 0 / 0.5);
  backdrop-filter: blur(2px);
}

dialog article {
  padding: 1.5rem;
}

dialog header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 1rem;
}

/* Prevent background scroll when modal open */
body:has(dialog[open]) {
  overflow: hidden;
}

With Tailwind:

<dialog class="rounded-lg shadow-xl max-w-lg w-[90vw] p-0 backdrop:bg-black/50 backdrop:backdrop-blur-sm"
        data-controller="dialog"
        data-action="click->dialog#clickOutside">
  <!-- content -->
</dialog>

Why Nested Turbo Frames?

The nested frame pattern (modal > modal_content) prevents content flashing:

<%= turbo_frame_tag :modal do %>
  <%= turbo_frame_tag :modal_content do %>
    <dialog>...</dialog>
  <% end %>
<% end %>

Problem without nested frame: When a form inside the modal has validation errors and re-renders, the outer frame briefly shows the old content before replacing it.

Solution with nested frame: The inner frame handles form re-renders independently, keeping the modal structure stable.

Form Handling in Modals

Successful Submission

Redirect with Turbo to close modal and update page:

# app/controllers/posts_controller.rb
def create
  @post = Post.new(post_params)

  if @post.save
    redirect_to posts_path, notice: "Post created!"
  else
    render :new, status: :unprocessable_entity
  end
end

The redirect navigates _top (full page), effectively closing the modal.

Validation Errors

Re-render the form with 422 status to keep modal open:

render :new, status: :unprocessable_entity

Turbo Stream Response (Stay in Modal)

To update content without closing:

def create
  @post = Post.new(post_params)

  if @post.save
    respond_to do |format|
      format.turbo_stream {
        render turbo_stream: [
          turbo_stream.append("posts", partial: "posts/post", locals: { post: @post }),
          turbo_stream.update("modal", "")  # Clear modal
        ]
      }
      format.html { redirect_to posts_path }
    end
  else
    render :new, status: :unprocessable_entity
  end
end

Confirmation Dialog Pattern

For destructive actions like delete:

The View

<%# app/views/posts/confirm_delete.html.erb %>
<%= turbo_frame_tag :modal do %>
  <dialog data-controller="dialog" data-action="click->dialog#clickOutside" open>
    <article>
      <h2>Delete Post?</h2>
      <p>Are you sure you want to delete "<%= @post.title %>"? This cannot be undone.</p>

      <footer class="flex gap-2 justify-end mt-4">
        <button data-action="dialog#close" class="btn btn-secondary">
          Cancel
        </button>
        <%= button_to "Delete", @post,
              method: :delete,
              class: "btn btn-danger",
              data: { turbo_confirm: false } %>
      </footer>
    </article>
  </dialog>
<% end %>

The Route

# config/routes.rb
resources :posts do
  member do
    get :confirm_delete
  end
end

The Trigger

<%= link_to "Delete", confirm_delete_post_path(@post), data: { turbo_frame: :modal } %>

Alert/Toast Pattern

For flash messages and notifications. Use show() instead of showModal() for non-modal presentation. See resources/toast-slideover-patterns.md for complete implementation.

<dialog class="toast" data-controller="toast" data-toast-duration-value="5000">
  <p><%= message %></p>
</dialog>

Key difference: show() opens without backdrop or focus trap (toasts), showModal() centers with backdrop (modals).

Slideover Panel Pattern

For side panels (settings, filters, details). See resources/toast-slideover-patterns.md for styling and animations.

<dialog class="slideover" data-controller="dialog" data-action="click->dialog#clickOutside">
  <aside>
    <header><h2>Filters</h2></header>
    <%= render "filters" %>
  </aside>
</dialog>

Accessibility Checklist

Native <dialog> handles most accessibility, but verify:

Focus management – First focusable element receives focus on open
Focus trap – Tab cycling stays within dialog (native behavior)
ESC closes – Native behavior with showModal()
Background inert – Content behind dialog is not interactive (native)
Visible close button – Not just ESC, provide visible control
Descriptive title – Use <h2> or aria-labelledby
Return focus – Focus returns to trigger element on close

Enhanced Accessibility

<dialog aria-labelledby="dialog-title"
        aria-describedby="dialog-description"
        data-controller="dialog">
  <h2 id="dialog-title">Confirm Action</h2>
  <p id="dialog-description">This action cannot be undone.</p>
  <!-- content -->
</dialog>

Focus Return

// Enhanced dialog controller with focus return
connect() {
  this.previouslyFocused = document.activeElement
  this.element.showModal()
}

close() {
  this.element.close()
  this.previouslyFocused?.focus()
}

Common Patterns Summary

Pattern	Container	Stimulus	`show` method
Modal form	`turbo_frame_tag :modal`	`dialog`	`showModal()`
Confirmation	`turbo_frame_tag :modal`	`dialog`	`showModal()`
Toast/Alert	Fixed position	`toast`	`show()`
Slideover	`turbo_frame_tag :modal`	`dialog`	`showModal()`

Anti-Patterns to Avoid

Anti-Pattern	Problem	Solution
Custom modal without `<dialog>`	No native accessibility	Use native `<dialog>`
Missing nested turbo-frame	Content flash on validation	Add inner frame
Not clearing frame on close	Stale content on reopen	Clear with `replaceChildren()` in `disconnect()`
z-index for stacking	Battles with other elements	`<dialog>` uses top layer
Manual focus trap	Complex, error-prone	`showModal()` handles it
Inline backdrop div	Extra markup	Use `::backdrop` pseudo-element

Testing Dialogs

# System test - use `within "dialog"` to scope assertions
within "dialog" do
  fill_in "Title", with: "My Post"
  click_button "Create"
end
expect(page).not_to have_selector("dialog[open]")  # Modal closed

Browser Support

Pattern	Chrome	Firefox	Safari
Native `<dialog>`	37+	98+	15.4+
Invoker Commands	135+	144+	26.2+
`@starting-style`	117+	129+	17.5+

For older browsers: dialog polyfill, invokers polyfill. See resources/zero-js-patterns.md for progressive enhancement strategies.

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台