actionview 7.0.1 → 7.1.1

data/lib/action_view/helpers/asset_tag_helper.rb

@@ -7,8 +7,9 @@ require "action_view/helpers/asset_url_helper"
 require "action_view/helpers/tag_helper"
 
 module ActionView
-  # = Action View Asset Tag Helpers
   module Helpers # :nodoc:
+    # = Action View Asset Tag \Helpers
+    #
     # This module provides methods for generating HTML that links views to assets such
     # as images, JavaScripts, stylesheets, and feeds. These methods do not verify
     # the assets exist before linking to them:
@@ -41,13 +42,14 @@ module ActionView
       # When the Asset Pipeline is enabled, you can pass the name of your manifest as
       # source, and include other JavaScript or CoffeeScript files inside the manifest.
       #
-      # If the server supports Early Hints header links for these assets will be
-      # automatically pushed.
+      # If the server supports HTTP Early Hints, and the +defer+ option is not
+      # enabled, \Rails will push a <tt>103 Early Hints</tt> response that links
+      # to the assets.
       #
       # ==== Options
       #
       # When the last parameter is a hash you can add HTML attributes using that
-      # parameter. The following options are supported:
+      # parameter. This includes but is not limited to the following options:
       #
       # * <tt>:extname</tt>  - Append an extension to the generated URL unless the extension
       #   already exists. This only applies for relative URLs.
@@ -59,6 +61,20 @@ module ActionView
       #   when it is set to true.
       # * <tt>:nonce</tt>  - When set to true, adds an automatic nonce value if
       #   you have Content Security Policy enabled.
+      # * <tt>:async</tt>  - When set to +true+, adds the +async+ HTML
+      #   attribute, allowing the script to be fetched in parallel to be parsed
+      #   and evaluated as soon as possible.
+      # * <tt>:defer</tt>  - When set to +true+, adds the +defer+ HTML
+      #   attribute, which indicates to the browser that the script is meant to
+      #   be executed after the document has been parsed. Additionally, prevents
+      #   sending the Preload Links header.
+      #
+      # Any other specified options will be treated as HTML attributes for the
+      # +script+ tag.
+      #
+      # For more information regarding how the <tt>:async</tt> and <tt>:defer</tt>
+      # options affect the <tt><script></tt> tag, please refer to the
+      # {MDN docs}[https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script].
       #
       # ==== Examples
       #
@@ -86,10 +102,17 @@ module ActionView
       #
       #   javascript_include_tag "http://www.example.com/xmlhr.js", nonce: true
       #   # => <script src="http://www.example.com/xmlhr.js" nonce="..."></script>
+      #
+      #   javascript_include_tag "http://www.example.com/xmlhr.js", async: true
+      #   # => <script src="http://www.example.com/xmlhr.js" async="async"></script>
+      #
+      #   javascript_include_tag "http://www.example.com/xmlhr.js", defer: true
+      #   # => <script src="http://www.example.com/xmlhr.js" defer="defer"></script>
       def javascript_include_tag(*sources)
         options = sources.extract_options!.stringify_keys
         path_options = options.extract!("protocol", "extname", "host", "skip_pipeline").symbolize_keys
         preload_links = []
+        use_preload_links_header = options["preload_links_header"].nil? ? preload_links_header : options.delete("preload_links_header")
         nopush = options["nopush"].nil? ? true : options.delete("nopush")
         crossorigin = options.delete("crossorigin")
         crossorigin = "anonymous" if crossorigin == true
@@ -98,7 +121,7 @@ module ActionView
 
         sources_tags = sources.uniq.map { |source|
           href = path_to_javascript(source, path_options)
-          if preload_links_header && !options["defer"] && href.present? && !href.start_with?("data:")
+          if use_preload_links_header && !options["defer"] && href.present? && !href.start_with?("data:")
             preload_link = "<#{href}>; rel=#{rel}; as=script"
             preload_link += "; crossorigin=#{crossorigin}" unless crossorigin.nil?
             preload_link += "; integrity=#{integrity}" unless integrity.nil?
@@ -115,7 +138,7 @@ module ActionView
           content_tag("script", "", tag_options)
         }.join("\n").html_safe
 
