govuk_design_system_formbuilder 2.0.0b2 → 2.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd1f1c56336a4852ae5915c148e7c47abeef5590f87fc083437a4f4a680addba
-  data.tar.gz: 929a16808249de59a675c3215837e1522d2982a46497fea6b207e90f9c9d8aa0
+  metadata.gz: 7450c096f60fc5960a22c6fa4012c478cd34dbe86bdd1b0fe09e034ad965422c
+  data.tar.gz: 62011bc3b81778fb0efc042fc9b04107b36ea69926ee23ba92044606d0f09601
 SHA512:
-  metadata.gz: ad2ad55fb5f7752862fde79ec8ffcfba5ef9cb1ea20e30b266c7152a7d78eef6fa9f40682f69a7db395b9f8104645735eb71c1efbc538506d3015fb888542932
-  data.tar.gz: 2c1d49579c09742a5dc2f8be8ddf7bcee4edb6d2d9d39e610705dfd10efc4bf0df18ad00026cd932d10b790aca1ee93a964079329ee9be0067c4c4f84c84a83a
+  metadata.gz: 9bb6242f2b97c9912d25748d07b25a2650a3bb85aaf168e73ff268caef449dda20d99df4ebcd3f460be90ba82c593be3f6732dff2640ac457b0020471676e894
+  data.tar.gz: 0f0b32faf4869aa47897e2f5acb517af84992726d1a8b52916f0670999afe284bef3112716416cfbb3f53e806364337ecdac560e5a7a0b9ff7e5a64e53cef2eb

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

@@ -26,6 +26,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -49,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: {}, **kwargs, &block)
-      Elements::Inputs::Text.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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+
@@ -76,6 +78,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -100,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: {}, **kwargs, &block)
-      Elements::Inputs::Phone.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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+
@@ -127,6 +131,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -149,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: {}, **kwargs, &block)
-      Elements::Inputs::Email.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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+
@@ -176,6 +182,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -197,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: {}, **kwargs, &block)
-      Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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+
@@ -224,6 +232,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -246,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: {}, **kwargs, &block)
-      Elements::Inputs::URL.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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+
@@ -273,6 +283,8 @@ module GOVUKDesignSystemFormBuilder
     # @param form_group [Hash] configures the form group
     # @option form_group classes [Array,String] sets the form group's classes
     # @option form_group kwargs [Hash] additional attributes added to the form group
+    # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
+    # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
     # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
     # @return [ActiveSupport::SafeBuffer] HTML output
     # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -298,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: {}, **kwargs, &block)
-      Elements::Inputs::Number.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **kwargs, &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
@@ -447,7 +459,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -488,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,
@@ -526,7 +538,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -623,7 +635,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -701,7 +713,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -710,6 +722,8 @@ module GOVUKDesignSystemFormBuilder
     # @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 kwargs [Hash] additional attributes added to the form group
     # @param block [Block] a block of HTML that will be used to populate the fieldset
@@ -725,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,
@@ -736,6 +750,7 @@ module GOVUKDesignSystemFormBuilder
         small: small,
         classes: classes,
         form_group: form_group,
+        multiple: multiple,
         &block
       ).html
     end
@@ -744,6 +759,7 @@ 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
@@ -766,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,
@@ -799,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
     #
@@ -823,7 +842,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -861,13 +880,18 @@ module GOVUKDesignSystemFormBuilder
     # part of the form that contains the error
     #
     # @param title [String] the error summary heading
+    # @param link_base_errors_to [Symbol,String] set the field that errors on +:base+ are linked
+    #   to, as there won't be a field representing the object base.
+    #
+    # @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'
     #
     # @see https://design-system.service.gov.uk/components/error-summary/ GOV.UK error summary
-    def govuk_error_summary(title = config.default_error_summary_title)
-      Elements::ErrorSummary.new(self, object_name, title).html
+    def govuk_error_summary(title = config.default_error_summary_title, link_base_errors_to: nil)
+      Elements::ErrorSummary.new(self, object_name, title, link_base_errors_to: link_base_errors_to).html
     end
 
     # Generates a fieldset containing the contents of the block
@@ -876,7 +900,7 @@ module GOVUKDesignSystemFormBuilder
     # @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
@@ -885,13 +909,13 @@ module GOVUKDesignSystemFormBuilder
     # @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
     #

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/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/error_summary.rb

@@ -3,10 +3,11 @@ module GOVUKDesignSystemFormBuilder
     class ErrorSummary < Base
       include Traits::Error
 
-      def initialize(builder, object_name, title)
-        @builder = builder
-        @object_name = object_name
-        @title = title
+      def initialize(builder, object_name, title, link_base_errors_to:)
+        @builder             = builder
+        @object_name         = object_name
+        @title               = title
+        @link_base_errors_to = link_base_errors_to
       end
 
       def html
@@ -54,7 +55,11 @@ module GOVUKDesignSystemFormBuilder
       end
 
       def field_id(attribute)
-        build_id('field-error', attribute_name: attribute)
+        if attribute.eql?(:base) && @link_base_errors_to.present?
+          build_id('field', attribute_name: @link_base_errors_to)
+        else
+          build_id('field-error', attribute_name: attribute)
+        end
       end
 
       def summary_title_id

data/lib/govuk_design_system_formbuilder/elements/hint.rb

@@ -8,6 +8,7 @@ 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
@@ -15,8 +16,7 @@ module GOVUKDesignSystemFormBuilder
         if content
           @raw = capture { content.call }
         else
-          @text  = retrieve_text(text)
-          @value = value
+          @text = retrieve_text(text)
         end
       end
 

data/lib/govuk_design_system_formbuilder/elements/legend.rb

@@ -11,7 +11,7 @@ module GOVUKDesignSystemFormBuilder
 
         case legend
         when NilClass
-          @active = false
+          # do nothing
         when Proc
           @raw = capture { legend.call }
         when Hash
@@ -23,7 +23,7 @@ module GOVUKDesignSystemFormBuilder
             @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
 
@@ -38,12 +38,18 @@ module GOVUKDesignSystemFormBuilder
       end
 
       def content
-        return nil unless active?
+        return unless active?
 
-        tag.legend(class: classes, **@html_attributes) do
-          content_tag(@tag, class: heading_classes) do
-            safe_join([caption_element, @text])
-          end
+        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
 

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.0b2'.freeze
+  VERSION = '2.1.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: govuk_design_system_formbuilder
 version: !ruby/object:Gem::Version
-  version: 2.0.0b2
+  version: 2.1.1
 platform: ruby
 authors:
 - Peter Yates
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-02 00:00:00.000000000 Z
+date: 2020-10-25 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: []