turbo_overlay 0.3.0

data/lib/turbo_overlay/configuration.rb

@@ -0,0 +1,226 @@
+module TurboOverlay
+  # Per-overlay-type config. `variant` is the Rails partial-variant
+  # symbol the type renders as.
+  class OverlayTypeConfig
+    attr_accessor :variant
+
+    def initialize(variant:)
+      @variant = variant
+    end
+  end
+
+  # Modal config. Adds `advance` (URL advance / history.pushState on
+  # open; browser-back closes the top overlay). Default off.
+  # Per-link override via `advance: true | "/custom" | false` on
+  # `modal_link_to`.
+  class ModalConfig < OverlayTypeConfig
+    attr_accessor :advance
+
+    def initialize(advance: false, **kwargs)
+      super(**kwargs)
+      @advance = advance
+    end
+  end
+
+  # Drawer config extends OverlayTypeConfig with a default position
+  # (`:left`, `:right`, `:top`, `:bottom`) used by shipped layouts.
+  # Per-instance position can be overridden by editing the layout.
+  # Also exposes `advance` (same semantics as ModalConfig).
+  class DrawerConfig < OverlayTypeConfig
+    attr_accessor :position, :advance
+
+    def initialize(position:, advance: false, **kwargs)
+      super(**kwargs)
+      @position = position
+      @advance  = advance
+    end
+  end
+
+  # Confirm prompt config. Controls how `data-turbo-confirm` is
+  # rendered when the gem's themed confirm hook is registered via
+  # `register(application, { confirm: true })`.
+  #
+  # - `style`: `:modal` (default) renders the prompt centered in the
+  #   modal chrome. `:popover` renders it anchored to the submitter
+  #   element (the clicked link or button), which is often friendlier
+  #   for destructive actions next to a row or button. Per-link
+  #   override via `data-turbo-confirm-style="popover"` (or `"modal"`)
+  #   on the link/form.
+  class ConfirmConfig
+    attr_accessor :style
+
+    def initialize(style:)
+      @style = style
+    end
+  end
+
+  # Hint config. Hover-triggered preview overlays. Hint attributes
+  # (`data-turbo-overlay-hint`, `data-turbo-overlay-hint-url`) compose
+  # with every overlay link helper and with plain `link_to`/`hint_link_to`.
+  #
+  # - `show_delay_ms`: hover must persist this long before the hint
+  #   shows (default 250ms).
+  # - `hide_delay_ms`: grace window after mouseleave before dismissing,
+  #   so the user can move the cursor into the hint (default 120ms).
+  class HintConfig < OverlayTypeConfig
+    attr_accessor :show_delay_ms, :hide_delay_ms
+
+    def initialize(show_delay_ms:, hide_delay_ms:, **kwargs)
+      super(**kwargs)
+      @show_delay_ms = show_delay_ms
+      @hide_delay_ms = hide_delay_ms
+    end
+  end
+
+  # Popover config extends OverlayTypeConfig with anchored-positioning
+  # defaults. Popovers attach to their trigger element rather than
+  # centering (modal) or pinning to an edge (drawer).
+  #
+  # - `position`: side of the trigger to attach to (`:top`, `:bottom`,
+  #   `:left`, `:right`). Default `:bottom`.
+  # - `align`: cross-axis alignment relative to the trigger
+  #   (`:start`, `:center`, `:end`). Default `:start`.
+  # - `offset`: pixels between trigger edge and dialog edge. Default `4`.
+  # - `auto_flip`: flip to the opposite side when the preferred
+  #   placement would overflow the viewport. Default `true`.
+  class PopoverConfig < OverlayTypeConfig
+    attr_accessor :position, :align, :offset, :auto_flip
+
+    def initialize(position:, align:, offset:, auto_flip:, **kwargs)
+      super(**kwargs)
+      @position  = position
+      @align     = align
+      @offset    = offset
+      @auto_flip = auto_flip
+    end
+  end
+
+  class Configuration
+    # DOM id of the host-page stack container that receives appended
+    # overlays. Emit it in your application layout via
+    # `<%= overlay_stack_tag %>`.
+    attr_accessor :stack_id
+
+    # CSS selectors whose clicks should not dismiss an open overlay.
+    # The list is consulted by the JS dismissal guard for backdrop
+    # clicks (modal/drawer) and outside-clicks (popover). Use this for
+    # body-appended widgets — flatpickr calendars, Select2 dropdowns,
+    # Tippy tooltips, Tom Select — that render their UI as siblings of
+    # the overlay in `<body>` and would otherwise read as
+    # outside-the-dialog clicks.
+    #
+    # This is developer config, not request data: never populate from
+    # user input. Entries are interpreted as CSS selectors and matched
+    # against any element in the DOM.
+    attr_reader :allowed_click_outside_selectors
+
+    # Selectors that would allowlist the entire document and pin
+    # overlays open forever. Reject at config time so misuse fails at
+    # boot, not at dismiss time.
+    FORBIDDEN_ALLOWLIST_SELECTORS = %w[* body html :root].freeze
+    private_constant :FORBIDDEN_ALLOWLIST_SELECTORS
+
+    def allowed_click_outside_selectors=(list)
+      list = Array(list)
+      list.each do |selector|
+        unless selector.is_a?(String)
+          raise ArgumentError,
+            "allowed_click_outside_selectors entries must be String CSS selectors; got #{selector.inspect}"
+        end
+        if FORBIDDEN_ALLOWLIST_SELECTORS.include?(selector.strip)
+          raise ArgumentError,
+            "allowed_click_outside_selectors entry #{selector.inspect} would allowlist the entire document " \
+            "and pin overlays open forever. Use a more specific selector."
+        end
+      end
+      @allowed_click_outside_selectors = list
+    end
+
+    def initialize
+      @stack_id = "turbo_overlay_stack"
+      @allowed_click_outside_selectors = []
+
+      @modal = ModalConfig.new(variant: :modal)
+
+      @drawer = DrawerConfig.new(
+        variant:  :drawer,
+        position: :right
+      )
+
+      @popover = PopoverConfig.new(
+        variant:   :popover,
+        position:  :bottom,
+        align:     :start,
+        offset:    4,
+        auto_flip: true
+      )
+
+      @confirm = ConfirmConfig.new(style: :modal)
+
+      @hint = HintConfig.new(
+        variant:       :hint,
+        show_delay_ms: 250,
+        hide_delay_ms: 120
+      )
+    end
+
+    # Modal config. With a block, yields the type config for setters;
+    # without a block, returns it for direct access.
+    def modal
+      yield @modal if block_given?
+      @modal
+    end
+
+    # Drawer config. Same shape as modal, plus a `position` attribute
+    # (`:left`, `:right`, `:top`, `:bottom`).
+    #
+    #   TurboOverlay.configure do |c|
+    #     c.drawer do |d|
+    #       d.position = :left
+    #     end
+    #   end
+    def drawer
+      yield @drawer if block_given?
+      @drawer
+    end
+
+    # Popover config. Anchored to the trigger element. Same shape as
+    # modal, plus `position`, `align`, `offset`, and `auto_flip`.
+    #
+    #   TurboOverlay.configure do |c|
+    #     c.popover do |p|
+    #       p.position = :top
+    #       p.align    = :center
+    #     end
+    #   end
+    def popover
+      yield @popover if block_given?
+      @popover
+    end
+
+    # Confirm-prompt config. Controls how `data-turbo-confirm` renders.
+    #
+    #   TurboOverlay.configure do |c|
+    #     c.confirm do |cf|
+    #       cf.style = :popover    # default :modal
+    #     end
+    #   end
+    def confirm
+      yield @confirm if block_given?
+      @confirm
+    end
+
+    # Hint config. Hover-triggered preview overlays.
+    #
+    #   TurboOverlay.configure do |c|
+    #     c.hint do |h|
+    #       h.show_delay_ms = 400
+    #       h.enabled       = false   # turn the feature off entirely
+    #     end
+    #   end
+    def hint
+      yield @hint if block_given?
+      @hint
+    end
+  end
+end

