govuk_design_system_formbuilder 1.2.3 → 2.0.0b1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b04804863d4a75157988de721c6fda535eb35df444b8a99a8830b7b9758f8e03
-  data.tar.gz: 162d14ae3760447cf707bc89195daa2a66ca104265258d751b1082325ed56aa8
+  metadata.gz: 52cc4abc62b3ac208e8fe2befb527b6deda60868d2094a3172d907bc0ce82654
+  data.tar.gz: fb0c810a65f025e226fe4dc0cee0c5b42b3b7baa499b032d6f88d4ec2fac9d54
 SHA512:
-  metadata.gz: 71814ceeaf1bb257102a0b4f3e04675bf44aa10a3b85837420d30295bf1b77e9f63c6498dc6d0a8560c5cfb7abcecd7ec057d7ce73a7b2f0f682849eae71a7ba
-  data.tar.gz: 16d9e596f3a56b25a5413aed0b996d1965cd0be1a2fb6653217cea9b41b1334f9918a75f71ea0f6ba51844b617bd0a2a3a0686c4c8fb34f05b999afce50f8f67
+  metadata.gz: 996a9f979a4eab0a16499f81cf39fdcfbd0c641dd5d2944c52be697cd6f1f8870b75c6fd4b498d3769265fa39168f7baefe36bb53255bc50a9bfcb82f06bd641
+  data.tar.gz: ef2f8f3eaba7ea21b2ae18a7a4ba8c181981164f36917d082ff5f2545896df17c6b27c9acab09621d3e5453013d9e5747e5f838b54bc2f2e68aed585980190d9

data/README.md

