govuk_design_system_formbuilder 2.0.0b1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52cc4abc62b3ac208e8fe2befb527b6deda60868d2094a3172d907bc0ce82654
-  data.tar.gz: fb0c810a65f025e226fe4dc0cee0c5b42b3b7baa499b032d6f88d4ec2fac9d54
+  metadata.gz: c55b78722270c864a735be507e018c420e14bee0e408c59da1bc61777c320bf7
+  data.tar.gz: b0d291bca6a13a77fe21db5c431bfea86184de8acd82b5e4cc3a3c944fdf322c
 SHA512:
-  metadata.gz: 996a9f979a4eab0a16499f81cf39fdcfbd0c641dd5d2944c52be697cd6f1f8870b75c6fd4b498d3769265fa39168f7baefe36bb53255bc50a9bfcb82f06bd641
-  data.tar.gz: ef2f8f3eaba7ea21b2ae18a7a4ba8c181981164f36917d082ff5f2545896df17c6b27c9acab09621d3e5453013d9e5747e5f838b54bc2f2e68aed585980190d9
+  metadata.gz: a130e8bb5964af17acb89a14f02ecda2ed989c1e18c6ed970a400945be78c5a8fdc0dd735333b026f51b75a5d090c4e6403f3594feedf595b21c294abec13ae7
+  data.tar.gz: 9afc6f6e12e26bdc2cd4eafc41f2d1e5a972829fd18bd2a2571550b683500320a66f6603d159af0e7c0943b57deeaf8b47267499ac4cf2c3577d207b555cfcba

data/README.md

