turbo-rails 1.5.0 → 2.0.2

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

@@ -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>.
@@ -33,9 +33,14 @@ module Turbo::Streams::Broadcasts
     broadcast_action_to(*streamables, action: :prepend, **opts)
   end
 
-  def broadcast_action_to(*streamables, action:, target: nil, targets: nil, **rendering)
+  def broadcast_refresh_to(*streamables, **opts)
+    broadcast_stream_to(*streamables, content: turbo_stream_refresh_tag)
+  end
+
+  def broadcast_action_to(*streamables, action:, target: nil, targets: nil, attributes: {}, **rendering)
     broadcast_stream_to(*streamables, content: turbo_stream_action_tag(action, target: target, targets: targets, template:
-      rendering.delete(:content) || rendering.delete(:html) || (rendering.any? ? render_format(:html, **rendering) : nil)
+      rendering.delete(:content) || rendering.delete(:html) || (rendering[:render] != false && rendering.any? ? render_format(:html, **rendering) : nil),
+      **attributes
     ))
   end
 
@@ -63,9 +68,15 @@ module Turbo::Streams::Broadcasts
     broadcast_action_later_to(*streamables, action: :prepend, **opts)
   end
 
-  def broadcast_action_later_to(*streamables, action:, target: nil, targets: nil, **rendering)
+  def broadcast_refresh_later_to(*streamables, request_id: Turbo.current_request_id, **opts)
+    refresh_debouncer_for(*streamables, request_id: request_id).debounce do
+      Turbo::Streams::BroadcastStreamJob.perform_later stream_name_from(streamables), content: turbo_stream_refresh_tag(request_id: request_id, **opts)
+    end
+  end
+
+  def broadcast_action_later_to(*streamables, action:, target: nil, targets: nil, attributes: {}, **rendering)
     Turbo::Streams::ActionBroadcastJob.perform_later \
-      stream_name_from(streamables), action: action, target: target, targets: targets, **rendering
+      stream_name_from(streamables), action: action, target: target, targets: targets, attributes: attributes, **rendering
   end
 
   def broadcast_render_to(*streamables, **rendering)
@@ -80,6 +91,9 @@ module Turbo::Streams::Broadcasts
     ActionCable.server.broadcast stream_name_from(streamables), content
   end
 
+  def refresh_debouncer_for(*streamables, request_id: nil) # :nodoc:
+    Turbo::ThreadDebouncer.for("turbo-refresh-debouncer-#{stream_name_from(streamables.including(request_id))}")
+  end
 
   private
     def render_format(format, **rendering)

data/app/controllers/concerns/turbo/request_id_tracking.rb

@@ -0,0 +1,12 @@
+module Turbo::RequestIdTracking
+  extend ActiveSupport::Concern
+
+  included do
+    around_action :turbo_tracking_request_id
+  end
+
+  private
+    def turbo_tracking_request_id(&block)
+      Turbo.with_request_id(request.headers["X-Turbo-Request-Id"], &block)
+    end
+end

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

@@ -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

@@ -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

@@ -1,29 +1,87 @@
+# 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
-  # Note: These helpers require a +yield :head+ provision in the layout.
-  #
-  # ==== 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>
-
   # 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
-    provide :head, tag.meta(name: "turbo-cache-control", content: "no-cache")
+    provide :head, turbo_exempts_page_from_cache_tag
+  end
+
+  # See +turbo_exempts_page_from_cache+.
+  def turbo_exempts_page_from_cache_tag
+    tag.meta(name: "turbo-cache-control", content: "no-cache")
   end
 
   # Specify that a cached version of the page should not be shown as a preview during an application visit.
   # Cannot be used along with +turbo_exempts_page_from_cache+.
   def turbo_exempts_page_from_preview
-    provide :head, tag.meta(name: "turbo-cache-control", content: "no-preview")
+    provide :head, turbo_exempts_page_from_preview_tag
+  end
+
+  # See +turbo_exempts_page_from_preview+.
+  def turbo_exempts_page_from_preview_tag
+    tag.meta(name: "turbo-cache-control", content: "no-preview")
   end
 
   # Force the page, when loaded by Turbo, to be cause a full page reload.
   def turbo_page_requires_reload