-        if preload_links_header
+        if use_preload_links_header
           send_preload_links_header(preload_links)
         end
 
@@ -130,8 +153,8 @@ module ActionView
       # set <tt>extname: false</tt> in the options.
       # You can modify the link attributes by passing a hash as the last argument.
       #
-      # If the server supports Early Hints header links for these assets will be
-      # automatically pushed.
+      # If the server supports HTTP Early Hints, \Rails will push a <tt>103 Early
+      # Hints</tt> response that links to the assets.
       #
       # ==== Options
       #
@@ -170,6 +193,7 @@ module ActionView
       def stylesheet_link_tag(*sources)
         options = sources.extract_options!.stringify_keys
         path_options = options.extract!("protocol", "extname", "host", "skip_pipeline").symbolize_keys
+        use_preload_links_header = options["preload_links_header"].nil? ? preload_links_header : options.delete("preload_links_header")
         preload_links = []
         crossorigin = options.delete("crossorigin")
         crossorigin = "anonymous" if crossorigin == true
@@ -178,7 +202,7 @@ module ActionView
 
         sources_tags = sources.uniq.map { |source|
           href = path_to_stylesheet(source, path_options)
-          if preload_links_header && href.present? && !href.start_with?("data:")
+          if use_preload_links_header && href.present? && !href.start_with?("data:")
             preload_link = "<#{href}>; rel=preload; as=style"
             preload_link += "; crossorigin=#{crossorigin}" unless crossorigin.nil?
             preload_link += "; integrity=#{integrity}" unless integrity.nil?
@@ -198,7 +222,7 @@ module ActionView
           tag(:link, tag_options)
         }.join("\n").html_safe
 
-        if preload_links_header
+        if use_preload_links_header
           send_preload_links_header(preload_links)
         end
 
@@ -325,16 +349,17 @@ module ActionView
         crossorigin = "anonymous" if crossorigin == true || (crossorigin.blank? && as_type == "font")
         integrity = options[:integrity]
         nopush = options.delete(:nopush) || false
+        rel = mime_type == "module" ? "modulepreload" : "preload"
 
         link_tag = tag.link(**{
-          rel: "preload",
+          rel: rel,
           href: href,
           as: as_type,
           type: mime_type,
           crossorigin: crossorigin
         }.merge!(options.symbolize_keys))
 
-        preload_link = "<#{href}>; rel=preload; as=#{as_type}"
+        preload_link = "<#{href}>; rel=#{rel}; as=#{as_type}"
         preload_link += "; type=#{mime_type}" if mime_type
         preload_link += "; crossorigin=#{crossorigin}" if crossorigin
         preload_link += "; integrity=#{integrity}" if integrity
@@ -395,7 +420,7 @@ module ActionView
         check_for_image_tag_errors(options)
         skip_pipeline = options.delete(:skip_pipeline)
 
-        options[:src] = resolve_image_source(source, skip_pipeline)
+        options[:src] = resolve_asset_source("image", source, skip_pipeline)
 
         if options[:srcset] && !options[:srcset].is_a?(String)
           options[:srcset] = options[:srcset].map do |src_path, size|
@@ -412,11 +437,72 @@ module ActionView
         tag("img", options)
       end
 
