govuk_design_system_formbuilder 1.2.0b1 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +2 -2
  3. data/lib/govuk_design_system_formbuilder.rb +2 -1
  4. data/lib/govuk_design_system_formbuilder/base.rb +5 -0
  5. data/lib/govuk_design_system_formbuilder/builder.rb +205 -77
  6. data/lib/govuk_design_system_formbuilder/containers/check_boxes_fieldset.rb +12 -11
  7. data/lib/govuk_design_system_formbuilder/containers/fieldset.rb +32 -16
  8. data/lib/govuk_design_system_formbuilder/containers/radio_buttons_fieldset.rb +12 -11
  9. data/lib/govuk_design_system_formbuilder/elements/caption.rb +34 -0
  10. data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection.rb +11 -13
  11. data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection_check_box.rb +17 -15
  12. data/lib/govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box.rb +20 -27
  13. data/lib/govuk_design_system_formbuilder/elements/date.rb +23 -25
  14. data/lib/govuk_design_system_formbuilder/elements/error_message.rb +8 -7
  15. data/lib/govuk_design_system_formbuilder/elements/error_summary.rb +23 -26
  16. data/lib/govuk_design_system_formbuilder/elements/file.rb +18 -19
  17. data/lib/govuk_design_system_formbuilder/elements/hint.rb +1 -4
  18. data/lib/govuk_design_system_formbuilder/elements/label.rb +30 -19
  19. data/lib/govuk_design_system_formbuilder/elements/radios/collection.rb +26 -24
  20. data/lib/govuk_design_system_formbuilder/elements/radios/collection_radio_button.rb +13 -13
  21. data/lib/govuk_design_system_formbuilder/elements/radios/fieldset_radio_button.rb +15 -19
  22. data/lib/govuk_design_system_formbuilder/elements/select.rb +8 -18
  23. data/lib/govuk_design_system_formbuilder/elements/submit.rb +27 -23
  24. data/lib/govuk_design_system_formbuilder/elements/text_area.rb +17 -23
  25. data/lib/govuk_design_system_formbuilder/traits/caption.rb +23 -0
  26. data/lib/govuk_design_system_formbuilder/traits/input.rb +19 -27
  27. data/lib/govuk_design_system_formbuilder/traits/label.rb +12 -1
  28. data/lib/govuk_design_system_formbuilder/traits/localisation.rb +2 -0
  29. data/lib/govuk_design_system_formbuilder/version.rb +1 -1
  30. metadata +21 -47
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b26402e9e41729882759af55f46d0ca77021301c3e47d1fdf71674a5b7e10635
4
- data.tar.gz: 29f61cc4bb6086cf19c08f57648be973aab134ef8a0b1ebded5a175cb8f79564
3
+ metadata.gz: dd5bdfc23cbf3aba262eee3caf3b16ef7ad34f12672f089a04e92044d289762d
4
+ data.tar.gz: dc41ebb9003313decf2eace4a4f3b48182d1e9b5c3b96a0c9b28a13aa17285f8
5
5
  SHA512:
