govuk_design_system_formbuilder 1.1.10 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20300d83e65da38b6ae0b3a20a6e4e1bbdd9d04a9911ecf29829417abe5ba6f
-  data.tar.gz: a62f856b0804bc22eacfabcf7c31166651cee64d2dee82d8454b92a693a4b553
+  metadata.gz: db9e3152ce56de44fbcb67ed0110cf9613ed0180597baf36cbc93316c41c72c5
+  data.tar.gz: 5df5f7b19116b6846cbe305e14006993b86194db2677017c29344f7132ad6f54
 SHA512:
-  metadata.gz: 586414dba6e14f1f4d8f16638b6634c1aedbadf600e4fbaf2ea67fd7bcae93cca3046a247187d08df5a609ceec318526f0effa4183fe8f903288f76926535e0a
-  data.tar.gz: 323c190132caefde2e449f6b8f9088fdd13a58a520c166a17c43b35d53bc13c613c770b4fea82efc470ad5c90fdcf0e976226bc61811430ff1e301f5d8e1a66c
+  metadata.gz: bfc94cbbf30b95c91c136dd00db6d666d631d94edcecb0e673eb9e03d0771b739b00a58708c967cf720a4dc1bc10af929faea8aee8b6f44ab2916434a0c0bc7f
+  data.tar.gz: 721f67fb7fa2eb2883fd6d47c89b4aa86b4dcdae371501fb151d9d050132be1a59a739197216c1726566fb1f28bbba9a64fbc41dd8eec4b946abaddddb06bc3f

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

@@ -11,6 +11,9 @@ module GOVUKDesignSystemFormBuilder
 
   # Default form builder configuration
   #
+  # * +:brand+ sets the value used to prefix all classes, used to allow the
+  #   builder to be branded for alternative (similar) design systems.
+  #
   # * +:default_legend_size+ controls the default size of legend text.
   #   Can be either +xl+, +l+, +m+ or +s+.
   #
@@ -38,6 +41,8 @@ module GOVUKDesignSystemFormBuilder
   #   particular context, allowing them to be independently customised.
   # ===
   DEFAULTS = {
+    brand: 'govuk',
+
     default_legend_size: 'm',
     default_legend_tag: 'h1',
     default_submit_button_text: 'Continue',
@@ -47,7 +52,8 @@ module GOVUKDesignSystemFormBuilder
     localisation_schema_fallback: %i(helpers __context__),
     localisation_schema_label: nil,
     localisation_schema_hint: nil,
-    localisation_schema_legend: nil
+    localisation_schema_legend: nil,
+    localisation_schema_caption: nil
   }.freeze
 
   DEFAULTS.each_key { |k| config_accessor(k) { DEFAULTS[k] } }

data/lib/govuk_design_system_formbuilder/base.rb

@@ -1,4 +1,12 @@
 module GOVUKDesignSystemFormBuilder
+  module PrefixableArray
+    refine Array do
+      def prefix(text, delimiter: '-')
+        map { |item| text + delimiter + item }
+      end
+    end
+  end
+
   class Base
     delegate :capture, :content_tag, :safe_join, :tag, :raw, :link_to, to: :@builder
     delegate :config, to: GOVUKDesignSystemFormBuilder
@@ -12,6 +20,10 @@ module GOVUKDesignSystemFormBuilder
 
   private
 
+    def brand(override = nil)
+      override || config.brand
+    end
+
     # returns the id value used for the input
     #
     # @note field_id is overridden so that the error summary can link to the

data/lib/govuk_design_system_formbuilder/builder.rb

@@ -8,15 +8,19 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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 args [Hash] args additional arguments are applied as attributes to +input+ 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 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
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example A required full name field with a placeholder
     #   = f.govuk_text_field :name,
@@ -24,8 +28,20 @@ module GOVUKDesignSystemFormBuilder
     #     hint_text: 'It says it on your birth certificate',
     #     required: true,
     #     placeholder: 'Ralph Wiggum'
-    def govuk_text_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example A text field with injected content
+    #   = f.govuk_text_field :pseudonym,
+    #     label: { text: 'Pseudonym' } do
+    #
+    #     p.govuk-inset-text
+    #       | Ensure your stage name is unique
+    #
+    # @example A text field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a input of type +tel+
@@ -34,16 +50,20 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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 args [Hash] args additional arguments are applied as attributes to +input+ 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 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
     # @see https://design-system.service.gov.uk/patterns/telephone-numbers/ GOV.UK Telephone number patterns
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example A required phone number field with a placeholder
     #   = f.govuk_phone_field :phone_number,