data/lib/turbo_overlay/controller.rb

@@ -0,0 +1,405 @@
+require "active_support/concern"
+require "securerandom"
+
+module TurboOverlay
+  # Controller concern. Include in `ApplicationController` (or any
+  # controller you want overlay-aware):
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include TurboOverlay::Controller
+  #   end
+  #
+  # The concern auto-installs a `layout` proc that swaps in the
+  # matching overlay layout for overlay requests and preserves
+  # `"turbo_rails/frame"` for plain turbo-frame requests (so including
+  # this concern does not regress Turbo's frame-layout optimization).
+  # For apps with a custom layout method, call `turbo_overlay_layout`
+  # from your method — see the README "A note on custom layouts"
+  # section.
+  module Controller
+    extend ActiveSupport::Concern
+
+    OVERLAY_FRAME_PREFIX    = "turbo_overlay_".freeze
+    OVERLAY_TYPE_HEADER     = "X-Turbo-Overlay".freeze
+    OVERLAY_ID_HEADER       = "X-Turbo-Overlay-Id".freeze
+    OVERLAY_POSITION_HEADER = "X-Turbo-Overlay-Position".freeze
+    OVERLAY_ALIGN_HEADER    = "X-Turbo-Overlay-Align".freeze
+    OVERLAY_OFFSET_HEADER   = "X-Turbo-Overlay-Offset".freeze
+    OVERLAY_BACKDROP_HEADER  = "X-Turbo-Overlay-Backdrop".freeze
+    OVERLAY_CLOSE_HEADER     = "X-Turbo-Overlay-Close".freeze
+    OVERLAY_KEEP_OPEN_HEADER = "X-Turbo-Overlay-Keep-Open".freeze
+
+    # Whitelists for values that originate from request headers and get
+    # reflected into rendered chrome (CSS class tokens, DOM ids,
+    # frame names). Constraining them at the resolver protects every
+    # downstream consumer — gem partials, generator templates, JS data
+    # attributes — without each having to re-validate.
+    ALLOWED_POSITIONS = %i[left right top bottom].freeze
+    ALLOWED_ALIGNS    = %i[start center end].freeze
+    OVERLAY_ID_FORMAT = /\A[A-Za-z0-9_-]{1,64}\z/.freeze
+    OFFSET_RANGE      = (-10_000..10_000).freeze
+
+    included do
+      prepend_before_action :_turbo_overlay_force_html_format
+      prepend_before_action :_turbo_overlay_set_variant
+      after_action :_turbo_overlay_set_stream_content_type
+
+      layout -> { turbo_overlay_layout }
+
+      helper_method :modal_request?,
+        :drawer_request?,
+        :popover_request?,
+        :hint_request?,
+        :overlay_request?, :turbo_overlay_id, :turbo_overlay_type,
+        :turbo_overlay_position, :turbo_overlay_align,
+        :turbo_overlay_offset, :turbo_overlay_backdrop?,
+        :turbo_overlay_close?, :turbo_overlay_keep_open_on_redirect?,
+        :overlay_prefetch_request?, :overlay_hintable_request?
+    end
+
+    # ----- modal -----
+
+    def modal_request?
+      turbo_overlay_type == :modal
+    end
+
+    # ----- drawer -----
+
+    def drawer_request?
+      turbo_overlay_type == :drawer
+    end
+
+    # ----- popover -----
+
+    def popover_request?
+      turbo_overlay_type == :popover
+    end
+
+    # ----- hint -----
+
+    def hint_request?
+      turbo_overlay_type == :hint
+    end
+
+    # ----- layout -----
+
+    # Layout name for the current request. Returns the matching overlay
+    # layout for overlay requests, `"turbo_rails/frame"` for plain
+    # turbo-frame requests (preserving Turbo's optimization, since our
+    # auto-installed `layout` proc replaces Turbo's), or `nil`
+    # otherwise so Rails picks the default layout.
+    #
+    # Apps with a custom layout method should call this first:
+    #
+    #   def custom_layout
+    #     turbo_overlay_layout || "my_app_layout"
+    #   end
+    def turbo_overlay_layout
+      case turbo_overlay_type
+      when :modal   then "turbo_overlay/modal"
+      when :drawer  then "turbo_overlay/drawer"
+      when :popover then "turbo_overlay/popover"
+      when :hint    then "turbo_overlay/hint"
+      else
+        "turbo_rails/frame" if respond_to?(:turbo_frame_request?) && turbo_frame_request?
+      end
+    end
+
+    # ----- generic -----
+
+    # True if the current request targets *any* configured overlay
+    # (initial open or in-overlay form re-render). Useful in shared
+    # partials.
+    def overlay_request?
+      !turbo_overlay_type.nil?
+    end
+
+    # True if the current request is a Turbo hover prefetch. Detected
+    # via the `X-Sec-Purpose: prefetch` request header that Turbo
+    # sends — the W3C `Sec-Purpose` is a Forbidden Header for
+    # JS-initiated `fetch()` requests, so Turbo prepends `X-`. Used
+    # by `overlay_stack_tag` to decide whether to render the action's
+    # `+hint` variant template inline.
+    def overlay_prefetch_request?
+      return false unless respond_to?(:request) && request
+      request.headers["X-Sec-Purpose"].to_s.include?("prefetch")
+    end
+
+    # True if the current request will use the hint template — either
+    # a hover prefetch (which the gem's JS extracts the template from)
+    # or an explicit `:hint` variant fetch. Gates the `+hint` variant
+    # auto-render in `overlay_stack_tag`.
+    def overlay_hintable_request?
+      hint_request? || overlay_prefetch_request?
+    end
+
+    # Returns `:modal`, `:drawer`, `:popover`, or `nil`. Detected from
+    # the `X-Turbo-Overlay` request header (initial open) or the
+    # `Turbo-Frame: turbo_overlay_<type>_<id>` header (form re-render
+    # inside an open overlay).
+    def turbo_overlay_type
+      return @_turbo_overlay_type if defined?(@_turbo_overlay_type)
+      @_turbo_overlay_type = _resolve_overlay_type
+    end
+
+    # The overlay id for the current request. Resolution order:
+    #
+    # 1. `X-Turbo-Overlay-Id` request header (caller supplied
+    #    `overlay_id:` on the link helper)
+    # 2. The `<id>` segment parsed from a
+    #    `Turbo-Frame: turbo_overlay_<type>_<id>` header (form re-render)
+    # 3. A freshly generated `SecureRandom.alphanumeric(8)` id,
+    #    memoized for the duration of the request
+    #
+    # Available in the controller and in views (e.g. for
+    # `turbo_stream.overlay(:close, id: turbo_overlay_id)`).
+    def turbo_overlay_id
+      return @_turbo_overlay_id if defined?(@_turbo_overlay_id)
+      @_turbo_overlay_id = _resolve_overlay_id
+    end
+
+    # The per-link position override for the current overlay request,
+    # parsed from the `X-Turbo-Overlay-Position` header. Returns a
+    # Symbol (`:left`, `:right`, `:top`, `:bottom`) or `nil` when the
+    # link didn't supply one. Drawer partials use this with a
+    # fallback to `TurboOverlay.configuration.drawer.position`;
+    # popover partials use it with a fallback to
+    # `TurboOverlay.configuration.popover.position`.
+    def turbo_overlay_position
+      return @_turbo_overlay_position if defined?(@_turbo_overlay_position)
+      @_turbo_overlay_position = _resolve_overlay_position
+    end
+
+    # The per-link cross-axis alignment for popovers, parsed from the
+    # `X-Turbo-Overlay-Align` header. Returns a Symbol (`:start`,
+    # `:center`, `:end`) or `nil`. Popover partials fall back to
+    # `TurboOverlay.configuration.popover.align`.
+    def turbo_overlay_align
+      return @_turbo_overlay_align if defined?(@_turbo_overlay_align)
+      @_turbo_overlay_align = _resolve_overlay_align
+    end
+
+    # The per-link pixel offset between trigger and popover, parsed
+    # from the `X-Turbo-Overlay-Offset` header. Returns an Integer or
+    # `nil`. Popover partials fall back to
+    # `TurboOverlay.configuration.popover.offset`.
+    def turbo_overlay_offset
+      return @_turbo_overlay_offset if defined?(@_turbo_overlay_offset)
+      @_turbo_overlay_offset = _resolve_overlay_offset
+    end
+
+    # Whether the current overlay request should render with a
+    # backdrop. Defaults to `true`; only `false` when the link helper
+    # explicitly passed `backdrop: false` (carried in the
+    # `X-Turbo-Overlay-Backdrop` header). Drawer partials switch the
+    # `<dialog>` open mode and CSS based on this.
+    def turbo_overlay_backdrop?
+      return @_turbo_overlay_backdrop if defined?(@_turbo_overlay_backdrop)
+      @_turbo_overlay_backdrop = _resolve_overlay_backdrop
+    end
+
+    # Whether the current overlay request should render the chrome's
+    # default close ("×") button. Defaults to `true`; only `false`
+    # when the link helper explicitly passed `close: false` (carried in
+    # the `X-Turbo-Overlay-Close` header). Chrome partials consult
+    # `overlay_close?` (view helper) which folds this into the full
+    # opt-out precedence chain.
+    def turbo_overlay_close?
+      return @_turbo_overlay_close if defined?(@_turbo_overlay_close)
+      @_turbo_overlay_close = _resolve_overlay_close
+    end
+
+    # Whether the overlay should stay open when a form descendant
+    # submits and the response is a redirect. Defaults to `false`
+    # (close-on-redirect is the gem's default); becomes `true` when
+    # the trigger link passed `keep_overlay_open_on_redirect: true`
+    # (carried in the `X-Turbo-Overlay-Keep-Open` header). The chrome
+    # partials reflect this onto the `<dialog>` as a data attribute
+    # the per-dialog submit-end listener reads.
+    def turbo_overlay_keep_open_on_redirect?
+      return @_turbo_overlay_keep_open if defined?(@_turbo_overlay_keep_open)
+      @_turbo_overlay_keep_open = _resolve_overlay_keep_open_on_redirect
+    end
+
+    # True for the initial open of an overlay (an `X-Turbo-Overlay`
+    # request that is not a form re-render inside an existing
+    # overlay frame). Used internally to decide between turbo-stream
+    # append wrapping and turbo-frame replace wrapping.
+    def turbo_overlay_initial_open?
+      return false unless turbo_overlay_type
+      !turbo_overlay_frame_re_render?
+    end
+
+    # True when this is a form/link response targeting an existing
+    # overlay's turbo-frame (form re-render in place). Mirrors the
+    # same prefetch guard as `_resolve_overlay_type`: a hover prefetch
+    # carries the enclosing frame's id in `Turbo-Frame` but is NOT a
+    # re-render — treating it as one would flip the response
+    # Content-Type to `text/vnd.turbo-stream.html` (via
+    # `_turbo_overlay_set_stream_content_type`) for a body that's a
+    # plain `<turbo-frame>`, an incoherent mismatch.
+    def turbo_overlay_frame_re_render?
+      return false unless respond_to?(:request) && request
+      return false if overlay_prefetch_request?
+      request.headers["Turbo-Frame"].to_s.start_with?(OVERLAY_FRAME_PREFIX)
+    end
+
+    private
+
+    def _resolve_overlay_type
+      return nil unless respond_to?(:request) && request
+
+      header = request.headers[OVERLAY_TYPE_HEADER].to_s.downcase
+      return :modal   if header == "modal"
+      return :drawer  if header == "drawer"
+      return :popover if header == "popover"
+      return :hint    if header == "hint"
+
+      # Turbo's hover prefetch carries the enclosing frame's id in the
+      # `Turbo-Frame` header. Falling into the frame-parse branch on a
+      # prefetch would route the prefetched URL through the overlay
+      # layout and return a frame-replace turbo-stream — which Turbo
+      # applies on receipt, replacing the open overlay's contents with
+      # whatever the prefetched URL renders. Skip the fallback so
+      # prefetches render as normal pages and Turbo just caches them.
+      # Explicit overlay opens (`X-Turbo-Overlay` header set by the
+      # gem's JS) are unaffected — those are matched above.
+      return nil if overlay_prefetch_request?
+
+      frame = request.headers["Turbo-Frame"].to_s
+      if frame.start_with?(OVERLAY_FRAME_PREFIX)
+        rest = frame[OVERLAY_FRAME_PREFIX.length..]
+        return :modal   if rest.start_with?("modal_")
+        return :drawer  if rest.start_with?("drawer_")
+        return :popover if rest.start_with?("popover_")
+      end
+
+      nil
+    end
+
+    def _resolve_overlay_id
+      return nil unless turbo_overlay_type
+
+      supplied = request.headers[OVERLAY_ID_HEADER].to_s
+      return supplied if supplied.match?(OVERLAY_ID_FORMAT)
+
+      frame = request.headers["Turbo-Frame"].to_s
+      if frame.start_with?(OVERLAY_FRAME_PREFIX)
+        rest = frame[OVERLAY_FRAME_PREFIX.length..]
+        underscore = rest.index("_")
+        if underscore
+          parsed = rest[(underscore + 1)..]
+          return parsed if parsed.match?(OVERLAY_ID_FORMAT)
+        end
+      end
+
+      SecureRandom.alphanumeric(8)
+    end
+
+    def _resolve_overlay_position
+      return nil unless respond_to?(:request) && request
+
+      value = request.headers[OVERLAY_POSITION_HEADER].to_s
+      return nil if value.empty?
+      sym = value.to_sym
+      ALLOWED_POSITIONS.include?(sym) ? sym : nil
+    end
+
+    def _resolve_overlay_align
+      return nil unless respond_to?(:request) && request
+
+      value = request.headers[OVERLAY_ALIGN_HEADER].to_s
+      return nil if value.empty?
+      sym = value.to_sym
+      ALLOWED_ALIGNS.include?(sym) ? sym : nil
+    end
+
+    def _resolve_overlay_offset
+      return nil unless respond_to?(:request) && request
+
+      value = request.headers[OVERLAY_OFFSET_HEADER].to_s
+      return nil if value.empty?
+      n = Integer(value, exception: false)
+      n && n.clamp(OFFSET_RANGE.min, OFFSET_RANGE.max)
+    end
+
+    def _resolve_overlay_backdrop
+      return true unless respond_to?(:request) && request
+      request.headers[OVERLAY_BACKDROP_HEADER].to_s != "false"
+    end
+
+    def _resolve_overlay_close
+      return true unless respond_to?(:request) && request
+      request.headers[OVERLAY_CLOSE_HEADER].to_s != "false"
+    end
+
+    def _resolve_overlay_keep_open_on_redirect
+      return false unless respond_to?(:request) && request
+      request.headers[OVERLAY_KEEP_OPEN_HEADER].to_s == "true"
+    end
+
+    def _turbo_overlay_set_variant
+      type = turbo_overlay_type
+      return unless type
+
+      config = TurboOverlay.configuration
+      type_config = case type
+                    when :modal   then config.modal
+                    when :drawer  then config.drawer
+                    when :popover then config.popover
+                    when :hint    then config.hint
+                    end
+      variant = type_config.variant
+      if request.variant.is_a?(Array)
+        request.variant << variant unless request.variant.include?(variant)
+      else
+        request.variant = variant
+      end
+    end
+
+    # Initial overlay opens are GET requests with Accept including
+    # `text/vnd.turbo-stream.html`. Force html format so Rails
+    # resolves `*.html.erb` templates normally (no need for the user
+    # to provide `*.turbo_stream.erb` variants); we override the
+    # response Content-Type after the action so Turbo still processes
+    # the embedded `<turbo-stream>` tags.
+    #
+    # Frame re-renders deliberately do NOT force the format. Apps
+    # typically branch the action on format
+    # (`respond_to { |format| format.turbo_stream { … }; format.html
+    # { redirect_to … } }`); forcing html here would pick the
+    # redirect branch on every successful save, and the redirected
+    # page would itself render through this concern's overlay
+    # layout — morphing the entire next page into the open dialog.
+    # Implicit renders (`render :edit` with no `respond_to`) still
+    # work: `request.format` stays `:turbo_stream`, Rails' template
+    # resolution walks `request.formats` and falls back to
+    # `<action>.html.erb`.
+    #
+    # Hint requests skip both: they're fetched by the gem's JS via
+    # plain `fetch()` (not Turbo), the Accept header is `text/html`
+    # already, and the response is parsed via DOMParser. Forcing the
+    # turbo-stream content type would make Turbo try to process the
+    # response if it ever did intercept it.
+    def _turbo_overlay_force_html_format
+      return unless turbo_overlay_initial_open?
+      return if turbo_overlay_type == :hint
+      request.format = :html
+    end
+
+    # Frame re-renders DO need the turbo-stream Content-Type even
+    # though the action template is `*.html.erb`: the overlay layout
+    # wraps the body in a `<turbo-stream action="replace"
+    # method="morph">` tag, and Turbo only processes stream actions
+    # when the response Content-Type is the turbo-stream mime. Rails
+    # would otherwise set it to `text/html` (matched-template mime),
+    # which makes Turbo treat the response as a frame body, find no
+    # matching `<turbo-frame>` at the top level, and silently drop it.
+    def _turbo_overlay_set_stream_content_type
+      return unless turbo_overlay_initial_open? || turbo_overlay_frame_re_render?
+      return if turbo_overlay_type == :hint
+      return unless response
+      response.content_type = "text/vnd.turbo-stream.html; charset=utf-8"
+    end
+  end
+end

