RubyGems - turbo_overlay - Versions diffs - 0.3.0 - Mend

turbo_overlay 0.3.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 (57) hide show

data/README.md ADDED Viewed

@@ -0,0 +1,330 @@
+# Turbo Overlay
+Render any Rails view inside a stackable modal, drawer, or popover
+using Turbo Streams — without duplicating templates, hand-rolling
+Stimulus controllers, or coupling your domain to a CSS framework.
+- **Four overlay types**: modal, drawer, popover, hover hint.
+- **Stacking by default.** Open an overlay from inside another and the
+  new one slides on top instead of replacing it. Dismissal affects
+  only the topmost layer.
+- **Themes ship in the gem** for Tailwind, Bootstrap 5, Bootstrap 3,
+  and plain CSS. Switch with one config option.
+- **Native `<dialog>`** for every theme — top-layer stacking, focus
+  trap, ESC/backdrop dismiss come from the browser. No `window.bootstrap`,
+  no jQuery, no z-index wars.
+- **Hover hints** with Turbo prefetch coordination. One fetch warms the
+  navigation *and* seeds a preview popover.
+- **Themed `data-turbo-confirm`** prompts that match your overlay look
+  and stack like one.
+## Requirements
+- Rails ≥ 6.1
+- turbo-rails ≥ 2.0 (Turbo 8) — required for `data-turbo-stream="true"` on GET links
+## Installation
+```ruby
+# Gemfile
+gem "turbo_overlay"
+```
+```bash
+bundle install
+bin/rails generate turbo_overlay:install --theme tailwind
+```
+Themes: `plain` (default), `tailwind`, `bootstrap5`, `bootstrap3`.
+The generator wires the host app: it copies the theme's chrome
+partials into `app/views/turbo_overlay/`, writes
+`config/initializers/turbo_overlay.rb`, injects `overlay_stack_tag`
+into your application layout, and registers the Stimulus / asset
+wiring appropriate to your build setup (importmap, propshaft,
+sprockets, jsbundling, cssbundling).
+### Required: `overlay_stack_tag` in your layout
+The gem **will not render overlays** without `overlay_stack_tag`
+present in your application layout. The generator injects it
+automatically when it finds `app/views/layouts/application.html.erb`,
+but verify it's there — and add it manually if you use a non-standard
+layout, run the generator with `--skip-layout-inject`, or the
+generator prints a yellow warning about it:
+```erb
+<%# app/views/layouts/application.html.erb %>
+<body>
+  <%= yield %>
+  <%= overlay_stack_tag %>
+</body>
+```
+This renders the slots overlays mount into. Without it, modal /
+drawer / popover / hint links navigate full-page instead of opening
+as overlays.
+### Required: `TurboOverlay::Controller` concern
+The final wiring step is your `ApplicationController`. Include the
+concern:
+```ruby
+class ApplicationController < ActionController::Base
+  include TurboOverlay::Controller
+end
+```
+Including the concern installs a `layout` proc that swaps to the
+matching overlay layout on overlay requests. Plain turbo-frame
+requests keep their turbo-rails layout.
+Overlay layouts **replace** your application layout for overlay
+requests — only the view content is wrapped in the dialog markup,
+not your nav, header, or footer.
+### Custom layouts
+If your controller uses its own layout method, call
+`turbo_overlay_layout` from it:
+```ruby
+layout :custom_layout
+def custom_layout
+  turbo_overlay_layout || "my_app_layout"
+end
+```
+A static `layout "admin"` declaration needs to be a method to thread
+`turbo_overlay_layout` through.
+If you skip the install generator the gem falls back to a plain
+`<dialog>` chrome so modals and drawers still work, just unstyled
+beyond the gem's CSS.
+See [docs/installation.md](docs/installation.md) for the full
+install generator output, bundling-app setup, and the `eject`
+generator.
+## Usage
+### Open a view in an overlay
+```erb
+<%= modal_link_to   "New User",   new_user_path %>
+<%= drawer_link_to  "Filters",    filters_path %>
+<%= popover_link_to "Edit",       edit_user_path(@user) %>
+```
+Modals and drawers stack. Popovers anchor to the trigger and replace
+each other; modals and drawers still stack on top of an open popover.
+See [docs/popovers.md](docs/popovers.md) for per-link options
+(`position:`, `align:`, `offset:`, `backdrop:`) and the
+single-popover behavior.
+For non-GET triggers — deleting an item, creating a record, kicking
+off a wizard — use the `button_to` counterparts:
+```erb
+<%= modal_button_to   "Delete", widget_path(@w), method: :delete %>
+<%= drawer_button_to  "Start wizard", wizards_path, method: :post %>
+<%= popover_button_to "Quick edit",   widget_path(@w), method: :patch %>
+```
+The form submits with the same `X-Turbo-Overlay-*` headers the link
+helpers send on click, so the controller renders identically.
+### Open an overlay from JavaScript
+For triggers that aren't anchors — a Google Maps marker, an SVG hit
+region, a custom element — call `TurboOverlay.visit(url, options)`.
+Full option parity with the link helpers, exposed as both a named
+export and a `window.TurboOverlay` global.
+```js
+// Modal from a map marker
+google.maps.event.addListener(marker, "click", () => {
+  TurboOverlay.visit("/places/123")
+})
+// Drawer with URL advance
+TurboOverlay.visit("/cart", { type: "drawer", advance: true })
+// Popover anchored to a non-anchor element — `anchor` is required
+button.addEventListener("click", (event) => {
+  TurboOverlay.visit("/preview/9", {
+    type: "popover",
+    anchor: event.currentTarget,
+    position: "top",
+  })
+})
+```
+Prefer the Rails link helpers for ordinary navigation; reach for
+`TurboOverlay.visit` only when the trigger isn't a link. See
+[docs/reference.md](docs/reference.md#javascript-api) for the full
+option list.
+### Customize what the overlay renders
+The chrome yields a body and reads two `content_for` blocks. The
+keys are generic so the same view renders correctly in a modal or
+a drawer:
+```erb
+<%# app/views/users/new.html.erb %>
+<% overlay_title "New User" %>
+<%= form_with(model: @user) do |f| %>
+  <%= f.text_field :name %>
+<% end %>
+<% overlay_footer do %>
+  <%= modal_dismiss_link_to "Cancel", users_path, class: "btn btn-secondary" %>
+  <button type="submit" class="btn btn-primary">Save</button>
+<% end %>
+```
+Variant templates pick different markup per chrome:
+```
+app/views/users/show.html.erb          # full-page
+app/views/users/show.html+modal.erb    # in a modal
+app/views/users/show.html+drawer.erb   # in a drawer
+app/views/users/show.html+popover.erb  # in a popover
+```
+See [docs/customization.md](docs/customization.md) for the
+overlay-template footgun, chrome partial structure, close-button
+suppression, and stable overlay ids.
+### Close the overlay
+Two paths, both supported.
+**Implicit (the default).** A form submission inside an overlay that
+redirects closes the overlay and visits the redirect target. Most
+Rails CRUD actions need no overlay-specific code:
+```ruby
+def create
+  @user = User.new(user_params)
+  if @user.save
+    redirect_to users_path                       # overlay closes; browser lands on /users
+  else
+    render :new, status: :unprocessable_entity   # form re-renders in place
+  end
+end
+```
+Validation failures (`:unprocessable_entity`, 422) don't redirect, so
+the form re-renders in the overlay with errors in place. If the
+redirect goes back to the page the overlay was opened from, the host
+page morphs in place behind the closing overlay so there's no
+flash-of-stale-content — no app configuration needed.
+**Explicit.** `turbo_stream.overlay(:close)` closes the top overlay
+from any non-redirect response. Useful when the action wants to
+update other parts of the page in the same response:
+```ruby
+render turbo_stream: [
+  turbo_stream.update("flash", partial: "shared/flash"),
+  turbo_stream.overlay(:close)
+]
+```
+See [docs/close-on-redirect.md](docs/close-on-redirect.md) for
+opt-outs (`keep_overlay_open_on_redirect`, per-form data attribute),
+the smooth-same-page-redirect mechanics, and stack-scoped close
+variants.
+ESC and clicking the backdrop dismiss the top overlay out of the
+box. Opt a specific overlay out with
+`data-turbo-overlay-backdrop-dismiss-value="false"`.
+### URL advance
+Pass `advance: true` on a modal or drawer link to push the link's
+target URL into the browser history bar when the overlay opens.
+Browser-back closes the top overlay instead of navigating away.
+Default off.
+```erb
+<%= modal_link_to  "Edit",  edit_user_path(@user), advance: true %>
+<%= drawer_link_to "Filter", filters_path,         advance: "/users?filtering" %>
+```
+Per-link `advance:` accepts `true` (push `link.href`), a String (push
+a custom URL), or `false` (opt out when a type default is on). Set
+the type default in the initializer:
+```ruby
+TurboOverlay.configure do |c|
+  c.modal  { |m| m.advance = true }
+  c.drawer { |d| d.advance = true }
+end
+```
+Popovers and hints never advance — they're ephemeral and shouldn't
+churn browser history.
+Note: the pushed URL is not guaranteed to re-open the overlay on a
+fresh visit; how the app routes that URL (full page, redirect, or a
+controller that itself opens the overlay) is the host app's call.
+### Loading state, themed confirms, and hover hints
+- [docs/loading-and-confirm.md](docs/loading-and-confirm.md) —
+  loading placeholders and themed `data-turbo-confirm`.
+- [docs/hints.md](docs/hints.md) — hover-preview popovers and the
+  `+hint` variant template.
+## Themes
+| Theme        | Modal | Drawer | Popover | Hint | Notes                                                       |
+|--------------|:-----:|:------:|:-------:|:----:|-------------------------------------------------------------|
+| `plain`      | ✓     | ✓      | ✓       | ✓    | Native `<dialog>`, minimal vanilla CSS                      |
+| `tailwind`   | ✓     | ✓      | ✓       | ✓    | Native `<dialog>`, Tailwind classes                         |
+| `bootstrap5` | ✓     | ✓      | ✓       | ✓    | Native `<dialog>` wrapping BS5 modal/offcanvas/popover markup |
+| `bootstrap3` | ✓     | ✓      | ✓       | ✓    | Native `<dialog>` wrapping BS3 modal/popover markup; vanilla drawer |
+Every theme uses the same JavaScript and CSS — only the chrome
+partial Rails renders inside the dialog varies. Animations honor
+`prefers-reduced-motion: reduce`. Stacking is handled by the
+browser's `<dialog>` top layer regardless of theme.
+## Documentation
+- [Installation](docs/installation.md) — generator details, bundling
+  apps, eject.
+- [Popovers](docs/popovers.md) — per-link positioning, single-popover
+  behavior, link targeting inside popovers.
+- [Hints](docs/hints.md) — hover previews, prefetch coordination,
+  the `+hint` variant template.
+- [Loading & confirm](docs/loading-and-confirm.md) — loading
+  placeholders and themed confirm dialogs.
+- [Customization](docs/customization.md) — chrome partials, variant
+  templates, stable ids, the full-page-render footgun.
+- [Third-party form widgets](docs/third-party-widgets.md) — using
+  Tom Select, flatpickr, Select2, Tippy inside overlays.
+- [Reference](docs/reference.md) — full configuration, helper
+  reference, JavaScript events.
+- [Accessibility](docs/accessibility.md) — what the gem gives you,
+  what you provide, known limitations.
+- [Architecture](docs/architecture.md) — request lifecycle, headers,
+  hint internals, JS module layout. Optional reading.
+## Development
+```bash
+bundle install
+bundle exec rake test            # Ruby suite
+node --test test/js/*.test.js    # JS pure-function tests
+```
+## License
+MIT — see `LICENSE.txt`.

data/Rakefile ADDED Viewed

@@ -0,0 +1,35 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  # Unit tests only — system tests bootstrap a Rails app and run
+  # under a separate `rake test:system` task so the dummy app doesn't
+  # have to load for every unit-test run.
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/system/**/*")
+  t.warning = false
+end
+namespace :test do
+  Rake::TestTask.new(:system) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/system/**/*_test.rb"]
+    t.warning = false
+  end
+end
+namespace :dummy do
+  desc "Boot the test/dummy Rails app on localhost so you can poke at it in a real browser (PORT=4001 by default)"
+  task :serve do
+    ENV["RAILS_ENV"] = "test"   # only env the dummy has configured
+    require_relative "test/dummy/config/environment"
+    require "rack/handler/puma"
+    port = ENV.fetch("PORT", "4001").to_i
+    puts "→ Dummy app on http://localhost:#{port}  (Ctrl-C to stop)"
+    Rack::Handler::Puma.run(Rails.application, Port: port, Silent: true)
+  end
+end
+task default: :test

data/app/assets/stylesheets/turbo_overlay.css ADDED Viewed

@@ -0,0 +1,234 @@
+/* === Bootstrap-style scaffold (transparent full-viewport <dialog>) === */
+dialog.turbo-overlay-scaffold {
+  border: 0; padding: 0; margin: 0; background: transparent;
+  max-width: none; max-height: none;
+}
+dialog.turbo-overlay-scaffold::backdrop { background: rgba(0, 0, 0, 0.5); }
+dialog.turbo-overlay-scaffold.turbo-overlay--modal {
+  width: 100%; height: 100%; overflow-y: auto;
+}
+dialog.turbo-overlay-scaffold.turbo-overlay--drawer { overflow: hidden; }
+dialog.turbo-overlay-scaffold.turbo-overlay--drawer-right  { inset: 0 0 0 auto; height: 100vh; width: 400px; max-width: 100vw; }
+dialog.turbo-overlay-scaffold.turbo-overlay--drawer-left   { inset: 0 auto 0 0; height: 100vh; width: 400px; max-width: 100vw; }
+dialog.turbo-overlay-scaffold.turbo-overlay--drawer-top    { inset: 0 0 auto 0; width: 100vw; max-height: 50vh; }
+dialog.turbo-overlay-scaffold.turbo-overlay--drawer-bottom { inset: auto 0 0 0; width: 100vw; max-height: 50vh; }
+dialog.turbo-overlay-scaffold .offcanvas {
+  position: static; visibility: visible; transform: none;
+  width: 100%; height: 100%; max-width: none; max-height: none;
+}
+dialog.turbo-overlay-scaffold .turbo-drawer-panel {
+  margin: 0; border-radius: 0; height: 100%; display: flex; flex-direction: column;
+  border: 0; box-shadow: 0 0 30px rgba(0, 0, 0, 0.15);
+}
+dialog.turbo-overlay-scaffold .turbo-drawer-body { flex: 1; overflow-y: auto; }
+/* === Plain theme ===
+   Baseline dialog visuals are wrapped in `:where()` so they have
+   zero specificity. The plain theme partials (which only set the
+   `.turbo-modal` / `.turbo-drawer` / `.turbo-popover` class) still
+   pick them up, but tailwind/bootstrap themes that add their own
+   classes to the dialog (e.g. `bg-white dark:bg-gray-800`) win
+   without a specificity battle — regardless of which stylesheet
+   loads later in the cascade.
+*/
+:where(dialog.turbo-modal) {
+  border: 0; padding: 0; border-radius: 8px;
+  max-width: 32rem; width: 90vw;
+  max-height: 90vh;
+  box-shadow: 0 20px 50px rgba(0, 0, 0, 0.25);
+}
+:where(dialog.turbo-modal)::backdrop { background: rgba(0, 0, 0, 0.5); }
+.turbo-modal__content { display: flex; flex-direction: column; max-height: 90vh; position: relative; }
+.turbo-modal__header {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 1rem 1.25rem; border-bottom: 1px solid #e5e7eb;
+  flex-shrink: 0;
+}
+.turbo-modal__title { margin: 0; font-size: 1.125rem; font-weight: 600; }
+.turbo-modal__close { background: none; border: 0; font-size: 1.5rem; cursor: pointer; line-height: 1; }
+.turbo-modal__close:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; border-radius: 2px; }
+.turbo-modal__close--floating { position: absolute; top: 0.5rem; right: 0.75rem; z-index: 1; }
+.turbo-modal__body { padding: 1.25rem; flex: 1; overflow-y: auto; }
+.turbo-modal__footer {
+  padding: 1rem 1.25rem; border-top: 1px solid #e5e7eb;
+  display: flex; justify-content: flex-end; gap: 0.5rem;
+  flex-shrink: 0;
+}
+:where(dialog.turbo-drawer) {
+  border: 0; padding: 0; margin: 0; background: white;
+  box-shadow: 0 0 30px rgba(0, 0, 0, 0.15);
+  max-width: 100vw; max-height: 100vh;
+}
+:where(dialog.turbo-drawer)::backdrop { background: rgba(0, 0, 0, 0.5); }
+:where(dialog.turbo-drawer.turbo-overlay--drawer-right)  { inset: 0 0 0 auto; height: 100vh; width: 24rem; }
+:where(dialog.turbo-drawer.turbo-overlay--drawer-left)   { inset: 0 auto 0 0; height: 100vh; width: 24rem; }
+:where(dialog.turbo-drawer.turbo-overlay--drawer-top)    { inset: 0 0 auto 0; width: 100vw; max-height: 50vh; }
+:where(dialog.turbo-drawer.turbo-overlay--drawer-bottom) { inset: auto 0 0 0; width: 100vw; max-height: 50vh; }
+.turbo-drawer__content { display: flex; flex-direction: column; height: 100%; position: relative; }
+.turbo-drawer__header {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 1rem 1.25rem; border-bottom: 1px solid #e5e7eb;
+}
+.turbo-drawer__title { margin: 0; font-size: 1.125rem; font-weight: 600; }
+.turbo-drawer__close { background: none; border: 0; font-size: 1.5rem; cursor: pointer; line-height: 1; }
+.turbo-drawer__close:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; border-radius: 2px; }
+.turbo-drawer__close--floating { position: absolute; top: 0.5rem; right: 0.75rem; z-index: 1; }
+.turbo-drawer__body { padding: 1.25rem; flex: 1; overflow-y: auto; }
+.turbo-drawer__footer {
+  padding: 1rem 1.25rem; border-top: 1px solid #e5e7eb;
+  display: flex; justify-content: flex-end; gap: 0.5rem;
+}
+/* === Popover (anchored to trigger, non-modal) === */
+:where(dialog.turbo-popover) {
+  border: 0; padding: 0; margin: 0; background: white;
+  border-radius: 6px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.15);
+  max-width: 22rem; max-height: 80vh; overflow: auto;
+}
+/* Popovers opened from inside an open modal dialog use showModal()
+   themselves to avoid the parent modal's inertness blocking them.
+   Make the resulting ::backdrop transparent so they still look like
+   anchored popovers, not modals. The :modal pseudo matches only when
+   entered via showModal. */
+dialog.turbo-overlay--popover:modal::backdrop { background: transparent; }
+.turbo-popover__content { display: flex; flex-direction: column; position: relative; }
+.turbo-popover__header {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 0.5rem 0.75rem; border-bottom: 1px solid #e5e7eb;
+}
+.turbo-popover__title { margin: 0; font-size: 0.95rem; font-weight: 600; }
+.turbo-popover__close { background: none; border: 0; font-size: 1.25rem; cursor: pointer; line-height: 1; }
+.turbo-popover__close:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; border-radius: 2px; }
+.turbo-popover__close--floating { position: absolute; top: 0.25rem; right: 0.5rem; z-index: 1; }
+.turbo-popover__body { padding: 0.75rem; }
+.turbo-popover__footer {
+  padding: 0.5rem 0.75rem; border-top: 1px solid #e5e7eb;
+  display: flex; justify-content: flex-end; gap: 0.5rem;
+}
+/* === Hint (hover-triggered preview, non-modal, non-dialog) === */
+/* Structural rules apply to every hint regardless of theme — JS sets
+   top/left via the same anchor math as the popover, and the
+   animation/closing classes drive the fade in/out. */
+.turbo-overlay-hint {
+  position: fixed; z-index: 1000;
+  pointer-events: auto;
+}
+.turbo-overlay-hint[data-state="entering"] { animation: turbo-overlay-fade-in 0.12s ease-out; }
+.turbo-overlay-hint[data-state="leaving"]  { animation: turbo-overlay-fade-out 0.12s ease-out forwards; }
+/* Plain-theme visuals — opt in by adding `turbo-hint` to the chrome
+   partial. The tailwind/bootstrap themes drop this class so their
+   own utility classes drive background/border/shadow without
+   collisions with the gem's plain defaults. (Tailwind v4 wraps its
+   utilities in `@layer utilities`; the gem's CSS is unlayered, which
+   wins over any layered rule regardless of specificity — including
+   `:where()`. Separating classes is the only reliable fix.) */
+.turbo-hint {
+  max-width: 20rem; padding: 0.75rem 1rem;
+  background: white;
+  border: 1px solid #e5e7eb;
+  border-radius: 6px;
+  box-shadow: 0 8px 24px rgba(0,0,0,0.12);
+  font-size: 0.875rem;
+}
+/* === Animations (apply to every theme via shared classes) === */
+dialog.turbo-overlay--modal[open]                            { animation: turbo-overlay-fade-in 0.15s ease-out; }
+dialog.turbo-overlay--modal[open]::backdrop                  { animation: turbo-overlay-backdrop-in 0.15s ease-out; }
+dialog.turbo-overlay--modal.turbo-overlay-closing            { animation: turbo-overlay-fade-out 0.15s ease-out forwards; }
+dialog.turbo-overlay--modal.turbo-overlay-closing::backdrop  { animation: turbo-overlay-backdrop-out 0.15s ease-out forwards; }
+dialog.turbo-overlay--drawer-right[open]                       { animation: turbo-overlay-slide-in-right 0.3s ease-out; }
+dialog.turbo-overlay--drawer-left[open]                        { animation: turbo-overlay-slide-in-left 0.3s ease-out; }
+dialog.turbo-overlay--drawer-top[open]                         { animation: turbo-overlay-slide-in-top 0.3s ease-out; }
+dialog.turbo-overlay--drawer-bottom[open]                      { animation: turbo-overlay-slide-in-bottom 0.3s ease-out; }
+dialog.turbo-overlay--drawer[open]::backdrop                   { animation: turbo-overlay-backdrop-in 0.3s ease-out; }
+dialog.turbo-overlay--drawer-right.turbo-overlay-closing       { animation: turbo-overlay-slide-out-right 0.3s ease-out forwards; }
+dialog.turbo-overlay--drawer-left.turbo-overlay-closing        { animation: turbo-overlay-slide-out-left 0.3s ease-out forwards; }
+dialog.turbo-overlay--drawer-top.turbo-overlay-closing         { animation: turbo-overlay-slide-out-top 0.3s ease-out forwards; }
+dialog.turbo-overlay--drawer-bottom.turbo-overlay-closing      { animation: turbo-overlay-slide-out-bottom 0.3s ease-out forwards; }
+dialog.turbo-overlay--drawer.turbo-overlay-closing::backdrop   { animation: turbo-overlay-backdrop-out 0.3s ease-out forwards; }
+/* Popovers position themselves by writing `transform: translate(...)`
+   so the placement stays in sync with compositor-thread scroll. The
+   open/close keyframes also use `transform`, so we set
+   `animation-composition: add` on the dialog — keyframe transforms
+   then compose with (rather than replace) the positioning transform. */
+dialog.turbo-overlay--popover                        { animation-composition: add; }
+dialog.turbo-overlay--popover:popover-open           { animation: turbo-overlay-popover-in  0.12s ease-out; }
+dialog.turbo-overlay--popover.turbo-overlay-closing  { animation: turbo-overlay-popover-out 0.12s ease-out forwards; }
+@keyframes turbo-overlay-fade-in     { from { opacity: 0; transform: scale(0.97); } to { opacity: 1; transform: scale(1); } }
+@keyframes turbo-overlay-fade-out    { from { opacity: 1; transform: scale(1); }    to { opacity: 0; transform: scale(0.97); } }
+@keyframes turbo-overlay-backdrop-in  { from { background: rgba(0,0,0,0); }   to { background: rgba(0,0,0,0.5); } }
+@keyframes turbo-overlay-backdrop-out { from { background: rgba(0,0,0,0.5); } to { background: rgba(0,0,0,0); } }
+@keyframes turbo-overlay-slide-in-right  { from { transform: translateX(100%); }  to { transform: translateX(0); } }
+@keyframes turbo-overlay-slide-in-left   { from { transform: translateX(-100%); } to { transform: translateX(0); } }
+@keyframes turbo-overlay-slide-in-top    { from { transform: translateY(-100%); } to { transform: translateY(0); } }
+@keyframes turbo-overlay-slide-in-bottom { from { transform: translateY(100%); }  to { transform: translateY(0); } }
+@keyframes turbo-overlay-slide-out-right  { from { transform: translateX(0); } to { transform: translateX(100%); } }
+@keyframes turbo-overlay-slide-out-left   { from { transform: translateX(0); } to { transform: translateX(-100%); } }
+@keyframes turbo-overlay-slide-out-top    { from { transform: translateY(0); } to { transform: translateY(-100%); } }
+@keyframes turbo-overlay-slide-out-bottom { from { transform: translateY(0); } to { transform: translateY(100%); } }
+@keyframes turbo-overlay-popover-in   { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: translateY(0); } }
+@keyframes turbo-overlay-popover-out  { from { opacity: 1; transform: translateY(0); }    to { opacity: 0; transform: translateY(-4px); } }
+@media (prefers-reduced-motion: reduce) {
+  dialog.turbo-overlay,
+  dialog.turbo-overlay::backdrop,
+  dialog.turbo-overlay.turbo-overlay-closing,
+  dialog.turbo-overlay.turbo-overlay-closing::backdrop,
+  .turbo-overlay-hint[data-state] { animation: none !important; }
+}
+/* === Loading state (cloned client-side while a request is in flight) === */
+/* Wrapped in :where() so themes that drop their own classes on the
+   loading partial win without specificity battles. */
+:where(.turbo-overlay-loading__body) {
+  display: flex; align-items: center; justify-content: center;
+  min-height: 8rem; padding: 2rem;
+}
+:where(.turbo-overlay-loading__spinner) {
+  display: inline-block;
+  width: 1.5rem; height: 1.5rem;
+  border: 3px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  opacity: 0.6;
+  animation: turbo-overlay-loading-spin 0.8s linear infinite;
+}
+:where(.turbo-overlay-loading__sr-only) {
+  position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+  overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
+}
+@keyframes turbo-overlay-loading-spin { to { transform: rotate(360deg); } }
+/* Drawer loading should fill its panel rather than rely on min-height. */
+:where(dialog.turbo-overlay--drawer.turbo-overlay--loading .turbo-overlay-loading__body) {
+  min-height: 100%;
+}
+/* Hint loading sits inside a tooltip-sized chrome — collapse the body's
+   default min-height/padding so the spinner doesn't bloat the hint. */
+:where(.turbo-overlay-hint.turbo-overlay--loading .turbo-overlay-loading__body) {
+  min-height: 0;
+  padding: 0;
+}
+@media (prefers-reduced-motion: reduce) {
+  .turbo-overlay-loading__spinner { animation: none !important; }
+}
+/* === Non-modal drawer (opened via dialog.show(), no ::backdrop) === */
+/* Non-modal <dialog> defaults to position: absolute (anchored to the
+   document), which breaks the side-pinned inset rules above. Force
+   fixed so the drawer stays anchored to the viewport. */
+dialog.turbo-overlay--no-backdrop { position: fixed; }
+/* === Scroll lock when any modal overlay is open === */
+/* Skip non-backdrop drawers — they're meant to coexist with page
+   interaction, including scrolling. */
+html:has(dialog.turbo-overlay[open]:not(.turbo-overlay--no-backdrop)) { overflow: hidden; }

