actionview 7.0.4 → 7.1.5.1

data/lib/action_view/helpers/csp_helper.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module ActionView
-  # = Action View CSP Helper
   module Helpers # :nodoc:
+    # = Action View CSP \Helpers
     module CspHelper
       # Returns a meta tag "csp-nonce" with the per-session nonce value
       # for allowing inline <script> tags.
@@ -11,7 +11,7 @@ module ActionView
       #     <%= csp_meta_tag %>
       #   </head>
       #
-      # This is used by the Rails UJS helper to create dynamically
+      # This is used by the \Rails UJS helper to create dynamically
       # loaded inline <script> elements.
       #
       def csp_meta_tag(**options)

data/lib/action_view/helpers/csrf_helper.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module ActionView
-  # = Action View CSRF Helper
   module Helpers # :nodoc:
+    # = Action View CSRF \Helpers
     module CsrfHelper
       # Returns meta tags "csrf-param" and "csrf-token" with the name of the cross-site
       # request forgery protection parameter and token, respectively.
@@ -16,8 +16,8 @@ module ActionView
       #
       # You don't need to use these tags for regular forms as they generate their own hidden fields.
       #
-      # For AJAX requests other than GETs, extract the "csrf-token" from the meta-tag and send as the
-      # "X-CSRF-Token" HTTP header. If you are using rails-ujs this happens automatically.
+      # For Ajax requests other than GETs, extract the "csrf-token" from the meta-tag and send as the
+      # +X-CSRF-Token+ HTTP header. If you are using rails-ujs, this happens automatically.
       #
       def csrf_meta_tags
         if defined?(protect_against_forgery?) && protect_against_forgery?

data/lib/action_view/helpers/date_helper.rb

@@ -10,7 +10,7 @@ require "active_support/core_ext/object/with_options"
 
 module ActionView
   module Helpers # :nodoc:
-    # = Action View Date Helpers
+    # = Action View \Date \Helpers
     #
     # The Date Helper primarily creates select/option tags for different kinds of dates and times or date and time
     # elements. All of the select-type methods share a number of common options that are as follows:
@@ -72,7 +72,7 @@ module ActionView
       #   distance_of_time_in_words(to_time, from_time, include_seconds: true)                        # => about 6 years
       #   distance_of_time_in_words(Time.now, Time.now)                                               # => less than a minute
       #
-      # With the <tt>scope</tt> option, you can define a custom scope for Rails
+      # With the <tt>scope</tt> option, you can define a custom scope for \Rails
       # to look up the translation.
       #
       # For example you can define the following in your locale (e.g. en.yml).
@@ -217,7 +217,7 @@ module ActionView
       # * <tt>:order</tt>             - Set to an array containing <tt>:day</tt>, <tt>:month</tt> and <tt>:year</tt> to
       #   customize the order in which the select fields are shown. If you leave out any of the symbols, the respective
       #   select will not be shown (like when you set <tt>discard_xxx: true</tt>. Defaults to the order defined in
-      #   the respective locale (e.g. [:year, :month, :day] in the en locale that ships with Rails).
+      #   the respective locale (e.g. [:year, :month, :day] in the en locale that ships with \Rails).
       # * <tt>:include_blank</tt>     - Include a blank option in every select field so it's possible to set empty
       #   dates.
       # * <tt>:default</tt>           - Set a default date if the affected date isn't set or is +nil+.
@@ -320,6 +320,10 @@ module ActionView
       #   # You can set :ampm option to true which will show the hours as: 12 PM, 01 AM .. 11 PM.
       #   time_select 'game', 'game_time', { ampm: true }
       #
+      #   # You can set :ignore_date option to true which will remove the hidden inputs for day,
+      #   # month, and year that are set by default on this helper when you only want the time inputs
+      #   time_select 'game', 'game_time', { ignore_date: true }
+      #
       # The selects are prepared for multi-parameter assignment to an Active Record object.
       #
       # Note: If the day is not included as an option but the month is, the day will be set to the 1st to ensure that
@@ -844,14 +848,14 @@ module ActionView
         if @options[:use_hidden] || @options[:discard_year]
           build_hidden(:year, val)
         else