6
- metadata.gz: d5c38d0cc478cddeb01c6624abb8b4bced314197bd6e1f788a36d94f8ca5c62d2c19a2da96a7e7a3c2555af994a07cf3b10d4ed83dd270135e3af86157c11f6f
7
- data.tar.gz: 95ca19e5a70cfc2f163e3ffadbd59b9644dc9f471723f468b56ea3e2d8a15c10761f651fc522ccf220a20c7b607083d3a0d71048d2ba240d5562e2cb06b2fae1
6
+ metadata.gz: e28d6305d6a07625bce2360e29694a2f120f0e321bca340659cd3a05a60083fa1c8f33c535f1df87ce7733a60a65d9ab5e5bab2335510c5b6a5e6e61c755067a
7
+ data.tar.gz: 86ca1256c95692912fd2255449ef7a97def4a59a5398ec691e297a6a8137e7bff13d3359ecf0daf7482ef396b2fc54cd9420c788060ece727360ce4a80af87f2
data/README.md CHANGED
@@ -7,10 +7,10 @@
7
7
  [![Test Coverage](https://api.codeclimate.com/v1/badges/fde73b5dc9476197281b/test_coverage)](https://codeclimate.com/github/DFE-Digital/govuk_design_system_formbuilder/test_coverage)
8
8
  [![Dependabot Status](https://api.dependabot.com/badges/status?host=github&repo=DFE-Digital/govuk_design_system_formbuilder)](https://dependabot.com)
9
9
  [![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)
10
- [![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.6.0-brightgreen)](https://design-system.service.gov.uk)
10
+ [![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.7.0-brightgreen)](https://design-system.service.gov.uk)
11
11
 
12
12
  This gem provides a easy-to-use form builder that generates forms that are
13
- fully-compliant with version 3.6.0 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
13
+ fully-compliant with version 3.7.0 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
14
14
  minimising the amount of markup you need to write.
15
15
 
16
16
  In addition to the basic markup, the more-advanced functionality of the Design
@@ -52,7 +52,8 @@ module GOVUKDesignSystemFormBuilder
52
52
  localisation_schema_fallback: %i(helpers __context__),
53
53
  localisation_schema_label: nil,
54
54
  localisation_schema_hint: nil,
55
- localisation_schema_legend: nil
55
+ localisation_schema_legend: nil,
56
+ localisation_schema_caption: nil
56
57
  }.freeze
57
58
 
58
59
  DEFAULTS.each_key { |k| config_accessor(k) { DEFAULTS[k] } }
@@ -18,6 +18,11 @@ module GOVUKDesignSystemFormBuilder
18
18
  @block_content = capture { block.call } if block_given?
19
19
  end
20
20
 
21
+ # objects that implement #to_s can be passed directly into #safe_join
22
+ def to_s
23
+ html || ''
24
+ end
25
+
21
26
  private
22
27
 
23
28
  def brand(override = nil)
@@ -8,15 +8,19 @@ module GOVUKDesignSystemFormBuilder
8
8
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
9
9
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
10
10
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
11
- # @param [Hash] label configures the associated label
11
+ # @param label [Hash,Proc] configures or sets the associated label content
12
12
  # @option label text [String] the label text
13
13
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
14
14
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
15
15
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
16
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
16
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
17
+ # @option caption text [String] the caption text
18
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
19
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
17
20
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
18
21
  # @return [ActiveSupport::SafeBuffer] HTML output
19
22
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
23
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
20
24
  #
21
25
  # @example A required full name field with a placeholder
22
26
  # = f.govuk_text_field :name,
@@ -32,8 +36,12 @@ module GOVUKDesignSystemFormBuilder
32
36
  # p.govuk-inset-text
33
37
  # | Ensure your stage name is unique
34
38
  #
35
- def govuk_text_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
36
- Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
39
+ # @example A text field with the label supplied as a proc
40
+ # = f.govuk_text_field :callsign,
41
+ # label: -> { tag.h3('Call-sign') }
42
+ #
43
+ def govuk_text_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
44
+ Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
37
45
  end
38
46
 
39
47
  # Generates a input of type +tel+
@@ -42,16 +50,20 @@ module GOVUKDesignSystemFormBuilder
42
50
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
43
51
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
44
52
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
45
- # @param [Hash] label configures the associated label
53
+ # @param label [Hash,Proc] configures or sets the associated label content
46
54
  # @option label text [String] the label text
47
55
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
48
56
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
49
57
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
50
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
58
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
59
+ # @option caption text [String] the caption text
60
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
61
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
51
62
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
52
63
  # @return [ActiveSupport::SafeBuffer] HTML output
53
64
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
54
65
  # @see https://design-system.service.gov.uk/patterns/telephone-numbers/ GOV.UK Telephone number patterns
66
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
55
67
  #
56
68
  # @example A required phone number field with a placeholder
57
69
  # = f.govuk_phone_field :phone_number,
@@ -67,8 +79,12 @@ module GOVUKDesignSystemFormBuilder
67
79
  # p.govuk-inset-text
68
80
  # | Yes, fax machines are still a thing
69
81
  #
70
- def govuk_phone_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
71
- Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
82
+ # @example A phone field with the label supplied as a proc
83
+ # = f.govuk_phone_field :work_number,
84
+ # label: -> { tag.h3('Work number') }
85
+ #
86
+ def govuk_phone_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
87
+ Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
72
88
  end
73
89
 
74
90
  # Generates a input of type +email+
@@ -77,31 +93,39 @@ module GOVUKDesignSystemFormBuilder
77
93
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
78
94
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
79
95
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
80
- # @param [Hash] label configures the associated label
96
+ # @param label [Hash,Proc] configures or sets the associated label content
81
97
  # @option label text [String] the label text
82
98
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
83
99
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
84
100
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
85
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
101
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
102
+ # @option caption text [String] the caption text
103
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
104
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
86
105
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
87
106
  # @return [ActiveSupport::SafeBuffer] HTML output
88
107
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
89
108
  # @see https://design-system.service.gov.uk/patterns/email-addresses/ GOV.UK Email address patterns
109
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
90
110
  #
91
111
  # @example An email address field with a placeholder
92
112
  # = f.govuk_email_field :email_address,
93
113
  # label: { text: 'Enter your email address' },
94
114
  # placeholder: 'ralph.wiggum@springfield.edu'
95
115
  #
96
- # @example A email field with injected content
97
- # = f.govuk_phone_field :email_address,
98
- # label: { text: 'Email address' } do
116
+ # @example An email field with injected content
117
+ # = f.govuk_phone_field :work_email,
118
+ # label: { text: 'Work email address' } do
99
119
  #
100
120
  # p.govuk-inset-text
101
121
  # | Use your work address
102
122
  #
103
- def govuk_email_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
104
- Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
123
+ # @example A email field with the label supplied as a proc
124
+ # = f.govuk_email_field :personal_email,
125
+ # label: -> { tag.h3('Personal email address') }
126
+ #
127
+ def govuk_email_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
128
+ Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
105
129
  end
106
130
 
107
131
  # Generates a input of type +password+
@@ -110,16 +134,20 @@ module GOVUKDesignSystemFormBuilder
110
134
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
111
135
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
112
136
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
113
- # @param [Hash] label configures the associated label
137
+ # @param label [Hash,Proc] configures or sets the associated label content
114
138
  # @option label text [String] the label text
115
139
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
116
140
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
117
141
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
118
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
142
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
143
+ # @option caption text [String] the caption text
144
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
145
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
119
146
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
120
147
  # @return [ActiveSupport::SafeBuffer] HTML output
121
148
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
122
149
  # @see https://design-system.service.gov.uk/patterns/passwords/ GOV.UK Password patterns
150
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
123
151
  #
124
152
  # @example A password field
125
153
  # = f.govuk_password_field :password,
@@ -132,8 +160,12 @@ module GOVUKDesignSystemFormBuilder
132
160
  # p.govuk-inset-text
133
161
  # | Ensure your password is at least 16 characters long
134
162
  #
135
- def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
136
- Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
163
+ # @example A password field with the label supplied as a proc
164
+ # = f.govuk_password_field :passcode,
165
+ # label: -> { tag.h3('What is your secret pass code?') }
166
+ #
167
+ def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, caption: {}, **args, &block)
168
+ Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
137
169
  end
138
170
 
139
171
  # Generates a input of type +url+
@@ -142,15 +174,19 @@ module GOVUKDesignSystemFormBuilder
142
174
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
143
175
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
144
176
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
145
- # @param [Hash] label configures the associated label
177
+ # @param label [Hash,Proc] configures or sets the associated label content
146
178
  # @option label text [String] the label text
147
179
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
148
180
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
149
181
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
150
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
182
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
183
+ # @option caption text [String] the caption text
184
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
185
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
151
186
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
152
187
  # @return [ActiveSupport::SafeBuffer] HTML output
153
188
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
189
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
154
190
  #
155
191
  # @example A url field with autocomplete
156
192
  # = f.govuk_url_field :favourite_website,
@@ -165,8 +201,12 @@ module GOVUKDesignSystemFormBuilder
165
201
  # p.govuk-inset-text
166
202
  # | This will be visible on your profile
167
203
  #
168
- def govuk_url_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
169
- Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
204
+ # @example A url field with the label supplied as a proc
205
+ # = f.govuk_url_field :work_website,
206
+ # label: -> { tag.h3("Enter your company's website") }
207
+ #
208
+ def govuk_url_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
209
+ Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
170
210
  end
171
211
 
172
212
  # Generates a input of type +number+
@@ -175,15 +215,19 @@ module GOVUKDesignSystemFormBuilder
175
215
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
176
216
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
177
217
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
178
- # @param [Hash] label configures the associated label
218
+ # @param label [Hash,Proc] configures or sets the associated label content
179
219
  # @option label text [String] the label text
180
220
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
181
221
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
182
222
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
223
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
224
+ # @option caption text [String] the caption text
225
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
183
226
  # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
184
227
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
185
228
  # @return [ActiveSupport::SafeBuffer] HTML output
186
229
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
230
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
187
231
  #
188
232
  # @example A number field with placeholder, min, max and step
189
233
  # = f.govuk_number_field :iq,
@@ -201,8 +245,12 @@ module GOVUKDesignSystemFormBuilder
201
245
  # | If you haven't measured your height in the last 6 months
202
246
  # do it now
203
247
  #
204
- def govuk_number_field(attribute_name, hint_text: nil, label: {}, width: nil, **args, &block)
205
- Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, width: width, **args, &block).html
248
+ # @example A number field with the label supplied as a proc
249
+ # = f.govuk_url_field :personal_best_over_100m,
250
+ # label: -> { tag.h3("How many seconds does it take you to run 100m?") }
251
+ #
252
+ def govuk_number_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, **args, &block)
253
+ Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, **args, &block).html
206
254
  end
207
255
 
208
256
  # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -211,11 +259,14 @@ module GOVUKDesignSystemFormBuilder
211
259
  #
212
260
  # @param attribute_name [Symbol] The name of the attribute
213
261
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
214
- # @param [Hash] label configures the associated label
262
+ # @param label [Hash,Proc] configures or sets the associated label content
215
263
  # @option label text [String] the label text
216
264
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
217
265
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
218
266
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
267
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
268
+ # @option caption text [String] the caption text
269
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
219
270
  # @param max_words [Integer] adds the GOV.UK max word count
220
271
  # @param max_chars [Integer] adds the GOV.UK max characters count
221
272
  # @param threshold [Integer] only show the +max_words+ and +max_chars+ warnings once a threshold (percentage) is reached
@@ -223,25 +274,31 @@ module GOVUKDesignSystemFormBuilder
223
274
  # @option args [Hash] args additional arguments are applied as attributes to the +textarea+ element
224
275
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
225
276
  # @return [ActiveSupport::SafeBuffer] HTML output
277
+ # @see https://design-system.service.gov.uk/components/textarea/ GOV.UK text area component
226
278
  # @see https://design-system.service.gov.uk/components/character-count GOV.UK character count component
279
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
227
280
  # @note Setting +max_chars+ or +max_words+ will add a caption beneath the +textarea+ with a live count of words
228
281
  # or characters
229
282
  #
230
283
  # @example A text area with a custom number of rows and a word limit
231
- # = f.govuk_number_field :cv,
284
+ # = f.govuk_text_area :cv,
232
285
  # label: { text: 'Tell us about your work history' },
233
286
  # rows: 8,
234
287
  # max_words: 300
235
288
  #
236
289
  # @example A text area with injected content
237
- # = f.govuk_number_field :description,
290
+ # = f.govuk_text_area :description,
238
291
  # label: { text: 'Where did the incident take place?' } do
239
292
  #
240
293
  # p.govuk-inset-text
241
294
  # | If you don't know exactly leave this section blank
242
295
  #
243
- def govuk_text_area(attribute_name, hint_text: nil, label: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, **args, &block)
244
- Elements::TextArea.new(self, object_name, attribute_name, hint_text: hint_text, label: label, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, **args, &block).html
296
+ # @example A text area with the label supplied as a proc
297
+ # = f.govuk_text_area :instructions,
298
+ # label: -> { tag.h3("How do you set it up?") }
299
+ #
300
+ def govuk_text_area(attribute_name, hint_text: nil, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, **args, &block)
301
+ Elements::TextArea.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, **args, &block).html
245
302
  end
246
303
 
247
304
  # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -259,21 +316,23 @@ module GOVUKDesignSystemFormBuilder
259
316
  # @return [ActiveSupport::SafeBuffer] HTML output
260
317
  #
261
318
  # @example A select box with hint
262
- # = f.govuk_number_field :grade,
319
+ # = f.govuk_collection_select :grade,
263
320
  # @grades,
264
321
  # :id,
265
322
  # :name,
266
323
  # hint_text: "If you took the test more than once enter your highest grade"
267
324
  #
268
325
  # @example A select box with injected content
269
- # = f.govuk_number_field :favourite_colour,
270
- # @colours,
271
- # :id,
272
- # :name do
326
+ # = f.govuk_collection_select(:favourite_colour, @colours, :id, :name) do
273
327
  #
274
328
  # p.govuk-inset-text
275
329
  # | Select the closest match
276
- def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, &block)
330
+ #
331
+ # @example A select box with the label supplied as a proc
332
+ # = f.govuk_collection_select(:team, @teams, :id, :name) do
333
+ # label: -> { tag.h3("Which team did you represent?") }
334
+ #
335
+ def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, caption: {}, &block)
277
336
  Elements::Select.new(
278
337
  self,
279
338
  object_name,
@@ -283,6 +342,7 @@ module GOVUKDesignSystemFormBuilder
283
342
  text_method: text_method,
284
343
  hint_text: hint_text,
285
344
  label: label,
345
+ caption: caption,
286
346
  options: options,
287
347
  html_options: html_options,
288
348
  &block
@@ -309,7 +369,7 @@ module GOVUKDesignSystemFormBuilder
309
369
  # When a +Proc+ is provided it must take a single argument that is a single member of the collection.
310
370
  # When a +nil+ value is provided the hint text will be retrieved from the locale. This is the default and param can be omitted.
311
371
  # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
312
- # @param legend [Hash] options for configuring the legend
372
+ # @param legend [Hash,Proc] options for configuring the legend
313
373
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
314
374
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
315
375
  # @param bold_labels [Boolean] controls whether the radio button labels are bold
@@ -318,6 +378,9 @@ module GOVUKDesignSystemFormBuilder
318
378
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
319
379
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
320
380
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
381
+ # @param caption [Hash] configures or sets the caption content which is inserted above the legend
382
+ # @option caption text [String] the caption text
383
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
321
384
  # @return [ActiveSupport::SafeBuffer] HTML output
322
385
  #
323
386
  # @example A collection of radio buttons for favourite colours, labels capitalised via a proc
@@ -337,14 +400,22 @@ module GOVUKDesignSystemFormBuilder
337
400
  # inline: false
338
401
  #
339
402
  # @example A collection of radio buttons for grades with injected content
340
- # = f.govuk_collection_radio_buttons :favourite_colour,
403
+ # = f.govuk_collection_radio_buttons :grade,
341
404
  # @grades,
342
405
  # :id,
343
406
  # :name do
344
407
  #
345
408
  # p.govuk-inset-text
346
409
  # | If you took the test more than once enter your highest grade
347
- def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, inline: false, small: false, bold_labels: false, classes: nil, &block)
410
+ #
411
+ # @example A collection of radio buttons with the legend supplied as a proc
412
+ # = f.govuk_collection_radio_buttons :category,
413
+ # @categories,
414
+ # :id,
415
+ # :name,
416
+ # legend: -> { tag.h3('Which category do you belong to?') }
417
+ #
418
+ def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, caption: {}, inline: false, small: false, bold_labels: false, classes: nil, &block)
348
419
  Elements::Radios::Collection.new(
349
420
  self,
350
421
  object_name,
@@ -355,6 +426,7 @@ module GOVUKDesignSystemFormBuilder
355
426
  hint_method: hint_method,
356
427
  hint_text: hint_text,
357
428
  legend: legend,
429
+ caption: caption,
358
430
  inline: inline,
359
431
  small: small,
360
432
  bold_labels: bold_labels,
@@ -367,30 +439,46 @@ module GOVUKDesignSystemFormBuilder
367
439
  #
368
440
  # @note The intention is to use {#govuk_radio_button} and {#govuk_radio_divider} within the passed-in block
369
441
  #
442
+ # @note To ensure the {#govuk_error_summary} link functions correctly ensure the first {#govuk_radio_button}
443
+ # is set to +link_errors: true+
444
+ #
370
445
  # @param attribute_name [Symbol] The name of the attribute
371
446
  # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
372
- # @param legend [Hash] options for configuring the legend
447
+ # @param legend [Hash,Proc] options for configuring the legend
373
448
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
374
449
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
375
450
  # @option legend text [String] the fieldset legend's text content
376
451
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
377
452
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
378
453
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
454
+ # @param caption [Hash] configures or sets the caption content which is inserted above the legend
455
+ # @option caption text [String] the caption text
456
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
379
457
  # @param block [Block] a block of HTML that will be used to populate the fieldset
380
458
  # @param classes [String] Classes to add to the radio button container.
381
459
  # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
460
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
382
461
  # @return [ActiveSupport::SafeBuffer] HTML output
383
462
  #
384
- # @example A collection of radio buttons for favourite colours with a divider
463
+ # @example A radio button fieldset for favourite colours with a divider
385
464
  #
386
- # = f.govuk_collection_radio_buttons :favourite_colour, inline: false do
387
- # = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
465
+ # = f.govuk_radio_buttons_fieldset :favourite_colour, inline: false do
466
+ # = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }, link_errors: true
388
467
  # = f.govuk_radio_button :favourite_colour, :green, label: { text: 'Green' }
389
468
  # = f.govuk_radio_divider
390
469
  # = f.govuk_radio_button :favourite_colour, :yellow, label: { text: 'Yellow' }
391
470
  #
392
- def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, inline: false, small: false, classes: nil, &block)
393
- Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, inline: inline, small: small, classes: classes, &block).html
471
+ # @example A radio button fieldset with the legend supplied as a proc
472
+ # = f.govuk_radio_buttons_fieldset :burger_id do
473
+ # @burgers,
474
+ # :id,
475
+ # :name,
476
+ # legend: -> { tag.h3('Which hamburger do you want with your meal?') } do
477
+ # = f.govuk_radio_button :burger_id, :regular, label: { text: 'Hamburger' }, link_errors: true
478
+ # = f.govuk_radio_button :burger_id, :cheese, label: { text: 'Cheeseburger' }
479
+ #
480
+ def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, caption: {}, inline: false, small: false, classes: nil, &block)
481
+ Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, caption: caption, inline: inline, small: small, classes: classes, &block).html
394
482
  end
