RubyGems - turbo-rails - Versions diffs - 2.0.1 → 2.0.2 - Mend

turbo-rails 2.0.1 → 2.0.2

Files changed (19) hide show

checksums.yaml +4 -4
data/README.md +13 -6
data/app/assets/javascripts/turbo.js +37 -35
data/app/assets/javascripts/turbo.min.js +6 -6
data/app/assets/javascripts/turbo.min.js.map +1 -1
data/app/channels/turbo/streams/broadcasts.rb +1 -1
data/app/controllers/turbo/frames/frame_request.rb +1 -1
data/app/controllers/turbo/native/navigation.rb +6 -3
data/app/helpers/turbo/drive_helper.rb +17 -18
data/app/helpers/turbo/frames_helper.rb +4 -7
data/app/helpers/turbo/streams/action_helper.rb +4 -1
data/app/helpers/turbo/streams_helper.rb +0 -1
data/app/models/concerns/turbo/broadcastable.rb +89 -15
data/lib/turbo/broadcastable/test_helper.rb +4 -4
data/lib/turbo/engine.rb +1 -0
data/lib/turbo/test_assertions/integration_test_assertions.rb +2 -2
data/lib/turbo/test_assertions.rb +2 -2
data/lib/turbo/version.rb +1 -1
metadata +2 -2

data/app/channels/turbo/streams/broadcasts.rb CHANGED Viewed

@@ -1,4 +1,4 @@
-# Provides the broadcast actions in synchronous and asynchrous form for the <tt>Turbo::StreamsChannel</tt>.
+# Provides the broadcast actions in synchronous and asynchronous form for the <tt>Turbo::StreamsChannel</tt>.
 # See <tt>Turbo::Broadcastable</tt> for the user-facing API that invokes these methods with most of the paperwork filled out already.
 #
 # Can be used directly using something like <tt>Turbo::StreamsChannel.broadcast_remove_to :entries, target: 1</tt>.

data/app/controllers/turbo/frames/frame_request.rb CHANGED Viewed

@@ -5,7 +5,7 @@
 # When that header is detected by the controller, we substitute our own minimal layout in place of the
 # application-supplied layout (since we're only working on an in-page frame, thus can skip the weight of the layout). We
 # use a minimal layout, rather than avoid the layout entirely, so that it's still possible to render content into the
-# <tt>head<tt>.
+# <tt>head</tt>.
 #
 # Accordingly, we ensure that the etag for the page is changed, such that a cache for a minimal-layout request isn't
 # served on a normal request and vice versa.

data/app/controllers/turbo/native/navigation.rb CHANGED Viewed

@@ -15,29 +15,32 @@ module Turbo::Native::Navigation
     request.user_agent.to_s.match?(/Turbo Native/)
   end
-  # Tell the Turbo Native app to dismiss a modal (if presented) or pop a screen off of the navigation stack.
+  # Tell the Turbo Native app to dismiss a modal (if presented) or pop a screen off of the navigation stack. Otherwise redirect to the given URL if Turbo Native is not present.
   def recede_or_redirect_to(url, **options)
     turbo_native_action_or_redirect url, :recede, :to, options
   end
-  # Tell the Turbo Native app to ignore this navigation.
+  # Tell the Turbo Native app to ignore this navigation, otherwise redirect to the given URL if Turbo Native is not present.
   def resume_or_redirect_to(url, **options)
     turbo_native_action_or_redirect url, :resume, :to, options
   end
-  # Tell the Turbo Native app to refresh the current screen.
+  # Tell the Turbo Native app to refresh the current screen, otherwise redirect to the given URL if Turbo Native is not present.
   def refresh_or_redirect_to(url, **options)
     turbo_native_action_or_redirect url, :refresh, :to, options
   end
+  # Same as <tt>recede_or_redirect_to</tt> but redirects to the previous page or provided fallback location if the Turbo Native app is not present.
   def recede_or_redirect_back_or_to(url, **options)
     turbo_native_action_or_redirect url, :recede, :back, options
   end
+  # Same as <tt>resume_or_redirect_to</tt> but redirects to the previous page or provided fallback location if the Turbo Native app is not present.
   def resume_or_redirect_back_or_to(url, **options)
     turbo_native_action_or_redirect url, :resume, :back, options
   end
+  # Same as <tt>refresh_or_redirect_to</tt> but redirects to the previous page or provided fallback location if the Turbo Native app is not present.
   def refresh_or_redirect_back_or_to(url, **options)
     turbo_native_action_or_redirect url, :refresh, :back, options
   end

data/app/helpers/turbo/drive_helper.rb CHANGED Viewed