data/lib/turbo_overlay/engine.rb

@@ -0,0 +1,52 @@
+require "rails/engine"
+require "turbo-rails"
+
+module TurboOverlay
+  class Engine < ::Rails::Engine
+    isolate_namespace TurboOverlay
+
+    initializer "turbo_overlay.action_view" do
+      ActiveSupport.on_load(:action_view) do
+        require "turbo_overlay/helpers/view_helper"
+        include TurboOverlay::Helpers::ViewHelper
+      end
+    end
+
+    initializer "turbo_overlay.turbo_stream_actions" do
+      require "turbo_overlay/helpers/stream_helper"
+      Turbo::Streams::TagBuilder.include(TurboOverlay::Helpers::StreamHelper)
+    end
+
+    # Eager-load the controller concern so `include TurboOverlay::Controller`
+    # works in user code without an explicit require.
+    initializer "turbo_overlay.controller_autoload" do
+      require "turbo_overlay/controller"
+    end
+
+    # Make the gem's `app/javascript` available to sprockets/propshaft
+    # so importmap-rails can serve the controllers + entry point.
+    initializer "turbo_overlay.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/javascript").to_s
+      end
+    end
+
+    # Pin the gem's JS for importmap-rails apps. Apps then write:
+    #
+    #   import { register } from "turbo_overlay"
+    #   register(application)
+    #
+    # in their Stimulus entry point. jsbundling apps either eject the
+    # JS via `bin/rails g turbo_overlay:eject --js` or add the gem's
+    # `app/javascript` dir to their bundler's resolve paths.
+    #
+    # Implementation: append the gem's `config/importmap.rb` to the
+    # host app's importmap paths so importmap-rails draws the pins
+    # during its own `importmap` initializer.
+    initializer "turbo_overlay.importmap", before: "importmap" do |app|
+      if app.config.respond_to?(:importmap) && app.config.importmap.respond_to?(:paths)
+        app.config.importmap.paths << root.join("config/importmap.rb")
+      end
+    end
+  end
+end