395
483
 
396
484
  # Generates a radio button
@@ -403,15 +491,16 @@ module GOVUKDesignSystemFormBuilder
403
491
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
404
492
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
405
493
  # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
494
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
406
495
  # @param block [Block] Any supplied HTML will be wrapped in a conditional
407
496
  # container and only revealed when the radio button is picked
408
- # @param link_errors [Boolean] controls whether this radio button should be linked to
497
+ # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
409
498
  # from the error summary. <b>Should only be set to +true+ for the first radio button in a fieldset</b>
410
499
  # @return [ActiveSupport::SafeBuffer] HTML output
411
500
  #
412
- # @example A collection of radio buttons for favourite colours with a divider
501
+ # @example A single radio button for our new favourite colour
413
502
  #
414
- # = f.govuk_collection_radio_buttons :favourite_colour, inline: false do
503
+ # = f.govuk_radio_buttons_fieldset :favourite_colour do
415
504
  # = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
416
505
  #
417
506
  def govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, link_errors: false, &block)
@@ -441,11 +530,14 @@ module GOVUKDesignSystemFormBuilder
441
530
  # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
442
531
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
443
532
  # @param classes [String] Classes to add to the checkbox container.
444
- # @param legend [Hash] options for configuring the legend
533
+ # @param legend [Hash,Proc] options for configuring the legend
445
534
  # @option legend text [String] the fieldset legend's text content
