turbo-rails 1.5.0 → 2.0.11

data/app/models/concerns/turbo/broadcastable.rb

@@ -1,4 +1,4 @@
-# Turbo streams can be broadcast directly from models that include this module (this is automatically done for Active Records).
+# Turbo streams can be broadcasted directly from models that include this module (this is automatically done for Active Records if ActiveJob is loaded).
 # This makes it convenient to execute both synchronous and asynchronous updates, and render directly from callbacks in models
 # or from controllers or jobs that act on those models. Here's an example:
 #
@@ -14,8 +14,8 @@
 #       end
 #   end
 #
-# This is an example from [HEY](https://hey.com), and the clearance is the model that drives
-# [the screener](https://hey.com/features/the-screener/), which gives users the power to deny first-time senders (petitioners)
+# This is an example from {HEY}[https://hey.com], and the clearance is the model that drives
+# {the screener}[https://hey.com/features/the-screener/], which gives users the power to deny first-time senders (petitioners)
 # access to their attention (as the examiner). When a new clearance is created upon receipt of an email from a first-time
 # sender, that'll trigger the call to broadcast_later, which in turn invokes <tt>broadcast_prepend_later_to</tt>.
 #
@@ -27,7 +27,7 @@
 # (which is derived by default from the plural model name of the model, but can be overwritten).
 #
 # You can also choose to render html instead of a partial inside of a broadcast
-# you do this by passing the `html:` option to any broadcast method that accepts the **rendering argument. Example:
+# you do this by passing the +html:+ option to any broadcast method that accepts the **rendering argument. Example:
 #
 #   class Message < ApplicationRecord
 #     belongs_to :user
@@ -40,8 +40,8 @@
 #       end
 #   end
 #
-# If you want to render a template instead of a partial, e.g. ('messages/index' or 'messages/show'), you can use the `template:` option.
-# Again, only to any broadcast method that accepts the `**rendering` argument. Example:
+# If you want to render a template instead of a partial, e.g. ('messages/index' or 'messages/show'), you can use the +template:+ option.
+# Again, only to any broadcast method that accepts the +**rendering+ argument. Example:
 #
 #   class Message < ApplicationRecord
 #     belongs_to :user
@@ -54,7 +54,7 @@
 #       end
 #   end
 #
-# If you want to render a renderable object you can use the `renderable:` option.
+# If you want to render a renderable object you can use the +renderable:+ option.
 #
 #   class Message < ApplicationRecord
 #     belongs_to :user
@@ -67,17 +67,99 @@
 #       end
 #   end
 #
-# There are four basic actions you can broadcast: <tt>remove</tt>, <tt>replace</tt>, <tt>append</tt>, and
-# <tt>prepend</tt>. As a rule, you should use the <tt>_later</tt> versions of everything except for remove when broadcasting
+# There are seven basic actions you can broadcast: <tt>after</tt>, <tt>append</tt>, <tt>before</tt>,
+# <tt>prepend</tt>, <tt>remove</tt>, <tt>replace</tt>, and
+# <tt>update</tt>. As a rule, you should use the <tt>_later</tt> versions of everything except for remove when broadcasting
 # within a real-time path, like a controller or model, since all those updates require a rendering step, which can slow down
 # execution. You don't need to do this for remove, since only the dom id for the model is used.
 #
-# In addition to the four basic actions, you can also use <tt>broadcast_render</tt>,
+# In addition to the seven basic actions, you can also use <tt>broadcast_render</tt>,
 # <tt>broadcast_render_to</tt> <tt>broadcast_render_later</tt>, and <tt>broadcast_render_later_to</tt>
 # to render a turbo stream template with multiple actions.
