turbo_overlay 0.3.0

data/app/javascript/turbo_overlay/stack_controller.js

@@ -0,0 +1,131 @@
+import { Controller } from "@hotwired/stimulus"
+import { getPopoverTrigger, clearPopoverTrigger } from "turbo_overlay/setup"
+import { setStackController } from "turbo_overlay/history"
+
+// Per-page stack registry. Mounted once on the host page via
+// `<%= overlay_stack_tag %>` (DOM id `turbo_overlay_stack`). Tracks the
+// order of currently-open overlays and routes server-issued
+// `turbo_stream.overlay(:close, …)` events to the matching overlay's
+// controller.
+//
+// Cross-cutting wiring (request-header injection, loading
+// placeholders, back/forward cache teardown, themed confirm) lives in
+// `turbo_overlay/setup`, which self-bootstraps on import from
+// `turbo_overlay` (the gem's entry point).
+
+export default class extends Controller {
+  static values = {
+    allowedClickOutsideSelectors: { type: Array, default: [] }
+  }
+
+  connect() {
+    this.entries = []
+
+    this._closeHandler = (event) => this.handleCloseEvent(event)
+    window.addEventListener("turbo-overlay:close", this._closeHandler)
+
+    setStackController(this)
+  }
+
+  disconnect() {
+    window.removeEventListener("turbo-overlay:close", this._closeHandler)
+    this.entries = []
+    setStackController(null)
+  }
+
+  register(entry) {
+    if (this.entries.some((e) => e.id === entry.id)) return false
+
+    // Single-popover behavior: opening a new popover closes any other
+    // open popovers. Modals and drawers keep their existing stacking.
+    if (entry.type === "popover") {
+      const existing = this.entries.filter((e) => e.type === "popover")
+      for (const prior of existing) {
+        if (prior.controller && typeof prior.controller.close === "function") {
+          prior.controller.close()
+        }
+      }
+    }
+
+    this.entries.push(entry)
+    return true
+  }
+
+  unregister(id) {
+    const before = this.entries.length
+    this.entries = this.entries.filter((e) => e.id !== id)
+    // Only clear the popover-trigger registry when we actually removed
+    // the entry. The disconnect path schedules a deferred unregister
+    // via queueMicrotask as a safety net for elements ripped out of
+    // the DOM without a close() — if close() already ran (and cleared
+    // the entry), that deferred call must not clobber a popoverTriggers
+    // entry that meanwhile has been re-pointed at a new overlay
+    // reusing the same id (e.g. a re-click on the same popover_link_to).
+    if (this.entries.length < before) clearPopoverTrigger(id)
+  }
+
+  getPopoverTrigger(id) {
+    return getPopoverTrigger(id)
+  }
+
+  has(id) {
+    return this.entries.some((e) => e.id === id)
+  }
+
+  updateController(id, controller) {
+    const entry = this.entries.find((e) => e.id === id)
+    if (entry) entry.controller = controller
+  }
+
+  get depth() {
+    return this.entries.length
+  }
+
+  topEntry(typeFilter = null) {
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      if (!typeFilter || this.entries[i].type === typeFilter) return this.entries[i]
+    }
+    return null
+  }
+
+  handleCloseEvent(event) {
+    const detail = event.detail || {}
+    const scope = detail.scope || "top"
+    const type = detail.type || null
+    const id = detail.id || null
+
+    const closes = []
+    if (id) {
+      const entry = this.entries.find((e) => e.id === id)
+      if (entry && entry.controller && typeof entry.controller.close === "function") {
+        closes.push(entry.controller.close())
+      }
+    } else if (scope === "all") {
+      const targets = type
+        ? this.entries.filter((e) => e.type === type)
+        : this.entries.slice()
+      for (let i = targets.length - 1; i >= 0; i--) {
+        const c = targets[i].controller
+        if (c && typeof c.close === "function") closes.push(c.close())
+      }
+    } else {
+      const top = this.topEntry(type)
+      if (top && top.controller && typeof top.controller.close === "function") {
+        closes.push(top.controller.close())
+      }
+    }
+
+    // Server-requested post-close navigation. Await the close
+    // animation(s) so the new page doesn't paint behind a
+    // still-animating overlay. The visit defaults to "advance" — pass
+    // visit_action: :replace from the server when you want the
+    // current history entry rewritten (e.g., a stale URL the user
+    // shouldn't be able to back into).
+    if (detail.visit && typeof window !== "undefined" && window.Turbo &&
+        typeof window.Turbo.visit === "function") {
+      Promise.all(closes).then(() => {
+        window.Turbo.visit(detail.visit, { action: detail.visitAction || "advance" })
+      })
+    }
+  }
+}