446
535
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
447
536
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
448
537
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
538
+ # @param caption [Hash] configures or sets the caption content which is inserted above the legend
539
+ # @option caption text [String] the caption text
540
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
449
541
  # @param block [Block] any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes
450
542
  # @return [ActiveSupport::SafeBuffer] HTML output
451
543
  #
@@ -467,14 +559,22 @@ module GOVUKDesignSystemFormBuilder
467
559
  # classes: 'app-overflow-scroll',
468
560
  #
469
561
  # @example A collection of check boxes for types of bread
470
- # = f.govuk_collection_radio_buttons :bread,
562
+ # = f.govuk_collection_check_boxes :bread,
471
563
  # @variety,
472
564
  # :id,
473
565
  # :name do
474
566
  #
475
567
  # p.govuk-inset-text
476
568
  # | Only Hearty Italian is available with the meal deal menu
477
- def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, small: false, classes: nil, &block)
569
+ #
570
+ # @example A collection of check boxes with the legend supplied as a proc
571
+ # = f.govuk_collection_check_boxes :sandwich_type,
572
+ # @breads,
573
+ # :id,
574
+ # :name,
575
+ # legend: -> { tag.h3('What kind of sandwich do you want?') }
576
+ #
577
+ def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, caption: {}, small: false, classes: nil, &block)
478
578
  Elements::CheckBoxes::Collection.new(
479
579
  self,
480
580
  object_name,
@@ -485,6 +585,7 @@ module GOVUKDesignSystemFormBuilder
485
585
  hint_method: hint_method,
486
586
  hint_text: hint_text,
487
587
  legend: legend,
588
+ caption: caption,
488
589
  small: small,
489
590
  classes: classes,
490
591
  &block
@@ -493,43 +594,54 @@ module GOVUKDesignSystemFormBuilder
493
594
 
494
595
  # Generate a fieldset intended to conatain one or more {#govuk_check_box}
495
596
  #
597
+ # @note To ensure the {#govuk_error_summary} link functions correctly ensure the first {#govuk_check_box}
598
+ # is set to +link_errors: true+
599
+ #
496
600
  # @param attribute_name [Symbol] The name of the attribute
497
601
  # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
498
602
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
499
- # @param legend [Hash] options for configuring the legend
603
+ # @param legend [Hash,Proc] options for configuring the legend
500
604
  # @option legend text [String] the fieldset legend's text content
501
605
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
502
606
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
503
607
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
608
+ # @param caption [Hash] configures or sets the caption content which is inserted above the legend
609
+ # @option caption text [String] the caption text
610
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
504
611
  # @param classes [String] Classes to add to the checkbox container.
505
612
  # @param block [Block] a block of HTML that will be used to populate the fieldset
506
613
  # @return [ActiveSupport::SafeBuffer] HTML output
507
614
  #
508
615
  # @example A collection of check boxes for sandwich fillings
509
- #
510
- # = f.govuk_check_boxes_fieldset :desired_filling,
616
+ # = f.govuk_check_boxes_fieldset :desired_filling, legend: { text: 'Which filling do you want?' },
511
617
  # = f.govuk_check_box :desired_filling, :cheese, label: { text: 'Cheese' }, link_errors: true
512
618
  # = f.govuk_check_box :desired_filling, :tomato, label: { text: 'Tomato' }
513
619
  #
514
- def govuk_check_boxes_fieldset(attribute_name, legend: {}, hint_text: {}, small: false, classes: nil, &block)
620
+ # @example A collection of check boxes for drinks choices with legend as a proc
621
+ # = f.govuk_check_boxes_fieldset :drink_id, legend: -> { tag.h3('Choose drinks to accompany your meal') },
622
+ # = f.govuk_check_box :desired_filling, :lemonade, label: { text: 'Lemonade' }, link_errors: true
623
+ # = f.govuk_check_box :desired_filling, :fizzy_orange, label: { text: 'Fizzy orange' }
624
+ #
625
+ def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint_text: {}, small: false, classes: nil, &block)
515
626
  Containers::CheckBoxesFieldset.new(
516
627
  self,
517
628
  object_name,
518
629
  attribute_name,
519
630
  hint_text: hint_text,
520
631
  legend: legend,
632
+ caption: caption,
521
633
  small: small,
522
634
  classes: classes,
523
635
  &block
524
636
  ).html