+#
+# == Page refreshes
+#
+# You can broadcast "page refresh" stream actions. This will make subscribed clients reload the
+# page. For pages that configure morphing and scroll preservation, this will translate into smooth
+# updates when it only updates the content that changed.
+#
+# This approach is an alternative to fine-grained stream actions targeting specific DOM elements. It
+# offers good fidelity with a much simpler programming model. As a tradeoff, the fidelity you can reach
+# is often not as high as with targeted stream actions since it renders the entire page again.
+#
+# The +broadcasts_refreshes+ class method configures the model to broadcast a "page refresh" on creates,
+# updates, and destroys to a stream name derived at runtime by the <tt>stream</tt> symbol invocation. Examples
+#
+#   class Board < ApplicationRecord
+#     broadcasts_refreshes
+#   end
+#
+# In this example, when a board is created, updated, or destroyed, a Turbo Stream for a
+# page refresh will be broadcasted to all clients subscribed to the "boards" stream.
+#
+# This works great in hierarchical structures, where the child record touches parent records automatically
+# to invalidate the cache:
+#
+#   class Column < ApplicationRecord
+#     belongs_to :board, touch: true # +Board+ will trigger a page refresh on column changes
+#   end
+#
+# You can also specify the streamable declaratively by passing a symbol to the +broadcasts_refreshes_to+ method:
+#
+#   class Column < ApplicationRecord
+#     belongs_to :board
+#     broadcasts_refreshes_to :board
+#   end
+#
+# For more granular control, you can also broadcast a "page refresh" to a stream name derived
+# from the passed <tt>streamables</tt> by using the instance-level methods <tt>broadcast_refresh_to</tt> or
+# <tt>broadcast_refresh_later_to</tt>. These methods are particularly useful when you want to trigger
+# a page refresh for more specific scenarios. Example:
+#
+#   class Clearance < ApplicationRecord
+#     belongs_to :petitioner, class_name: "Contact"
+#     belongs_to :examiner,   class_name: "User"
+#
+#     after_create_commit :broadcast_refresh_later
+#
+#     private
+#       def broadcast_refresh_later
+#         broadcast_refresh_later_to examiner.identity, :clearances
+#       end
+#   end
+#
+# In this example, a "page refresh" is broadcast to the stream named "identity:<identity-id>:clearances"
+# after a new clearance is created. All clients subscribed to this stream will refresh the page to reflect
+# the changes.
+#
+# When broadcasting page refreshes, Turbo will automatically debounce multiple calls in a row to only broadcast the last one.
+# This is meant for scenarios where you process records in mass. Because of the nature of such signals, it makes no sense to
+# broadcast them repeatedly and individually.
+# == Suppressing broadcasts
+#
+# Sometimes, you need to disable broadcasts in certain scenarios. You can use <tt>.suppressing_turbo_broadcasts</tt> to create
+# execution contexts where broadcasts are disabled:
+#
+#   class Message < ApplicationRecord
+#     after_create_commit :update_message
+#
+#     private
+#       def update_message
+#         broadcast_replace_to(user, :message, target: "message", renderable: MessageComponent.new)
+#       end
+#   end
+#
+#   Message.suppressing_turbo_broadcasts do
+#     Message.create!(board: board) # This won't broadcast the replace action
+#   end
 module Turbo::Broadcastable
   extend ActiveSupport::Concern
 
+  included do
+    thread_mattr_accessor :suppressed_turbo_broadcasts, instance_accessor: false
+    delegate :suppressed_turbo_broadcasts?, to: "self.class"
+  end
+
   module ClassMethods
     # Configures the model to broadcast creates, updates, and destroys to a stream name derived at runtime by the
     # <tt>stream</tt> symbol invocation. By default, the creates are appended to a dom id target name derived from
@@ -112,10 +194,46 @@ module Turbo::Broadcastable
       after_destroy_commit -> { broadcast_remove }
     end
 
+    # Configures the model to broadcast a "page refresh" on creates, updates, and destroys to a stream
+    # name derived at runtime by the <tt>stream</tt> symbol invocation. Examples:
+    #
+    #   class Message < ApplicationRecord
+    #     belongs_to :board
+    #     broadcasts_refreshes_to :board
+    #   end
+    #
+    #   class Message < ApplicationRecord
+    #     belongs_to :board
+    #     broadcasts_refreshes_to ->(message) { [ message.board, :messages ] }
+    #   end
+    def broadcasts_refreshes_to(stream)
+      after_commit -> { broadcast_refresh_later_to(stream.try(:call, self) || send(stream)) }
+    end
+
+    # Same as <tt>#broadcasts_refreshes_to</tt>, but the designated stream for page refreshes is automatically set to
+    # the current model, for creates - to the model plural name, which can be overriden by passing <tt>stream</tt>.
+    def broadcasts_refreshes(stream = model_name.plural)
+      after_create_commit  -> { broadcast_refresh_later_to(stream) }
+      after_update_commit  -> { broadcast_refresh_later }
+      after_destroy_commit -> { broadcast_refresh }
+    end
+
     # All default targets will use the return of this method. Overwrite if you want something else than <tt>model_name.plural</tt>.
     def broadcast_target_default
       model_name.plural
     end