@@ -7,10 +7,10 @@
 [![Test Coverage](https://api.codeclimate.com/v1/badges/fde73b5dc9476197281b/test_coverage)](https://codeclimate.com/github/DFE-Digital/govuk_design_system_formbuilder/test_coverage)
 [![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=DFE-Digital/govuk_design_system_formbuilder)](https://dependabot.com)
 [![GitHub license](https://img.shields.io/github/license/DFE-Digital/govuk_design_system_formbuilder)](https://github.com/DFE-Digital/govuk_design_system_formbuilder/blob/master/LICENSE)
-[![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.7.0-brightgreen)](https://design-system.service.gov.uk)
+[![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.8.1-brightgreen)](https://design-system.service.gov.uk)
 
 This gem provides a easy-to-use form builder that generates forms that are
-fully-compliant with version 3.7.0 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
+fully-compliant with version 3.8.1 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
 minimising the amount of markup you need to write.
 
 In addition to the basic markup, the more-advanced functionality of the Design

data/lib/govuk_design_system_formbuilder.rb

@@ -88,7 +88,7 @@ module GOVUKDesignSystemFormBuilder
   end
 
   class FormBuilder < ActionView::Helpers::FormBuilder
-    delegate :content_tag, :tag, :safe_join, :safe_concat, :capture, :link_to, :raw, to: :@template
+    delegate :content_tag, :tag, :safe_join, :link_to, :capture, to: :@template
 
     include GOVUKDesignSystemFormBuilder::Builder
   end

data/lib/govuk_design_system_formbuilder/base.rb

@@ -8,7 +8,7 @@ module GOVUKDesignSystemFormBuilder
   end
 
   class Base
-    delegate :capture, :content_tag, :safe_join, :tag, :raw, :link_to, to: :@builder
+    delegate :content_tag, :safe_join, :tag, :link_to, :capture, to: :@builder
     delegate :config, to: GOVUKDesignSystemFormBuilder
 
     def initialize(builder, object_name, attribute_name, &block)

data/lib/govuk_design_system_formbuilder/builder.rb

@@ -5,7 +5,11 @@ module GOVUKDesignSystemFormBuilder
     # Generates a input of type +text+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    #
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -17,6 +21,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -25,7 +32,7 @@ module GOVUKDesignSystemFormBuilder
     # @example A required full name field with a placeholder
     #   = f.govuk_text_field :name,
     #     label: { text: 'Full name' },
-    #     hint_text: 'It says it on your birth certificate',
+    #     hint: { text: 'It says it on your birth certificate' },
     #     required: true,
     #     placeholder: 'Ralph Wiggum'
     #
@@ -40,14 +47,17 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_text_field :callsign,
     #     label: -> { tag.h3('Call-sign') }
     #
-    def govuk_text_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
-      Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
+      Elements::Inputs::Text.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a input of type +tel+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -59,6 +69,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -68,7 +81,7 @@ module GOVUKDesignSystemFormBuilder
     # @example A required phone number field with a placeholder
     #   = f.govuk_phone_field :phone_number,
     #     label: { text: 'UK telephone number' },
-    #     hint_text: 'Include the dialling code',
+    #     hint: { text: 'Include the dialling code' },
     #     required: true,
     #     placeholder: '0123 456 789'
     #
@@ -83,14 +96,17 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_phone_field :work_number,
     #     label: -> { tag.h3('Work number') }
     #
-    def govuk_phone_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
-      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
+      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a input of type +email+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -102,6 +118,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -124,14 +143,17 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_email_field :personal_email,
     #     label: -> { tag.h3('Personal email address') }
     #
-    def govuk_email_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
-      Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
+      Elements::Inputs::Email.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a input of type +password+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -143,6 +165,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -164,14 +189,17 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_password_field :passcode,
     #     label: -> { tag.h3('What is your secret pass code?') }
     #
-    def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, caption: {}, **args, &block)
-      Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, **args, &block)
+      Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a input of type +url+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -183,6 +211,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -205,14 +236,17 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_url_field :work_website,
     #     label: -> { tag.h3("Enter your company's website") }
     #
-    def govuk_url_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
-      Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
+      Elements::Inputs::URL.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a input of type +number+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
     #   or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
     # @param label [Hash,Proc] configures or sets the associated label content
@@ -224,6 +258,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -249,8 +286,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_url_field :personal_best_over_100m,
     #     label: -> { tag.h3("How many seconds does it take you to run 100m?") }
     #
-    def govuk_number_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
-      Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
+    def govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
+      Elements::Inputs::Number.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
     end
 
     # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -258,7 +295,10 @@ module GOVUKDesignSystemFormBuilder
     # automatically
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param label [Hash,Proc] configures or sets the associated label content
     # @option label text [String] the label text
     # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
@@ -272,6 +312,9 @@ module GOVUKDesignSystemFormBuilder
     # @param threshold [Integer] only show the +max_words+ and +max_chars+ warnings once a threshold (percentage) is reached
     # @param rows [Integer] sets the initial number of rows
     # @option args [Hash] args additional arguments are applied as attributes to the +textarea+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/textarea/ GOV.UK text area component
@@ -297,8 +340,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_text_area :instructions,
     #     label: -> { tag.h3("How do you set it up?") }
     #
-    def govuk_text_area(attribute_name, hint_text: nil, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, **args, &block)
-      Elements::TextArea.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, **args, &block).html
+    def govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **args, &block)
+      Elements::TextArea.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, form_group: form_group, **args, &block).html
     end
 
     # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -307,12 +350,21 @@ module GOVUKDesignSystemFormBuilder
     # @param collection [Enumerable<Object>] Options to be added to the +select+ element
     # @param value_method [Symbol] The method called against each member of the collection to provide the value
     # @param text_method [Symbol] The method called against each member of the collection to provide the text
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @option label text [String] the label text
     # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
     # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
     # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
+    # @param options [Hash] Options hash passed through to Rails' +collection_select+ helper
+    # @param html_options [Hash] HTML Options hash passed through to Rails' +collection_select+ helper
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
+    # @see https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-collection_select Rails collection_select (called by govuk_collection_select)
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
     # @example A select box with hint
@@ -320,7 +372,7 @@ module GOVUKDesignSystemFormBuilder
     #     @grades,
     #     :id,
     #     :name,
-    #     hint_text: "If you took the test more than once enter your highest grade"
+    #     hint: { text: "If you took the test more than once enter your highest grade" }
     #
     # @example A select box with injected content
     #   = f.govuk_collection_select(:favourite_colour, @colours, :id, :name) do
@@ -332,7 +384,7 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_collection_select(:team, @teams, :id, :name) do
     #     label: -> { tag.h3("Which team did you represent?") }
     #
-    def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, caption: {}, &block)
+    def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint: {}, label: {}, caption: {}, form_group: {}, &block)
       Elements::Select.new(
         self,
         object_name,
@@ -340,11 +392,12 @@ module GOVUKDesignSystemFormBuilder
         collection,
         value_method: value_method,
         text_method: text_method,
-        hint_text: hint_text,
+        hint: hint,
         label: label,
         caption: caption,
         options: options,
         html_options: html_options,
+        form_group: form_group,
         &block
       ).html
     end
@@ -368,12 +421,15 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_method [Symbol, Proc, nil] The method called against each member of the collection to provide the hint text.
     #   When a +Proc+ is provided it must take a single argument that is a single member of the collection.
     #   When a +nil+ value is provided the hint text will be retrieved from the locale. This is the default and param can be omitted.
-    # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param legend [Hash,Proc] options for configuring the legend
     # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
     # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
     # @param bold_labels [Boolean] controls whether the radio button labels are bold
-    # @param classes [String] Classes to add to the radio button container.
+    # @param classes [Array,String] Classes to add to the radio button container.
     # @option legend text [String] the fieldset legend's text content
     # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
     # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
@@ -396,7 +452,7 @@ module GOVUKDesignSystemFormBuilder
     #    ->(option) { option.name.upcase },
     #    :description,
     #    legend: { text: 'Pick your favourite colour', size: 'm' },
-    #    hint_text: 'If you cannot find the exact match choose something close',
+    #    hint: { text: 'If you cannot find the exact match choose something close' },
     #    inline: false
     #
     # @example A collection of radio buttons for grades with injected content
@@ -415,7 +471,7 @@ module GOVUKDesignSystemFormBuilder
     #    :name,
     #    legend: -> { tag.h3('Which category do you belong to?') }
     #
-    def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, caption: {}, inline: false, small: false, bold_labels: false, classes: nil, &block)
+    def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, inline: false, small: false, bold_labels: false, classes: nil, form_group: {}, &block)
       Elements::Radios::Collection.new(
         self,
         object_name,
@@ -424,13 +480,14 @@ module GOVUKDesignSystemFormBuilder
         value_method: value_method,
         text_method: text_method,
         hint_method: hint_method,
-        hint_text: hint_text,
+        hint: hint,
         legend: legend,
         caption: caption,
         inline: inline,
         small: small,
         bold_labels: bold_labels,
         classes: classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -443,7 +500,10 @@ module GOVUKDesignSystemFormBuilder
     #   is set to +link_errors: true+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param legend [Hash,Proc] options for configuring the legend
     # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
     # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
@@ -454,8 +514,11 @@ module GOVUKDesignSystemFormBuilder
     # @param caption [Hash] configures or sets the caption content which is inserted above the legend
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] a block of HTML that will be used to populate the fieldset
-    # @param classes [String] Classes to add to the radio button container.
+    # @param classes [Array,String] Classes to add to the radio button container.
     # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
     # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     # @return [ActiveSupport::SafeBuffer] HTML output
@@ -477,15 +540,18 @@ module GOVUKDesignSystemFormBuilder
     #      = f.govuk_radio_button :burger_id, :regular, label: { text: 'Hamburger' }, link_errors: true
     #      = f.govuk_radio_button :burger_id, :cheese, label: { text: 'Cheeseburger' }
     #
-    def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, caption: {}, inline: false, small: false, classes: nil, &block)
-      Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, caption: caption, inline: inline, small: small, classes: classes, &block).html
+    def govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, classes: nil, form_group: {}, &block)
+      Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint: hint, legend: legend, caption: caption, inline: inline, small: small, classes: classes, form_group: form_group, &block).html
     end
 
     # Generates a radio button
     #
     # @note This should only be used from within a {#govuk_radio_buttons_fieldset}
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] the contents of the hint
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @option legend text [String] the fieldset legend's text content
     # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
     # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
@@ -503,8 +569,8 @@ module GOVUKDesignSystemFormBuilder
     #  = f.govuk_radio_buttons_fieldset :favourite_colour do
     #    = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
     #