+      # Returns an HTML picture tag for the +sources+. If +sources+ is a string,
+      # a single picture tag will be returned. If +sources+ is an array, a picture
+      # tag with nested source tags for each source will be returned. The
+      # +sources+ can be full paths, files that exist in your public images
+      # directory, or Active Storage attachments. Since the picture tag requires
+      # an img tag, the last element you provide will be used for the img tag.
+      # For complete control over the picture tag, a block can be passed, which
+      # will populate the contents of the tag accordingly.
+      #
+      # ==== Options
+      #
+      # When the last parameter is a hash you can add HTML attributes using that
+      # parameter. Apart from all the HTML supported options, the following are supported:
+      #
+      # * <tt>:image</tt> - Hash of options that are passed directly to the +image_tag+ helper.
+      #
+      # ==== Examples
+      #
+      #   picture_tag("picture.webp")
+      #   # => <picture><img src="/images/picture.webp" /></picture>
+      #   picture_tag("gold.png", :image => { :size => "20" })
+      #   # => <picture><img height="20" src="/images/gold.png" width="20" /></picture>
+      #   picture_tag("gold.png", :image => { :size => "45x70" })
+      #   # => <picture><img height="70" src="/images/gold.png" width="45" /></picture>
+      #   picture_tag("picture.webp", "picture.png")
+      #   # => <picture><source srcset="/images/picture.webp" /><source srcset="/images/picture.png" /><img src="/images/picture.png" /></picture>
+      #   picture_tag("picture.webp", "picture.png", :image => { alt: "Image" })
+      #   # => <picture><source srcset="/images/picture.webp" /><source srcset="/images/picture.png" /><img alt="Image" src="/images/picture.png" /></picture>
+      #   picture_tag(["picture.webp", "picture.png"], :image => { alt: "Image" })
+      #   # => <picture><source srcset="/images/picture.webp" /><source srcset="/images/picture.png" /><img alt="Image" src="/images/picture.png" /></picture>
+      #   picture_tag(:class => "my-class") { tag(:source, :srcset => image_path("picture.webp")) + image_tag("picture.png", :alt => "Image") }
+      #   # => <picture class="my-class"><source srcset="/images/picture.webp" /><img alt="Image" src="/images/picture.png" /></picture>
+      #   picture_tag { tag(:source, :srcset => image_path("picture-small.webp"), :media => "(min-width: 600px)") + tag(:source, :srcset => image_path("picture-big.webp")) + image_tag("picture.png", :alt => "Image") }
+      #   # => <picture><source srcset="/images/picture-small.webp" media="(min-width: 600px)" /><source srcset="/images/picture-big.webp" /><img alt="Image" src="/images/picture.png" /></picture>
+      #
+      # Active Storage blobs (images that are uploaded by the users of your app):
+      #
+      #   picture_tag(user.profile_picture)
+      #   # => <picture><img src="/rails/active_storage/blobs/.../profile_picture.webp" /></picture>
+      def picture_tag(*sources, &block)
+        sources.flatten!
+        options = sources.extract_options!.symbolize_keys
+        image_options = options.delete(:image) || {}
+        skip_pipeline = options.delete(:skip_pipeline)
+
+        content_tag("picture", options) do
+          if block.present?
+            capture(&block).html_safe
+          elsif sources.size <= 1
+            image_tag(sources.last, image_options)
+          else
+            source_tags = sources.map do |source|
+              tag("source",
+               srcset: resolve_asset_source("image", source, skip_pipeline),
+               type: Template::Types[File.extname(source)[1..]]&.to_s)
+            end
+            safe_join(source_tags << image_tag(sources.last, image_options))
+          end
+        end
+      end
+
       # Returns an HTML video tag for the +sources+. If +sources+ is a string,
       # a single video tag will be returned. If +sources+ is an array, a video
       # tag with nested source tags for each source will be returned. The
-      # +sources+ can be full paths or files that exist in your public videos
-      # directory.
+      # +sources+ can be full paths, files that exist in your public videos
+      # directory, or Active Storage attachments.
       #
       # ==== Options
       #
@@ -455,6 +541,11 @@ module ActionView
       #   # => <video><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
       #   video_tag(["trailer.ogg", "trailer.flv"], size: "160x120")
       #   # => <video height="120" width="160"><source src="/videos/trailer.ogg" /><source src="/videos/trailer.flv" /></video>