525
637
  end
526
638
 
527
- # Generates a single fieldset, intended for use within a {#govuk_check_boxes_fieldset}
639
+ # Generates a single check box, intended for use within a {#govuk_check_boxes_fieldset}
528
640
  #
529
641
  # @param attribute_name [Symbol] The name of the attribute
530
642
  # @param value [Boolean,String,Symbol,Integer] The value of the checkbox when it is checked
531
643
  # @param hint_text [String] the contents of the hint
532
- # @param link_errors [Boolean] controls whether this radio button should be linked to
644
+ # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
533
645
  # @option label text [String] the label text
534
646
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
535
647
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
@@ -565,14 +677,13 @@ module GOVUKDesignSystemFormBuilder
565
677
  # @param text [String] the button text
566
678
  # @param warning [Boolean] makes the button red ({https://design-system.service.gov.uk/components/button/#warning-buttons warning}) when true
567
679
  # @param secondary [Boolean] makes the button grey ({https://design-system.service.gov.uk/components/button/#secondary-buttons secondary}) when true
568
- # @todo The GOV.UK design system also supports {https://design-system.service.gov.uk/components/button/#disabled-buttons disabled buttons}, they
569
- # should probably be supported too
570
680
  # @param classes [String] Classes to add to the submit button
571
681
  # @param prevent_double_click [Boolean] adds JavaScript to safeguard the