@@ -7,41 +7,32 @@
 [![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.1-brightgreen)](https://design-system.service.gov.uk)
 
-This gem provides a easy-to-use form builder that generates forms that are
-fully-compliant with version 3.8.1 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
-minimising the amount of markup you need to write.
+This library provides an easy-to-use form builder for the [GOV.UK Design System](https://design-system.service.gov.uk/).
 
-In addition to the basic markup, the more-advanced functionality of the Design
-System is exposed via the API. Adding [JavaScript-enhanced word count
-checking](https://govuk-form-builder.netlify.app/form-elements/text-area/)
-to text areas or [setting the size and weight of
-labels](https://govuk-form-builder.netlify.app/introduction/labels-hints-and-legends/)
-on text fields requires only a single argument.
+It is intended to make creating forms **quick**, **easy** and **familiar** for Ruby on Rails developers.
 
 ## Documentation 📚
 
 The gem comes with [a full guide](https://govuk-form-builder.netlify.app/) that
-covers most aspects of day-to-day use, along with code and output examples. The guide
-is generated from the builder itself so it will always be up to date.
-
-If you're still not sure what a form builder is or how it works, don't worry!
-[This screencast](https://www.youtube.com/watch?v=PhoFZ0qXAlA) should give you
-an idea of what's on offer and the official guide goes into a bit more depth on
-how everything works.
+covers most aspects of day-to-day use, along with code and output examples. The
+examples in the guide are generated from the builder itself so it will always
+be up to date.
 
 [![Netlify Status](https://api.netlify.com/api/v1/badges/d4c50b8d-6ca3-4797-9ab3-6e0731c72b44/deploy-status)](https://app.netlify.com/sites/govuk-form-builder/deploys)
 
 ## What's included 🧳
 
 * 100% compatibility with the GOV.UK Design System
-* Full control of labels, hints, fieldsets and legends
+* Full control of labels, legends, hints, captions and fieldsets
 * No overwriting of Rails' default form helpers
 * Automatic ARIA associations between hints, errors and inputs
 * Most helpers take blocks for arbitrary content
 * Additional params for programmatically adding hints to check box and radio
   button collections
+* Full I18n support
+* Automatic handling of ActiveRecord validation error messages
 * No external dependencies
 * An exhaustive test suite
 * [Extensive technical documentation](https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder)
@@ -68,8 +59,9 @@ pre-configured template:
 
 ## Setup 🔧
 
-To use the form builder in an ad hoc basis you can specify it
-as an argument to `form_for` or `form_with`:
+To use the form builder in an ad hoc basis you can specify it as an argument to
+`form_for` or `form_with`. These examples are written in [Slim](https://slim-lang.com) but
+other templating languages like ERB and [Haml](https://haml.info/) work just as well.
 
 ```slim
 = form_for @some_object, builder: GOVUKDesignSystemFormBuilder::FormBuilder do |f|
@@ -99,16 +91,16 @@ Now we can get started!
     :name,
     :description,
     label: { text: "Which department do you work for?" },
-    hint_text: "If you don't know ask your manager" }
+    hint: { text: "If you don't know ask your manager" }
 
   = f.govuk_submit 'Away we go!'
 ```
 
 ## Developing and running the tests 👨🏻‍🏭
 
-The form builder is covered by RSpec, to run all the tests first ensure that
-all of the development and testing prerequisite gems are installed. At the root
-of a freshly-cloned repo run:
+The form builder is tested with RSpec. To run all the tests first ensure that
+the development and testing prerequisite gems are installed. At the root of a
+freshly-cloned repo run:
 
 ```sh
 bundle
@@ -117,7 +109,7 @@ bundle
 Now, if everything was successful, run RSpec:
 
 ```sh
-bundle exec rspec -fd
+bundle exec rspec
 ```
 
 ## Contributing 📦

data/lib/govuk_design_system_formbuilder.rb

@@ -21,7 +21,7 @@ module GOVUKDesignSystemFormBuilder
   #   Can be either +xl+, +l+, +m+ or +s+.
   #
   # * +:default_legend_tag+ controls the default tag that legends are
-  #   wrapped in. Defaults to +h1+.
+  #   wrapped in. Defaults to +nil+.
   #
   # * +:default_submit_button_text+ sets the value assigned to +govuk_submit+,
   #   defaults to 'Continue'.
@@ -47,7 +47,7 @@ module GOVUKDesignSystemFormBuilder
     brand: 'govuk',
 
     default_legend_size: 'm',
-    default_legend_tag: 'h1',
+    default_legend_tag: nil,
     default_caption_size: 'm',
     default_submit_button_text: 'Continue',
     default_radio_divider_text: 'or',

data/lib/govuk_design_system_formbuilder/builder.rb

@@ -8,7 +8,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -17,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -47,8 +51,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_text_field :callsign,
     #     label: -> { tag.h3('Call-sign') }
     #
-    def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
-      Elements::Inputs::Text.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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+
@@ -57,7 +61,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -65,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -96,8 +104,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_phone_field :work_number,
     #     label: -> { tag.h3('Work number') }
     #
-    def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
-      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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+
@@ -106,7 +114,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -114,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -143,8 +155,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_email_field :personal_email,
     #     label: -> { tag.h3('Personal email address') }
     #
-    def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
-      Elements::Inputs::Email.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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+
@@ -153,7 +165,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -161,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -189,8 +205,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_password_field :passcode,
     #     label: -> { tag.h3('What is your secret pass code?') }
     #
-    def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, **args, &block)
-      Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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+
@@ -199,7 +215,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -207,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -236,8 +256,8 @@ module GOVUKDesignSystemFormBuilder
     #   = f.govuk_url_field :work_website,
     #     label: -> { tag.h3("Enter your company's website") }
     #
-    def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
-      Elements::Inputs::URL.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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+
@@ -246,7 +266,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
@@ -254,13 +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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -286,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: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
-      Elements::Inputs::Number.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
+    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
@@ -298,23 +322,25 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -340,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: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **args, &block)
-      Elements::TextArea.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, form_group: form_group, **args, &block).html
+    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
@@ -353,16 +379,17 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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 [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
-    # @option form_group args [Hash] additional attributes added to the form group
+    # @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
@@ -424,19 +451,21 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
-    # @param legend [Hash,Proc] options for configuring the legend
+    # @option 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
     # @param classes [Array,String] Classes to add to the radio button container.
     # @option legend text [String] the fieldset legend's text content
     # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
-    # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
+    # @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
@@ -471,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: {}, legend: {}, caption: {}, inline: false, small: false, bold_labels: false, classes: nil, form_group: {}, &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,
@@ -503,20 +532,22 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
-    # @param legend [Hash,Proc] options for configuring the legend
+    # @option 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 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 form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
-    # @option form_group args [Hash] additional attributes added to the form group
+    # @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
@@ -551,11 +582,13 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
-    # @option legend text [String] the fieldset legend's text content
-    # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
-    # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
-    # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
+    # @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
@@ -596,20 +629,21 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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+
+    # @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+
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
     #
@@ -674,20 +708,24 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
+    # @option 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 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 [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 args [Hash] additional attributes added to the form group
+    # @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
     #
@@ -701,7 +739,7 @@ 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: {}, small: false, classes: nil, form_group: {}, &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,
@@ -712,6 +750,7 @@ module GOVUKDesignSystemFormBuilder
         small: small,
         classes: classes,
         form_group: form_group,
+        multiple: multiple,
         &block
       ).html
     end
@@ -720,15 +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 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 args [Hash] additional arguments are applied as attributes to the hint
+    # @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
@@ -741,12 +782,13 @@ module GOVUKDesignSystemFormBuilder
     #     label: { text: 'Do you agree with our terms and conditions?' },
     #     hint: { text: 'You will not be able to proceed unless you do' }
     #
-    def govuk_check_box(attribute_name, value, hint: {}, 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,
+        unchecked_value,
         hint: hint,
         label: label,
         link_errors: link_errors,
@@ -774,6 +816,8 @@ module GOVUKDesignSystemFormBuilder
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @note Only the first additional button or link (passed in via a block) will be given the
     #   correct left margin, subsequent buttons will need to be manually accounted for
+    # @note This helper always renders an +<input type='submit'>+ tag, HTML content is not supported inside. You
+    #   can place +<button>+ tags inside the form to have the same effect
     # @see https://design-system.service.gov.uk/components/button/#stop-users-from-accidentally-sending-information-more-than-once
     #   GOV.UK double click prevention
     #
@@ -794,19 +838,21 @@ module GOVUKDesignSystemFormBuilder
     # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
     #   supplied the hint will be wrapped in a +div+ instead of a +span+
     # @option hint text [String] the hint text
-    # @option hint args [Hash] additional arguments are applied as attributes to the hint
-    # @param legend [Hash,Proc] options for configuring the legend
+    # @option 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 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 [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
-    # @option form_group args [Hash] additional attributes added to the form group
+    # @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
@@ -835,6 +881,9 @@ module GOVUKDesignSystemFormBuilder
     #
     # @param title [String] the error summary heading
     #
+    # @note Only the first error in the +#errors+ array for each attribute will
+    #   be included.
+    #
     # @example An error summary with a custom title
     #   = f.govuk_error_summary 'Uh-oh, spaghettios'
     #
@@ -845,24 +894,26 @@ 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 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' }
+    #   = f.govuk_fieldset legend: { text: 'Address' } do
     #     = f.govuk_text_field :street
     #     = 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_fieldset legend: -> { tag.h3('Skills') } do
     #     = f.govuk_text_area :physical
     #     = f.govuk_text_area :mental
     #
@@ -880,17 +931,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+
+    # @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 args [Hash] additional arguments are applied as attributes to the hint
-    # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
+    # @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 args [Hash] additional attributes added to the form group
+    # @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
@@ -909,8 +962,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: {}, form_group: {}, **args, &block)
-      Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **args, &block).html
+    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

data/lib/govuk_design_system_formbuilder/containers/check_boxes_fieldset.rb

@@ -4,7 +4,7 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Error
       include Traits::Hint
 
-      def initialize(builder, object_name, attribute_name, hint:, legend:, caption:, small:, classes:, form_group:, &block)
+      def initialize(builder, object_name, attribute_name, hint:, legend:, caption:, small:, classes:, form_group:, multiple:, &block)
         super(builder, object_name, attribute_name, &block)
 
         @legend        = legend
@@ -13,19 +13,30 @@ module GOVUKDesignSystemFormBuilder
         @small         = small
         @classes       = classes
         @form_group    = form_group
+        @multiple      = multiple
         @block_content = capture { block.call }
       end
 
       def html
         Containers::FormGroup.new(@builder, @object_name, @attribute_name, **@form_group).html do
           Containers::Fieldset.new(@builder, @object_name, @attribute_name, **fieldset_options).html do
-            safe_join([hint_element, error_element, checkboxes])
+            safe_join([hint_element, error_element, hidden_field, checkboxes])
           end
         end
       end
 
     private
 
+      def hidden_field
+        return unless @multiple
+
+        @builder.hidden_field(@attribute_name, value: "", name: hidden_field_name)
+      end
+
+      def hidden_field_name
+        format("%<object_name>s[%<attribute_name>s][]", object_name: @object_name, attribute_name: @attribute_name)
+      end
+
       def fieldset_options
         {
           legend: @legend,

data/lib/govuk_design_system_formbuilder/containers/form_group.rb

@@ -4,12 +4,12 @@ module GOVUKDesignSystemFormBuilder
       def initialize(builder, object_name, attribute_name, classes: nil, **kwargs)
         super(builder, object_name, attribute_name)
 
-        @classes       = classes
-        @extra_options = kwargs
+        @classes         = classes
+        @html_attributes = kwargs
       end
 
       def html
-        tag.div(class: classes, **@extra_options) { yield }
+        tag.div(class: classes, **@html_attributes) { yield }
       end
 
     private

data/lib/govuk_design_system_formbuilder/elements/caption.rb

@@ -3,21 +3,26 @@ module GOVUKDesignSystemFormBuilder
     class Caption < Base
       include Traits::Localisation
 
-      def initialize(builder, object_name, attribute_name, text:, size: nil)
+      def initialize(builder, object_name, attribute_name, text: nil, size: nil, **kwargs)
         super(builder, object_name, attribute_name)
 
-        @text       = text(text)
-        @size_class = size_class(size)
+        @text            = text(text)
+        @size_class      = size_class(size)
+        @html_attributes = kwargs
       end
 
       def html
-        return nil if @text.blank?
+        return nil unless active?
 
-        tag.span(@text, class: @size_class)
+        tag.span(@text, class: @size_class, **@html_attributes)
       end
 
     private
 
+      def active?
+        @text.present?
+      end
+
       def text(override)
         override || localised_text(:caption)
       end

data/lib/govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box.rb

@@ -8,14 +8,15 @@ module GOVUKDesignSystemFormBuilder
         include Traits::Hint
         include Traits::Conditional
 
-        def initialize(builder, object_name, attribute_name, value, label:, hint:, link_errors:, multiple:, &block)
+        def initialize(builder, object_name, attribute_name, value, unchecked_value, label:, hint:, link_errors:, multiple:, &block)
           super(builder, object_name, attribute_name)
 
-          @value       = value
-          @label       = label
-          @hint        = hint
-          @multiple    = multiple
-          @link_errors = link_errors
+          @value           = value
+          @unchecked_value = unchecked_value
+          @label           = label
+          @hint            = hint
+          @multiple        = multiple
+          @link_errors     = link_errors
 
           if block_given?
             @conditional_content = wrap_conditional(block)
@@ -36,7 +37,7 @@ module GOVUKDesignSystemFormBuilder
         end
 
         def check_box
-          @builder.check_box(@attribute_name, options, @value, false)
+          @builder.check_box(@attribute_name, options, @value, @unchecked_value)
         end
 
         def options

data/lib/govuk_design_system_formbuilder/elements/file.rb

@@ -11,11 +11,11 @@ module GOVUKDesignSystemFormBuilder
       def initialize(builder, object_name, attribute_name, hint:, label:, caption:, form_group:, **kwargs, &block)
         super(builder, object_name, attribute_name, &block)
 
-        @label         = label
-        @caption       = caption
-        @hint          = hint
-        @extra_options = kwargs
-        @form_group    = form_group
+        @label           = label
+        @caption         = caption
+        @hint            = hint
+        @html_attributes = kwargs
+        @form_group      = form_group
       end
 
       def html
@@ -27,7 +27,7 @@ module GOVUKDesignSystemFormBuilder
     private
 
       def file
-        @builder.file_field(@attribute_name, **options, **@extra_options)
+        @builder.file_field(@attribute_name, **options, **@html_attributes)
       end
 
       def options

data/lib/govuk_design_system_formbuilder/elements/hint.rb

@@ -8,20 +8,20 @@ module GOVUKDesignSystemFormBuilder
       def initialize(builder, object_name, attribute_name, value: nil, text: nil, content: nil, radio: false, checkbox: false, **kwargs)
         super(builder, object_name, attribute_name)
 
+        @value           = value
         @radio           = radio
         @checkbox        = checkbox
         @html_attributes = kwargs
 
         if content
-          @content = capture { content.call }
+          @raw = capture { content.call }
         else
-          @text  = retrieve_text(text)
-          @value = value
+          @text = retrieve_text(text)
         end
       end
 
       def active?
-        [@text, @content].any?(&:present?)
+        [@text, @raw].any?(&:present?)
       end
 
       def html
@@ -43,11 +43,11 @@ module GOVUKDesignSystemFormBuilder
       end
 
       def hint_tag
-        @content.presence ? 'div' : 'span'
+        @raw.presence ? 'div' : 'span'
       end
 
       def hint_body
-        @content || @text
+        @raw || @text
       end
 
       def retrieve_text(supplied)

data/lib/govuk_design_system_formbuilder/elements/label.rb

@@ -6,22 +6,24 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Caption
       include Traits::Localisation
 
-      def initialize(builder, object_name, attribute_name, text: nil, value: nil, size: nil, hidden: false, radio: false, checkbox: false, tag: nil, link_errors: true, content: nil, caption: nil)
+      def initialize(builder, object_name, attribute_name, text: nil, value: nil, size: nil, hidden: false, radio: false, checkbox: false, tag: nil, link_errors: true, content: nil, caption: nil, **kwargs)
         super(builder, object_name, attribute_name)
 
+        @value           = value # used by field_id
+        @tag             = tag
+        @radio           = radio
+        @checkbox        = checkbox
+        @link_errors     = link_errors
+        @html_attributes = kwargs
+
         # content is passed in directly via a proc and overrides
         # the other display options
         if content
           @content = capture { content.call }
         else
-          @value       = value # used by field_id
-          @text        = retrieve_text(text, hidden)
-          @size_class  = size_class(size)
-          @radio       = radio
-          @checkbox    = checkbox
-          @tag         = tag
-          @link_errors = link_errors
-          @caption     = caption
+          @text       = retrieve_text(text, hidden)
+          @size_class = size_class(size)
+          @caption    = caption
         end
       end
 
@@ -42,7 +44,7 @@ module GOVUKDesignSystemFormBuilder
     private
 
       def label
-        @builder.label(@attribute_name, **options) do
+        @builder.label(@attribute_name, **options, **@html_attributes) do
           @content || safe_join([caption, @text])
         end
       end

data/lib/govuk_design_system_formbuilder/elements/legend.rb

@@ -4,22 +4,26 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Caption
       include Traits::Localisation
 
-      def initialize(builder, object_name, attribute_name, legend:, caption:)
+      def initialize(builder, object_name, attribute_name, legend:, caption:, **kwargs)
         super(builder, object_name, attribute_name)
 
+        @html_attributes = kwargs
+
         case legend
+        when NilClass
+          # do nothing
         when Proc
           @raw = capture { legend.call }
         when Hash
           defaults.merge(legend).tap do |l|
-            @text    = text(l.dig(:text))
+            @text    = retrieve_text(l.dig(:text))
             @hidden  = l.dig(:hidden)
             @tag     = l.dig(:tag)
             @size    = l.dig(:size)
             @caption = caption
           end
         else
-          fail(ArgumentError, %(legend must be a Proc or Hash))
+          fail(ArgumentError, %(legend must be a NilClass, Proc or Hash))
         end
       end
 
@@ -29,18 +33,28 @@ module GOVUKDesignSystemFormBuilder
 
     private
 
+      def active?
+        [@text, @raw].any?(&:present?)
+      end
+
       def content
-        if @text.present?
-          tag.legend(class: classes) do
-            content_tag(@tag, class: heading_classes) do
-              safe_join([caption_element, @text])
-            end
-          end
+        return unless active?
+
+        tag.legend(legend_text, class: classes, **@html_attributes)
+      end
+
+      def legend_text
+        caption_and_text = safe_join([caption_element, @text])
+
+        if @tag.present?
+          content_tag(@tag, class: heading_classes) { caption_and_text }
+        else
+          caption_and_text
         end
       end
 
-      def text(supplied_text)
-        supplied_text || localised_text(:legend)
+      def retrieve_text(supplied_text)
+        [supplied_text, localised_text(:legend), @attribute_name&.capitalize].compact.first
       end
 
       def classes

data/lib/govuk_design_system_formbuilder/elements/radios/fieldset_radio_button.rb

@@ -39,7 +39,7 @@ module GOVUKDesignSystemFormBuilder
         end
 
         def label_element
-          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, **label_content, **label_options, **@label)
+          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, **label_content, **label_options)
         end
 
         def label_options

data/lib/govuk_design_system_formbuilder/traits/caption.rb

@@ -8,15 +8,7 @@ module GOVUKDesignSystemFormBuilder
       end
 
       def caption_options
-        { text: nil }.merge({ text: caption_text, size: caption_size }.compact)
-      end
-
-      def caption_text
-        @caption&.dig(:text)
-      end
-
-      def caption_size
-        @caption&.dig(:size)
+        @caption
       end
     end
   end

data/lib/govuk_design_system_formbuilder/traits/input.rb

@@ -1,38 +1,58 @@
 module GOVUKDesignSystemFormBuilder
   module Traits
     module Input
-      def initialize(builder, object_name, attribute_name, hint:, label:, caption:, width:, form_group:, **kwargs, &block)
+      def initialize(builder, object_name, attribute_name, hint:, label:, caption:, prefix_text:, suffix_text:, width:, form_group:, **kwargs, &block)
         super(builder, object_name, attribute_name, &block)
 
         @width           = width
         @label           = label
         @caption         = caption
         @hint            = hint
+        @prefix_text     = prefix_text
+        @suffix_text     = suffix_text
         @html_attributes = kwargs
         @form_group      = form_group
       end
 
       def html
         Containers::FormGroup.new(@builder, @object_name, @attribute_name, **@form_group).html do
-          safe_join([label_element, supplemental_content, hint_element, error_element, input])
+          safe_join([label_element, supplemental_content, hint_element, error_element, content])
         end
       end
 
     private
 
+      def content
+        if affixed?
+          affixed_input
+        else
+          input
+        end
+      end
+
+      def affixed_input
+        content_tag('div', class: %(#{brand}-input__wrapper)) do
+          safe_join([prefix, input, suffix])
+        end
+      end
+
       def input
-        @builder.send(builder_method, @attribute_name, **input_options, **@html_attributes)
+        @builder.send(builder_method, @attribute_name, **options, **@html_attributes)
+      end
+
+      def affixed?
+        [@prefix_text, @suffix_text].any?
       end
 
-      def input_options
+      def options
         {
           id: field_id(link_errors: true),
-          class: input_classes,
+          class: classes,
           aria: { describedby: described_by(hint_id, error_id, supplemental_id) }
         }
       end
 
-      def input_classes
+      def classes
         [%(#{brand}-input)].push(width_classes, error_classes).compact
       end
 
@@ -64,6 +84,22 @@ module GOVUKDesignSystemFormBuilder
         else fail(ArgumentError, "invalid width '#{@width}'")
         end
       end
+
+      def prefix
+        return nil if @prefix_text.blank?
+
+        tag.span(@prefix_text, class: %(#{brand}-input__prefix), **affix_options)
+      end
+
+      def suffix
+        return nil if @suffix_text.blank?
+
+        tag.span(@suffix_text, class: %(#{brand}-input__suffix), **affix_options)
+      end
+
+      def affix_options
+        { aria: { hidden: true } }
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/version.rb

@@ -1,3 +1,3 @@
 module GOVUKDesignSystemFormBuilder
-  VERSION = '2.0.0b1'.freeze
+  VERSION = '2.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_design_system_formbuilder
 version: !ruby/object:Gem::Version
-  version: 2.0.0b1
+  version: 2.1.0
 platform: ruby
 authors:
 - Peter Yates
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-27 00:00:00.000000000 Z
+date: 2020-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -134,14 +134,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.18.5
+        version: 0.17.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.18.5
+        version: 0.17.1
 - !ruby/object:Gem::Dependency
   name: htmlbeautifier
   requirement: !ruby/object:Gem::Requirement
@@ -176,14 +176,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.21.0
+        version: 3.23.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.21.0
+        version: 3.23.0
 - !ruby/object:Gem::Dependency
   name: rubypants
   requirement: !ruby/object:Gem::Requirement
@@ -303,7 +303,7 @@ metadata:
   documentation_uri: https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder
   homepage_uri: https://govuk-form-builder.netlify.app
   source_code_uri: https://github.com/DFE-Digital/govuk_design_system_formbuilder
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -314,12 +314,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: GOV.UK-compliant Rails form builder
 test_files: []