govuk_design_system_formbuilder 0.7.9 → 0.7.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a58527f914ed7e0cef5f178663fd7969e4fd2cc0b6fa631f0c6e370aac3430e
-  data.tar.gz: 93c8461e3a90d144f477a1fa79b8082c8679d34aa0a2473f89ea693a01836c8a
+  metadata.gz: 73b7bd429e21b82e45676784581f4fe11b9416f64ef2b91352e8eebdfab59137
+  data.tar.gz: 7cdabd663e9355585c53102a15269af7771bac0cbcd4c0c3a6c679d231505a66
 SHA512:
-  metadata.gz: ffdbdd1aae03e6514927a6daeecc215e70b3bfd653491860b4ce148359689ae00d90cb35aa529b53016a64c89d8e84fe0678335b47055dad7089b930304f6ac6
-  data.tar.gz: ce348d7c0a8cc1aee7dda9297b64a3389e6d7d136ba422f54e155d7e14786634b591de980744f68f04d1c20971026dffd94c16931aab24fbcb87e7fa96174987
+  metadata.gz: 8d770e843277f1d75dc2c1dbe3948f6213188e11329290a545812a272ee9a2fc7223101410ca94251af83c8d4548916d9d9c3cac9de837525fdfaa9414401e3b
+  data.tar.gz: bc8fe7c54322289504f46bfdbdb00615b938c9dda38ce6b89e822042943e1f4fe3bf503f856339499f7a6da243b0465b647ad33c089d23085dc2d9c17c35075f

data/README.md

@@ -1,37 +1,68 @@
 # GOV.UK Design System Form Builder for Rails
 