+
+    # Executes +block+ preventing both synchronous and asynchronous broadcasts from this model.
+    def suppressing_turbo_broadcasts(&block)
+      original, self.suppressed_turbo_broadcasts = self.suppressed_turbo_broadcasts, true
+      yield
+    ensure
+      self.suppressed_turbo_broadcasts = original
+    end
+
+    def suppressed_turbo_broadcasts?
+      suppressed_turbo_broadcasts
+    end
   end
 
   # Remove this broadcastable model from the dom for subscribers of the stream name identified by the passed streamables.
@@ -123,13 +241,13 @@ module Turbo::Broadcastable
   #
   #   # Sends <turbo-stream action="remove" target="clearance_5"></turbo-stream> to the stream named "identity:2:clearances"
   #   clearance.broadcast_remove_to examiner.identity, :clearances
-  def broadcast_remove_to(*streamables, target: self)
-    Turbo::StreamsChannel.broadcast_remove_to(*streamables, target: target)
+  def broadcast_remove_to(*streamables, target: self, **rendering)
+    Turbo::StreamsChannel.broadcast_remove_to(*streamables, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_remove_to</tt>, but the designated stream is automatically set to the current model.
-  def broadcast_remove
-    broadcast_remove_to self
+  def broadcast_remove(**rendering)
+    broadcast_remove_to self, **rendering
   end
 
   # Replace this broadcastable model in the dom for subscribers of the stream name identified by the passed
@@ -142,8 +260,12 @@ module Turbo::Broadcastable
   #   # Sends <turbo-stream action="replace" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_replace_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
+  #
+  #   # Sends <turbo-stream action="replace" method="morph" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   clearance.broadcast_replace_to examiner.identity, :clearance, attributes: { method: :morph }, partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_replace_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_replace_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_replace_to(*streamables, **extract_options_and_add_target(rendering, target: self)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_replace_to</tt>, but the designated stream is automatically set to the current model.
@@ -161,8 +283,12 @@ module Turbo::Broadcastable
   #   # Sends <turbo-stream action="update" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_update_to examiner.identity, :clearances, partial: "clearances/other_partial", locals: { a: 1 }
+  #
+  #   # sends <turbo-stream action="update" method="morph" target="clearance_5"><template><div id="clearance_5">Other partial</div></template></turbo-stream>
+  #   # to the stream named "identity:2:clearances"
+  #   # clearance.broadcast_update_to examiner.identity, :clearances, attributes: { method: :morph }, partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_update_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_update_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_update_to(*streamables, **extract_options_and_add_target(rendering, target: self)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_update_to</tt>, but the designated stream is automatically set to the current model.
@@ -182,8 +308,10 @@ module Turbo::Broadcastable
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_before_to examiner.identity, :clearances, target: "clearance_5",
   #     partial: "clearances/other_partial", locals: { a: 1 }
-  def broadcast_before_to(*streamables, target:, **rendering)
-    Turbo::StreamsChannel.broadcast_before_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+  def broadcast_before_to(*streamables, target: nil, targets: nil, **rendering)
+    raise ArgumentError, "at least one of target or targets is required" unless target || targets
+
+    Turbo::StreamsChannel.broadcast_before_to(*streamables, **extract_options_and_add_target(rendering.merge(target: target, targets: targets)))
   end
 
   # Insert a rendering of this broadcastable model after the target identified by it's dom id passed as <tt>target</tt>
@@ -198,8 +326,10 @@ module Turbo::Broadcastable
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_after_to examiner.identity, :clearances, target: "clearance_5",
   #     partial: "clearances/other_partial", locals: { a: 1 }
-  def broadcast_after_to(*streamables, target:, **rendering)
-    Turbo::StreamsChannel.broadcast_after_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+  def broadcast_after_to(*streamables, target: nil, targets: nil, **rendering)
+    raise ArgumentError, "at least one of target or targets is required" unless target || targets
+
+    Turbo::StreamsChannel.broadcast_after_to(*streamables, **extract_options_and_add_target(rendering.merge(target: target, targets: targets)))
   end
 
   # Append a rendering of this broadcastable model to the target identified by it's dom id passed as <tt>target</tt>
@@ -215,7 +345,7 @@ module Turbo::Broadcastable
   #   clearance.broadcast_append_to examiner.identity, :clearances, target: "clearances",
   #     partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_append_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_append_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_append_to(*streamables, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_append_to</tt>, but the designated stream is automatically set to the current model.
@@ -236,7 +366,7 @@ module Turbo::Broadcastable
   #   clearance.broadcast_prepend_to examiner.identity, :clearances, target: "clearances",
   #     partial: "clearances/other_partial", locals: { a: 1 }
   def broadcast_prepend_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_prepend_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_prepend_to(*streamables, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_prepend_to</tt>, but the designated stream is automatically set to the current model.
@@ -244,24 +374,36 @@ module Turbo::Broadcastable
     broadcast_prepend_to self, target: target, **rendering
   end
 
+  #  Broadcast a "page refresh" to the stream name identified by the passed <tt>streamables</tt>. Example:
+  #
+  #   # Sends <turbo-stream action="refresh"></turbo-stream> to the stream named "identity:2:clearances"
+  #   clearance.broadcast_refresh_to examiner.identity, :clearances
+  def broadcast_refresh_to(*streamables)
+    Turbo::StreamsChannel.broadcast_refresh_to(*streamables) unless suppressed_turbo_broadcasts?
+  end
+
+  #  Same as <tt>#broadcast_refresh_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_refresh
+    broadcast_refresh_to self
+  end
+
   # Broadcast a named <tt>action</tt>, allowing for dynamic dispatch, instead of using the concrete action methods. Examples:
   #
   #   # Sends <turbo-stream action="prepend" target="clearances"><template><div id="clearance_5">My Clearance</div></template></turbo-stream>
   #   # to the stream named "identity:2:clearances"
   #   clearance.broadcast_action_to examiner.identity, :clearances, action: :prepend, target: "clearances"
-  def broadcast_action_to(*streamables, action:, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering))
+  def broadcast_action_to(*streamables, action:, target: broadcast_target_default, attributes: {}, **rendering)
+    Turbo::StreamsChannel.broadcast_action_to(*streamables, action: action, attributes: attributes, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_action_to</tt>, but the designated stream is automatically set to the current model.
-  def broadcast_action(action, target: broadcast_target_default, **rendering)
-    broadcast_action_to self, action: action, target: target, **rendering
+  def broadcast_action(action, target: broadcast_target_default, attributes: {}, **rendering)
+    broadcast_action_to self, action: action, target: target, attributes: attributes, **rendering
   end
 
-
   # Same as <tt>broadcast_replace_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_replace_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_replace_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_replace_later_to(*streamables, **extract_options_and_add_target(rendering, target: self)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_replace_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -271,7 +413,7 @@ module Turbo::Broadcastable
 
   # Same as <tt>broadcast_update_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_update_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_update_later_to(*streamables, target: self, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_update_later_to(*streamables, **extract_options_and_add_target(rendering, target: self)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_update_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -281,7 +423,7 @@ module Turbo::Broadcastable
 
   # Same as <tt>broadcast_append_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_append_later_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_append_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_append_later_to(*streamables, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_append_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -291,7 +433,7 @@ module Turbo::Broadcastable
 
   # Same as <tt>broadcast_prepend_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_prepend_later_to(*streamables, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_prepend_later_to(*streamables, target: target, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_prepend_later_to(*streamables, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_prepend_later_to</tt>, but the designated stream is automatically set to the current model.
@@ -299,14 +441,24 @@ module Turbo::Broadcastable
     broadcast_prepend_later_to self, target: target, **rendering
   end
 
+  #  Same as <tt>broadcast_refresh_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  def broadcast_refresh_later_to(*streamables)
+    Turbo::StreamsChannel.broadcast_refresh_later_to(*streamables, request_id: Turbo.current_request_id) unless suppressed_turbo_broadcasts?
+  end
+
+  #  Same as <tt>#broadcast_refresh_later_to</tt>, but the designated stream is automatically set to the current model.
+  def broadcast_refresh_later
+    broadcast_refresh_later_to self
+  end
+
   # Same as <tt>broadcast_action_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
-  def broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, **rendering)
-    Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, target: target, **broadcast_rendering_with_defaults(rendering))
+  def broadcast_action_later_to(*streamables, action:, target: broadcast_target_default, attributes: {}, **rendering)
+    Turbo::StreamsChannel.broadcast_action_later_to(*streamables, action: action, attributes: attributes, **extract_options_and_add_target(rendering, target: target)) unless suppressed_turbo_broadcasts?
   end
 
   # Same as <tt>#broadcast_action_later_to</tt>, but the designated stream is automatically set to the current model.