-          options                     = {}
-          options[:start]             = @options[:start_year] || middle_year - 5
-          options[:end]               = @options[:end_year] || middle_year + 5
-          options[:step]              = options[:start] < options[:end] ? 1 : -1
-          options[:leading_zeros]     = false
-          options[:max_years_allowed] = @options[:max_years_allowed] || 1000
-
-          if (options[:end] - options[:start]).abs > options[:max_years_allowed]
+          options         = {}
+          options[:start] = @options[:start_year] || middle_year - 5
+          options[:end]   = @options[:end_year] || middle_year + 5
+          options[:step]  = options[:start] < options[:end] ? 1 : -1
+
+          max_years_allowed = @options[:max_years_allowed] || 1000
+
+          if (options[:end] - options[:start]).abs > max_years_allowed
             raise ArgumentError, "There are too many years options to be built. Are you sure you haven't mistyped something? You can provide the :max_years_allowed parameter."
           end
 
@@ -936,7 +940,7 @@ module ActionView
         #
         #   month_name(1) # => 1
         #
-        # If the <tt>:use_two_month_numbers</tt> option is passed:
+        # If the <tt>:use_two_digit_numbers</tt> option is passed:
         #
         #   month_name(1) # => '01'
         #
@@ -1001,22 +1005,25 @@ module ActionView
         end
 
         # Build select option HTML from date value and options.
-        #  build_options(15, start: 1, end: 31)
-        #  => "<option value="1">1</option>
-        #      <option value="2">2</option>
-        #      <option value="3">3</option>..."
         #
-        # If <tt>use_two_digit_numbers: true</tt> option is passed
-        #  build_options(15, start: 1, end: 31, use_two_digit_numbers: true)
-        #  => "<option value="1">01</option>
-        #      <option value="2">02</option>
-        #      <option value="3">03</option>..."
+        #   build_options(15, start: 1, end: 31)
+        #   => "<option value="1">1</option>
+        #       <option value="2">2</option>
+        #       <option value="3">3</option>..."
+        #
+        # If <tt>use_two_digit_numbers: true</tt> option is passed:
+        #
+        #   build_options(15, start: 1, end: 31, use_two_digit_numbers: true)
+        #   => "<option value="1">01</option>
+        #       <option value="2">02</option>
+        #       <option value="3">03</option>..."
+        #
+        # If <tt>:step</tt> options is passed:
         #