+      #
+      # Active Storage blobs (videos that are uploaded by the users of your app):
+      #
+      #   video_tag(user.intro_video)
+      #   # => <video src="/rails/active_storage/blobs/.../intro_video.mp4"></video>
       def video_tag(*sources)
         options = sources.extract_options!.symbolize_keys
         public_poster_folder = options.delete(:poster_skip_pipeline)
@@ -468,8 +559,8 @@ module ActionView
       # Returns an HTML audio tag for the +sources+. If +sources+ is a string,
       # a single audio tag will be returned. If +sources+ is an array, an audio
       # tag with nested source tags for each source will be returned. The
-      # +sources+ can be full paths or files that exist in your public audios
-      # directory.
+      # +sources+ can be full paths, files that exist in your public audios
+      # directory, or Active Storage attachments.
       #
       # When the last parameter is a hash you can add HTML attributes using that
       # parameter.
@@ -482,6 +573,11 @@ module ActionView
       #   # => <audio autoplay="autoplay" controls="controls" src="/audios/sound.wav"></audio>
       #   audio_tag("sound.wav", "sound.mid")
       #   # => <audio><source src="/audios/sound.wav" /><source src="/audios/sound.mid" /></audio>
+      #
+      # Active Storage blobs (audios that are uploaded by the users of your app):
+      #
+      #   audio_tag(user.name_pronunciation_audio)
+      #   # => <audio src="/rails/active_storage/blobs/.../name_pronunciation_audio.mp3"></audio>
       def audio_tag(*sources)
         multiple_sources_tag_builder("audio", sources)
       end
@@ -496,29 +592,29 @@ module ActionView
 
           if sources.size > 1
             content_tag(type, options) do
-              safe_join sources.map { |source| tag("source", src: send("path_to_#{type}", source, skip_pipeline: skip_pipeline)) }
+              safe_join sources.map { |source| tag("source", src: resolve_asset_source(type, source, skip_pipeline)) }
             end
           else
-            options[:src] = send("path_to_#{type}", sources.first, skip_pipeline: skip_pipeline)
+            options[:src] = resolve_asset_source(type, sources.first, skip_pipeline)
             content_tag(type, nil, options)
           end
         end
 
-        def resolve_image_source(source, skip_pipeline)
+        def resolve_asset_source(asset_type, source, skip_pipeline)
           if source.is_a?(Symbol) || source.is_a?(String)
-            path_to_image(source, skip_pipeline: skip_pipeline)
+            path_to_asset(source, type: asset_type.to_sym, skip_pipeline: skip_pipeline)
           else
             polymorphic_url(source)
           end
         rescue NoMethodError => e
-          raise ArgumentError, "Can't resolve image into URL: #{e}"
+          raise ArgumentError, "Can't resolve #{asset_type} into URL: #{e}"
         end
 
         def extract_dimensions(size)
           size = size.to_s
-          if /\A\d+x\d+\z/.match?(size)
+          if /\A\d+(?:\.\d+)?x\d+(?:\.\d+)?\z/.match?(size)
             size.split("x")
-          elsif /\A\d+\z/.match?(size)
+          elsif /\A\d+(?:\.\d+)?\z/.match?(size)
             [size, size]
           end
         end
@@ -539,40 +635,29 @@ module ActionView
           end
         end
 
-        MAX_HEADER_SIZE = 8_000 # Some HTTP client and proxies have a 8kiB header limit
+        # Some HTTP client and proxies have a 4kiB header limit, but more importantly
+        # including preload links has diminishing returns so it's best to not go overboard
+        MAX_HEADER_SIZE = 1_000 # :nodoc:
+
         def send_preload_links_header(preload_links, max_header_size: MAX_HEADER_SIZE)
           return if preload_links.empty?