@@ -51,8 +71,20 @@ module GOVUKDesignSystemFormBuilder
     #     hint_text: 'Include the dialling code',
     #     required: true,
     #     placeholder: '0123 456 789'
-    def govuk_phone_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example A phone field with injected content
+    #   = f.govuk_phone_field :fax_number,
+    #     label: { text: 'Fax number' } do
+    #
+    #     p.govuk-inset-text
+    #       | Yes, fax machines are still a thing
+    #
+    # @example A phone field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a input of type +email+
@@ -61,23 +93,39 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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 args [Hash] args additional arguments are applied as attributes to +input+ 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 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
     # @see https://design-system.service.gov.uk/patterns/email-addresses/ GOV.UK Email address patterns
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example An email address field with a placeholder
     #   = f.govuk_email_field :email_address,
     #     label: { text: 'Enter your email address' },
     #     placeholder: 'ralph.wiggum@springfield.edu'
-    def govuk_email_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example An email field with injected content
+    #   = f.govuk_phone_field :work_email,
+    #     label: { text: 'Work email address' } do
+    #
+    #     p.govuk-inset-text
+    #       | Use your work address
+    #
+    # @example A email field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a input of type +password+
@@ -86,22 +134,38 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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 args [Hash] args additional arguments are applied as attributes to +input+ 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 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
     # @see https://design-system.service.gov.uk/patterns/passwords/ GOV.UK Password patterns
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example A password field
     #   = f.govuk_password_field :password,
     #     label: { text: 'Enter your password' }
-    def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example A password field with injected content
+    #   = f.govuk_password_field :password,
+    #     label: { text: 'Password' } do
+    #
+    #     p.govuk-inset-text
+    #       | Ensure your password is at least 16 characters long
+    #
+    # @example A password field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a input of type +url+
@@ -110,23 +174,39 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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 args [Hash] args additional arguments are applied as attributes to +input+ 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 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
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example A url field with autocomplete
     #   = f.govuk_url_field :favourite_website,
     #     label: { text: 'Enter your favourite website' },
     #     placeholder: 'https://www.gov.uk',
     #     autocomplete: 'url'
-    def govuk_url_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example A url field with injected content
+    #   = f.govuk_url_field :personal_website,
+    #     label: { text: 'Enter your website' } do
+    #
+    #       p.govuk-inset-text
+    #         | This will be visible on your profile
+    #
+    # @example A url field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a input of type +number+
@@ -135,15 +215,19 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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 [Hash] label configures the associated label
+    # @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
+    # @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 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
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
     # @example A number field with placeholder, min, max and step
     #   = f.govuk_number_field :iq,
@@ -152,8 +236,21 @@ module GOVUKDesignSystemFormBuilder
     #     min: 80,
     #     max: 150,
     #     step: 5
-    def govuk_number_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
-      Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
+    #
+    # @example A number field with injected content
+    #   = f.govuk_number_field :height_in_cm,
+    #     label: { text: 'Height in centimetres' } do
+    #
+    #       p.govuk-inset-text
+    #         | If you haven't measured your height in the last 6 months
+    #           do it now
+    #
+    # @example A number field with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -162,11 +259,14 @@ module GOVUKDesignSystemFormBuilder
     #
     # @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 [Hash] label configures the associated label
+    # @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
+    # @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 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
@@ -174,17 +274,31 @@ module GOVUKDesignSystemFormBuilder
     # @option args [Hash] args additional arguments are applied as attributes to the +textarea+ element
     # @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
     # @see https://design-system.service.gov.uk/components/character-count GOV.UK character count component
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     # @note Setting +max_chars+ or +max_words+ will add a caption beneath the +textarea+ with a live count of words
     #   or characters
     #
     # @example A text area with a custom number of rows and a word limit
-    #   = f.govuk_number_field :cv,
+    #   = f.govuk_text_area :cv,
     #     label: { text: 'Tell us about your work history' },
     #     rows: 8,
     #     max_words: 300