572
682
  # form from being submitted more than once
573
683
  # @param validate [Boolean] adds the formnovalidate to the submit button when true, this disables all
574
684
  # client-side validation provided by the browser. This is to provide a more consistent and accessible user
575
685
  # experience
686
+ # @param disabled [Boolean] makes the button disabled when true
576
687
  # @param block [Block] Any supplied HTML will be inserted immediately after
577
688
  # the submit button. It is intended for other buttons directly related to
578
689
  # the form's operation, such as 'Cancel' or 'Safe draft'
@@ -587,8 +698,8 @@ module GOVUKDesignSystemFormBuilder
587
698
  # = f.govuk_submit "Proceed", prevent_double_click: true do
588
699
  # = link_to 'Cancel', some_other_path, class: 'govuk-button__secondary'
589
700
  #
590
- def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, prevent_double_click: true, validate: false, &block)
591
- Elements::Submit.new(self, text, warning: warning, secondary: secondary, classes: classes, prevent_double_click: prevent_double_click, validate: validate, &block).html
701
+ def govuk_submit(text = config.default_submit_button_text, warning: false, secondary: false, classes: nil, prevent_double_click: true, validate: false, disabled: false, &block)
702
+ Elements::Submit.new(self, text, warning: warning, secondary: secondary, classes: classes, prevent_double_click: prevent_double_click, validate: validate, disabled: disabled, &block).html
592
703
  end