-          return if respond_to?(:response) && response.sending?
+          response_present = respond_to?(:response) && response
+          return if response_present && response.sending?
 
           if respond_to?(:request) && request
             request.send_early_hints("Link" => preload_links.join("\n"))
           end
 
-          if respond_to?(:response) && response
-            header = response.headers["Link"]
-            header = header ? header.dup : +""
-
-            # rindex count characters not bytes, but we assume non-ascii characters
-            # are rare in urls, and we have a 192 bytes margin.
-            last_line_offset = header.rindex("\n")
-            last_line_size = if last_line_offset
-              header.bytesize - last_line_offset
-            else
-              header.bytesize
-            end
-
+          if response_present
+            header = +response.headers["Link"].to_s
             preload_links.each do |link|
-              if link.bytesize + last_line_size + 1 < max_header_size
-                unless header.empty?
-                  header << ","
-                  last_line_size += 1
-                end
+              break if header.bytesize + link.bytesize > max_header_size
+
+              if header.empty?
+                header << link
               else
-                header << "\n"
-                last_line_size = 0
+                header << "," << link
               end
-              header << link
-              last_line_size += link.bytesize
             end
 
             response.headers["Link"] = header

data/lib/action_view/helpers/asset_url_helper.rb

@@ -3,8 +3,9 @@
 require "zlib"
 
 module ActionView
-  # = Action View Asset URL Helpers
   module Helpers # :nodoc:
+    # = Action View Asset URL \Helpers
+    #
     # This module provides methods for generating asset paths and
     # URLs.
     #
@@ -16,8 +17,8 @@ module ActionView
     #
     # === Using asset hosts
     #
-    # By default, Rails links to these assets on the current host in the public
-    # folder, but you can direct Rails to link to assets from a dedicated asset
+    # By default, \Rails links to these assets on the current host in the public
+    # folder, but you can direct \Rails to link to assets from a dedicated asset
     # server by setting <tt>ActionController::Base.asset_host</tt> in the application
     # configuration, typically in <tt>config/environments/production.rb</tt>.
     # For example, you'd define <tt>assets.example.com</tt> to be your asset
@@ -196,7 +197,7 @@ module ActionView
           source = "#{source}#{extname}"
         end
 
-        if source[0] != ?/
+        unless source.start_with?(?/)
           if options[:skip_pipeline]
             source = public_compute_asset_path(source, options)
           else
@@ -219,7 +220,7 @@ module ActionView
 
       # Computes the full URL to an asset in the public directory. This
       # will use +asset_path+ internally, so most of their behaviors
-      # will be the same. If :host options is set, it overwrites global
+      # will be the same. If +:host+ options is set, it overwrites global
       # +config.action_controller.asset_host+ setting.
       #
       # All other options provided are forwarded to +asset_path+ call.
@@ -324,7 +325,7 @@ module ActionView
 
       # Computes the full URL to a JavaScript asset in the public javascripts directory.
       # This will use +javascript_path+ internally, so most of their behaviors will be the same.
-      # Since +javascript_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +javascript_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   javascript_url "js/xmlhr.js", host: "http://stage.example.com" # => http://stage.example.com/assets/js/xmlhr.js
@@ -351,7 +352,7 @@ module ActionView
 
       # Computes the full URL to a stylesheet asset in the public stylesheets directory.
       # This will use +stylesheet_path+ internally, so most of their behaviors will be the same.
-      # Since +stylesheet_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +stylesheet_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   stylesheet_url "css/style.css", host: "http://stage.example.com" # => http://stage.example.com/assets/css/style.css
@@ -372,7 +373,7 @@ module ActionView
       #   image_path("http://www.example.com/img/edit.png")          # => "http://www.example.com/img/edit.png"
       #
       # If you have images as application resources this method may conflict with their named routes.