-  def broadcast_action_later(action:, target: broadcast_target_default, **rendering)
-    broadcast_action_later_to self, action: action, target: target, **rendering
+  def broadcast_action_later(action:, target: broadcast_target_default, attributes: {}, **rendering)
+    broadcast_action_later_to self, action: action, target: target, attributes: attributes, **rendering
   end
 
   # Render a turbo stream template with this broadcastable model passed as the local variable. Example:
@@ -325,7 +477,7 @@ module Turbo::Broadcastable
   #
   # Note that rendering inline via this method will cause template rendering to happen synchronously. That is usually not
   # desireable for model callbacks, certainly not if those callbacks are inside of a transaction. Most of the time you should
-  # be using `broadcast_render_later`, unless you specifically know why synchronous rendering is needed.
+  # be using +broadcast_render_later+, unless you specifically know why synchronous rendering is needed.
   def broadcast_render(**rendering)
     broadcast_render_to self, **rendering
   end
@@ -335,12 +487,12 @@ module Turbo::Broadcastable
   #
   # Note that rendering inline via this method will cause template rendering to happen synchronously. That is usually not
   # desireable for model callbacks, certainly not if those callbacks are inside of a transaction. Most of the time you should
-  # be using `broadcast_render_later_to`, unless you specifically know why synchronous rendering is needed.
+  # be using +broadcast_render_later_to+, unless you specifically know why synchronous rendering is needed.
   def broadcast_render_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_render_to(*streamables, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_render_to(*streamables, **extract_options_and_add_target(rendering, target: self)) unless suppressed_turbo_broadcasts?
   end
 
-  # Same as <tt>broadcast_action_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
+  # Same as <tt>broadcast_render_to</tt> but run asynchronously via a <tt>Turbo::Streams::BroadcastJob</tt>.
   def broadcast_render_later(**rendering)
     broadcast_render_later_to self, **rendering
   end
@@ -348,25 +500,32 @@ module Turbo::Broadcastable
   # Same as <tt>broadcast_render_later</tt> but run with the added option of naming the stream using the passed
   # <tt>streamables</tt>.
   def broadcast_render_later_to(*streamables, **rendering)
-    Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **broadcast_rendering_with_defaults(rendering))
+    Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **extract_options_and_add_target(rendering)) unless suppressed_turbo_broadcasts?
   end
 
