actionview 7.1.5.2 → 8.1.2.1

data/lib/action_view/helpers/number_helper.rb

@@ -26,6 +26,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_phone.
       #
+      #   number_to_phone("1234567890")         # => "123-456-7890"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -42,6 +44,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_currency.
       #
+      #   number_to_currency("1234")               # => "$1234.00"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -54,6 +58,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_percentage.
       #
+      #   number_to_percentage("99")               # => "99.000%"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -66,6 +72,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_delimited.
       #
+      #   number_with_delimiter("1234")               # => "1,234"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -78,6 +86,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_rounded.
       #
+      #   number_with_precision("1234")               # => "1234.000"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -90,6 +100,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_human_size.
       #
+      #   number_to_human_size("1234")               # => "1.21 KB"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #
@@ -102,6 +114,8 @@ module ActionView
 
       # Delegates to ActiveSupport::NumberHelper#number_to_human.
       #
+      #   number_to_human("1234")               # => "1.23 Thousand"
+      #
       # Additionally, supports a +:raise+ option that will cause
       # InvalidNumberError to be raised if +number+ is not a valid number:
       #

data/lib/action_view/helpers/output_safety_helper.rb

@@ -24,11 +24,11 @@ module ActionView # :nodoc:
       # the supplied separator, are HTML escaped unless they are HTML
       # safe, and the returned string is marked as HTML safe.
       #
-      #   safe_join([raw("<p>foo</p>"), "<p>bar</p>"], "<br />")
-      #   # => "<p>foo</p>&lt;br /&gt;&lt;p&gt;bar&lt;/p&gt;"
+      #   safe_join([tag.p("foo"), "<p>bar</p>"], "<br>")
+      #   # => "<p>foo</p>&lt;br&gt;&lt;p&gt;bar&lt;/p&gt;"
       #
-      #   safe_join([raw("<p>foo</p>"), raw("<p>bar</p>")], raw("<br />"))
-      #   # => "<p>foo</p><br /><p>bar</p>"
+      #   safe_join([tag.p("foo"), tag.p("bar")], tag.br)
+      #   # => "<p>foo</p><br><p>bar</p>"
       #
       def safe_join(array, sep = $,)
         sep = ERB::Util.unwrapped_html_escape(sep)
@@ -38,8 +38,7 @@ module ActionView # :nodoc:
 
       # Converts the array to a comma-separated sentence where the last element is
       # joined by the connector word. This is the html_safe-aware version of
-      # ActiveSupport's {Array#to_sentence}[https://api.rubyonrails.org/classes/Array.html#method-i-to_sentence].
-      #
+      # ActiveSupport's Array#to_sentence.
       def to_sentence(array, options = {})
         options.assert_valid_keys(:words_connector, :two_words_connector, :last_word_connector, :locale)
 

data/lib/action_view/helpers/rendering_helper.rb

@@ -1,32 +1,140 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionView
   module Helpers # :nodoc:
-    # = Action View \Rendering \Helpers
+    # # Action View Rendering Helpers
     #
-    # Implements methods that allow rendering from a view context.
-    # In order to use this module, all you need is to implement
-    # view_renderer that returns an ActionView::Renderer object.
+    # Implements methods that allow rendering from a view context. In order to use
+    # this module, all you need is to implement view_renderer that returns an
+    # ActionView::Renderer object.
     module RenderingHelper