-      # The alias +path_to_image+ is provided to avoid that. Rails uses the alias internally, and
+      # The alias +path_to_image+ is provided to avoid that. \Rails uses the alias internally, and
       # plugin authors are encouraged to do so.
       def image_path(source, options = {})
         path_to_asset(source, { type: :image }.merge!(options))
@@ -381,7 +382,7 @@ module ActionView
 
       # Computes the full URL to an image asset.
       # This will use +image_path+ internally, so most of their behaviors will be the same.
-      # Since +image_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +image_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   image_url "edit.png", host: "http://stage.example.com" # => http://stage.example.com/assets/edit.png
@@ -407,7 +408,7 @@ module ActionView
 
       # Computes the full URL to a video asset in the public videos directory.
       # This will use +video_path+ internally, so most of their behaviors will be the same.
-      # Since +video_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +video_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   video_url "hd.avi", host: "http://stage.example.com" # => http://stage.example.com/videos/hd.avi
@@ -433,7 +434,7 @@ module ActionView
 
       # Computes the full URL to an audio asset in the public audios directory.
       # This will use +audio_path+ internally, so most of their behaviors will be the same.
-      # Since +audio_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +audio_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   audio_url "horse.wav", host: "http://stage.example.com" # => http://stage.example.com/audios/horse.wav
@@ -458,7 +459,7 @@ module ActionView
 
       # Computes the full URL to a font asset.
       # This will use +font_path+ internally, so most of their behaviors will be the same.
-      # Since +font_url+ is based on +asset_url+ method you can set :host options. If :host
+      # Since +font_url+ is based on +asset_url+ method you can set +:host+ options. If +:host+
       # options is set, it overwrites global +config.action_controller.asset_host+ setting.
       #
       #   font_url "font.ttf", host: "http://stage.example.com" # => http://stage.example.com/fonts/font.ttf

data/lib/action_view/helpers/atom_feed_helper.rb

@@ -3,8 +3,8 @@
 require "set"
 
 module ActionView
-  # = Action View Atom Feed Helpers
   module Helpers # :nodoc:
+    # = Action View Atom Feed \Helpers
     module AtomFeedHelper
       # Adds easy defaults to writing Atom feeds with the Builder template engine (this does not work on ERB or any other
       # template languages).
@@ -82,9 +82,9 @@ module ActionView
       #     end
       #
       # The Atom spec defines five elements (content rights title subtitle
-      # summary) which may directly contain xhtml content if type: 'xhtml'
+      # summary) which may directly contain XHTML content if type: 'xhtml'
       # is specified as an attribute. If so, this helper will take care of
-      # the enclosing div and xhtml namespace declaration. Example usage:
+      # the enclosing div and XHTML namespace declaration. Example usage:
       #
       #    entry.summary type: 'xhtml' do |xhtml|
       #      xhtml.p pluralize(order.line_items.count, "line item")
@@ -102,7 +102,7 @@ module ActionView
           options[:schema_date] = "2005" # The Atom spec copyright date
         end
 
-        xml = options.delete(:xml) || eval("xml", block.binding)
+        xml = options.delete(:xml) || block.binding.local_variable_get(:xml)
         xml.instruct!
         if options[:instruct]
           options[:instruct].each do |target, attrs|
@@ -134,7 +134,7 @@ module ActionView
         end
 
         private
-          # Delegate to xml builder, first wrapping the element in an xhtml
+          # Delegate to XML Builder, first wrapping the element in an XHTML
           # namespaced div element if the method and arguments indicate
           # that an xhtml_block? is desired.
           def method_missing(method, *arguments, &block)

data/lib/action_view/helpers/cache_helper.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module ActionView
-  # = Action View Cache Helper
   module Helpers # :nodoc:
+    # = Action View Cache \Helpers
     module CacheHelper
       class UncacheableFragmentError < StandardError; end
 
@@ -281,14 +281,8 @@ module ActionView
         controller.read_fragment(name, options)
       end
 