593
704
 
594
705
  # Generates three inputs for the +day+, +month+ and +year+ components of a date
@@ -598,11 +709,14 @@ module GOVUKDesignSystemFormBuilder
598
709
  # be 'rounded' up to +2019-10-01+.
599
710
  # @param attribute_name [Symbol] The name of the attribute
600
711
  # @param hint_text [String] the contents of the hint
601
- # @param legend [Hash] options for configuring the legend
712
+ # @param legend [Hash,Proc] options for configuring the legend
602
713
  # @option legend text [String] the fieldset legend's text content
603
714
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
604
715
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
605
716
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
717
+ # @param caption [Hash] configures or sets the caption content which is inserted above the legend
718
+ # @option caption text [String] the caption text
719
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
606
720
  # @param omit_day [Boolean] do not render a day input, only capture month and year
607
721
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input group
608
722
  # @param date_of_birth [Boolean] if +true+ {https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values birth date auto completion attributes}
@@ -610,6 +724,7 @@ module GOVUKDesignSystemFormBuilder
610
724
  # @return [ActiveSupport::SafeBuffer] HTML output
611
725
  #
612
726
  # @see https://github.com/alphagov/govuk-frontend/issues/1449 GOV.UK date input element attributes, using text instead of number
727
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
613
728
  #
614
729
  # @example A regular date input with a legend, hint and injected content
615
730
  # = f.govuk_date_field :starts_on,
@@ -619,8 +734,11 @@ module GOVUKDesignSystemFormBuilder
619
734
  # p.govuk-inset-text
620
735
  # | If you don't fill this in you won't be eligable for a refund
621
736
  #