-    def govuk_text_area(attribute_name, hint_text: nil, label: {}, 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, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, **args, &block).html
+    #
+    # @example A text area with injected content
+    #   = f.govuk_text_area :description,
+    #     label: { text: 'Where did the incident take place?' } do
+    #
+    #     p.govuk-inset-text
+    #       | If you don't know exactly leave this section blank
+    #
+    # @example A text area with the label supplied as a proc
+    #   = 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
     end
 
     # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -200,7 +314,25 @@ module GOVUKDesignSystemFormBuilder
     # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
-    def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, &block)
+    #
+    # @example A select box with hint
+    #   = f.govuk_collection_select :grade,
+    #     @grades,
+    #     :id,
+    #     :name,
+    #     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
+    #
+    #       p.govuk-inset-text
+    #         | Select the closest match
+    #
+    # @example A select box with the label supplied as a proc
+    #   = 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)
       Elements::Select.new(
         self,
         object_name,
@@ -210,6 +342,7 @@ module GOVUKDesignSystemFormBuilder
         text_method: text_method,
         hint_text: hint_text,
         label: label,
+        caption: caption,
         options: options,
         html_options: html_options,
         &block
@@ -229,19 +362,25 @@ module GOVUKDesignSystemFormBuilder
     # @param collection [Enumerable<Object>] Options to be added to the +select+ element
     # @param value_method [Symbol, Proc] The method called against each member of the collection to provide the value.
     #   When a +Proc+ is provided it must take a single argument that is a single member of the collection
-    # @param text_method [Symbol, Proc] The method called against each member of the collection to provide the label text.
-    #   When a +Proc+ is provided it must take a single argument that is a single member of the collection
-    # @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 text_method [Symbol, Proc, nil] The method called against each member of the collection to provide the label 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 label text will be retrieved from the locale.
+    # @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] options for configuring the legend
+    # @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.
     # @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+, defaults to +h1+
+    # @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 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+
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
     # @example A collection of radio buttons for favourite colours, labels capitalised via a proc
@@ -259,7 +398,24 @@ module GOVUKDesignSystemFormBuilder
     #    legend: { text: 'Pick your favourite colour', size: 'm' },
     #    hint_text: 'If you cannot find the exact match choose something close',
     #    inline: false
-    def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, inline: false, small: false, bold_labels: false, classes: nil, &block)
+    #
+    # @example A collection of radio buttons for grades with injected content
+    #  = f.govuk_collection_radio_buttons :grade,
+    #    @grades,
+    #    :id,
+    #    :name do
+    #
+    #      p.govuk-inset-text
+    #        | If you took the test more than once enter your highest grade
+    #
+    # @example A collection of radio buttons with the legend supplied as a proc
+    #  = f.govuk_collection_radio_buttons :category,
+    #    @categories,
+    #    :id,
+    #    :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)
       Elements::Radios::Collection.new(
         self,
         object_name,
@@ -270,6 +426,7 @@ module GOVUKDesignSystemFormBuilder
         hint_method: hint_method,
         hint_text: hint_text,
         legend: legend,
+        caption: caption,
         inline: inline,
         small: small,
         bold_labels: bold_labels,
@@ -282,29 +439,46 @@ module GOVUKDesignSystemFormBuilder
     #
     # @note The intention is to use {#govuk_radio_button} and {#govuk_radio_divider} within the passed-in block
     #
+    # @note To ensure the {#govuk_error_summary} link functions correctly ensure the first {#govuk_radio_button}
+    #   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] options for configuring the legend
+    # @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
     # @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 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 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.
     # @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
     #
-    # @example A collection of radio buttons for favourite colours with a divider
+    # @example A radio button fieldset for favourite colours with a divider
     #
-    #  = f.govuk_collection_radio_buttons :favourite_colour, inline: false do
-    #    = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
+    #  = f.govuk_radio_buttons_fieldset :favourite_colour, inline: false do
+    #    = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }, link_errors: true
     #    = f.govuk_radio_button :favourite_colour, :green, label: { text: 'Green' }
     #    = f.govuk_radio_divider
     #    = f.govuk_radio_button :favourite_colour, :yellow, label: { text: 'Yellow' }
     #
-    def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, inline: false, small: false, classes: nil, &block)
-      Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, inline: inline, small: small, classes: classes, &block).html
+    # @example A radio button fieldset with the legend supplied as a proc
+    #  = f.govuk_radio_buttons_fieldset :burger_id do
+    #    @burgers,
+    #    :id,
+    #    :name,
+    #    legend: -> { tag.h3('Which hamburger do you want with your meal?') } do
+    #      = 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
     end
 
     # Generates a radio button