-      def write_fragment_for(name, options)
-        pos = output_buffer.length
-        yield
-        output_safe = output_buffer.html_safe?
-        fragment = output_buffer.slice!(pos..-1)
-        if output_safe
-          self.output_buffer = output_buffer.class.new(output_buffer)
-        end
+      def write_fragment_for(name, options, &block)
+        fragment = output_buffer.capture(&block)
         controller.write_fragment(name, fragment, options)
       end
 

data/lib/action_view/helpers/capture_helper.rb

@@ -3,18 +3,22 @@
 require "active_support/core_ext/string/output_safety"
 
 module ActionView
-  # = Action View Capture Helper
   module Helpers # :nodoc:
-    # CaptureHelper exposes methods to let you extract generated markup which
+    # = Action View Capture \Helpers
+    #
+    # \CaptureHelper exposes methods to let you extract generated markup which
     # can be used in other parts of a template or layout file.
     #
-    # It provides a method to capture blocks into variables through capture and
-    # a way to capture a block of markup for use in a layout through {content_for}[rdoc-ref:ActionView::Helpers::CaptureHelper#content_for].
+    # It provides a method to capture blocks into variables through #capture and
+    # a way to capture a block of markup for use in a layout through #content_for.
+    #
+    # As well as provides a method when using streaming responses through #provide.
+    # See ActionController::Streaming for more information.
     module CaptureHelper
-      # The capture method extracts part of a template as a String object.
+      # The capture method extracts part of a template as a string object.
       # You can then use this object anywhere in your templates, layout, or helpers.
       #
-      # The capture method can be used in ERB templates...
+      # The capture method can be used in \ERB templates...
       #
       #   <% @greeting = capture do %>
       #     Welcome to my shiny new web page!  The date and time is
@@ -40,11 +44,18 @@ module ActionView
       #
       #   @greeting # => "Welcome to my shiny new web page! The date and time is 2018-09-06 11:09:16 -0500"
       #
-      def capture(*args)
+      def capture(*args, &block)
         value = nil
-        buffer = with_output_buffer { value = yield(*args) }
-        if (string = buffer.presence || value) && string.is_a?(String)
-          ERB::Util.html_escape string
+        @output_buffer ||= ActionView::OutputBuffer.new
+        buffer = @output_buffer.capture { value = yield(*args) }
+
+        case string = buffer.presence || value
+        when OutputBuffer
+          string.to_s
+        when ActiveSupport::SafeBuffer
+          string
+        when String
+          ERB::Util.html_escape(string)
         end
       end
 
@@ -121,7 +132,7 @@ module ActionView
       #     <li><%= link_to 'Home', action: 'index' %></li>
       #   <% end %>
       #
-      #  And in another place:
+      # And in another place:
       #
       #   <% content_for :navigation do %>
       #     <li><%= link_to 'Login', action: 'login' %></li>
@@ -137,7 +148,7 @@ module ActionView
       #     <li><%= link_to 'Home', action: 'index' %></li>
       #   <% end %>
       #
-      #   <%#  Add some other content, or use a different template: %>
+      #   <%# Add some other content, or use a different template: %>
       #
       #   <% content_for :navigation, flush: true do %>
       #     <li><%= link_to 'Login', action: 'login' %></li>
@@ -172,6 +183,8 @@ module ActionView
       # concatenate several times to the same buffer when rendering a given
       # template, you should use +content_for+, if not, use +provide+ to tell
       # the layout to stop looking for more contents.
+      #
+      # See ActionController::Streaming for more information.
       def provide(name, content = nil, &block)
         content = capture(&block) if block_given?
         result = @view_flow.append!(name, content) if content
@@ -179,6 +192,7 @@ module ActionView
       end
 
       # <tt>content_for?</tt> checks whether any content has been captured yet using <tt>content_for</tt>.
+      #
       # Useful to render parts of your layout differently based on what is in your views.
       #
       #   <%# This is the layout %>