-
   private
     def broadcast_target_default
       self.class.broadcast_target_default
     end
 
+    def extract_options_and_add_target(rendering = {}, target: broadcast_target_default)
+      broadcast_rendering_with_defaults(rendering).tap do |options|
+        options[:target] = target if !options.key?(:target) && !options.key?(:targets)
+      end
+    end
+
     def broadcast_rendering_with_defaults(options)
       options.tap do |o|
         # Add the current instance into the locals with the element name (which is the un-namespaced name)
         # as the key. This parallels how the ActionView::ObjectRenderer would create a local variable.
-        o[:locals] = (o[:locals] || {}).reverse_merge!(model_name.element.to_sym => self)
+        o[:locals] = (o[:locals] || {}).reverse_merge!(model_name.element.to_sym => self).compact
 
         if o[:html] || o[:partial]
           return o
         elsif o[:template] || o[:renderable]
           o[:layout] = false
+        elsif o[:render] == false
+          return o
         else
           # if none of these options are passed in, it will set a partial from #to_partial_path
           o[:partial] ||= to_partial_path

data/app/models/turbo/debouncer.rb

@@ -0,0 +1,24 @@
+class Turbo::Debouncer
+  attr_reader :delay, :scheduled_task
+
+  DEFAULT_DELAY = 0.5
+
+  def initialize(delay: DEFAULT_DELAY)
+    @delay = delay
+    @scheduled_task = nil
+  end
+
+  def debounce(&block)
+    scheduled_task&.cancel unless scheduled_task&.complete?
+    @scheduled_task = Concurrent::ScheduledTask.execute(delay, &block)
+  end
+
+  def wait
+    scheduled_task&.wait(wait_timeout)
+  end
+
+  private
+    def wait_timeout
+      delay + 1
+    end
+end