-    provide :head, tag.meta(name: "turbo-visit-control", content: "reload")
+    provide :head, turbo_page_requires_reload_tag
+  end
+
+  # See +turbo_page_requires_reload+.
+  def turbo_page_requires_reload_tag
+    tag.meta(name: "turbo-visit-control", content: "reload")
+  end
+
+  # Configure how to handle page refreshes. A page refresh happens when
+  # Turbo loads the current page again with a *replace* visit:
+  #
+  # === Parameters:
+  #
+  # * <tt>method</tt> - Method to update the +<body>+ of the page
+  #   during a page refresh. It can be one of:
+  #   * +replace:+: Replaces the existing +<body>+ with the new one. This is the
+  #   default behavior.
+  #   * +morph:+: Morphs the existing +<body>+ into the new one.
+  #
+  # * <tt>scroll</tt> - Controls the scroll behavior when a page refresh happens. It
+  #   can be one of:
+  #   * +reset:+: Resets scroll to the top, left corner. This is the default.
+  #   * +preserve:+: Keeps the scroll.
+  #
+  # === Example Usage:
+  #
+  #   turbo_refreshes_with(method: :morph, scroll: :preserve)
+  def turbo_refreshes_with(method: :replace, scroll: :reset)
+    provide :head, turbo_refresh_method_tag(method)
+    provide :head, turbo_refresh_scroll_tag(scroll)
+  end
+
+  # Configure method to perform page refreshes. See +turbo_refreshes_with+.
+  def turbo_refresh_method_tag(method = :replace)
+    raise ArgumentError, "Invalid refresh option '#{method}'" unless method.in?(%i[ replace morph ])
+    tag.meta(name: "turbo-refresh-method", content: method)
+  end
+
+  # Configure scroll strategy for page refreshes. See +turbo_refreshes_with+.
+  def turbo_refresh_scroll_tag(scroll = :reset)
+    raise ArgumentError, "Invalid scroll option '#{scroll}'" unless scroll.in?(%i[ reset preserve ])
+    tag.meta(name: "turbo-refresh-scroll", content: scroll)
   end
 end
+

data/app/helpers/turbo/frames_helper.rb

@@ -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>
@@ -24,19 +24,19 @@ module Turbo::FramesHelper
   #   <% end %>
   #   # => <turbo-frame id="tray"><div>My tray frame!</div></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:
+  #   <%= 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:
   #
   #   <%= 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.first
+    id = ids.first.respond_to?(:to_key) ? ActionView::RecordIdentifier.dom_id(*ids) : ids.join('_')
     src = url_for(src) if src.present?
 
     tag.turbo_frame(**attributes.merge(id: id, src: src, target: target).compact, &block)

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

@@ -22,9 +22,8 @@ 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 == :remove ? "" : tag.template(template.to_s.html_safe)
+    template = action.to_sym.in?(%i[ remove refresh ]) ? "" : tag.template(template.to_s.html_safe)
 
     if target = convert_to_turbo_stream_dom_id(target)
       tag.turbo_stream(template, **attributes, action: action, target: target)
@@ -35,6 +34,14 @@ 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
+
   private
     def convert_to_turbo_stream_dom_id(target, include_selector: false)
       if Array(target).any? { |value| value.respond_to?(:to_key) }

data/app/helpers/turbo/streams_helper.rb

@@ -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/javascript/turbo/index.js

@@ -8,4 +8,6 @@ export { cable }
 
 import { encodeMethodIntoRequestBody } from "./fetch_requests"
 
+window.Turbo = Turbo
+
 addEventListener("turbo:before-fetch-request", encodeMethodIntoRequestBody)

data/app/jobs/turbo/streams/action_broadcast_job.rb

@@ -2,7 +2,7 @@
 class Turbo::Streams::ActionBroadcastJob < ActiveJob::Base
   discard_on ActiveJob::DeserializationError
   
-  def perform(stream, action:, target:, **rendering)
-    Turbo::StreamsChannel.broadcast_action_to stream, action: action, target: target, **rendering
+  def perform(stream, action:, target:, attributes: {}, **rendering)
+    Turbo::StreamsChannel.broadcast_action_to stream, action: action, target: target, attributes: attributes, **rendering
   end
 end

data/app/jobs/turbo/streams/broadcast_job.rb

@@ -2,7 +2,7 @@
 # turbo stream templates.
 class Turbo::Streams::BroadcastJob < ActiveJob::Base
   discard_on ActiveJob::DeserializationError
-  
+
   def perform(stream, **rendering)
     Turbo::StreamsChannel.broadcast_render_to stream, **rendering
   end

data/app/jobs/turbo/streams/broadcast_stream_job.rb

@@ -0,0 +1,7 @@
+class Turbo::Streams::BroadcastStreamJob < ActiveJob::Base
+  discard_on ActiveJob::DeserializationError
+
+  def perform(stream, content:)
+    Turbo::StreamsChannel.broadcast_stream_to(stream, content: content)
+  end
+end