@@ -1,22 +1,21 @@
+# Helpers to configure Turbo Drive via meta directives. They come in two
+# variants:
+#
+# The recommended option is to include +yield :head+ in the +<head>+ section
+# of the layout. Then you can use the helpers in any view.
+#
+# ==== Example
+#
+#   # app/views/application.html.erb
+#   <html><head><%= yield :head %></head><body><%= yield %></html>
+#
+#   # app/views/trays/index.html.erb
+#   <% turbo_exempts_page_from_cache %>
+#   <p>Page that shouldn't be cached by Turbo</p>
+#
+# Alternatively, you can use the +_tag+ variant of the helpers to only get the
+# HTML for the meta directive.
 module Turbo::DriveHelper
-  # Helpers to configure Turbo Drive via meta directives. They come in two
-  # variants:
-  #
-  # The recommended option is to include +yield :head+ in the +<head>+ section
-  # of the layout. Then you can use the helpers in any view.
-  #
-  # ==== Example
-  #
-  #   # app/views/application.html.erb
-  #   <html><head><%= yield :head %></head><body><%= yield %></html>
-  #
-  #   # app/views/trays/index.html.erb
-  #   <% turbo_exempts_page_from_cache %>
-  #   <p>Page that shouldn't be cached by Turbo</p>
-  #
-  # Alternatively, you can use the +_tag+ variant of the helpers to only get the
-  # HTML for the meta directive.
   # Pages that are more likely than not to be a cache miss can skip turbo cache to avoid visual jitter.
   # Cannot be used along with +turbo_exempts_page_from_preview+.
   def turbo_exempts_page_from_cache

data/app/helpers/turbo/frames_helper.rb CHANGED Viewed

@@ -2,7 +2,7 @@ module Turbo::FramesHelper
   # Returns a frame tag that can either be used simply to encapsulate frame content or as a lazy-loading container that starts empty but
   # fetches the URL supplied in the +src+ attribute.
   #
-  # === Examples
+  # ==== Examples
   #
   #   <%= turbo_frame_tag "tray", src: tray_path(tray) %>
   #   # => <turbo-frame id="tray" src="http://example.com/trays/1"></turbo-frame>
@@ -27,17 +27,14 @@ module Turbo::FramesHelper
   #   <%= turbo_frame_tag [user_id, "tray"], src: tray_path(tray) %>
   #   # => <turbo-frame id="1_tray" src="http://example.com/trays/1"></turbo-frame>
   #
-  # The `turbo_frame_tag` helper will convert the arguments it receives to their
-  # `dom_id` if applicable to easily generate unique ids for Turbo Frames:
+  # The +turbo_frame_tag+ helper will convert the arguments it receives to their
+  # +dom_id+ if applicable to easily generate unique ids for Turbo Frames:
   #
   #   <%= turbo_frame_tag(Article.find(1)) %>
   #   # => <turbo-frame id="article_1"></turbo-frame>
   #
   #   <%= turbo_frame_tag(Article.find(1), "comments") %>
-  #   # => <turbo-frame id="article_1_comments"></turbo-frame>
-  #
-  #   <%= turbo_frame_tag(Article.find(1), Comment.new) %>
-  #   # => <turbo-frame id="article_1_new_comment"></turbo-frame>
+  #   # => <turbo-frame id="comments_article_1"></turbo-frame>
   def turbo_frame_tag(*ids, src: nil, target: nil, **attributes, &block)
     id = ids.first.respond_to?(:to_key) ? ActionView::RecordIdentifier.dom_id(*ids) : ids.join('_')
     src = url_for(src) if src.present?

data/app/helpers/turbo/streams/action_helper.rb CHANGED Viewed

@@ -22,7 +22,6 @@ module Turbo::Streams::ActionHelper
   #   message = Message.find(1)
   #   turbo_stream_action_tag "remove", target: [message, :special]
   #   # => <turbo-stream action="remove" target="special_message_1"></turbo-stream>
-  #
   def turbo_stream_action_tag(action, target: nil, targets: nil, template: nil, **attributes)
     template = action.to_sym.in?(%i[ remove refresh ]) ? "" : tag.template(template.to_s.html_safe)
@@ -35,6 +34,10 @@ module Turbo::Streams::ActionHelper
     end
   end
+  # Creates a `turbo-stream` tag with an `action="refresh"` attribute. Example:
+  #
+  #   turbo_stream_refresh_tag
+  #   # => <turbo-stream action="refresh"></turbo-stream>
   def turbo_stream_refresh_tag(request_id: Turbo.current_request_id, **attributes)
     turbo_stream_action_tag(:refresh, **{ "request-id": request_id }.compact, **attributes)
   end

data/app/helpers/turbo/streams_helper.rb CHANGED Viewed