data/app/javascript/turbo_overlay/submit_close.js

@@ -0,0 +1,49 @@
+// Pure decision function for the per-dialog `turbo:submit-end`
+// listener installed by the overlay controller. Returns true when
+// the overlay should close in response to a form submission's redirect.
+//
+// Inputs:
+//   form          — the submitting <form> element (event.target)
+//   dialog        — the overlay <dialog> hosting the controller
+//   fetchResponse — event.detail.fetchResponse from turbo:submit-end
+//
+// Close-on-redirect is the default. Three opt-outs, finest-grained
+// wins. None of these short-circuit the others — checking the form
+// attribute first means a form-level opt-out works inside an overlay
+// whose link did not opt out, and the dialog attribute is meaningless
+// for forms outside the dialog (filtered by descendant check first).
+//
+// 1. Form is not a descendant of this dialog — not our submission.
+// 2. Response is not a followed redirect — leave it alone.
+// 3. The form opts out via data-turbo-overlay-keep-open-on-redirect.
+// 4. The dialog opts out (link helper set keep_overlay_open_on_redirect: true).
+export function shouldCloseOnRedirect({ form, dialog, fetchResponse }) {
+  if (!form || !dialog) return false
+  if (!form.tagName || form.tagName !== "FORM") return false
+  if (!dialog.contains(form)) return false
+  if (!fetchResponse || !fetchResponse.redirected) return false
+  if (form.dataset && form.dataset.turboOverlayKeepOpenOnRedirect === "true") return false
+  if (dialog.dataset && dialog.dataset.turboOverlayKeepOpenOnRedirect === "true") return false
+  return true
+}
+
+// Same-page-redirect predicate for the smooth-close path: returns true
+// when the redirect target's pathname matches the URL the overlay was
+// opened from. Used by overlay_controller to decide between the
+// morph-behind path (true) and the existing close-then-visit path
+// (false). Pathname-only — query string and hash differ freely.
+// Cross-origin and missing inputs return false.
+export function isSamePageRedirect({ dialog, fetchResponse }) {
+  const openerUrl = dialog && dialog.dataset && dialog.dataset.turboOverlayOpenerUrl
+  if (!openerUrl) return false
+  const respUrl = fetchResponse && fetchResponse.response && fetchResponse.response.url
+  if (!respUrl) return false
+  try {
+    const base = (typeof document !== "undefined" && document.baseURI) || undefined
+    const a = new URL(openerUrl, base)
+    const b = new URL(respUrl, base)
+    return a.origin === b.origin && a.pathname === b.pathname
+  } catch (_) {
+    return false
+  }
+}

data/app/javascript/turbo_overlay/visit.js