@@ -315,17 +489,19 @@ module GOVUKDesignSystemFormBuilder
     # @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
     # @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
     #   container and only revealed when the radio button is picked
-    # @param link_errors [Boolean] controls whether this radio button should be linked to
+    # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
     #   from the error summary. <b>Should only be set to +true+ for the first radio button in a fieldset</b>
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
-    # @example A collection of radio buttons for favourite colours with a divider
+    # @example A single radio button for our new favourite colour
     #
-    #  = f.govuk_collection_radio_buttons :favourite_colour, inline: false do
-    #    = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' } do
+    #  = 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
@@ -354,10 +530,14 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
     # @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 legend [Hash] options for configuring the legend
+    # @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+
     # @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 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 block [Block] any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
@@ -377,7 +557,24 @@ module GOVUKDesignSystemFormBuilder
     #    hint_text: "If it isn't listed here, tough luck",
     #    inline: false,
     #    classes: 'app-overflow-scroll',
-    def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, classes: nil, &block)
+    #
+    # @example A collection of check boxes for types of bread
+    #  = f.govuk_collection_check_boxes :bread,
+    #    @variety,
+    #    :id,
+    #    :name do
+    #
+    #      p.govuk-inset-text
+    #        | Only Hearty Italian is available with the meal deal menu
+    #
+    # @example A collection of check boxes with the legend supplied as a proc
+    #  = f.govuk_collection_check_boxes :sandwich_type,
+    #    @breads,
+    #    :id,
+    #    :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)
       Elements::CheckBoxes::Collection.new(
         self,
         object_name,
@@ -388,6 +585,7 @@ module GOVUKDesignSystemFormBuilder
         hint_method: hint_method,
         hint_text: hint_text,
         legend: legend,
+        caption: caption,
         small: small,
         classes: classes,
         &block
@@ -396,42 +594,54 @@ module GOVUKDesignSystemFormBuilder
 
     # Generate a fieldset intended to conatain one or more {#govuk_check_box}
     #
+    # @note To ensure the {#govuk_error_summary} link functions correctly ensure the first {#govuk_check_box}
+    #   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 small [Boolean] controls whether small check boxes are used instead of regular-sized ones
-    # @param legend [Hash] options for configuring the legend
+    # @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+
     # @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 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 block [Block] a block of HTML that will be used to populate the fieldset
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
     # @example A collection of check boxes for sandwich fillings
-    #
-    #  = f.govuk_check_boxes_fieldset :desired_filling,
+    #  = f.govuk_check_boxes_fieldset :desired_filling, legend: { text: 'Which filling do you want?' },
     #    = f.govuk_check_box :desired_filling, :cheese, label: { text: 'Cheese' }, link_errors: true
     #    = f.govuk_check_box :desired_filling, :tomato, label: { text: 'Tomato' }
     #
-    def govuk_check_boxes_fieldset(attribute_name, legend: {}, hint_text: {}, small: false, classes: nil, &block)
+    # @example A collection of check boxes for drinks choices with legend as a proc
+    #  = f.govuk_check_boxes_fieldset :drink_id, legend: -> { tag.h3('Choose drinks to accompany your meal') },
+    #    = 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)
       Containers::CheckBoxesFieldset.new(
         self,
         object_name,
         attribute_name,
         hint_text: hint_text,
         legend: legend,
+        caption: caption,
         small: small,
         classes: classes,
         &block
       ).html
     end
 
-    # Generates a single fieldset, intended for use within a {#govuk_check_boxes_fieldset}
+    # Generates a single check box, intended for use within a {#govuk_check_boxes_fieldset}
     #
     # @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 link_errors [Boolean] controls whether this radio button should be linked to
+    # @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
@@ -469,6 +679,7 @@ module GOVUKDesignSystemFormBuilder
     # @param secondary [Boolean] makes the button grey ({https://design-system.service.gov.uk/components/button/#secondary-buttons secondary}) when true
     # @todo The GOV.UK design system also supports {https://design-system.service.gov.uk/components/button/#disabled-buttons disabled buttons}, they
     #   should probably be supported too
+    # @param classes [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
@@ -488,8 +699,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_submit "Proceed", prevent_double_click: true do
     #     = link_to 'Cancel', some_other_path, class: 'govuk-button__secondary'
     #
-    def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, prevent_double_click: true, validate: false, &block)
-      Elements::Submit.new(self, text, warning: warning, secondary: secondary, prevent_double_click: prevent_double_click, validate: validate, &block).html
+    def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, prevent_double_click: true, validate: false, &block)
+      Elements::Submit.new(self, text, warning: warning, secondary: secondary, classes: classes, prevent_double_click: prevent_double_click, validate: validate, &block).html
     end
 
     # Generates three inputs for the +day+, +month+ and +year+ components of a date