data/app/models/turbo/streams/tag_builder.rb

@@ -22,6 +22,24 @@
 #   <%= turbo_stream.append dom_id(topic_merge) do %>
 #     <%= link_to topic_merge.topic.name, topic_path(topic_merge.topic) %>
 #   <% end %>
+#
+# To integrate with custom actions, extend this class in response to the :turbo_streams_tag_builder load hook:
+#
+#   ActiveSupport.on_load :turbo_streams_tag_builder do
+#     def highlight(target)
+#       action :highlight, target
+#     end
+#
+#     def highlight_all(targets)
+#       action_all :highlight, targets
+#     end
+#   end
+#
+#   turbo_stream.highlight "my-element"
+#   # => <turbo-stream action="highlight" target="my-element"><template></template></turbo-stream>
+#
+#   turbo_stream.highlight_all ".my-selector"
+#   # => <turbo-stream action="highlight" targets=".my-selector"><template></template></turbo-stream>
 class Turbo::Streams::TagBuilder
   include Turbo::Streams::ActionHelper
 
@@ -59,8 +77,9 @@ class Turbo::Streams::TagBuilder
   #   <%= turbo_stream.replace "clearance_5" do %>
   #     <div id='clearance_5'>Replace the dom target identified by clearance_5</div>
   #   <% end %>
-  def replace(target, content = nil, **rendering, &block)
-    action :replace, target, content, **rendering, &block
+  #   <%= turbo_stream.replace clearance, "<div>Morph the dom target</div>", method: :morph %>
+  def replace(target, content = nil, method: nil, **rendering, &block)
+    action :replace, target, content, method: method, **rendering, &block
   end
 
   # Replace the <tt>targets</tt> in the dom with either the <tt>content</tt> passed in, a rendering result determined
@@ -72,8 +91,9 @@ class Turbo::Streams::TagBuilder
   #   <%= turbo_stream.replace_all ".clearance_item" do %>
   #     <div class='.clearance_item'>Replace the dom target identified by the class clearance_item</div>
   #   <% end %>
-  def replace_all(targets, content = nil, **rendering, &block)
-    action_all :replace, targets, content, **rendering, &block
+  #   <%= turbo_stream.replace_all clearance, "<div>Morph the dom target</div>", method: :morph %>
+  def replace_all(targets, content = nil, method: nil, **rendering, &block)
+    action_all :replace, targets, content, method: method, **rendering, &block
   end
 
   # Insert the <tt>content</tt> passed in, a rendering result determined by the <tt>rendering</tt> keyword arguments,
@@ -137,8 +157,9 @@ class Turbo::Streams::TagBuilder
   #   <%= turbo_stream.update "clearance_5" do %>
   #     Update the content of the dom target identified by clearance_5
   #   <% end %>
-  def update(target, content = nil, **rendering, &block)
-    action :update, target, content, **rendering, &block
+  #   <%= turbo_stream.update clearance, "<div>Morph the dom target</div>", method: :morph %>
+  def update(target, content = nil, method: nil, **rendering, &block)
+    action :update, target, content, method: method, **rendering, &block
   end
 
   # Update the <tt>targets</tt> in the dom with either the <tt>content</tt> passed in or a rendering result determined
@@ -150,8 +171,9 @@ class Turbo::Streams::TagBuilder
   #   <%= turbo_stream.update_all "clearance_item" do %>
   #     Update the content of the dom target identified by the class clearance_item
   #   <% end %>
-  def update_all(targets, content = nil, **rendering, &block)
-    action_all :update, targets, content, **rendering, &block
+  #   <%= turbo_stream.update_all clearance, "<div>Morph the dom target</div>", method: :morph %>
+  def update_all(targets, content = nil, method: nil, **rendering, &block)
+    action_all :update, targets, content, method: method, **rendering, &block
   end
 
   # Append to the target in the dom identified with <tt>target</tt> either the <tt>content</tt> passed in or a
@@ -210,23 +232,37 @@ class Turbo::Streams::TagBuilder
     action_all :prepend, targets, content, **rendering, &block
   end
 