@@ -48,7 +48,6 @@ module Turbo::StreamsHelper
   # It is also possible to pass additional parameters to the channel by passing them through `data` attributes:
   #
   #   <%= turbo_stream_from "room", channel: RoomChannel, data: {room_name: "room #1"} %>
-  #
   def turbo_stream_from(*streamables, **attributes)
     attributes[:channel] = attributes[:channel]&.to_s || "Turbo::StreamsChannel"
     attributes[:"signed-stream-name"] = Turbo::StreamsChannel.signed_stream_name(streamables)

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

@@ -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,15 +67,74 @@
 #       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 +broadcast_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
+#     broadcast_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 +broadcast_refreshes_to+ method:
+#
+#   class Column < ApplicationRecord
+#     belongs_to :board
+#     broadcast_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
@@ -136,7 +195,17 @@ module Turbo::Broadcastable
     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.
+    # 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
@@ -293,10 +362,15 @@ 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
@@ -315,7 +389,6 @@ module Turbo::Broadcastable
     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)) unless suppressed_turbo_broadcasts?
@@ -356,10 +429,12 @@ 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
@@ -390,7 +465,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
@@ -400,12 +475,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)) 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
@@ -416,7 +491,6 @@ module Turbo::Broadcastable
     Turbo::StreamsChannel.broadcast_render_later_to(*streamables, **broadcast_rendering_with_defaults(rendering)) unless suppressed_turbo_broadcasts?
   end
   private
     def broadcast_target_default
       self.class.broadcast_target_default

data/lib/turbo/broadcastable/test_helper.rb CHANGED Viewed

@@ -11,14 +11,14 @@ module Turbo
       # Asserts that `<turbo-stream>` elements were broadcast over Action Cable
       #
-      # === Arguments
+      # ==== Arguments
       #
       # * <tt>stream_name_or_object</tt> the objects used to generate the
       #   channel Action Cable name, or the name itself
       # * <tt>&block</tt> optional block executed before the
       #   assertion
       #
-      # === Options
+      # ==== Options
       #
       # * <tt>count:</tt> the number of `<turbo-stream>` elements that are
       # expected to be broadcast
@@ -70,7 +70,7 @@ module Turbo
       # Asserts that no `<turbo-stream>` elements were broadcast over Action Cable
       #
-      # === Arguments
+      # ==== Arguments
       #
       # * <tt>stream_name_or_object</tt> the objects used to generate the
       #   channel Action Cable name, or the name itself
@@ -113,7 +113,7 @@ module Turbo
       # Captures any `<turbo-stream>` elements that were broadcast over Action Cable
       #
-      # === Arguments
+      # ==== Arguments
       #
       # * <tt>stream_name_or_object</tt> the objects used to generate the
       #   channel Action Cable name, or the name itself

data/lib/turbo/engine.rb CHANGED Viewed

@@ -84,6 +84,7 @@ module Turbo
         require "turbo/broadcastable/test_helper"
         include Turbo::TestAssertions
+        include Turbo::Broadcastable::TestHelper
       end
       ActiveSupport.on_load(:action_dispatch_integration_test) do

data/lib/turbo/test_assertions/integration_test_assertions.rb CHANGED Viewed

@@ -4,7 +4,7 @@ module Turbo
       # Assert that the Turbo Stream request's response body's HTML contains a
       # `<turbo-stream>` element.
       #
-      # === Options
+      # ==== Options
       #
       # * <tt>:status</tt> [Integer, Symbol] the HTTP response status
       # * <tt>:action</tt> [String] matches the element's <tt>[action]</tt>
@@ -47,7 +47,7 @@ module Turbo
       # Assert that the Turbo Stream request's response body's HTML does not
       # contain a `<turbo-stream>` element.
       #
-      # === Options
+      # ==== Options
       #
       # * <tt>:status</tt> [Integer, Symbol] the HTTP response status
       # * <tt>:action</tt> [String] matches the element's <tt>[action]</tt>

data/lib/turbo/test_assertions.rb CHANGED Viewed

@@ -10,7 +10,7 @@ module Turbo
     # Assert that the rendered fragment of HTML contains a `<turbo-stream>`
     # element.
     #
-    # === Options
+    # ==== Options
     #
     # * <tt>:action</tt> [String] matches the element's <tt>[action]</tt>
     #   attribute
@@ -55,7 +55,7 @@ module Turbo
     # Assert that the rendered fragment of HTML does not contain a `<turbo-stream>`
     # element.
     #
-    # === Options
+    # ==== Options
     #
     # * <tt>:action</tt> [String] matches the element's <tt>[action]</tt>
     #   attribute

data/lib/turbo/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module Turbo
-  VERSION = "2.0.1"
+  VERSION = "2.0.2"
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turbo-rails
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - Sam Stephenson
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-08 00:00:00.000000000 Z
+date: 2024-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob