RubyGems - govuk_design_system_formbuilder - Versions diffs - 1.2.7 → 2.0.0b4 - Mend

govuk_design_system_formbuilder 1.2.7 → 2.0.0b4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

checksums.yaml CHANGED

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73f7852a0c839a3c662b7c5551c2e3e96d37c32fde6af4ad861cfd37f8c0d79f
-  data.tar.gz: 3252d8a1c64a4457de52ad87c2a7c9e5945b7400e7ee279c8e3910ee8f4a0cc4
+  metadata.gz: d1a220934d67c1a26afea6d623bd2424156b6b4b71ef88411703da5ae761d778
+  data.tar.gz: 808f12be46a25c60e1b1f97d074778bb1a8e1245a78a37672b6282dc4cdeb1fd
 SHA512:
-  metadata.gz: 9dd6efdac09f58e06bb8241aacc420bfb016960320cbbf4c9496ed163a5f2ff1f63c79d5f5dca381b7da4f5efa5c75997a8a10542755de3f8a67adb19393756e
-  data.tar.gz: b8ea6181c35e29784d8ebcb00bdb1a9d32d5970b26d260336413aaa8b475bee0a7ff085b64e05cb385014563ea7fb8799847c59d2408726a1fdd5b733b55b844
+  metadata.gz: 8fa051693840ca2463c6115bb0e4e4e53d68a0322697d49d186f83328635abee391466474da54cdc82fcbc77c28b055b10d7cb8374495965d00d8c4a8562134f
+  data.tar.gz: e8e93bdcbcd3d00b6d62477c52e0f2b4fa387de30825c479db38e1dfb4a1be89e316ff091c3eef1a0f0a917ad12581c26a565dc46cdfa55e1f5212053e459992

data/README.md CHANGED

@@ -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.8.1-brightgreen)](https://design-system.service.gov.uk)
+[![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.9.0-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.8.1 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
+fully-compliant with version 3.9.0 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/builder.rb CHANGED

@@ -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 kwargs [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
@@ -13,11 +17,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -26,7 +36,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'
     #
@@ -41,14 +51,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, form_group_classes: nil, **args, &block)
-      Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::Text.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &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 kwargs [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
@@ -56,11 +69,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -70,7 +89,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'
     #
@@ -85,14 +104,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, form_group_classes: nil, **args, &block)
-      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &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 kwargs [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
@@ -100,11 +122,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -127,14 +155,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, form_group_classes: nil, **args, &block)
-      Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::Email.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &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 kwargs [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
@@ -142,11 +173,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -168,14 +205,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, form_group_classes: nil, caption: {}, **args, &block)
-      Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &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 kwargs [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,11 +223,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -210,14 +256,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, form_group_classes: nil, **args, &block)
-      Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::URL.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &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 kwargs [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
@@ -225,11 +274,17 @@ module GOVUKDesignSystemFormBuilder
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @option kwargs [Hash] kwargs 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 kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @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
@@ -255,8 +310,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, form_group_classes: nil, **args, &block)
-      Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
+      Elements::Inputs::Number.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, prefix_text: prefix_text, suffix_text: suffix_text, **kwargs, &block).html
     end
     # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -264,21 +319,28 @@ 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 kwargs [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
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
     # @param max_words [Integer] adds the GOV.UK max word count
     # @param max_chars [Integer] adds the GOV.UK max characters count
     # @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_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option kwargs [Hash] kwargs 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 kwargs [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
@@ -304,8 +366,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, form_group_classes: 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, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **kwargs, &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, **kwargs, &block).html
     end
     # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -314,14 +376,20 @@ 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 kwargs [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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group kwargs [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
@@ -331,7 +399,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
@@ -343,7 +411,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: {}, form_group_classes: nil, &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,
@@ -351,12 +419,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_classes: form_group_classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -380,8 +448,11 @@ 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 legend [Hash,Proc] options for configuring the legend
+    # @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 kwargs [Hash] additional arguments are applied as attributes to the hint
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @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
@@ -390,9 +461,11 @@ module GOVUKDesignSystemFormBuilder
     # @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+
     # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
     # @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+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
     # @example A collection of radio buttons for favourite colours, labels capitalised via a proc
@@ -408,7 +481,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
@@ -427,7 +500,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, form_group_classes: nil, &block)
+    def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method = nil, 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,
@@ -436,14 +509,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_classes: form_group_classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -456,18 +529,25 @@ 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 legend [Hash,Proc] options for configuring the legend
+    # @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 kwargs [Hash] additional arguments are applied as attributes to the hint
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @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
     # @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+
     # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
     # @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_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group kwargs [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 [Array,String] Classes to add to the radio button container.
     # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
@@ -491,19 +571,24 @@ 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, form_group_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, form_group_classes: form_group_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
-    # @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+
-    # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @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 kwargs [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
+    # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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
     # @param block [Block] Any supplied HTML will be wrapped in a conditional
@@ -517,8 +602,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
@@ -541,10 +626,13 @@ 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 kwargs [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 [Array,String] Classes to add to the checkbox container.
-    # @param legend [Hash,Proc] options for configuring the legend
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @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+
@@ -552,7 +640,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 form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group kwargs [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
     #
@@ -569,7 +660,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',
     #
@@ -589,7 +680,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, form_group_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,
@@ -598,12 +689,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_classes: form_group_classes,
+        form_group: form_group,
         &block
       ).html
     end
@@ -614,18 +705,27 @@ 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 kwargs [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
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @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+
     # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
     # @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+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
     # @param classes [Array,String] Classes to add to the checkbox container.
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @param form_group [Hash] configures the form group
+    # @param multiple [Boolean] when true adds a +[]+ suffix the +name+ of the automatically-generated hidden field
+    #   (ie. <code>project[invoice_attributes][]</code>). When false, no +[]+ suffix is added (ie. <code>project[accepted]</code>)
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group kwargs [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
     #
@@ -639,17 +739,18 @@ 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, form_group_classes: nil, &block)
+    def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, classes: nil, form_group: {}, multiple: true, &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_classes: form_group_classes,
+        form_group: form_group,
+        multiple: multiple,
         &block
       ).html
     end
@@ -658,12 +759,17 @@ 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 unchecked_value [Boolean,String,Symbol,Integer] The value of the checkbox when it is unchecked
+    # @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 kwargs [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
     # @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
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @param multiple [Boolean] controls whether the check box is part of a collection or represents a single attribute
     # @param block [Block] any HTML passed in will form the contents of the fieldset
     # @return [ActiveSupport::SafeBuffer] HTML output
@@ -674,15 +780,16 @@ 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, unchecked_value = false, hint: {}, label: {}, link_errors: false, multiple: true, &block)
       Elements::CheckBoxes::FieldsetCheckBox.new(
         self,
         object_name,
         attribute_name,
         value,
-        hint_text: hint_text,
+        unchecked_value,
+        hint: hint,
         label: label,
         link_errors: link_errors,
         multiple: multiple,
@@ -726,17 +833,24 @@ 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 legend [Hash,Proc] options for configuring the legend
+    # @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 kwargs [Hash] additional arguments are applied as attributes to the hint
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @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+
     # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
     # @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+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
     # @param omit_day [Boolean] do not render a day input, only capture month and year
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @param form_group [Hash] configures the form group
+    # @option form_group classes [Array,String] sets the form group's classes
+    # @option form_group kwargs [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
@@ -748,7 +862,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
@@ -756,8 +870,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, form_group_classes: nil, &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, form_group_classes: form_group_classes, &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
@@ -775,15 +889,17 @@ module GOVUKDesignSystemFormBuilder
     # Generates a fieldset containing the contents of the block
     #
-    # @param legend [Hash,Proc] options for configuring the legend
+    # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
     # @param described_by [Array<String>] the ids of the elements that describe this fieldset, usually hints and errors
     # @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+
     # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
     # @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+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
     #
     # @example A fieldset containing address fields
     #   = f.govuk_fieldset legend: { text: 'Address' }
@@ -810,12 +926,19 @@ module GOVUKDesignSystemFormBuilder
     # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
     # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
     # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
+    # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
     # @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+
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
-    # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
+    # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
+    # @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 kwargs [Hash] additional arguments are applied as attributes to the hint
+    # @option kwargs [Hash] kwargs 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 kwargs [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
@@ -834,8 +957,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, form_group_classes: nil, **args, &block)
-      Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint_text: hint_text, form_group_classes: form_group_classes, **args, &block).html
+    def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **kwargs, &block)
+      Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **kwargs, &block).html
     end
   end
 end