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

turbo-rails 2.0.0 → 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

checksums.yaml +4 -4
data/README.md +13 -6
data/app/assets/javascripts/turbo.js +38 -36
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 +2 -2
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.
@@ -33,6 +33,6 @@ module Turbo::Frames::FrameRequest
     end
     def turbo_frame_request_id
-      request.headers["Turbo-Frame"]
+      request&.headers["Turbo-Frame"]
     end
 end

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.0"
+  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.0
+  version: 2.0.2
 platform: ruby
 authors:
 - Sam Stephenson
@@ -10,7 +10,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-07 00:00:00.000000000 Z
+date: 2024-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activejob