data/app/javascript/turbo_overlay/dialog_utils.js ADDED Viewed

@@ -0,0 +1,46 @@
+// Small DOM helpers shared between the setup module, the per-dialog
+// Stimulus controller, and the hint state machine. Kept pure-DOM (no
+// imports from setup.js or controllers) so any module can depend on
+// it without creating cycles.
+// Close a <dialog> that may already be closed. The native close()
+// throws InvalidStateError when the dialog isn't open; we strip the
+// `open` attribute as a fallback so the dialog is closed after this
+// returns even when close() raises (e.g. a dialog left with [open]
+// but no top-layer entry, which a browser may refuse to close).
+export function safelyCloseDialog(dialog) {
+  if (!dialog) return
+  try { dialog.close() } catch (_) { dialog.removeAttribute("open") }
+}
+// Dismiss a popover-mode dialog. hidePopover() is only available in
+// browsers that support the Popover API, and throws when the dialog
+// isn't showing as a popover. Both are non-fatal — callers want
+// "ensure popover is hidden."
+export function safelyHidePopover(dialog) {
+  if (!dialog || typeof dialog.hidePopover !== "function") return
+  try { dialog.hidePopover() } catch (_) { /* not currently a popover */ }
+}
+// Reset a <dialog>'s positioning styles so popover-positioning math
+// can place it via a single `transform: translate(...)`. Default
+// <dialog> styles (margin: auto, right/bottom set, position relative
+// or absolute depending on open state) and the `dialog:modal` UA
+// `inset: 0` interfere with anchored placement.
+//
+// We pin the dialog at viewport origin (top: 0, left: 0) and carry
+// the actual placement on `transform`. Transforms run on the
+// compositor thread, so they stay in sync with scroll-induced repaint
+// instead of trailing by a frame (which produces a "springy" feel on
+// momentum scrolling). The CSS for popovers sets
+// `animation-composition: add` so the entry/exit keyframes compose
+// with our positioning transform instead of overriding it.
+export function normalizePopoverDialogStyles(dialog) {
+  if (!dialog) return
+  dialog.style.position = "fixed"
+  dialog.style.top      = "0"
+  dialog.style.left     = "0"
+  dialog.style.right    = "auto"
+  dialog.style.bottom   = "auto"
+  dialog.style.margin   = "0"
+}