-    def govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, link_errors: false, &block)
-      Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint_text: hint_text, label: label, link_errors: link_errors, &block).html
+    def govuk_radio_button(attribute_name, value, hint: {}, label: {}, link_errors: false, &block)
+      Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint: hint, label: label, link_errors: link_errors, &block).html
     end
 
     # Inserts a text divider into a list of radio buttons
@@ -527,9 +593,12 @@ module GOVUKDesignSystemFormBuilder
     # @param text_method [Symbol] The method called against each member of the collection to provide the label text
     # @param hint_method [Symbol, Proc] The method called against each member of the collection to provide the hint text.
     #   When a +Proc+ is provided it must take a single argument that is a single member of the collection
-    # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
-    # @param classes [String] Classes to add to the checkbox container.
+    # @param classes [Array,String] Classes to add to the checkbox container.
     # @param legend [Hash,Proc] options for configuring the legend
     # @option legend text [String] the fieldset legend's text content
     # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
@@ -538,6 +607,9 @@ module GOVUKDesignSystemFormBuilder
     # @param caption [Hash] configures or sets the caption content which is inserted above the legend
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
@@ -554,7 +626,7 @@ module GOVUKDesignSystemFormBuilder
     #    :name,
     #    :description,
     #    legend: { text: 'What do you want in your sandwich?', size: 'm' },
-    #    hint_text: "If it isn't listed here, tough luck",
+    #    hint: { text: "If it isn't listed here, tough luck" },
     #    inline: false,
     #    classes: 'app-overflow-scroll',
     #
@@ -574,7 +646,7 @@ module GOVUKDesignSystemFormBuilder
     #    :name,
     #    legend: -> { tag.h3('What kind of sandwich do you want?') }
     #
-    def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, caption: {}, small: false, classes: nil, &block)
+    def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, classes: nil, form_group: {}, &block)
       Elements::CheckBoxes::Collection.new(
         self,
         object_name,
@@ -583,11 +655,12 @@ module GOVUKDesignSystemFormBuilder
         value_method: value_method,
         text_method: text_method,
         hint_method: hint_method,
-        hint_text: hint_text,
+        hint: hint,
         legend: legend,
         caption: caption,
         small: small,
         classes: classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -598,7 +671,10 @@ module GOVUKDesignSystemFormBuilder
     #   is set to +link_errors: true+
     #
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
     # @param legend [Hash,Proc] options for configuring the legend
     # @option legend text [String] the fieldset legend's text content
@@ -608,7 +684,10 @@ module GOVUKDesignSystemFormBuilder
     # @param caption [Hash] configures or sets the caption content which is inserted above the legend
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
-    # @param classes [String] Classes to add to the checkbox container.
+    # @param classes [Array,String] Classes to add to the checkbox container.
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] a block of HTML that will be used to populate the fieldset
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
@@ -622,16 +701,17 @@ module GOVUKDesignSystemFormBuilder
     #    = f.govuk_check_box :desired_filling, :lemonade, label: { text: 'Lemonade' }, link_errors: true
     #    = f.govuk_check_box :desired_filling, :fizzy_orange, label: { text: 'Fizzy orange' }
     #