-      # Returns the result of a render that's dictated by the options hash. The primary options are:
+      # Renders a template and returns the result.
+      #
+      # Pass the template to render as the first argument. This is shorthand
+      # syntax for partial rendering, so the template filename should be
+      # prefixed with an underscore. The partial renderer looks for the partial
+      # template in the directory of the calling template first.
+      #
+      #     <% # app/views/posts/new.html.erb %>
+      #     <%= render "form" %>
+      #     # => renders app/views/posts/_form.html.erb
+      #
+      # Use the complete view path to render a partial from another directory.
+      #
+      #     <% # app/views/posts/show.html.erb %>
+      #     <%= render "comments/form" %>
+      #     # => renders app/views/comments/_form.html.erb
+      #
+      # Without the rendering mode, the second argument can be a Hash of local
+      # variable assignments for the template.
+      #
+      #     <% # app/views/posts/new.html.erb %>
+      #     <%= render "form", post: Post.new %>
+      #     # => renders app/views/posts/_form.html.erb
+      #
+      # If the first argument responds to `render_in`, the template will be rendered
+      # by calling `render_in` with the current view context.
+      #
+      #     class Greeting
+      #       def render_in(view_context)
+      #         view_context.render html: "<h1>Hello, World</h1>"
+      #       end
+      #
+      #       def format
+      #         :html
+      #       end
+      #     end
+      #
+      #     <%= render Greeting.new %>
+      #     # => "<h1>Hello, World</h1>"
+      #
+      # #### Rendering Mode
+      #
+      # Pass the rendering mode as first argument to override it.
+      #
+      # `:partial`
+      # :   See ActionView::PartialRenderer for details.
+      #
+      #         <%= render partial: "form", locals: { post: Post.new } %>
+      #         # => renders app/views/posts/_form.html.erb
+      #
+      # `:file`
+      # :   Renders the contents of a file. This option should **not** be used with
+      #     unsanitized user input.
+      #
+      #         <%= render file: "/path/to/some/file" %>
+      #         # => renders /path/to/some/file
+      #
+      # `:inline`
+      # :   Renders an ERB template string.
+      #
+      #         <% name = "World" %>
+      #         <%= render inline: "<h1>Hello, <%= name %>!</h1>" %>
+      #         # => renders "<h1>Hello, World!</h1>"
+      #
+      # `:body`
+      # :   Renders the provided text, and sets the format as `:text`.
+      #
+      #         <%= render body: "Hello, World!" %>
+      #         # => renders "Hello, World!"
+      #
+      # `:plain`
+      # :   Renders the provided text, and sets the format as `:text`.
+      #
+      #         <%= render plain: "Hello, World!" %>
+      #         # => renders "Hello, World!"
+      #
+      # `:html`
+      # :   Renders the provided HTML string, and sets the format as
+      #     `:html`. If the string is not `html_safe?`, performs HTML escaping on
+      #     the string before rendering.
+      #
+      #         <%= render html: "<h1>Hello, World!</h1>".html_safe %>
+      #         # => renders "<h1>Hello, World!</h1>"
+      #
+      #         <%= render html: "<h1>Hello, World!</h1>" %>
+      #         # => renders "&lt;h1&gt;Hello, World!&lt;/h1&gt;"
+      #
+      # `:renderable`
+      # :   Renders the provided object by calling `render_in` with the current view
+      #     context. The format is determined by calling `format` on the
+      #     renderable if it responds to `format`, falling back to `:html` by
+      #     default.
+      #
+      #         <%= render renderable: Greeting.new %>
+      #         # => renders "<h1>Hello, World</h1>"
+      #
+      #
+      # #### Options
+      #
+      # `:locals`
+      # :   Hash of local variable assignments for the template.
+      #
+      #         <%= render inline: "<h1>Hello, <%= name %>!</h1>", locals: { name: "World" } %>
+      #         # => renders "<h1>Hello, World!</h1>"
+      #
+      # `:formats`
+      # :   Override the current format to render a template for a different format.
+      #
+      #         <% # app/views/posts/show.html.erb %>
+      #         <%= render template: "posts/content", formats: [:text] %>
+      #         # => renders app/views/posts/content.text.erb
       #
-      # * <tt>:partial</tt> - See ActionView::PartialRenderer.
-      # * <tt>:file</tt> - Renders an explicit template file (this used to be the old default), add +:locals+ to pass in those.
-      # * <tt>:inline</tt> - Renders an inline template similar to how it's done in the controller.
-      # * <tt>:plain</tt> - Renders the text passed in out. Setting the content
-      #   type as <tt>text/plain</tt>.
-      # * <tt>:html</tt> - Renders the HTML safe string passed in out, otherwise
-      #   performs HTML escape on the string first. Setting the content type as
-      #   <tt>text/html</tt>.
-      # * <tt>:body</tt> - Renders the text passed in, and inherits the content
-      #   type of <tt>text/plain</tt> from ActionDispatch::Response object.
+      # `:variants`
+      # :   Render a template for a different variant.
       #
-      # If no <tt>options</tt> hash is passed or if <tt>:update</tt> is specified, then:
+      #         <% # app/views/posts/show.html.erb %>
+      #         <%= render template: "posts/content", variants: [:tablet] %>
+      #         # => renders app/views/posts/content.html+tablet.erb
       #