-        # If <tt>:step</tt> options is passed
-        #  build_options(15, start: 1, end: 31, step: 2)
-        #  => "<option value="1">1</option>
-        #      <option value="3">3</option>
-        #      <option value="5">5</option>..."
+        #   build_options(15, start: 1, end: 31, step: 2)
+        #   => "<option value="1">1</option>
+        #       <option value="3">3</option>
+        #       <option value="5">5</option>..."
         def build_options(selected, options = {})
           options = {
             leading_zeros: true, ampm: false, use_two_digit_numbers: false
@@ -1041,22 +1048,25 @@ module ActionView
         end
 
         # Build select option HTML for day.
-        #  build_day_options(2)
-        #  => "<option value="1">1</option>
-        #      <option value="2" selected="selected">2</option>
-        #      <option value="3">3</option>..."
+        #
+        #   build_day_options(2)
+        #   => "<option value="1">1</option>
+        #       <option value="2" selected="selected">2</option>
+        #       <option value="3">3</option>..."
         #
         # If <tt>day_format: ->(day) { day.ordinalize }</tt> option is passed to DateTimeSelector
-        #  build_day_options(2)
-        #  => "<option value="1">1st</option>
-        #      <option value="2" selected="selected">2nd</option>
-        #      <option value="3">3rd</option>..."
+        #
+        #   build_day_options(2)
+        #   => "<option value="1">1st</option>
+        #       <option value="2" selected="selected">2nd</option>
+        #       <option value="3">3rd</option>..."
         #
         # If <tt>use_two_digit_numbers: true</tt> option is passed to DateTimeSelector
-        #  build_day_options(2)
-        #  => "<option value="1">01</option>
-        #      <option value="2" selected="selected">02</option>
-        #      <option value="3">03</option>..."
+        #
+        #   build_day_options(2)
+        #   => "<option value="1">01</option>
+        #       <option value="2" selected="selected">02</option>
+        #       <option value="3">03</option>..."
         def build_day_options(selected)
           select_options = []
           (1..31).each do |value|
@@ -1070,17 +1080,11 @@ module ActionView
         end
 
         # Build select option HTML for year.
-        # If <tt>year_format</tt> option is not passed
-        #  build_year_options(1998, start: 1998, end: 2000)
-        #  => "<option value="1998" selected="selected">1998</option>
-        #      <option value="1999">1999</option>
-        #      <option value="2000">2000</option>"
         #
-        # If <tt>year_format</tt> option is passed
-        #  build_year_options(1998, start: 1998, end: 2000, year_format: ->year { "Heisei #{ year - 1988 }" })
-        #  => "<option value="1998" selected="selected">Heisei 10</option>
-        #      <option value="1999">Heisei 11</option>
-        #      <option value="2000">Heisei 12</option>"
+        #   build_year_options(1998, start: 1998, end: 2000)
+        #   => "<option value="1998" selected="selected">1998</option>
+        #       <option value="1999">1999</option>
+        #       <option value="2000">2000</option>"
         def build_year_options(selected, options = {})
           start = options.delete(:start)
           stop = options.delete(:end)
@@ -1098,10 +1102,11 @@ module ActionView
         end
 
         # Builds select tag from date type and HTML select options.
-        #  build_select(:month, "<option value="1">January</option>...")
-        #  => "<select id="post_written_on_2i" name="post[written_on(2i)]">
-        #        <option value="1">January</option>...
-        #      </select>"
+        #
+        #   build_select(:month, "<option value="1">January</option>...")
+        #   => "<select id="post_written_on_2i" name="post[written_on(2i)]">
+        #         <option value="1">January</option>...
+        #       </select>"
         def build_select(type, select_options_as_html)
           select_options = {
             id: input_id_from_type(type),
@@ -1118,9 +1123,10 @@ module ActionView
           (content_tag("select", select_html.html_safe, select_options) + "\n").html_safe
         end
 
-        # Builds the CSS class value for the select element
-        #  css_class_attribute(:year, 'date optional', { year: 'my-year' })
-        #  => "date optional my-year"
+        # Builds the CSS class value for the select element.
+        #
+        #   css_class_attribute(:year, 'date optional', { year: 'my-year' })
+        #   => "date optional my-year"
         def css_class_attribute(type, html_options_class, options) # :nodoc:
           css_class = \
             case options
@@ -1134,8 +1140,9 @@ module ActionView
         end
 
         # Builds a prompt option tag with supplied options or from default options.
-        #  prompt_option_tag(:month, prompt: 'Select month')
-        #  => "<option value="">Select month</option>"
+        #
+        #   prompt_option_tag(:month, prompt: 'Select month')
+        #   => "<option value="">Select month</option>"
         def prompt_option_tag(type, options)
           prompt = \
             case options
@@ -1152,8 +1159,9 @@ module ActionView
         end
 
         # Builds hidden input tag for date part and value.
-        #  build_hidden(:year, 2008)
-        #  => "<input type="hidden" id="date_year" name="date[year]" value="2008" autocomplete="off" />"
+        #
+        #   build_hidden(:year, 2008)
+        #   => "<input type="hidden" id="date_year" name="date[year]" value="2008" autocomplete="off" />"
         def build_hidden(type, value)
           select_options = {
             type: "hidden",

data/lib/action_view/helpers/debug_helper.rb

@@ -3,10 +3,10 @@
 require "action_view/helpers/tag_helper"
 
 module ActionView
-  # = Action View Debug Helper
-  #
-  # Provides a set of methods for making it easier to debug Rails objects.
   module Helpers # :nodoc:
+    # = Action View Debug \Helpers
+    #
+    # Provides a set of methods for making it easier to debug \Rails objects.
     module DebugHelper
       include TagHelper
 

data/lib/action_view/helpers/form_helper.rb

@@ -13,8 +13,9 @@ require "active_support/core_ext/string/output_safety"
 require "active_support/core_ext/string/inflections"
 
 module ActionView
-  # = Action View Form Helpers
   module Helpers # :nodoc:
+    # = Action View Form \Helpers
+    #
     # Form helpers are designed to make working with resources much easier
     # compared to using vanilla HTML.
     #
@@ -28,7 +29,7 @@ module ActionView
     # when the form is initially displayed, input fields corresponding to attributes
     # of the resource should show the current values of those attributes.
     #
-    # In Rails, this is usually achieved by creating the form using +form_for+ and
+    # In \Rails, this is usually achieved by creating the form using +form_for+ and
     # a number of related helper methods. +form_for+ generates an appropriate <tt>form</tt>
     # tag and yields a form builder object that knows the model the form is about.
     # Input fields are created by calling methods defined on the form builder, which
@@ -122,7 +123,7 @@ module ActionView
       # of a specific model object.
       #
       # The method can be used in several slightly different ways, depending on
-      # how much you wish to rely on Rails to infer automatically from the model
+      # how much you wish to rely on \Rails to infer automatically from the model
       # how the form should be constructed. For a generic model object, a form
       # can be created by passing +form_for+ a string or symbol representing
       # the object we are concerned with:
@@ -251,7 +252,7 @@ module ActionView
       # form is going to be sent. However, further simplification is possible
       # if the record passed to +form_for+ is a _resource_, i.e. it corresponds
       # to a set of RESTful routes, e.g. defined using the +resources+ method
-      # in <tt>config/routes.rb</tt>. In this case Rails will simply infer the
+      # in <tt>config/routes.rb</tt>. In this case \Rails will simply infer the
       # appropriate URL from the record itself. For example,
       #
       #   <%= form_for @post do |f| %>
@@ -438,7 +439,7 @@ module ActionView
           model       = nil
           object_name = record
         else
-          model       = convert_to_model(record)
+          model       = record
           object      = _object_for_form_builder(record)
           raise ArgumentError, "First argument in form cannot contain nil or be empty" unless object
           object_name = options[:as] || model_name_from_record_or_class(object).param_key
@@ -496,7 +497,7 @@ module ActionView
       #     <%= form.text_field :title %>
       #   <% end %>
       #   # =>
-      #   <form method="post" data-remote="true">
+      #   <form method="post">
       #     <input type="text" name="title">
       #   </form>
       #
@@ -555,7 +556,7 @@ module ActionView
       # is a _resource_. It corresponds to a set of RESTful routes, most likely
       # defined via +resources+ in <tt>config/routes.rb</tt>.
       #
-      # So when passing such a model record, Rails infers the URL and method.
+      # So when passing such a model record, \Rails infers the URL and method.
       #
       #   <%= form_with model: @post do |form| %>
       #     ...
@@ -618,12 +619,12 @@ module ActionView
       # * <tt>:local</tt> - Whether to use standard HTTP form submission.
       #   When set to <tt>true</tt>, the form is submitted via standard HTTP.
       #   When set to <tt>false</tt>, the form is submitted as a "remote form", which
-      #   is handled by Rails UJS as an XHR. When unspecified, the behavior is derived
+      #   is handled by \Rails UJS as an XHR. When unspecified, the behavior is derived
       #   from <tt>config.action_view.form_with_generates_remote_forms</tt> where the
       #   config's value is actually the inverse of what <tt>local</tt>'s value would be.
-      #   As of Rails 6.1, that configuration option defaults to <tt>false</tt>
+      #   As of \Rails 6.1, that configuration option defaults to <tt>false</tt>
       #   (which has the equivalent effect of passing <tt>local: true</tt>).
-      #   In previous versions of Rails, that configuration option defaults to
+      #   In previous versions of \Rails, that configuration option defaults to
       #   <tt>true</tt> (the equivalent of passing <tt>local: false</tt>).
       # * <tt>:skip_enforcing_utf8</tt> - If set to true, a hidden input with name
       #   utf8 is not output.
@@ -756,10 +757,14 @@ module ActionView
 
         if model
           if url != false
-            url ||= polymorphic_path(model, format: format)
+            url ||= if format.nil?
+              polymorphic_path(model, {})
+            else
+              polymorphic_path(model, format: format)
+            end
           end
 
-          model   = _object_for_form_builder(model)
+          model   = convert_to_model(_object_for_form_builder(model))
           scope ||= model_name_from_record_or_class(model).param_key
         end
 
@@ -1001,8 +1006,8 @@ module ActionView
       #   <% end %>
       #
       # When a collection is used you might want to know the index of each
-      # object into the array. For this purpose, the <tt>index</tt> method
-      # is available in the FormBuilder object.
+      # object in the array. For this purpose, the <tt>index</tt> method is
+      # available in the FormBuilder object.
       #
       #   <%= form_for @person do |person_form| %>
       #     ...
@@ -1113,6 +1118,8 @@ module ActionView
       #       post:
       #         cost: "Total cost"
       #
+      # <code></code>
+      #
       #   label(:post, :cost)
       #   # => <label for="post_cost">Total cost</label>
       #
@@ -1311,7 +1318,7 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # because parameter name repetition is precisely what Rails seeks to distinguish
+      # because parameter name repetition is precisely what \Rails seeks to distinguish
       # the elements of the array. For each item with a checked check box you
       # get an extra ghost item with only that attribute, assigned to "0".
       #
@@ -1494,6 +1501,12 @@ module ActionView
       #   datetime_field("user", "born_on", min: "2014-05-20T00:00:00")
       #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" min="2014-05-20T00:00:00.000" />
       #
+      # By default, provided datetimes will be formatted including seconds. You can render just the date, hour,
+      # and minute by passing <tt>include_seconds: false</tt>.
+      #
+      #   @user.born_on = Time.current
+      #   datetime_field("user", "born_on", include_seconds: false)
+      #   # => <input id="user_born_on" name="user[born_on]" type="datetime-local" value="2014-05-20T14:35" />
       def datetime_field(object_name, method, options = {})
         Tags::DatetimeLocalField.new(object_name, method, self, options).render
       end
@@ -1610,6 +1623,8 @@ module ActionView
         end
     end
 
+    # = Action View Form Builder
+    #
     # A +FormBuilder+ object is associated with a particular model object and
     # allows you to generate fields associated with the model object. The
     # +FormBuilder+ object is yielded when using +form_for+ or +fields_for+.
@@ -1735,7 +1750,7 @@ module ActionView
       # <tt><button></tt> element should be treated as the <tt><form></tt>
       # element's submit button, regardless of where it exists in the DOM.
       def id
-        options.dig(:html, :id)
+        options.dig(:html, :id) || options[:id]
       end
 
       # Generate an HTML <tt>id</tt> attribute value for the given field
@@ -1754,7 +1769,7 @@ module ActionView
       # <tt>aria-describedby</tt> attribute referencing the <tt><span></tt>
       # element, sharing a common <tt>id</tt> root (<tt>post_title</tt>, in this
       # case).
-      def field_id(method, *suffixes, namespace: @options[:namespace], index: @index)
+      def field_id(method, *suffixes, namespace: @options[:namespace], index: @options[:index])
         @template.field_id(@object_name, method, *suffixes, namespace: namespace, index: index)
       end
 
@@ -1766,15 +1781,15 @@ module ActionView
       #
       #   <%= form_for @post do |f| %>
       #     <%= f.text_field :title, name: f.field_name(:title, :subtitle) %>
-      #     <%# => <input type="text" name="post[title][subtitle]">
+      #     <%# => <input type="text" name="post[title][subtitle]"> %>
       #   <% end %>
       #
       #   <%= form_for @post do |f| %>
-      #     <%= f.field_tag :tag, name: f.field_name(:tag, multiple: true) %>
-      #     <%# => <input type="text" name="post[tag][]">
+      #     <%= f.text_field :tag, name: f.field_name(:tag, multiple: true) %>
+      #     <%# => <input type="text" name="post[tag][]"> %>
       #   <% end %>
       #
-      def field_name(method, *methods, multiple: false, index: @index)
+      def field_name(method, *methods, multiple: false, index: @options[:index])
         object_name = @options.fetch(:as) { @object_name }
 
         @template.field_name(object_name, method, *methods, index: index, multiple: multiple)
@@ -2074,6 +2089,18 @@ module ActionView
       # DateHelper that are designed to work with an object as base, like
       # FormOptionsHelper#collection_select and DateHelper#datetime_select.
       #
+      # +fields_for+ tries to be smart about parameters, but it can be confused if both
+      # name and value parameters are provided and the provided value has the shape of an
+      # option Hash. To remove the ambiguity, explicitly pass an option Hash, even if empty.
+      #
+      #   <%= form_for @person do |person_form| %>
+      #     ...
+      #     <%= fields_for :permission, @person.permission, {} do |permission_fields| %>
+      #       Admin?: <%= check_box_tag permission_fields.field_name(:admin), @person.permission[:admin] %>
+      #     <% end %>
+      #     ...
+      #   <% end %>
+      #
       # === Nested Attributes Examples
       #
       # When the object belonging to the current scope has a nested attribute
@@ -2238,7 +2265,7 @@ module ActionView
       #   <% end %>
       #
       # When a collection is used you might want to know the index of each
-      # object into the array. For this purpose, the <tt>index</tt> method
+      # object in the array. For this purpose, the <tt>index</tt> method
       # is available in the FormBuilder object.
       #
       #   <%= form_for @person do |person_form| %>
@@ -2254,8 +2281,9 @@ module ActionView
       # to store the ID of the record. There are circumstances where this
       # hidden field is not needed and you can pass <tt>include_id: false</tt>
       # to prevent fields_for from rendering it automatically.
-      def fields_for(record_name, record_object = nil, fields_options = {}, &block)
-        fields_options, record_object = record_object, nil if record_object.is_a?(Hash) && record_object.extractable_options?
+      def fields_for(record_name, record_object = nil, fields_options = nil, &block)
+        fields_options, record_object = record_object, nil if fields_options.nil? && record_object.is_a?(Hash) && record_object.extractable_options?
+        fields_options ||= {}
         fields_options[:builder] ||= options[:builder]
         fields_options[:namespace] = options[:namespace]
         fields_options[:parent_builder] = self
@@ -2332,6 +2360,8 @@ module ActionView
       #       post:
       #         cost: "Total cost"
       #
+      # <code></code>
+      #
       #   label(:cost)
       #   # => <label for="post_cost">Total cost</label>
       #
@@ -2412,7 +2442,7 @@ module ActionView
       #     ...
       #   <% end %>
       #
-      # because parameter name repetition is precisely what Rails seeks to distinguish
+      # because parameter name repetition is precisely what \Rails seeks to distinguish
       # the elements of the array. For each item with a checked check box you
       # get an extra ghost item with only that attribute, assigned to "0".
       #
@@ -2495,7 +2525,7 @@ module ActionView
       # * Creates standard HTML attributes for the tag.
       # * <tt>:disabled</tt> - If set to true, the user will not be able to use this input.
       # * <tt>:multiple</tt> - If set to true, *in most updated browsers* the user will be allowed to select multiple files.
-      # * <tt>:include_hidden</tt> - When <tt>multiple: true</tt> and <tt>include_hidden: true</tt>, the field will be prefixed with an <tt><input type="hidden"></tt> field with an empty value to support submitting an empty collection of files.
+      # * <tt>:include_hidden</tt> - When <tt>multiple: true</tt> and <tt>include_hidden: true</tt>, the field will be prefixed with an <tt><input type="hidden"></tt> field with an empty value to support submitting an empty collection of files. Since <tt>include_hidden</tt> will default to <tt>config.active_storage.multiple_file_field_include_hidden</tt> if you don't specify <tt>include_hidden</tt>, you will need to pass <tt>include_hidden: false</tt> to prevent submitting an empty collection of files when passing <tt>multiple: true</tt>.
       # * <tt>:accept</tt> - If set to one or multiple mime-types, the user will be suggested a filter when choosing a file. You still need to set up model validations.
       #
       # ==== Examples

data/lib/action_view/helpers/form_options_helper.rb

@@ -8,8 +8,9 @@ require "active_support/core_ext/array/wrap"
 require "action_view/helpers/text_helper"
 
 module ActionView
-  # = Action View Form Option Helpers
   module Helpers # :nodoc:
+    # = Action View Form Option \Helpers
+    #
     # Provides a number of methods for turning different kinds of containers into a set of option tags.
     #
     # The <tt>collection_select</tt>, <tt>select</tt> and <tt>time_zone_select</tt> methods take an <tt>options</tt> parameter, a hash:
@@ -500,6 +501,8 @@ module ActionView
       #   <tt><optgroup></tt> label while the second value must be an array of options. The second value can be a
       #   nested array of text-value pairs. See <tt>options_for_select</tt> for more info.
       #    Ex. ["North America",[["United States","US"],["Canada","CA"]]]
+      #   An optional third value can be provided as HTML attributes for the <tt>optgroup</tt>.
+      #    Ex. ["North America",[["United States","US"],["Canada","CA"]], { disabled: "disabled" }]
       # * +selected_key+ - A value equal to the +value+ attribute for one of the <tt><option></tt> tags,
       #   which will have the +selected+ attribute set. Note: It is possible for this value to match multiple options
       #   as you might have the same option in multiple groups. Each will then get <tt>selected="selected"</tt>.