@@ -499,10 +710,14 @@ module GOVUKDesignSystemFormBuilder
     #   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] options for configuring the legend
+    # @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+
     # @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 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 omit_day [Boolean] do not render a day input, only capture month and year
     # @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}
@@ -510,13 +725,21 @@ module GOVUKDesignSystemFormBuilder
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
     # @see https://github.com/alphagov/govuk-frontend/issues/1449 GOV.UK date input element attributes, using text instead of number
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     #
-    # @example A regular date input with a legend and hint
+    # @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' }
-    def govuk_date_field(attribute_name, hint_text: nil, legend: {}, date_of_birth: false, omit_day: false, &block)
-      Elements::Date.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, date_of_birth: date_of_birth, omit_day: omit_day, &block).html
+    #     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
+    #
+    # @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
     end
 
     # Generates a summary of errors in the form, each linking to the corresponding
@@ -524,12 +747,6 @@ module GOVUKDesignSystemFormBuilder
     #
     # @param title [String] the error summary heading
     #
-    # @todo Currently the summary anchors link to the inline error messages themselves rather to
-    #   the accompanying input. More work is required to improve this and it needs to be
-    #   handled in a less-generic manner. For example, we can't link to a specific radio button
-    #   if one hasn't been chosen but we should link to a {#govuk_text_field} if one has been left
-    #   blank
-    #
     # @example An error summary with a custom title
     #   = f.govuk_error_summary 'Uh-oh, spaghettios'
     #
@@ -540,11 +757,15 @@ module GOVUKDesignSystemFormBuilder
 
     # Generates a fieldset containing the contents of the block
     #
-    # @param legend [Hash] options for configuring the legend
+    # @param legend [Hash,Proc] options for configuring the legend
     # @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
+    # @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+
     #
     # @example A fieldset containing address fields
     #   = f.govuk_fieldset legend: { text: 'Address' }
@@ -552,10 +773,16 @@ module GOVUKDesignSystemFormBuilder
     #     = f.govuk_text_field :town
     #     = f.govuk_text_field :city
     #
+    # @example A fieldset with the legend as a proc
+    #   = f.govuk_fieldset legend: -> { tag.h3('Skills') }
+    #     = f.govuk_text_area :physical
+    #     = f.govuk_text_area :mental
+    #
     # @see https://design-system.service.gov.uk/components/fieldset/ GOV.UK fieldset
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     # @return [ActiveSupport::SafeBuffer] HTML output
-    def govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block)
-      Containers::Fieldset.new(self, legend: legend, described_by: described_by).html(&block)
+    def govuk_fieldset(legend: { text: 'Fieldset heading' }, caption: {}, described_by: nil, &block)
+      Containers::Fieldset.new(self, legend: legend, caption: caption, described_by: described_by, &block).html
     end
 
     # Generates an input of type +file+
@@ -565,21 +792,31 @@ 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
+    # @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 +input+ element
+    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     #
-    # @example A photo upload field with file type specifier
-    #   = f.govuk_file_field :photo, label: { text: 'Upload your photo' }, accept: 'image/*'
+    # @example A photo upload field with file type specifier and injected content
+    #   = f.govuk_file_field :photo, label: { text: 'Upload your photo' }, accept: 'image/*' do
+    #
+    #     p.govuk-inset-text
+    #       | Explicit images will result in account termination
+    #
+    # @example A CV upload field with label as a proc
+    #   = f.govuk_file_field :cv, label: -> { tag.h3('Upload your CV') }
     #
     # @see https://design-system.service.gov.uk/components/file-upload/ GOV.UK file upload
+    # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
     # @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file MDN documentation for file upload
     #
     # @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: {}, hint_text: nil, **args, &block)
-      Elements::File.new(self, object_name, attribute_name, label: label, hint_text: hint_text, **args, &block).html
+    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
     end
   end
 end