622
- def govuk_date_field(attribute_name, hint_text: nil, legend: {}, date_of_birth: false, omit_day: false, &block)
623
- Elements::Date.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, date_of_birth: date_of_birth, omit_day: omit_day, &block).html
737
+ # @example A date input with legend supplied as a proc
738
+ # = f.govuk_date_field :finishes_on,
739
+ # legend: -> { tag.h3('Which category do you belong to?') }
740
+ def govuk_date_field(attribute_name, hint_text: nil, legend: {}, caption: {}, date_of_birth: false, omit_day: false, &block)
741
+ Elements::Date.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, caption: caption, date_of_birth: date_of_birth, omit_day: omit_day, &block).html
624
742
  end
625
743
 
626
744
  # Generates a summary of errors in the form, each linking to the corresponding
@@ -628,12 +746,6 @@ module GOVUKDesignSystemFormBuilder
628
746
  #
629
747
  # @param title [String] the error summary heading
630
748
  #
631
- # @todo Currently the summary anchors link to the inline error messages themselves rather to
632
- # the accompanying input. More work is required to improve this and it needs to be
633
- # handled in a less-generic manner. For example, we can't link to a specific radio button
634
- # if one hasn't been chosen but we should link to a {#govuk_text_field} if one has been left
635
- # blank
636
- #
637
749
  # @example An error summary with a custom title
638
750
  # = f.govuk_error_summary 'Uh-oh, spaghettios'
639
751
  #
@@ -644,12 +756,15 @@ module GOVUKDesignSystemFormBuilder
644
756
 
645
757
  # Generates a fieldset containing the contents of the block
646
758
  #
647
- # @param legend [Hash] options for configuring the legend
759
+ # @param legend [Hash,Proc] options for configuring the legend
648
760
  # @param described_by [Array<String>] the ids of the elements that describe this fieldset, usually hints and errors
649
761
  # @option legend text [String] the fieldset legend's text content
650
762
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
651
763
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
652
764
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
765
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
766
+ # @option caption text [String] the caption text
767
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
653
768
  #
654
769
  # @example A fieldset containing address fields
655
770
  # = f.govuk_fieldset legend: { text: 'Address' }
@@ -657,10 +772,16 @@ module GOVUKDesignSystemFormBuilder
657
772
  # = f.govuk_text_field :town
658
773
  # = f.govuk_text_field :city
659
774
  #
775
+ # @example A fieldset with the legend as a proc
776
+ # = f.govuk_fieldset legend: -> { tag.h3('Skills') }
777
+ # = f.govuk_text_area :physical
778
+ # = f.govuk_text_area :mental
779
+ #
660
780
  # @see https://design-system.service.gov.uk/components/fieldset/ GOV.UK fieldset
781
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
661
782
  # @return [ActiveSupport::SafeBuffer] HTML output
662
- def govuk_fieldset(legend: { text: 'Fieldset heading' }, described_by: nil, &block)
663
- Containers::Fieldset.new(self, legend: legend, described_by: described_by).html(&block)
783
+ def govuk_fieldset(legend: { text: 'Fieldset heading' }, caption: {}, described_by: nil, &block)
784
+ Containers::Fieldset.new(self, legend: legend, caption: caption, described_by: described_by, &block).html
664
785
  end
665
786
 
666
787
  # Generates an input of type +file+
@@ -670,8 +791,11 @@ module GOVUKDesignSystemFormBuilder
670
791
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
671
792
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
672
793
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
794
+ # @param caption [Hash] configures or sets the caption content which is inserted above the label
795
+ # @option caption text [String] the caption text
796
+ # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
673
797
  # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
674
- # @option args [Hash] args additional arguments are applied as attributes to +input+ element
798
+ # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
675
799
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
676
800
  #
677
801
  # @example A photo upload field with file type specifier and injected content
@@ -680,14 +804,18 @@ module GOVUKDesignSystemFormBuilder
680
804
  # p.govuk-inset-text
681
805
  # | Explicit images will result in account termination
682
806
  #
807
+ # @example A CV upload field with label as a proc
808
+ # = f.govuk_file_field :cv, label: -> { tag.h3('Upload your CV') }
809
+ #
683
810
  # @see https://design-system.service.gov.uk/components/file-upload/ GOV.UK file upload
811
+ # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
684
812
  # @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file MDN documentation for file upload
685
813
  #
686
814
  # @note Remember to set +multipart: true+ when creating a form with file
687
815
  # uploads, {https://guides.rubyonrails.org/form_helpers.html#uploading-files see
688
816
  # the Rails documentation} for more information
689
- def govuk_file_field(attribute_name, label: {}, hint_text: nil, **args, &block)
690
- Elements::File.new(self, object_name, attribute_name, label: label, hint_text: hint_text, **args, &block).html
817
+ def govuk_file_field(attribute_name, label: {}, caption: {}, hint_text: nil, **args, &block)
818
+ Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint_text: hint_text, **args, &block).html
691
819
  end
692
820
  end
693
821
  end