[Feature] Dialog: use native <dialog> element (#343)

Merged
DJ
5mo ago
+119-31

Closes #343

How to reproduce the original problem

Before this change, opening the browser devtools and inspecting an open Dialog revealed the modal rendered as nested <div> elements cloned from a <template> tag — no native <dialog> semantics, no top-layer rendering, no built-in focus trap, and Esc required a manual keydown listener wired via a Stimulus action.

Steps:

  1. Visit any page on https://rubyui.com/docs/dialog
  2. Click "Open Dialog"
  3. Open browser devtools → Elements panel
  4. Observe the modal is rendered as <div data-controller="ruby-ui--dialog"> — no <dialog> element in the DOM

What changed

FileChange
gem/lib/ruby_ui/dialog/dialog_content.rbRemoved <template> wrapper and custom backdrop <div>; DialogContent now renders directly as a native <dialog> element with data-ruby-ui--dialog-target="dialog" and a click->ruby-ui--dialog#backdropClick action. The CSS backdrop: pseudo-element replaces the manual overlay div.
gem/lib/ruby_ui/dialog/dialog_controller.jsReplaced the insertAdjacentHTML / element.remove() pattern with dialogTarget.showModal() / dialogTarget.close(). Backdrop click is handled by comparing event.target === dialogTarget. A close event listener removes overflow-hidden from the body so Esc (which fires close natively) also unlocks scroll.
gem/test/ruby_ui/dialog_test.rbAdded 8 focused tests: regression test asserting <dialog> is rendered (not <div> / <template>), Stimulus target/action attributes, size variants, open value, trigger action, and close button action.

Public API is fully preserved — all component names, size variants, open: prop, and Stimulus action names (open, dismiss) remain unchanged.

Testing instructions

Automated tests

cd gem
bundle exec rake test TEST=test/ruby_ui/dialog_test.rb   # 233 tests, 1022 assertions
bundle exec rake                                          # full suite + linter

Manual browser verification (docs site)

  1. Start the docs site (cd docs && bin/dev)
  2. Navigate to /docs/dialog
  3. Click "Open Dialog"
  4. Open DevTools → Elements panel — confirm the modal is a <dialog> element (not a <div>)
  5. Press Esc — dialog should close and body scroll should be restored
  6. Click "Open Dialog" again, then click the backdrop (outside the dialog panel) — dialog should close
  7. Click "Open Dialog" again, then click the Cancel button — dialog should close
  8. While the dialog is open, confirm the page body does not scroll (overflow-hidden is applied to <body>)

Summary by cubic

Move Dialog to the native

element using showModal()/close() for top-layer rendering, native backdrop, focus trap, and Esc‑to‑close while keeping the public API and Stimulus actions unchanged. Also clear body scroll lock on controller disconnect to avoid stuck scrolling during Turbo navigation.
  • Refactors

    • Native <dialog>: DialogContent renders <dialog> with data-ruby-ui--dialog-target="dialog" and click->ruby-ui--dialog#backdropClick; controller uses showModal()/close() and listens for close to restore body scroll.
    • Removed template cloning and overlay; styling moved to backdrop:/open: utilities; tests cover native <dialog>, attributes, size variants, and open/dismiss actions.
  • Bug Fixes

    • Clear overflow-hidden in disconnect() so navigating with Turbo while a dialog is open doesn’t leave the page locked; rebuilt MCP registry to include native-dialog changes.