+  # Creates a `turbo-stream` tag with an `[action="refresh"`] attribute and a
+  # `[request-id]` attribute that defaults to `Turbo.current_request_id`:
+  #
+  #   turbo_stream.refresh
+  #   # => <turbo-stream action="refresh" request-id="ef083d55-7516-41b1-ad28-16f553399c6a"></turbo-stream>
+  #
+  #   turbo_stream.refresh request_id: "abc123"
+  #   # => <turbo-stream action="refresh" request-id="abc123"></turbo-stream>
+  def refresh(...)
+    turbo_stream_refresh_tag(...)
+  end
+
   # Send an action of the type <tt>name</tt> to <tt>target</tt>. Options described in the concrete methods.
-  def action(name, target, content = nil, allow_inferred_rendering: true, **rendering, &block)
+  def action(name, target, content = nil, method: nil, allow_inferred_rendering: true, **rendering, &block)
     template = render_template(target, content, allow_inferred_rendering: allow_inferred_rendering, **rendering, &block)
 
-    turbo_stream_action_tag name, target: target, template: template
+    turbo_stream_action_tag name, target: target, template: template, method: method
   end
 
   # Send an action of the type <tt>name</tt> to <tt>targets</tt>. Options described in the concrete methods.
-  def action_all(name, targets, content = nil, allow_inferred_rendering: true, **rendering, &block)
+  def action_all(name, targets, content = nil, method: nil, allow_inferred_rendering: true, **rendering, &block)
     template = render_template(targets, content, allow_inferred_rendering: allow_inferred_rendering, **rendering, &block)
 
-    turbo_stream_action_tag name, targets: targets, template: template
+    turbo_stream_action_tag name, targets: targets, template: template, method: method
   end
 
   private
     def render_template(target, content = nil, allow_inferred_rendering: true, **rendering, &block)
       case
+      when target.respond_to?(:render_in) && content.nil?
+        target.render_in(@view_context, &block)
       when content.respond_to?(:render_in)
         content.render_in(@view_context, &block)
       when content
@@ -246,4 +282,6 @@ class Turbo::Streams::TagBuilder
         @view_context.render(partial: record, formats: :html)
       end
     end
+
+  ActiveSupport.run_load_hooks :turbo_streams_tag_builder, self
 end

data/app/models/turbo/thread_debouncer.rb

@@ -0,0 +1,28 @@
+# A decorated debouncer that will store instances in the current thread clearing them
+# after the debounced logic triggers.
+class Turbo::ThreadDebouncer
+  delegate :wait, to: :debouncer
+
+  def self.for(key, delay: Turbo::Debouncer::DEFAULT_DELAY)
+    Thread.current[key] ||= new(key, Thread.current, delay: delay)
+  end
+
+  private_class_method :new
+
+  def initialize(key, thread, delay: )
+    @key = key
+    @debouncer = Turbo::Debouncer.new(delay: delay)
+    @thread = thread
+  end
+
+  def debounce
+    debouncer.debounce do
+      yield.tap do
+        thread[key] = nil
+      end
+    end
+  end
+
+  private
+    attr_reader :key, :debouncer, :thread
+end

data/config/routes.rb

@@ -1,6 +1,5 @@
-# FIXME: Offer flag to opt out of these native routes
 Rails.application.routes.draw do
-  get "recede_historical_location"  => "turbo/native/navigation#recede",  as: :turbo_recede_historical_location
-  get "resume_historical_location"  => "turbo/native/navigation#resume",  as: :turbo_resume_historical_location
-  get "refresh_historical_location" => "turbo/native/navigation#refresh", as: :turbo_refresh_historical_location
+  get "recede_historical_location", to: "turbo/native/navigation#recede", as: :turbo_recede_historical_location
+  get "resume_historical_location", to: "turbo/native/navigation#resume", as: :turbo_resume_historical_location
+  get "refresh_historical_location", to: "turbo/native/navigation#refresh", as: :turbo_refresh_historical_location
 end if Turbo.draw_routes

data/lib/install/turbo_with_importmap.rb

@@ -2,4 +2,4 @@ say "Import Turbo"
 append_to_file "app/javascript/application.js", %(import "@hotwired/turbo-rails"\n)
 
 say "Pin Turbo"
-append_to_file "config/importmap.rb", %(pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true\n)
+append_to_file "config/importmap.rb", %(pin "@hotwired/turbo-rails", to: "turbo.min.js"\n)