-      # If an object responding to +render_in+ is passed, +render_in+ is called on the object,
-      # passing in the current view context.
+      # `:handlers`
+      # :   Render a template for a different handler.
       #
-      # Otherwise, a partial is rendered using the second parameter as the locals hash.
+      #         <% # app/views/posts/show.html.erb %>
+      #         <%= render template: "posts/content", handlers: [:builder] %>
+      #         # => renders app/views/posts/content.html.builder
       def render(options = {}, locals = {}, &block)
         case options
         when Hash
@@ -47,52 +155,54 @@ module ActionView
       end
 
       # Overrides _layout_for in the context object so it supports the case a block is
-      # passed to a partial. Returns the contents that are yielded to a layout, given a
-      # name or a block.
+      # passed to a partial. Returns the contents that are yielded to a layout, given
+      # a name or a block.
       #
-      # You can think of a layout as a method that is called with a block. If the user calls
-      # <tt>yield :some_name</tt>, the block, by default, returns <tt>content_for(:some_name)</tt>.
-      # If the user calls simply +yield+, the default block returns <tt>content_for(:layout)</tt>.
+      # You can think of a layout as a method that is called with a block. If the user
+      # calls `yield :some_name`, the block, by default, returns
+      # `content_for(:some_name)`. If the user calls simply `yield`, the default block
+      # returns `content_for(:layout)`.
       #
       # The user can override this default by passing a block to the layout:
       #
-      #   # The template
-      #   <%= render layout: "my_layout" do %>
-      #     Content
-      #   <% end %>
+      #     # The template
+      #     <%= render layout: "my_layout" do %>
+      #       Content
+      #     <% end %>
       #
-      #   # The layout
-      #   <html>
-      #     <%= yield %>
-      #   </html>
+      #     # The layout
+      #     <html>
+      #       <%= yield %>
+      #     </html>
       #
-      # In this case, instead of the default block, which would return <tt>content_for(:layout)</tt>,
-      # this method returns the block that was passed in to <tt>render :layout</tt>, and the response
+      # In this case, instead of the default block, which would return `content_for(:layout)`,
+      # this method returns the block that was passed in to `render :layout`, and the response
       # would be
       #
-      #   <html>
-      #     Content
-      #   </html>
+      #     <html>
+      #       Content
+      #     </html>
       #
-      # Finally, the block can take block arguments, which can be passed in by +yield+:
+      # Finally, the block can take block arguments, which can be passed in by
+      # `yield`:
       #
-      #   # The template
-      #   <%= render layout: "my_layout" do |customer| %>
-      #     Hello <%= customer.name %>
-      #   <% end %>
+      #     # The template
+      #     <%= render layout: "my_layout" do |customer| %>
+      #       Hello <%= customer.name %>
+      #     <% end %>
       #
-      #   # The layout
-      #   <html>
-      #     <%= yield Struct.new(:name).new("David") %>
-      #   </html>
+      #     # The layout
+      #     <html>
+      #       <%= yield Struct.new(:name).new("David") %>
+      #     </html>
       #
-      # In this case, the layout would receive the block passed into <tt>render :layout</tt>,
+      # In this case, the layout would receive the block passed into `render :layout`,
       # and the struct specified would be passed into the block as an argument. The result
       # would be
       #
-      #   <html>
-      #     Hello David
-      #   </html>
+      #     <html>
+      #       Hello David
+      #     </html>
       #
       def _layout_for(*args, &block)
         name = args.first

data/lib/action_view/helpers/sanitize_helper.rb

@@ -24,6 +24,12 @@ module ActionView
       #
       # Custom sanitization rules can also be provided.
       #
+      # <b>Warning</b>: Adding disallowed tags or attributes to the allowlists may introduce
+      # vulnerabilities into your application. Please rely on the default allowlists whenever
+      # possible, because they are curated to maintain security and safety. If you think that the
+      # default allowlists should be expanded, please {open an issue on the rails-html-sanitizer
+      # project}[https://github.com/rails/rails-html-sanitizer/issues].
+      #
       # Please note that sanitizing user-provided text does not guarantee that the
       # resulting markup is valid or even well-formed.
       #