@@ -0,0 +1,52 @@
+import { buildOverlayDataset, validateVisitArgs } from "turbo_overlay/options"
+
+// Open an overlay from JavaScript — the programmatic counterpart to
+// `modal_link_to` / `drawer_link_to` / `popover_link_to`. Reuses the
+// existing click pipeline: a detached `<a>` is built with the right
+// `data-turbo-overlay-*` attributes, briefly attached to the document,
+// clicked, and removed. Turbo's FormLinkClickObserver routes the click
+// through its stream-fetch path, the gem's document click hook captures
+// the trigger, and `turbo:before-fetch-request` emits the X-Turbo-Overlay-*
+// headers as it does for any link click.
+//
+// Use this for non-anchor triggers (map pins, canvas hit-tests, custom
+// elements). For ordinary HTML links, prefer the Rails helpers.
+//
+//   TurboOverlay.visit("/places/123")                              // modal (default)
+//   TurboOverlay.visit("/cart", { type: "drawer", advance: true })
+//   TurboOverlay.visit("/preview/9", { type: "popover", anchor: pinEl, position: "top" })
+//
+// Popovers must supply an `anchor` element — positioning derives from
+// its `getBoundingClientRect()`. The synthesized link has no useful rect
+// of its own.
+//
+// Validation, type list, and dataset construction live in `options.js`
+// so they round-trip with the same table the fetch hook reads and stay
+// unit-testable without a DOM.
+
+export function visit(url, options = {}) {
+  const type = validateVisitArgs(url, options)
+  const link = document.createElement("a")
+  link.href = url
+  link.hidden = true
+  link.style.position = "absolute"
+  link.style.left = "-9999px"
+  const dataset = buildOverlayDataset(type, options)
+  for (const k in dataset) link.dataset[k] = dataset[k]
+  if (options.anchor) {
+    // Non-enumerable so it doesn't show up via spread/JSON, but the
+    // click handler in setup.js can still read it.
+    Object.defineProperty(link, "__turboOverlayAnchor", {
+      value: options.anchor,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+  }
+  document.body.appendChild(link)
+  try {
+    link.click()
+  } finally {
+    link.remove()
+  }
+}

data/app/views/layouts/turbo_overlay/drawer.html.erb

@@ -0,0 +1,5 @@
+<%= overlay_response_wrapper(:drawer) do %>
+  <%= render layout: "turbo_overlay/drawer" do %>
+    <%= yield %>
+  <% end %>
+<% end %>

data/app/views/layouts/turbo_overlay/hint.html.erb

@@ -0,0 +1,10 @@
+<%# Layout for :hint-variant responses fetched by the gem's hint
+    module via explicit `hint_url:`. Same wire shape as the
+    inline-hint template emitted by `overlay_stack_tag` so the JS
+    extractor has one code path: a <template id="…"> wrapping the
+    hint chrome partial wrapping the response body.
+
+    The body is whatever the action's view rendered — typically a
+    `show.html+hint.erb` variant template, but a plain
+    `show.html.erb` works if the entire view fits a hint preview. %>
+<template id="turbo-overlay-hint"><%= render layout: "turbo_overlay/hint" do %><%= yield %><% end %></template>

data/app/views/layouts/turbo_overlay/modal.html.erb

@@ -0,0 +1,5 @@
+<%= overlay_response_wrapper(:modal) do %>
+  <%= render layout: "turbo_overlay/modal" do %>
+    <%= yield %>
+  <% end %>
+<% end %>

data/app/views/layouts/turbo_overlay/popover.html.erb

@@ -0,0 +1,5 @@
+<%= overlay_response_wrapper(:popover) do %>
+  <%= render layout: "turbo_overlay/popover" do %>
+    <%= yield %>
+  <% end %>
+<% end %>

data/app/views/turbo_overlay/_drawer.html.erb

@@ -0,0 +1,49 @@
+<% loading      = local_assigns.fetch(:loading, false) %>
+<% position    = turbo_overlay_position || TurboOverlay.configuration.drawer.position %>
+<% backdrop    = turbo_overlay_backdrop? %>
+<% close_button = local_assigns.fetch(:close) { overlay_close? } %>
+<dialog class="<%= class_names("turbo-overlay", "turbo-overlay--drawer", "turbo-overlay--drawer-#{position}", "turbo-drawer", "turbo-overlay--loading": loading, "turbo-overlay--no-backdrop": !backdrop) %>"
+        <% if loading %>
+        role="status"
+        aria-live="polite"
+        aria-label="Loading"
+        <% else %>
+        data-controller="turbo-overlay"
+        data-turbo-overlay-id-value="<%= turbo_overlay_id %>"
+        data-turbo-overlay-type-value="drawer"
+        data-turbo-overlay-backdrop-value="<%= backdrop %>"
+        <% if turbo_overlay_keep_open_on_redirect? %>data-turbo-overlay-keep-open-on-redirect="true"<% end %>
+        data-action="cancel->turbo-overlay#cancel click->turbo-overlay#backdropClick"
+        aria-labelledby="turbo-drawer-title-<%= turbo_overlay_id %>"
+        <% end %>>
+  <div class="turbo-drawer__content">
+    <% if !loading && content_for?(:overlay_title) %>
+      <header class="turbo-drawer__header">
+        <h2 id="turbo-drawer-title-<%= turbo_overlay_id %>" class="turbo-drawer__title">
+          <%= yield(:overlay_title) %>
+        </h2>
+        <% if close_button %>
+          <button type="button"
+                  class="turbo-drawer__close"
+                  data-action="turbo-overlay#close"
+                  aria-label="Close"><span aria-hidden="true">&times;</span></button>
+        <% end %>
+      </header>
+    <% elsif !loading && close_button %>
+      <button type="button"
+              class="turbo-drawer__close turbo-drawer__close--floating"
+              data-action="turbo-overlay#close"
+              aria-label="Close"><span aria-hidden="true">&times;</span></button>
+    <% end %>
+
+    <div class="turbo-drawer__body">
+      <%= yield %>
+    </div>
+
+    <% if !loading && content_for?(:overlay_footer) %>
+      <footer class="turbo-drawer__footer">
+        <%= yield(:overlay_footer) %>
+      </footer>
+    <% end %>
+  </div>
+</dialog>

data/app/views/turbo_overlay/_hint.html.erb

@@ -0,0 +1,6 @@
+<% loading = local_assigns.fetch(:loading, false) %>
+<div popover="manual"
+     class="<%= class_names("turbo-overlay-hint", "turbo-hint", "turbo-overlay--loading": loading) %>"
+     <% if loading %>role="status" aria-live="polite" aria-label="Loading"<% else %>role="tooltip"<% end %>>
+  <%= yield %>
+</div>

data/app/views/turbo_overlay/_loading.html.erb

@@ -0,0 +1,12 @@
+<%# Body content for an overlay's loading placeholder. Wrapped in the
+    matching chrome at template-emission time by `overlay_stack_tag`
+    (modal/drawer/popover/hint). Sizing comes from the gem's CSS so the
+    same partial fits all chrome contexts — hint chrome collapses the
+    body's min-height/padding so the spinner sits flush in the small
+    tooltip. Add a chrome-specific override at `_loading.html+<variant>.erb`
+    if you need different markup for one variant.
+%>
+<div class="turbo-overlay-loading__body">
+  <span class="turbo-overlay-loading__spinner" aria-hidden="true"></span>
+  <span class="turbo-overlay-loading__sr-only">Loading…</span>
+</div>

data/app/views/turbo_overlay/_modal.html.erb

@@ -0,0 +1,46 @@
+<% loading      = local_assigns.fetch(:loading, false) %>
+<% close_button = local_assigns.fetch(:close) { overlay_close? } %>
+<dialog class="<%= class_names("turbo-overlay", "turbo-overlay--modal", "turbo-modal", "turbo-overlay--loading": loading) %>"
+        <% if loading %>
+        role="status"
+        aria-live="polite"
+        aria-label="Loading"
+        <% else %>
+        data-controller="turbo-overlay"
+        data-turbo-overlay-id-value="<%= turbo_overlay_id %>"
+        data-turbo-overlay-type-value="modal"
+        <% if turbo_overlay_keep_open_on_redirect? %>data-turbo-overlay-keep-open-on-redirect="true"<% end %>
+        data-action="cancel->turbo-overlay#cancel click->turbo-overlay#backdropClick"
+        aria-labelledby="turbo-modal-title-<%= turbo_overlay_id %>"
+        <% end %>>
+  <div class="turbo-modal__content">
+    <% if !loading && content_for?(:overlay_title) %>
+      <header class="turbo-modal__header">
+        <h2 id="turbo-modal-title-<%= turbo_overlay_id %>" class="turbo-modal__title">
+          <%= yield(:overlay_title) %>
+        </h2>
+        <% if close_button %>
+          <button type="button"
+                  class="turbo-modal__close"
+                  data-action="turbo-overlay#close"
+                  aria-label="Close"><span aria-hidden="true">&times;</span></button>
+        <% end %>
+      </header>
+    <% elsif !loading && close_button %>
+      <button type="button"
+              class="turbo-modal__close turbo-modal__close--floating"
+              data-action="turbo-overlay#close"
+              aria-label="Close"><span aria-hidden="true">&times;</span></button>
+    <% end %>
+
+    <div class="turbo-modal__body">
+      <%= yield %>
+    </div>
+
+    <% if !loading && content_for?(:overlay_footer) %>
+      <footer class="turbo-modal__footer">
+        <%= yield(:overlay_footer) %>
+      </footer>
+    <% end %>
+  </div>
+</dialog>

data/app/views/turbo_overlay/_popover.html.erb

@@ -0,0 +1,54 @@
+<% loading      = local_assigns.fetch(:loading, false) %>
+<% position    = turbo_overlay_position || TurboOverlay.configuration.popover.position %>
+<% align       = turbo_overlay_align    || TurboOverlay.configuration.popover.align %>
+<% offset      = turbo_overlay_offset   || TurboOverlay.configuration.popover.offset %>
+<% close_button = local_assigns.fetch(:close) { defined?(@_overlay_close) && @_overlay_close != false } %>
+<dialog popover="manual"
+        class="<%= class_names("turbo-overlay", "turbo-overlay--popover", "turbo-popover", "turbo-overlay--no-backdrop", "turbo-overlay--loading": loading) %>"
+        <% if loading %>
+        role="status"
+        aria-live="polite"
+        aria-label="Loading"
+        <% else %>
+        data-controller="turbo-overlay"
+        data-turbo-overlay-id-value="<%= turbo_overlay_id %>"
+        data-turbo-overlay-type-value="popover"
+        data-turbo-overlay-backdrop-value="false"
+        data-turbo-overlay-position-value="<%= position %>"
+        data-turbo-overlay-align-value="<%= align %>"
+        data-turbo-overlay-offset-value="<%= offset %>"
+        <% if turbo_overlay_keep_open_on_redirect? %>data-turbo-overlay-keep-open-on-redirect="true"<% end %>
+        data-action="cancel->turbo-overlay#cancel"
+        aria-labelledby="turbo-popover-title-<%= turbo_overlay_id %>"
+        <% end %>>
+  <div class="turbo-popover__content">
+    <% if !loading && content_for?(:overlay_title) %>
+      <header class="turbo-popover__header">
+        <h2 id="turbo-popover-title-<%= turbo_overlay_id %>" class="turbo-popover__title">
+          <%= yield(:overlay_title) %>
+        </h2>
+        <% if close_button %>
+          <button type="button"
+                  class="turbo-popover__close"
+                  data-action="turbo-overlay#close"
+                  aria-label="Close"><span aria-hidden="true">&times;</span></button>
+        <% end %>
+      </header>
+    <% elsif !loading && close_button %>
+      <button type="button"
+              class="turbo-popover__close turbo-popover__close--floating"
+              data-action="turbo-overlay#close"
+              aria-label="Close"><span aria-hidden="true">&times;</span></button>
+    <% end %>
+
+    <div class="turbo-popover__body">
+      <%= yield %>
+    </div>
+
+    <% if !loading && content_for?(:overlay_footer) %>
+      <footer class="turbo-popover__footer">
+        <%= yield(:overlay_footer) %>
+      </footer>
+    <% end %>
+  </div>
+</dialog>

data/config/importmap.rb

@@ -0,0 +1,11 @@
+pin "turbo_overlay", to: "turbo_overlay/index.js", preload: true
+pin "turbo_overlay/setup", to: "turbo_overlay/setup.js", preload: true
+pin "turbo_overlay/stack_controller", to: "turbo_overlay/stack_controller.js", preload: true
+pin "turbo_overlay/overlay_controller", to: "turbo_overlay/overlay_controller.js", preload: true
+pin "turbo_overlay/hint", to: "turbo_overlay/hint.js", preload: true
+pin "turbo_overlay/popover_position", to: "turbo_overlay/popover_position.js", preload: true
+pin "turbo_overlay/dialog_utils", to: "turbo_overlay/dialog_utils.js", preload: true
+pin "turbo_overlay/history", to: "turbo_overlay/history.js", preload: true
+pin "turbo_overlay/submit_close", to: "turbo_overlay/submit_close.js", preload: true
+pin "turbo_overlay/options", to: "turbo_overlay/options.js", preload: true
+pin "turbo_overlay/visit", to: "turbo_overlay/visit.js", preload: true

data/lib/generators/turbo_overlay/eject_generator.rb

@@ -0,0 +1,115 @@
+require "rails/generators/base"
+
+module TurboOverlay
+  module Generators
+    # Copies gem-owned plumbing into the host app for full control.
+    # Once ejected, gem upgrades to that subset don't flow through.
+    # (Chrome partials are copied by the install generator and live in
+    # the app from day one, so they're not part of eject.)
+    #
+    #   bin/rails g turbo_overlay:eject --js
+    #   bin/rails g turbo_overlay:eject --css
+    #   bin/rails g turbo_overlay:eject --layouts
+    class EjectGenerator < ::Rails::Generators::Base
+      GEM_ROOT = File.expand_path("../../..", __dir__)
+
+      class_option :js,
+        type: :boolean,
+        default: false,
+        desc: "Copy the Stimulus controllers into app/javascript/turbo_overlay/"
+
+      class_option :css,
+        type: :boolean,
+        default: false,
+        desc: "Copy the stylesheet into app/assets/stylesheets/turbo_overlay.css"
+
+      class_option :layouts,
+        type: :boolean,
+        default: false,
+        desc: "Copy the four overlay layouts into app/views/layouts/turbo_overlay/"
+
+      def print_help_if_no_flags
+        return if any_flag_given?
+
+        say <<~MSG
+
+          Nothing to eject. Pass one or more flags:
+
+            --js        Copy Stimulus controllers to app/javascript/turbo_overlay/
+            --css       Copy the stylesheet to app/assets/stylesheets/turbo_overlay.css
+            --layouts   Copy modal/drawer/popover layouts to app/views/layouts/
+
+          Ejected files become app-owned — gem upgrades to those files no
+          longer apply. (Chrome partials are copied by `turbo_overlay:install`
+          and already live in your app.)
+
+        MSG
+      end
+
+      def eject_javascript
+        return unless options[:js]
+
+        copy_gem_file "app/javascript/turbo_overlay/index.js",
+          "app/javascript/turbo_overlay/index.js"
+        copy_gem_file "app/javascript/turbo_overlay/setup.js",
+          "app/javascript/turbo_overlay/setup.js"
+        copy_gem_file "app/javascript/turbo_overlay/stack_controller.js",
+          "app/javascript/turbo_overlay/stack_controller.js"
+        copy_gem_file "app/javascript/turbo_overlay/overlay_controller.js",
+          "app/javascript/turbo_overlay/overlay_controller.js"
+        copy_gem_file "app/javascript/turbo_overlay/hint.js",
+          "app/javascript/turbo_overlay/hint.js"
+        copy_gem_file "app/javascript/turbo_overlay/popover_position.js",
+          "app/javascript/turbo_overlay/popover_position.js"
+        copy_gem_file "app/javascript/turbo_overlay/submit_close.js",
+          "app/javascript/turbo_overlay/submit_close.js"
+
+        say <<~MSG, :yellow
+
+          JS ejected. Update your Stimulus entry to import locally:
+
+            import { register as registerTurboOverlay } from "./turbo_overlay/index"
+            registerTurboOverlay(application, { confirm: true })
+
+          And remove the gem's importmap pin if you had one.
+
+        MSG
+      end
+
+      def eject_stylesheet
+        return unless options[:css]
+
+        copy_gem_file "app/assets/stylesheets/turbo_overlay.css",
+          "app/assets/stylesheets/turbo_overlay.css"
+      end
+
+      def eject_layouts
+        return unless options[:layouts]
+
+        copy_gem_file "app/views/layouts/turbo_overlay/modal.html.erb",
+          "app/views/layouts/turbo_overlay/modal.html.erb"
+        copy_gem_file "app/views/layouts/turbo_overlay/drawer.html.erb",
+          "app/views/layouts/turbo_overlay/drawer.html.erb"
+        copy_gem_file "app/views/layouts/turbo_overlay/popover.html.erb",
+          "app/views/layouts/turbo_overlay/popover.html.erb"
+        copy_gem_file "app/views/layouts/turbo_overlay/hint.html.erb",
+          "app/views/layouts/turbo_overlay/hint.html.erb"
+      end
+
+      private
+
+      def any_flag_given?
+        options[:js] || options[:css] || options[:layouts]
+      end
+
+      def copy_gem_file(source_relative, destination_relative)
+        source = File.join(GEM_ROOT, source_relative)
+        unless File.exist?(source)
+          say_status :missing, source_relative, :red
+          return
+        end
+        create_file destination_relative, File.read(source)
+      end
+    end
+  end
+end