-    def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint_text: {}, small: false, classes: nil, &block)
+    def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, classes: nil, form_group: {}, &block)
       Containers::CheckBoxesFieldset.new(
         self,
         object_name,
         attribute_name,
-        hint_text: hint_text,
+        hint: hint,
         legend: legend,
         caption: caption,
         small: small,
         classes: classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -640,7 +720,10 @@ module GOVUKDesignSystemFormBuilder
     #
     # @param attribute_name [Symbol] The name of the attribute
     # @param value [Boolean,String,Symbol,Integer] The value of the checkbox when it is checked
-    # @param hint_text [String] the contents of the hint
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
     # @option label text [String] the label text
     # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
@@ -656,15 +739,15 @@ module GOVUKDesignSystemFormBuilder
     #     multiple: false,
     #     link_errors: true,
     #     label: { text: 'Do you agree with our terms and conditions?' },
-    #     hint_text: 'You will not be able to proceed unless you do'
+    #     hint: { text: 'You will not be able to proceed unless you do' }
     #
-    def govuk_check_box(attribute_name, value, hint_text: nil, label: {}, link_errors: false, multiple: true, &block)
+    def govuk_check_box(attribute_name, value, hint: {}, label: {}, link_errors: false, multiple: true, &block)
       Elements::CheckBoxes::FieldsetCheckBox.new(
         self,
         object_name,
         attribute_name,
         value,
-        hint_text: hint_text,
+        hint: hint,
         label: label,
         link_errors: link_errors,
         multiple: multiple,
@@ -677,7 +760,7 @@ module GOVUKDesignSystemFormBuilder
     # @param text [String] the button text
     # @param warning [Boolean] makes the button red ({https://design-system.service.gov.uk/components/button/#warning-buttons warning}) when true
     # @param secondary [Boolean] makes the button grey ({https://design-system.service.gov.uk/components/button/#secondary-buttons secondary}) when true
-    # @param classes [String] Classes to add to the submit button
+    # @param classes [Array,String] Classes to add to the submit button
     # @param prevent_double_click [Boolean] adds JavaScript to safeguard the
     #   form from being submitted more than once
     # @param validate [Boolean] adds the formnovalidate to the submit button when true, this disables all
@@ -708,7 +791,10 @@ module GOVUKDesignSystemFormBuilder
     #   of {https://bugs.ruby-lang.org/issues/5988 this} bug, so incorrect dates like +2019-09-31+ will
     #   be 'rounded' up to +2019-10-01+.
     # @param attribute_name [Symbol] The name of the attribute
-    # @param hint_text [String] the contents of the hint
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @param legend [Hash,Proc] options for configuring the legend
     # @option legend text [String] the fieldset legend's text content
     # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
@@ -718,6 +804,9 @@ module GOVUKDesignSystemFormBuilder
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
     # @param omit_day [Boolean] do not render a day input, only capture month and year
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input group
     # @param date_of_birth [Boolean] if +true+ {https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values birth date auto completion attributes}
     #   will be added to the inputs
@@ -729,7 +818,7 @@ module GOVUKDesignSystemFormBuilder
     # @example A regular date input with a legend, hint and injected content
     #   = f.govuk_date_field :starts_on,
     #     legend: { 'When does your event start?' },
-    #     hint_text: 'Leave this field blank if you don't know exactly' } do
+    #     hint: { text: 'Leave this field blank if you don't know exactly' } do
     #
     #       p.govuk-inset-text
     #         | If you don't fill this in you won't be eligable for a refund
@@ -737,8 +826,8 @@ module GOVUKDesignSystemFormBuilder
     # @example A date input with legend supplied as a proc
     #  = f.govuk_date_field :finishes_on,
     #    legend: -> { tag.h3('Which category do you belong to?') }
-    def govuk_date_field(attribute_name, hint_text: nil, legend: {}, caption: {}, date_of_birth: false, omit_day: false, &block)
-      Elements::Date.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, caption: caption, date_of_birth: date_of_birth, omit_day: omit_day, &block).html
+    def govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group: {}, &block)
+      Elements::Date.new(self, object_name, attribute_name, hint: hint, legend: legend, caption: caption, date_of_birth: date_of_birth, omit_day: omit_day, form_group: form_group, &block).html
     end
 
     # Generates a summary of errors in the form, each linking to the corresponding
@@ -794,8 +883,14 @@ module GOVUKDesignSystemFormBuilder
     # @param caption [Hash] configures or sets the caption content which is inserted above the label
     # @option caption text [String] the caption text
     # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
-    # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
+    # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
+    #   supplied the hint will be wrapped in a +div+ instead of a +span+
+    # @option hint text [String] the hint text
+    # @option hint args [Hash] additional arguments are applied as attributes to the hint
     # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group args [Hash] additional attributes added to the form group
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     #
     # @example A photo upload field with file type specifier and injected content
@@ -814,8 +909,8 @@ module GOVUKDesignSystemFormBuilder
     # @note Remember to set +multipart: true+ when creating a form with file
     #   uploads, {https://guides.rubyonrails.org/form_helpers.html#uploading-files see
     #   the Rails documentation} for more information
-    def govuk_file_field(attribute_name, label: {}, caption: {}, hint_text: nil, **args, &block)
-      Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint_text: hint_text, **args, &block).html
+    def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **args, &block)
+      Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **args, &block).html
     end
   end
 end