actionview 7.0.8.7 → 7.2.2.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,22 @@ 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.
+      # * <tt>:nopush</tt>  - Specify if the use of server push is not desired
+      #   for the script. Defaults to +true+.
+      #
+      # 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 +104,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 +123,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 +140,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 +155,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
       #
@@ -143,6 +168,10 @@ module ActionView
       #   that path.
       # * <tt>:skip_pipeline</tt>  - This option is used to bypass the asset pipeline
       #   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>:nopush</tt>  - Specify if the use of server push is not desired
+      #   for the stylesheet. Defaults to +true+.
       #
       # ==== Examples
       #
@@ -167,9 +196,13 @@ module ActionView
       #   stylesheet_link_tag "random.styles", "/css/stylish"
       #   # => <link href="/assets/random.styles" rel="stylesheet" />
       #   #    <link href="/css/stylish.css" rel="stylesheet" />
+      #
+      #   stylesheet_link_tag "style", nonce: true
+      #   # => <link href="/assets/style.css" rel="stylesheet" nonce="..." />
       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 +211,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?
@@ -190,6 +223,9 @@ module ActionView
             "crossorigin" => crossorigin,
             "href" => href
           }.merge!(options)
+          if tag_options["nonce"] == true
+            tag_options["nonce"] = content_security_policy_nonce
+          end
 
           if apply_stylesheet_media_default && tag_options["media"].blank?
             tag_options["media"] = "screen"
@@ -198,7 +234,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
 
@@ -327,13 +363,13 @@ module ActionView
         nopush = options.delete(:nopush) || false
         rel = mime_type == "module" ? "modulepreload" : "preload"
 
-        link_tag = tag.link(**{
+        link_tag = tag.link(
           rel: rel,
           href: href,
           as: as_type,
           type: mime_type,
-          crossorigin: crossorigin
-        }.merge!(options.symbolize_keys))
+          crossorigin: crossorigin,
+          **options.symbolize_keys)
 
         preload_link = "<#{href}>; rel=#{rel}; as=#{as_type}"
         preload_link += "; type=#{mime_type}" if mime_type
@@ -354,8 +390,8 @@ module ActionView
       # You can add HTML attributes using the +options+. The +options+ supports
       # additional keys for convenience and conformance:
       #
-      # * <tt>:size</tt> - Supplied as "{Width}x{Height}" or "{Number}", so "30x45" becomes
-      #   width="30" and height="45", and "50" becomes width="50" and height="50".
+      # * <tt>:size</tt> - Supplied as <tt>"#{width}x#{height}"</tt> or <tt>"#{number}"</tt>, so <tt>"30x45"</tt> becomes
+      #   <tt>width="30" height="45"</tt>, and <tt>"50"</tt> becomes <tt>width="50" height="50"</tt>.
       #   <tt>:size</tt> will be ignored if the value is not in the correct format.
       # * <tt>:srcset</tt> - If supplied as a hash or array of <tt>[source, descriptor]</tt>
       #   pairs, each image path will be expanded before the list is formatted as a string.
@@ -396,7 +432,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|
@@ -413,11 +449,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
       #
@@ -426,8 +523,8 @@ module ActionView
       #
       # * <tt>:poster</tt> - Set an image (like a screenshot) to be shown
       #   before the video loads. The path is calculated like the +src+ of +image_tag+.
-      # * <tt>:size</tt> - Supplied as "{Width}x{Height}" or "{Number}", so "30x45" becomes
-      #   width="30" and height="45", and "50" becomes width="50" and height="50".
+      # * <tt>:size</tt> - Supplied as <tt>"#{width}x#{height}"</tt> or <tt>"#{number}"</tt>, so <tt>"30x45"</tt> becomes
+      #   <tt>width="30" height="45"</tt>, and <tt>"50"</tt> becomes <tt>width="50" height="50"</tt>.
       #   <tt>:size</tt> will be ignored if the value is not in the correct format.
       # * <tt>:poster_skip_pipeline</tt> will bypass the asset pipeline when using
       #   the <tt>:poster</tt> option instead using an asset in the public folder.
@@ -456,6 +553,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)
@@ -469,8 +571,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.
@@ -483,6 +585,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
@@ -497,29 +604,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+|\d+.\d+)x(\d+|\d+.\d+)\z/.match?(size)
+          if /\A\d+(?:\.\d+)?x\d+(?:\.\d+)?\z/.match?(size)
             size.split("x")
-          elsif /\A(\d+|\d+.\d+)\z/.match?(size)
+          elsif /\A\d+(?:\.\d+)?\z/.match?(size)
             [size, size]
           end
         end
@@ -540,43 +647,32 @@ 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"))
+            request.send_early_hints("link" => preload_links.join(","))
           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
+            response.headers["link"] = header
           end
         end
     end

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

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
 
@@ -76,11 +76,11 @@ module ActionView
       #   render 'comments/comments'
       #   render('comments/comments')
       #
-      #   render "header" translates to render("comments/header")
+      #   render "header"        # translates to render("comments/header")
       #
-      #   render(@topic)         translates to render("topics/topic")
-      #   render(topics)         translates to render("topics/topic")
-      #   render(message.topics) translates to render("topics/topic")
+      #   render(@topic)         # translates to render("topics/topic")
+      #   render(topics)         # translates to render("topics/topic")
+      #   render(message.topics) # translates to render("topics/topic")
       #
       # It's not possible to derive all render calls like that, though.
       # Here are a few examples of things that can't be derived:
@@ -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,24 @@ 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) }
+
+        string = if @output_buffer.equal?(value)
+          buffer
+        else
+          buffer.presence || value
+        end
+
+        case string
+        when OutputBuffer
+          string.to_s
+        when ActiveSupport::SafeBuffer
+          string
+        when String
+          ERB::Util.html_escape(string)
         end
       end
 
@@ -172,6 +189,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 +198,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 %>