+[![Build Status](https://travis-ci.com/DFE-Digital/govuk_design_system_formbuilder.svg?branch=master)](https://travis-ci.com/DFE-Digital/govuk_design_system_formbuilder)
+[![Maintainability](https://api.codeclimate.com/v1/badges/fde73b5dc9476197281b/maintainability)](https://codeclimate.com/github/DFE-Digital/govuk_design_system_formbuilder/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/fde73b5dc9476197281b/test_coverage)](https://codeclimate.com/github/DFE-Digital/govuk_design_system_formbuilder/test_coverage)
+
+This gem provides a easy-to-use form builder that generates forms that are
+fully-compliant with 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
+System is exposed via the API. Adding [JavaScript-enhanced word count
+checking](https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder#govuk_text_area-instance_method)
+to text areas or [setting the size and weight of
+labels](https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder#govuk_text_field-instance_method)
+on text fields requires only a single argument.
+
+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 😅
+
 ## What's included
 
-* 100% compatibility with the [GOV.UK Design System](https://design-system.service.gov.uk/)
+* 100% compatibility with the GOV.UK Design System
 * Full control of labels, hints, fieldsets and legends
 * No overwriting of Rails' default form helpers
 * Automatic ARIA associations between hints, errors and inputs
-* Most helpers take a block for arbitrary content
+* Most helpers take blocks for arbitrary content
 * Additional params for programmatically adding hints to check box and radio
   button collections
 * No external dependencies
+* [Extensive documentation](https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder)
+* An exhaustive test suite
 
 ## Installation
 
 You can install the form builder gem by running the `gem install
 govuk_design_system_formbuilder` or by adding the following line
-to your `Gemfile`
+to your `Gemfile`:
 
 ```sh
 gem 'govuk_design_system_formbuilder'
 ```
 
+To make full use of this tool, you will need a Rails application with the latest [GOV.UK
+Frontend](https://github.com/alphagov/govuk-frontend) assets installed and
+configured.
+
+To get up and running quickly and easily try kickstarting your project with a
+pre-configured template:
+
+* [DfE Boilerplate](https://github.com/DFE-Digital/govuk-rails-boilerplate)
+* [MoJ Rails Template](https://github.com/ministryofjustice/moj_rails_template)
+
 ## Setup
 
 To use the form builder in an ad hoc basis you can specify it
-as an argument to `form_for`
-
+as an argument to `form_for` or `form_with`:
 
 ```slim
 = form_for @some_object, builder: GOVUKDesignSystemFormBuilder::FormBuilder do |f|
+  ...
 ```
 
-To set it globally, just add this to your `ApplicationController`
+To set it globally, just add this line to your `ApplicationController`:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -44,16 +75,16 @@ Now we can get started! 🎉
 ```slim
 = form_for @person do |f|
 
-  = f.govuk_text_field :full_name, label: { text: 'Your full name' }
+  = f.govuk_text_field :full_name, label: { text: "Your full name" }
 
-  = f.govuk_number_field :age, label: { text: 'Age' }
+  = f.govuk_number_field :age, label: { text: "Age" }
 
   = f.govuk_collection_select :department_id,
     @departments,
     :id,
     :name,
     :description,
-    label: { text: 'Which department do you work for?' },
+    label: { text: "Which department do you work for?" },
     hint_text: "If you don't know ask your manager" }
 
   = f.govuk_submit 'Away we go!'
@@ -63,25 +94,28 @@ Now we can get started! 🎉
 
 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
+of a freshly-cloned repo run:
 
 ```sh
 bundle
 ```
 
-Now, if everything was successful, run RSpec
+Now, if everything was successful, run RSpec:
 
 ```sh
 rspec -fd
 ```
 
+## Contributing
+
+Bug reports and feature requests are most welcome, please raise an issue or
+submit a pull request.
+
+Currently we're using [GOVUK Lint](https://github.com/alphagov/govuk-lint) to
+ensure code meets the GOV.UK guidelines. Please ensure that any PRs also adhere
+to this standard.
+
 ## Thanks
 
 This project was inspired by [MoJ's GovukElementsFormBuilder](https://github.com/ministryofjustice/govuk_elements_form_builder),
-but tackles some problems in a different manner. It provides the following
-advantages by providing:
-
-* no reliance on a custom proxy/block buffer
-* idiomatic Ruby
-* a modular codebase
-* a more-robust test suite
+but is leaner, more modular and written in a more idiomatic style.

data/lib/govuk_design_system_formbuilder.rb

@@ -6,19 +6,29 @@ require 'govuk_design_system_formbuilder/elements/hint'
 require 'govuk_design_system_formbuilder/elements/label'
 require 'govuk_design_system_formbuilder/elements/input'
 require 'govuk_design_system_formbuilder/elements/date'
-require 'govuk_design_system_formbuilder/elements/radios/collection_radio'
-require 'govuk_design_system_formbuilder/elements/radios/fieldset_radio'
+require 'govuk_design_system_formbuilder/elements/select'
+require 'govuk_design_system_formbuilder/elements/submit'
+require 'govuk_design_system_formbuilder/elements/text_area'
+require 'govuk_design_system_formbuilder/elements/file'
+
+require 'govuk_design_system_formbuilder/elements/radios/collection'
+require 'govuk_design_system_formbuilder/elements/radios/collection_radio_button'
+require 'govuk_design_system_formbuilder/elements/radios/fieldset_radio_button'
+
+require 'govuk_design_system_formbuilder/elements/check_boxes/collection'
 require 'govuk_design_system_formbuilder/elements/check_boxes/collection_check_box'
+require 'govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box'
 require 'govuk_design_system_formbuilder/elements/check_boxes/label'
 require 'govuk_design_system_formbuilder/elements/check_boxes/hint'
+
 require 'govuk_design_system_formbuilder/elements/error_message'
 require 'govuk_design_system_formbuilder/elements/error_summary'
-require 'govuk_design_system_formbuilder/elements/submit'
-require 'govuk_design_system_formbuilder/elements/text_area'
 
+require 'govuk_design_system_formbuilder/containers/check_boxes_fieldset'
 require 'govuk_design_system_formbuilder/containers/form_group'
 require 'govuk_design_system_formbuilder/containers/fieldset'
 require 'govuk_design_system_formbuilder/containers/radios'
+require 'govuk_design_system_formbuilder/containers/radio_buttons_fieldset'
 require 'govuk_design_system_formbuilder/containers/check_boxes'
 require 'govuk_design_system_formbuilder/containers/character_count'
 
@@ -28,4 +38,9 @@ module GOVUKDesignSystemFormBuilder
 
     include GOVUKDesignSystemFormBuilder::Builder
   end
+
+  # Disable Rails' div.field_with_error wrapper
+  ActionView::Base.field_error_proc = Proc.new do |html_tag, _instance|
+    html_tag.html_safe
+  end
 end

data/lib/govuk_design_system_formbuilder/base.rb

@@ -6,12 +6,41 @@ module GOVUKDesignSystemFormBuilder
       @attribute_name = attribute_name
     end
 
-    def html
-      fail 'should be overridden'
+    def hint_element
+      @hint_element ||= Elements::Hint.new(@builder, @object_name, @attribute_name, @hint_text)
+    end
+
+    def error_element
+      @error_element ||= Elements::ErrorMessage.new(@builder, @object_name, @attribute_name)
+    end
+
+    def label_element
+      @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, @label)
+    end
+
+    # returns the id value used for the input
+    #
+    # @note field_id is overridden so that the error summary can link to the
+    #   correct element.
+    #
+    #   It's straightforward for inputs with a single element (like a textarea
+    #   or text input) but the GOV.UK Design System requires that the error
+    #   summary link to the first checkbox or radio in a list, so additional
+    #   logic is requred
+    #
+    # @return [String] the element's +id+
+    # @see https://design-system.service.gov.uk/components/error-summary/#linking-from-the-error-summary-to-each-answer
+    #   GOV.UK linking to elements from the error summary
+    def field_id(link_errors: false)
+      if link_errors && has_errors?
+        build_id('field-error', include_value: false)
+      else
+        build_id('field')
+      end
     end
 
     def hint_id
-      return nil unless @hint_text.present?
+      return nil if @hint_text.blank?
 
       build_id('hint')
     end
@@ -26,35 +55,43 @@ module GOVUKDesignSystemFormBuilder
       build_id('conditional')
     end
 
-    def attribute_descriptor
-      build_id(nil, '_', '-')
-    end
-
     def has_errors?
       @builder.object.errors.any? &&
         @builder.object.errors.messages.dig(@attribute_name).present?
     end
 
-    def attribute_identifier
-      "%<object_name>s[%<attribute_name>s]" % {
-        object_name: @object_name,
-        attribute_name: @attribute_name
-      }
-    end
-
     def wrap_conditional(block)
       @builder.content_tag('div', class: conditional_classes, id: conditional_id) do
         @builder.capture { block.call }
       end
     end
 
+    def described_by(*ids)
+      ids.flatten.compact.join(' ').presence
+    end
+
   private
 
-    def build_id(id_type, delimiter = '-', replace = '_', override_attribute_name: nil)
+    # Builds the values used for HTML id attributes throughout the builder
+    #
+    # @param id_type [String] a description of the id's type, eg +hint+, +error+
+    # @param delimiter [String] the characters used to 'split' the output
+    # @param replace [String] the targets to be replaced by the delimiter
+    # @param attribute_name [String] overrides the object's +@attribute_name+
+    # @param include_value [Boolean] controls whether or not the value will form part
+    #   of the final id
+    #
+    # @return [String] the id composed of object, attribute, value and type
+    #
+    # @example
+    #   build_id('hint') #=> "person-name-hint"
+    def build_id(id_type, delimiter = '-', replace = '_', attribute_name: nil, include_value: true)
+      attribute = attribute_name || @attribute_name
+      value     = include_value && @value || nil
       [
         @object_name,
-        (override_attribute_name || @attribute_name),
-        @value,
+        attribute,
+        value,
         id_type
       ]
         .compact

data/lib/govuk_design_system_formbuilder/builder.rb

@@ -9,6 +9,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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 args [Hash] args additional arguments are applied as attributes to +input+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -32,6 +33,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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 args [Hash] args additional arguments are applied as attributes to +input+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -56,6 +58,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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 args [Hash] args additional arguments are applied as attributes to +input+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -78,6 +81,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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 args [Hash] args additional arguments are applied as attributes to +input+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -100,6 +104,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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 args [Hash] args additional arguments are applied as attributes to the +input+ element
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -124,6 +129,7 @@ module GOVUKDesignSystemFormBuilder
     # @param [Hash] label configures the associated label
     # @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
     # @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
@@ -152,37 +158,22 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
     # @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
     # @return [ActiveSupport::SafeBuffer] HTML output
-    def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: { class: 'govuk-select' }, hint_text: nil, label: {})
-      label_element = Elements::Label.new(self, object_name, attribute_name, label)
-      hint_element  = Elements::Hint.new(self, object_name, attribute_name, hint_text)
-      error_element = Elements::ErrorMessage.new(self, object_name, attribute_name)
-
-      Containers::FormGroup.new(self, object_name, attribute_name).html do
-        safe_join([
-          label_element.html,
-          hint_element.html,
-          error_element.html,
-
-          (yield if block_given?),
-
-          collection_select(
-            attribute_name,
-            collection,
-            value_method,
-            text_method,
-            options,
-            html_options.merge(
-              aria: {
-                describedby: [
-                  hint_element.hint_id,
-                  error_element.error_id
-                ].compact.join(' ').presence
-              }
-            )
-          )
-        ])
-      end
+    def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, &block)
+      Elements::Select.new(
+        self,
+        object_name,
+        attribute_name,
+        collection,
+        value_method: value_method,
+        text_method: text_method,
+        hint_text: hint_text,
+        label: label,
+        options: options,
+        html_options: html_options,
+        &block
+      ).html
     end
 
     # Generates a radio button for each item in the supplied collection
@@ -196,7 +187,7 @@ module GOVUKDesignSystemFormBuilder
     # @param text_method [Symbol] The method called against each member of the collection to provide the text
     # @param hint_method [Symbol] The method called against each member of the collection to provide the hint text
     # @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 hash
+    # @param legend [Hash] 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
@@ -219,29 +210,21 @@ 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: { text: nil, size: 'm' }, inline: false, small: false)
-      hint_element  = Elements::Hint.new(self, object_name, attribute_name, hint_text)
-      error_element = Elements::ErrorMessage.new(self, object_name, attribute_name)
-
-      Containers::FormGroup.new(self, object_name, attribute_name).html do
-        Containers::Fieldset.new(self, legend: legend, described_by: [error_element.error_id, hint_element.hint_id]).html do
-          safe_join(
-            [
-              hint_element.html,
-              error_element.html,
-
-              (yield if block_given?),
-              Containers::Radios.new(self, inline: inline, small: small).html do
-                safe_join(
-                  collection.map do |item|
-                    Elements::Radios::CollectionRadio.new(self, object_name, attribute_name, item, value_method, text_method, hint_method).html
-                  end
-                )
-              end
-            ].compact
-          )
-        end
-      end
+    def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: { text: nil, size: 'm' }, inline: false, small: false, &block)
+      Elements::Radios::Collection.new(
+        self,
+        object_name,
+        attribute_name,
+        collection,
+        value_method: value_method,
+        text_method: text_method,
+        hint_method: hint_method,
+        hint_text: hint_text,
+        legend: legend,
+        inline: inline,
+        small: small,
+        &block
+      ).html
     end
 
     # Generates a radio button fieldset container and injects the supplied block contents
@@ -250,12 +233,13 @@ module GOVUKDesignSystemFormBuilder
     #
     # @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 hash
+    # @param legend [Hash] 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+
+    # @param block [Block] a block of HTML that will be used to populate the fieldset
     # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
     # @return [ActiveSupport::SafeBuffer] HTML output
     #
@@ -267,21 +251,8 @@ module GOVUKDesignSystemFormBuilder
     #    = 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)
-      hint_element  = Elements::Hint.new(self, object_name, attribute_name, hint_text)
-      error_element = Elements::ErrorMessage.new(self, object_name, attribute_name)
-
-      Containers::FormGroup.new(self, object_name, attribute_name).html do
-        Containers::Fieldset.new(self, legend: legend, described_by: [error_element.error_id, hint_element.hint_id]).html do
-          safe_join([
-            hint_element.html,
-            error_element.html,
-            Containers::Radios.new(self, inline: inline, small: small).html do
-              yield
-            end
-          ])
-        end
-      end
+    def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, inline: false, small: false, &block)
+      Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, inline: inline, small: small, &block).html
     end
 
     # Generates a radio button
@@ -295,6 +266,8 @@ module GOVUKDesignSystemFormBuilder
     # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
     # @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
+    #   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
@@ -302,8 +275,8 @@ module GOVUKDesignSystemFormBuilder
     #  = f.govuk_collection_radio_buttons :favourite_colour, inline: false do
     #    = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' } do
     #
-    def govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, &block)
-      Elements::Radios::FieldsetRadio.new(self, object_name, attribute_name, value, hint_text: hint_text, label: label, &block).html
+    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
     end
 
     # Inserts a text divider into a list of radio buttons
@@ -327,7 +300,7 @@ module GOVUKDesignSystemFormBuilder
     # @param hint_method [Symbol] The method called against each member of the collection to provide the hint text
     # @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 hash
+    # @param legend [Hash] 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+
@@ -350,25 +323,84 @@ module GOVUKDesignSystemFormBuilder
     #    hint_text: "If it isn't listed here, tough luck",
     #    inline: false
     def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, &block)
-      hint_element  = Elements::Hint.new(self, object_name, attribute_name, hint_text)
-      error_element = Elements::ErrorMessage.new(self, object_name, attribute_name)
+      Elements::CheckBoxes::Collection.new(
+        self,
+        object_name,
+        attribute_name,
+        collection,
+        value_method: value_method,
+        text_method: text_method,
+        hint_method: hint_method,
+        hint_text: hint_text,
+        legend: legend,
+        small: small,
+        &block
+      ).html
+    end
+
+    # Generate a fieldset intended to conatain one or more {#govuk_check_box}
+    #
+    # @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
+    # @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+
+    # @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_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, &block)
+      Containers::CheckBoxesFieldset.new(
+        self,
+        object_name,
+        attribute_name,
+        hint_text: hint_text,
+        legend: legend,
+        small: small,
+        &block
+      ).html
+    end
 
-      Containers::FormGroup.new(self, object_name, attribute_name).html do
-        Containers::Fieldset.new(self, legend: legend, described_by: [error_element.error_id, hint_element.hint_id]).html do
-          safe_join(
-            [
-              hint_element.html,
-              error_element.html,
-              (block.call if block_given?),
-              Containers::CheckBoxes.new(self, small: small).html do
-                collection_check_boxes(attribute_name, collection, value_method, text_method) do |check_box|
-                  Elements::CheckBoxes::CollectionCheckBox.new(self, attribute_name, check_box, hint_method).html
-                end
-              end
-            ]
-          )
-        end
-      end
+    # Generates a single fieldset, 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
+    # @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
+    # @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
+    #
+    # @example A single check box for terms and conditions
+    #   = f.govuk_check_box :terms_agreed,
+    #     true,
+    #     multiple: false,
+    #     link_errors: true,
+    #     label: { text: 'Do you agree with our terms and conditions?' },
+    #     hint_text: 'You will not be able to proceed unless you do'
+    #
+    def govuk_check_box(attribute_name, value, hint_text: nil, label: {}, link_errors: false, multiple: true, &block)
+      Elements::CheckBoxes::FieldsetCheckBox.new(
+        self,
+        object_name,
+        attribute_name,
+        value,
+        hint_text: hint_text,
+        label: label,
+        link_errors: link_errors,
+        multiple: multiple,
+        &block
+      ).html
     end
 
     # Generates a submit button, green by default
@@ -408,7 +440,7 @@ 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 hash
+    # @param legend [Hash] 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+
@@ -448,7 +480,7 @@ module GOVUKDesignSystemFormBuilder
 
     # Generates a fieldset containing the contents of the block
     #
-    # @param legend [Hash] options for configuring the hash
+    # @param legend [Hash] 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+
@@ -465,5 +497,27 @@ module GOVUKDesignSystemFormBuilder
     def govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block)
       Containers::Fieldset.new(self, legend: legend, described_by: described_by).html(&block)
     end
+
+    # Generates an input of type +file+
+    #
+    # @param attribute_name [Symbol] The name of the attribute
+    # @option label text [String] the label text
+    # @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
+    # @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
+    #
+    # @example A photo upload field with file type specifier
+    #   = f.govuk_file_field :photo, label: { text: 'Upload your photo' }, accept: 'image/*'
+    #
+    # @see https://design-system.service.gov.uk/components/file-upload/ GOV.UK file upload
+    # @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)
+      Elements::File.new(self, object_name, attribute_name, label: label, hint_text: hint_text, **args).html
+    end
   end
 end