govuk_design_system_formbuilder 1.2.7 → 2.0.0b4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (26) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +2 -2
  3. data/lib/govuk_design_system_formbuilder/builder.rb +213 -90
  4. data/lib/govuk_design_system_formbuilder/containers/check_boxes_fieldset.rb +21 -10
  5. data/lib/govuk_design_system_formbuilder/containers/form_group.rb +4 -3
  6. data/lib/govuk_design_system_formbuilder/containers/radio_buttons_fieldset.rb +10 -10
  7. data/lib/govuk_design_system_formbuilder/elements/caption.rb +10 -5
  8. data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection.rb +12 -12
  9. data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection_check_box.rb +6 -2
  10. data/lib/govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box.rb +13 -8
  11. data/lib/govuk_design_system_formbuilder/elements/date.rb +8 -8
  12. data/lib/govuk_design_system_formbuilder/elements/file.rb +8 -8
  13. data/lib/govuk_design_system_formbuilder/elements/hint.rb +35 -8
  14. data/lib/govuk_design_system_formbuilder/elements/label.rb +18 -12
  15. data/lib/govuk_design_system_formbuilder/elements/legend.rb +18 -10
  16. data/lib/govuk_design_system_formbuilder/elements/radios/collection.rb +14 -14
  17. data/lib/govuk_design_system_formbuilder/elements/radios/collection_radio_button.rb +9 -1
  18. data/lib/govuk_design_system_formbuilder/elements/radios/fieldset_radio_button.rb +12 -4
  19. data/lib/govuk_design_system_formbuilder/elements/select.rb +11 -11
  20. data/lib/govuk_design_system_formbuilder/elements/text_area.rb +11 -11
  21. data/lib/govuk_design_system_formbuilder/traits/caption.rb +1 -9
  22. data/lib/govuk_design_system_formbuilder/traits/collection_item.rb +1 -1
  23. data/lib/govuk_design_system_formbuilder/traits/hint.rb +15 -2
  24. data/lib/govuk_design_system_formbuilder/traits/input.rb +49 -13
  25. data/lib/govuk_design_system_formbuilder/version.rb +1 -1
  26. metadata +11 -11
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 73f7852a0c839a3c662b7c5551c2e3e96d37c32fde6af4ad861cfd37f8c0d79f
4
- data.tar.gz: 3252d8a1c64a4457de52ad87c2a7c9e5945b7400e7ee279c8e3910ee8f4a0cc4
3
+ metadata.gz: d1a220934d67c1a26afea6d623bd2424156b6b4b71ef88411703da5ae761d778
4
+ data.tar.gz: 808f12be46a25c60e1b1f97d074778bb1a8e1245a78a37672b6282dc4cdeb1fd
5
5
  SHA512:
6
- metadata.gz: 9dd6efdac09f58e06bb8241aacc420bfb016960320cbbf4c9496ed163a5f2ff1f63c79d5f5dca381b7da4f5efa5c75997a8a10542755de3f8a67adb19393756e
7
- data.tar.gz: b8ea6181c35e29784d8ebcb00bdb1a9d32d5970b26d260336413aaa8b475bee0a7ff085b64e05cb385014563ea7fb8799847c59d2408726a1fdd5b733b55b844
6
+ metadata.gz: 8fa051693840ca2463c6115bb0e4e4e53d68a0322697d49d186f83328635abee391466474da54cdc82fcbc77c28b055b10d7cb8374495965d00d8c4a8562134f
7
+ data.tar.gz: e8e93bdcbcd3d00b6d62477c52e0f2b4fa387de30825c479db38e1dfb4a1be89e316ff091c3eef1a0f0a917ad12581c26a565dc46cdfa55e1f5212053e459992
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.8.1-brightgreen)](https://design-system.service.gov.uk)
10
+ [![GOV.UK Design System Version](https://img.shields.io/badge/GOV.UK%20Design%20System-3.9.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.8.1 of the [GOV.UK Design System](https://design-system.service.gov.uk/),
13
+ fully-compliant with version 3.9.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
data/lib/govuk_design_system_formbuilder/builder.rb CHANGED
@@ -5,7 +5,11 @@ module GOVUKDesignSystemFormBuilder
5
5
  # Generates a input of type +text+
6
6
  #
7
7
  # @param attribute_name [Symbol] The name of the attribute
8
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
8
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
9
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
10
+ # @option hint text [String] the hint text
11
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
12
+ #
9
13
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
10
14
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
11
15
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -13,11 +17,17 @@ module GOVUKDesignSystemFormBuilder
13
17
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
14
18
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
15
19
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
20
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
16
21
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
17
22
  # @option caption text [String] the caption text
18
23
  # @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
20
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
24
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
25
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
26
+ # @param form_group [Hash] configures the form group
27
+ # @option form_group classes [Array,String] sets the form group's classes
28
+ # @option form_group kwargs [Hash] additional attributes added to the form group
29
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
30
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
21
31
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
22
32
  # @return [ActiveSupport::SafeBuffer] HTML output
23
33
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -26,7 +36,7 @@ module GOVUKDesignSystemFormBuilder
26
36
  # @example A required full name field with a placeholder
27
37
  # = f.govuk_text_field :name,
28
38
  # label: { text: 'Full name' },
29
- # hint_text: 'It says it on your birth certificate',
39
+ # hint: { text: 'It says it on your birth certificate' },
30
40
  # required: true,
31
41
  # placeholder: 'Ralph Wiggum'
32
42
  #
@@ -41,14 +51,17 @@ module GOVUKDesignSystemFormBuilder
41
51
  # = f.govuk_text_field :callsign,
42
52
  # label: -> { tag.h3('Call-sign') }
43
53
  #
44
- def govuk_text_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, form_group_classes: nil, **args, &block)
45
- Elements::Inputs::Text.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
54
+ def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
55
+ 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
46
56
  end
47
57
 
48
58
  # Generates a input of type +tel+
49
59
  #
50
60
  # @param attribute_name [Symbol] The name of the attribute
51
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
61
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
62
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
63
+ # @option hint text [String] the hint text
64
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
52
65
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
53
66
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
54
67
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -56,11 +69,17 @@ module GOVUKDesignSystemFormBuilder
56
69
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
57
70
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
58
71
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
72
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
59
73
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
60
74
  # @option caption text [String] the caption text
61
75
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
62
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
63
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
76
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
77
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
78
+ # @param form_group [Hash] configures the form group
79
+ # @option form_group classes [Array,String] sets the form group's classes
80
+ # @option form_group kwargs [Hash] additional attributes added to the form group
81
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
82
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
64
83
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
65
84
  # @return [ActiveSupport::SafeBuffer] HTML output
66
85
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -70,7 +89,7 @@ module GOVUKDesignSystemFormBuilder
70
89
  # @example A required phone number field with a placeholder
71
90
  # = f.govuk_phone_field :phone_number,
72
91
  # label: { text: 'UK telephone number' },
73
- # hint_text: 'Include the dialling code',
92
+ # hint: { text: 'Include the dialling code' },
74
93
  # required: true,
75
94
  # placeholder: '0123 456 789'
76
95
  #
@@ -85,14 +104,17 @@ module GOVUKDesignSystemFormBuilder
85
104
  # = f.govuk_phone_field :work_number,
86
105
  # label: -> { tag.h3('Work number') }
87
106
  #
88
- def govuk_phone_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, form_group_classes: nil, **args, &block)
89
- Elements::Inputs::Phone.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
107
+ def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
108
+ 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
90
109
  end
91
110
 
92
111
  # Generates a input of type +email+
93
112
  #
94
113
  # @param attribute_name [Symbol] The name of the attribute
95
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
114
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
115
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
116
+ # @option hint text [String] the hint text
117
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
96
118
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
97
119
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
98
120
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -100,11 +122,17 @@ module GOVUKDesignSystemFormBuilder
100
122
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
101
123
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
102
124
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
125
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
103
126
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
104
127
  # @option caption text [String] the caption text
105
128
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
106
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
107
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
129
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
130
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
131
+ # @param form_group [Hash] configures the form group
132
+ # @option form_group classes [Array,String] sets the form group's classes
133
+ # @option form_group kwargs [Hash] additional attributes added to the form group
134
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
135
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
108
136
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
109
137
  # @return [ActiveSupport::SafeBuffer] HTML output
110
138
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -127,14 +155,17 @@ module GOVUKDesignSystemFormBuilder
127
155
  # = f.govuk_email_field :personal_email,
128
156
  # label: -> { tag.h3('Personal email address') }
129
157
  #
130
- def govuk_email_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, form_group_classes: nil, **args, &block)
131
- Elements::Inputs::Email.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
158
+ def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
159
+ 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
132
160
  end
133
161
 
134
162
  # Generates a input of type +password+
135
163
  #
136
164
  # @param attribute_name [Symbol] The name of the attribute
137
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
165
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
166
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
167
+ # @option hint text [String] the hint text
168
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
138
169
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
139
170
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
140
171
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -142,11 +173,17 @@ module GOVUKDesignSystemFormBuilder
142
173
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
143
174
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
144
175
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
176
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
145
177
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
146
178
  # @option caption text [String] the caption text
147
179
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
148
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
149
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
180
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
181
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
182
+ # @param form_group [Hash] configures the form group
183
+ # @option form_group classes [Array,String] sets the form group's classes
184
+ # @option form_group kwargs [Hash] additional attributes added to the form group
185
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
186
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
150
187
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
151
188
  # @return [ActiveSupport::SafeBuffer] HTML output
152
189
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -168,14 +205,17 @@ module GOVUKDesignSystemFormBuilder
168
205
  # = f.govuk_password_field :passcode,
169
206
  # label: -> { tag.h3('What is your secret pass code?') }
170
207
  #
171
- def govuk_password_field(attribute_name, hint_text: nil, label: {}, width: nil, form_group_classes: nil, caption: {}, **args, &block)
172
- Elements::Inputs::Password.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
208
+ def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
209
+ 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
173
210
  end
174
211
 
175
212
  # Generates a input of type +url+
176
213
  #
177
214
  # @param attribute_name [Symbol] The name of the attribute
178
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
215
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
216
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
217
+ # @option hint text [String] the hint text
218
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
179
219
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
180
220
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
181
221
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -183,11 +223,17 @@ module GOVUKDesignSystemFormBuilder
183
223
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
184
224
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
185
225
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
226
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
186
227
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
187
228
  # @option caption text [String] the caption text
188
229
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
189
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
190
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
230
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
231
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
232
+ # @param form_group [Hash] configures the form group
233
+ # @option form_group classes [Array,String] sets the form group's classes
234
+ # @option form_group kwargs [Hash] additional attributes added to the form group
235
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
236
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
191
237
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
192
238
  # @return [ActiveSupport::SafeBuffer] HTML output
193
239
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -210,14 +256,17 @@ module GOVUKDesignSystemFormBuilder
210
256
  # = f.govuk_url_field :work_website,
211
257
  # label: -> { tag.h3("Enter your company's website") }
212
258
  #
213
- def govuk_url_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, form_group_classes: nil, **args, &block)
214
- Elements::Inputs::URL.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
259
+ def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
260
+ 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
215
261
  end
216
262
 
217
263
  # Generates a input of type +number+
218
264
  #
219
265
  # @param attribute_name [Symbol] The name of the attribute
220
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
266
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
267
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
268
+ # @option hint text [String] the hint text
269
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
221
270
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
222
271
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
223
272
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -225,11 +274,17 @@ module GOVUKDesignSystemFormBuilder
225
274
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
226
275
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
227
276
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
277
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
228
278
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
229
279
  # @option caption text [String] the caption text
230
280
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
231
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
232
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
281
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
282
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
283
+ # @param form_group [Hash] configures the form group
284
+ # @option form_group classes [Array,String] sets the form group's classes
285
+ # @option form_group kwargs [Hash] additional attributes added to the form group
286
+ # @param prefix_text [String] the text placed before the input. No prefix will be added if left +nil+
287
+ # @param suffix_text [String] the text placed after the input. No suffix will be added if left +nil+
233
288
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
234
289
  # @return [ActiveSupport::SafeBuffer] HTML output
235
290
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -255,8 +310,8 @@ module GOVUKDesignSystemFormBuilder
255
310
  # = f.govuk_url_field :personal_best_over_100m,
256
311
  # label: -> { tag.h3("How many seconds does it take you to run 100m?") }
257
312
  #
258
- def govuk_number_field(attribute_name, hint_text: nil, label: {}, caption: {}, width: nil, form_group_classes: nil, **args, &block)
259
- Elements::Inputs::Number.new(self, object_name, attribute_name, hint_text: hint_text, label: label, caption: caption, width: width, form_group_classes: form_group_classes, **args, &block).html
313
+ def govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, prefix_text: nil, suffix_text: nil, **kwargs, &block)
314
+ 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
260
315
  end
261
316
 
262
317
  # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -264,21 +319,28 @@ module GOVUKDesignSystemFormBuilder
264
319
  # automatically
265
320
  #
266
321
  # @param attribute_name [Symbol] The name of the attribute
267
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
322
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
323
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
324
+ # @option hint text [String] the hint text
325
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
268
326
  # @param label [Hash,Proc] configures or sets the associated label content
269
327
  # @option label text [String] the label text
270
328
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
271
329
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
272
330
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
331
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
273
332
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
274
333
  # @option caption text [String] the caption text
275
334
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
335
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
276
336
  # @param max_words [Integer] adds the GOV.UK max word count
277
337
  # @param max_chars [Integer] adds the GOV.UK max characters count
278
338
  # @param threshold [Integer] only show the +max_words+ and +max_chars+ warnings once a threshold (percentage) is reached
279
339
  # @param rows [Integer] sets the initial number of rows
280
- # @option args [Hash] args additional arguments are applied as attributes to the +textarea+ element
281
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
340
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +textarea+ element
341
+ # @param form_group [Hash] configures the form group
342
+ # @option form_group classes [Array,String] sets the form group's classes
343
+ # @option form_group kwargs [Hash] additional attributes added to the form group
282
344
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
283
345
  # @return [ActiveSupport::SafeBuffer] HTML output
284
346
  # @see https://design-system.service.gov.uk/components/textarea/ GOV.UK text area component
@@ -304,8 +366,8 @@ module GOVUKDesignSystemFormBuilder
304
366
  # = f.govuk_text_area :instructions,
305
367
  # label: -> { tag.h3("How do you set it up?") }
306
368
  #
307
- def govuk_text_area(attribute_name, hint_text: nil, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group_classes: nil, **args, &block)
308
- 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, form_group_classes: form_group_classes, **args, &block).html
369
+ def govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **kwargs, &block)
370
+ Elements::TextArea.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, form_group: form_group, **kwargs, &block).html
309
371
  end
310
372
 
311
373
  # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -314,14 +376,20 @@ module GOVUKDesignSystemFormBuilder
314
376
  # @param collection [Enumerable<Object>] Options to be added to the +select+ element
315
377
  # @param value_method [Symbol] The method called against each member of the collection to provide the value
316
378
  # @param text_method [Symbol] The method called against each member of the collection to provide the text
317
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
379
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
380
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
381
+ # @option hint text [String] the hint text
382
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
318
383
  # @option label text [String] the label text
319
384
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
320
385
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
321
386
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
387
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
322
388
  # @param options [Hash] Options hash passed through to Rails' +collection_select+ helper
323
389
  # @param html_options [Hash] HTML Options hash passed through to Rails' +collection_select+ helper
324
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
390
+ # @param form_group [Hash] configures the form group
391
+ # @option form_group classes [Array,String] sets the form group's classes
392
+ # @option form_group kwargs [Hash] additional attributes added to the form group
325
393
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
326
394
  # @see https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-collection_select Rails collection_select (called by govuk_collection_select)
327
395
  # @return [ActiveSupport::SafeBuffer] HTML output
@@ -331,7 +399,7 @@ module GOVUKDesignSystemFormBuilder
331
399
  # @grades,
332
400
  # :id,
333
401
  # :name,
334
- # hint_text: "If you took the test more than once enter your highest grade"
402
+ # hint: { text: "If you took the test more than once enter your highest grade" }
335
403
  #
336
404
  # @example A select box with injected content
337
405
  # = f.govuk_collection_select(:favourite_colour, @colours, :id, :name) do
@@ -343,7 +411,7 @@ module GOVUKDesignSystemFormBuilder
343
411
  # = f.govuk_collection_select(:team, @teams, :id, :name) do
344
412
  # label: -> { tag.h3("Which team did you represent?") }
345
413
  #
346
- def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint_text: nil, label: {}, caption: {}, form_group_classes: nil, &block)
414
+ def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint: {}, label: {}, caption: {}, form_group: {}, &block)
347
415
  Elements::Select.new(
348
416
  self,
349
417
  object_name,
@@ -351,12 +419,12 @@ module GOVUKDesignSystemFormBuilder
351
419
  collection,
352
420
  value_method: value_method,
353
421
  text_method: text_method,
354
- hint_text: hint_text,
422
+ hint: hint,
355
423
  label: label,
356
424
  caption: caption,
357
425
  options: options,
358
426
  html_options: html_options,
359
- form_group_classes: form_group_classes,
427
+ form_group: form_group,
360
428
  &block
361
429
  ).html
362
430
  end
@@ -380,8 +448,11 @@ module GOVUKDesignSystemFormBuilder
380
448
  # @param hint_method [Symbol, Proc, nil] The method called against each member of the collection to provide the hint text.
381
449
  # When a +Proc+ is provided it must take a single argument that is a single member of the collection.
382
450
  # When a +nil+ value is provided the hint text will be retrieved from the locale. This is the default and param can be omitted.
383
- # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
384
- # @param legend [Hash,Proc] options for configuring the legend
451
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
452
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
453
+ # @option hint text [String] the hint text
454
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
455
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
385
456
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
386
457
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
387
458
  # @param bold_labels [Boolean] controls whether the radio button labels are bold
@@ -390,9 +461,11 @@ module GOVUKDesignSystemFormBuilder
390
461
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
391
462
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
392
463
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
464
+ # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
393
465
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
394
466
  # @option caption text [String] the caption text
395
467
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
468
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
396
469
  # @return [ActiveSupport::SafeBuffer] HTML output
397
470
  #
398
471
  # @example A collection of radio buttons for favourite colours, labels capitalised via a proc
@@ -408,7 +481,7 @@ module GOVUKDesignSystemFormBuilder
408
481
  # ->(option) { option.name.upcase },
409
482
  # :description,
410
483
  # legend: { text: 'Pick your favourite colour', size: 'm' },
411
- # hint_text: 'If you cannot find the exact match choose something close',
484
+ # hint: { text: 'If you cannot find the exact match choose something close' },
412
485
  # inline: false
413
486
  #
414
487
  # @example A collection of radio buttons for grades with injected content
@@ -427,7 +500,7 @@ module GOVUKDesignSystemFormBuilder
427
500
  # :name,
428
501
  # legend: -> { tag.h3('Which category do you belong to?') }
429
502
  #
430
- 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, form_group_classes: nil, &block)
503
+ 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)
431
504
  Elements::Radios::Collection.new(
432
505
  self,
433
506
  object_name,
@@ -436,14 +509,14 @@ module GOVUKDesignSystemFormBuilder
436
509
  value_method: value_method,
437
510
  text_method: text_method,
438
511
  hint_method: hint_method,
439
- hint_text: hint_text,
512
+ hint: hint,
440
513
  legend: legend,
441
514
  caption: caption,
442
515
  inline: inline,
443
516
  small: small,
444
517
  bold_labels: bold_labels,
445
518
  classes: classes,
446
- form_group_classes: form_group_classes,
519
+ form_group: form_group,
447
520
  &block
448
521
  ).html
449
522
  end
@@ -456,18 +529,25 @@ module GOVUKDesignSystemFormBuilder
456
529
  # is set to +link_errors: true+
457
530
  #
458
531
  # @param attribute_name [Symbol] The name of the attribute
459
- # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
460
- # @param legend [Hash,Proc] options for configuring the legend
532
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
533
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
534
+ # @option hint text [String] the hint text
535
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
536
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
461
537
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
462
538
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
463
539
  # @option legend text [String] the fieldset legend's text content
464
540
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
465
541
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
466
542
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
543
+ # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
467
544
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
468
545
  # @option caption text [String] the caption text
469
546
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
470
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
547
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
548
+ # @param form_group [Hash] configures the form group
549
+ # @option form_group classes [Array,String] sets the form group's classes
550
+ # @option form_group kwargs [Hash] additional attributes added to the form group
471
551
  # @param block [Block] a block of HTML that will be used to populate the fieldset
472
552
  # @param classes [Array,String] Classes to add to the radio button container.
473
553
  # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
@@ -491,19 +571,24 @@ module GOVUKDesignSystemFormBuilder
491
571
  # = f.govuk_radio_button :burger_id, :regular, label: { text: 'Hamburger' }, link_errors: true
492
572
  # = f.govuk_radio_button :burger_id, :cheese, label: { text: 'Cheeseburger' }
493
573
  #
494
- def govuk_radio_buttons_fieldset(attribute_name, hint_text: nil, legend: {}, caption: {}, inline: false, small: false, classes: nil, form_group_classes: nil, &block)
495
- Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint_text: hint_text, legend: legend, caption: caption, inline: inline, small: small, classes: classes, form_group_classes: form_group_classes, &block).html
574
+ def govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, classes: nil, form_group: {}, &block)
575
+ Containers::RadioButtonsFieldset.new(self, object_name, attribute_name, hint: hint, legend: legend, caption: caption, inline: inline, small: small, classes: classes, form_group: form_group, &block).html
496
576
  end
497
577
 
498
578
  # Generates a radio button
499
579
  #
500
580
  # @note This should only be used from within a {#govuk_radio_buttons_fieldset}
501
581
  # @param attribute_name [Symbol] The name of the attribute
502
- # @param hint_text [String] the contents of the hint
503
- # @option legend text [String] the fieldset legend's text content
504
- # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
505
- # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
506
- # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
582
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
583
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
584
+ # @option hint text [String] the hint text
585
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
586
+ # @param label [Hash,Proc] configures or sets the associated label content
587
+ # @option label text [String] the label text
588
+ # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
589
+ # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
590
+ # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
591
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
507
592
  # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
508
593
  # @see https://design-system.service.gov.uk/styles/typography/#headings-with-captions Headings with captions
509
594
  # @param block [Block] Any supplied HTML will be wrapped in a conditional
@@ -517,8 +602,8 @@ module GOVUKDesignSystemFormBuilder
517
602
  # = f.govuk_radio_buttons_fieldset :favourite_colour do
518
603
  # = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
519
604
  #
520
- def govuk_radio_button(attribute_name, value, hint_text: nil, label: {}, link_errors: false, &block)
521
- Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint_text: hint_text, label: label, link_errors: link_errors, &block).html
605
+ def govuk_radio_button(attribute_name, value, hint: {}, label: {}, link_errors: false, &block)
606
+ Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint: hint, label: label, link_errors: link_errors, &block).html
522
607
  end
523
608
 
524
609
  # Inserts a text divider into a list of radio buttons
@@ -541,10 +626,13 @@ module GOVUKDesignSystemFormBuilder
541
626
  # @param text_method [Symbol] The method called against each member of the collection to provide the label text
542
627
  # @param hint_method [Symbol, Proc] The method called against each member of the collection to provide the hint text.
543
628
  # When a +Proc+ is provided it must take a single argument that is a single member of the collection
544
- # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
629
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
630
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
631
+ # @option hint text [String] the hint text
632
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
545
633
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
546
634
  # @param classes [Array,String] Classes to add to the checkbox container.
547
- # @param legend [Hash,Proc] options for configuring the legend
635
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
548
636
  # @option legend text [String] the fieldset legend's text content
549
637
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
550
638
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
@@ -552,7 +640,10 @@ module GOVUKDesignSystemFormBuilder
552
640
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
553
641
  # @option caption text [String] the caption text
554
642
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
555
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
643
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
644
+ # @param form_group [Hash] configures the form group
645
+ # @option form_group classes [Array,String] sets the form group's classes
646
+ # @option form_group kwargs [Hash] additional attributes added to the form group
556
647
  # @param block [Block] any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes
557
648
  # @return [ActiveSupport::SafeBuffer] HTML output
558
649
  #
@@ -569,7 +660,7 @@ module GOVUKDesignSystemFormBuilder
569
660
  # :name,
570
661
  # :description,
571
662
  # legend: { text: 'What do you want in your sandwich?', size: 'm' },
572
- # hint_text: "If it isn't listed here, tough luck",
663
+ # hint: { text: "If it isn't listed here, tough luck" },
573
664
  # inline: false,
574
665
  # classes: 'app-overflow-scroll',
575
666
  #
@@ -589,7 +680,7 @@ module GOVUKDesignSystemFormBuilder
589
680
  # :name,
590
681
  # legend: -> { tag.h3('What kind of sandwich do you want?') }
591
682
  #
592
- def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint_text: nil, legend: {}, caption: {}, small: false, classes: nil, form_group_classes: nil, &block)
683
+ def govuk_collection_check_boxes(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, small: false, classes: nil, form_group: {}, &block)
593
684
  Elements::CheckBoxes::Collection.new(
594
685
  self,
595
686
  object_name,
@@ -598,12 +689,12 @@ module GOVUKDesignSystemFormBuilder
598
689
  value_method: value_method,
599
690
  text_method: text_method,
600
691
  hint_method: hint_method,
601
- hint_text: hint_text,
692
+ hint: hint,
602
693
  legend: legend,
603
694
  caption: caption,
604
695
  small: small,
605
696
  classes: classes,
606
- form_group_classes: form_group_classes,
697
+ form_group: form_group,
607
698
  &block
608
699
  ).html
609
700
  end
@@ -614,18 +705,27 @@ module GOVUKDesignSystemFormBuilder
614
705
  # is set to +link_errors: true+
615
706
  #
616
707
  # @param attribute_name [Symbol] The name of the attribute
617
- # @param hint_text [String] The content of the fieldset hint. No hint will be injected if left +nil+
708
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
709
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
710
+ # @option hint text [String] the hint text
711
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
618
712
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
619
- # @param legend [Hash,Proc] options for configuring the legend
713
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
620
714
  # @option legend text [String] the fieldset legend's text content
621
715
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
622
716
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
623
717
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
718
+ # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
624
719
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
625
720
  # @option caption text [String] the caption text
626
721
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
722
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
627
723
  # @param classes [Array,String] Classes to add to the checkbox container.
628
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
724
+ # @param form_group [Hash] configures the form group
725
+ # @param multiple [Boolean] when true adds a +[]+ suffix the +name+ of the automatically-generated hidden field
726
+ # (ie. <code>project[invoice_attributes][]</code>). When false, no +[]+ suffix is added (ie. <code>project[accepted]</code>)
727
+ # @option form_group classes [Array,String] sets the form group's classes
728
+ # @option form_group kwargs [Hash] additional attributes added to the form group
629
729
  # @param block [Block] a block of HTML that will be used to populate the fieldset
630
730
  # @return [ActiveSupport::SafeBuffer] HTML output
631
731
  #
@@ -639,17 +739,18 @@ module GOVUKDesignSystemFormBuilder
639
739
  # = f.govuk_check_box :desired_filling, :lemonade, label: { text: 'Lemonade' }, link_errors: true
640
740
  # = f.govuk_check_box :desired_filling, :fizzy_orange, label: { text: 'Fizzy orange' }
641
741
  #
642
- def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint_text: {}, small: false, classes: nil, form_group_classes: nil, &block)
742
+ def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, classes: nil, form_group: {}, multiple: true, &block)
643
743
  Containers::CheckBoxesFieldset.new(
644
744
  self,
645
745
  object_name,
646
746
  attribute_name,
647
- hint_text: hint_text,
747
+ hint: hint,
648
748
  legend: legend,
649
749
  caption: caption,
650
750
  small: small,
651
751
  classes: classes,
652
- form_group_classes: form_group_classes,
752
+ form_group: form_group,
753
+ multiple: multiple,
653
754
  &block
654
755
  ).html
655
756
  end
@@ -658,12 +759,17 @@ module GOVUKDesignSystemFormBuilder
658
759
  #
659
760
  # @param attribute_name [Symbol] The name of the attribute
660
761
  # @param value [Boolean,String,Symbol,Integer] The value of the checkbox when it is checked
661
- # @param hint_text [String] the contents of the hint
762
+ # @param unchecked_value [Boolean,String,Symbol,Integer] The value of the checkbox when it is unchecked
763
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
764
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
765
+ # @option hint text [String] the hint text
766
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
662
767
  # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
663
768
  # @option label text [String] the label text
664
769
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
665
770
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
666
771
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
772
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
667
773
  # @param multiple [Boolean] controls whether the check box is part of a collection or represents a single attribute
668
774
  # @param block [Block] any HTML passed in will form the contents of the fieldset
669
775
  # @return [ActiveSupport::SafeBuffer] HTML output
@@ -674,15 +780,16 @@ module GOVUKDesignSystemFormBuilder
674
780
  # multiple: false,
675
781
  # link_errors: true,
676
782
  # label: { text: 'Do you agree with our terms and conditions?' },
677
- # hint_text: 'You will not be able to proceed unless you do'
783
+ # hint: { text: 'You will not be able to proceed unless you do' }
678
784
  #
679
- def govuk_check_box(attribute_name, value, hint_text: nil, label: {}, link_errors: false, multiple: true, &block)
785
+ def govuk_check_box(attribute_name, value, unchecked_value = false, hint: {}, label: {}, link_errors: false, multiple: true, &block)
680
786
  Elements::CheckBoxes::FieldsetCheckBox.new(
681
787
  self,
682
788
  object_name,
683
789
  attribute_name,
684
790
  value,
685
- hint_text: hint_text,
791
+ unchecked_value,
792
+ hint: hint,
686
793
  label: label,
687
794
  link_errors: link_errors,
688
795
  multiple: multiple,
@@ -726,17 +833,24 @@ module GOVUKDesignSystemFormBuilder
726
833
  # of {https://bugs.ruby-lang.org/issues/5988 this} bug, so incorrect dates like +2019-09-31+ will
727
834
  # be 'rounded' up to +2019-10-01+.
728
835
  # @param attribute_name [Symbol] The name of the attribute
729
- # @param hint_text [String] the contents of the hint
730
- # @param legend [Hash,Proc] options for configuring the legend
836
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
837
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
838
+ # @option hint text [String] the hint text
839
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
840
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
731
841
  # @option legend text [String] the fieldset legend's text content
732
842
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
733
843
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
734
844
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
845
+ # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
735
846
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
736
847
  # @option caption text [String] the caption text
737
848
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
849
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
738
850
  # @param omit_day [Boolean] do not render a day input, only capture month and year
739
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
851
+ # @param form_group [Hash] configures the form group
852
+ # @option form_group classes [Array,String] sets the form group's classes
853
+ # @option form_group kwargs [Hash] additional attributes added to the form group
740
854
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input group
741
855
  # @param date_of_birth [Boolean] if +true+ {https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values birth date auto completion attributes}
742
856
  # will be added to the inputs
@@ -748,7 +862,7 @@ module GOVUKDesignSystemFormBuilder
748
862
  # @example A regular date input with a legend, hint and injected content
749
863
  # = f.govuk_date_field :starts_on,
750
864
  # legend: { 'When does your event start?' },
751
- # hint_text: 'Leave this field blank if you don't know exactly' } do
865
+ # hint: { text: 'Leave this field blank if you don't know exactly' } do
752
866
  #
753
867
  # p.govuk-inset-text
754
868
  # | If you don't fill this in you won't be eligable for a refund
@@ -756,8 +870,8 @@ module GOVUKDesignSystemFormBuilder
756
870
  # @example A date input with legend supplied as a proc
757
871
  # = f.govuk_date_field :finishes_on,
758
872
  # legend: -> { tag.h3('Which category do you belong to?') }
759
- def govuk_date_field(attribute_name, hint_text: nil, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group_classes: nil, &block)
760
- 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, form_group_classes: form_group_classes, &block).html
873
+ def govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group: {}, &block)
874
+ Elements::Date.new(self, object_name, attribute_name, hint: hint, legend: legend, caption: caption, date_of_birth: date_of_birth, omit_day: omit_day, form_group: form_group, &block).html
761
875
  end
762
876
 
763
877
  # Generates a summary of errors in the form, each linking to the corresponding
@@ -775,15 +889,17 @@ module GOVUKDesignSystemFormBuilder
775
889
 
776
890
  # Generates a fieldset containing the contents of the block
777
891
  #
778
- # @param legend [Hash,Proc] options for configuring the legend
892
+ # @param legend [NilClass,Hash,Proc] options for configuring the legend. Legend will be omitted if +nil+.
779
893
  # @param described_by [Array<String>] the ids of the elements that describe this fieldset, usually hints and errors
780
894
  # @option legend text [String] the fieldset legend's text content
781
895
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
782
896
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
783
897
  # @option legend hidden [Boolean] control the visibility of the legend. Hidden legends will still be read by screenreaders
898
+ # @option legend kwargs [Hash] additional arguments are applied as attributes on the +legend+ element
784
899
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
785
900
  # @option caption text [String] the caption text
786
901
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
902
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
787
903
  #
788
904
  # @example A fieldset containing address fields
789
905
  # = f.govuk_fieldset legend: { text: 'Address' }
@@ -810,12 +926,19 @@ module GOVUKDesignSystemFormBuilder
810
926
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
811
927
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
812
928
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
929
+ # @option label kwargs [Hash] additional arguments are applied as attributes on the +label+ element
813
930
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
814
931
  # @option caption text [String] the caption text
815
932
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
816
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
817
- # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
818
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
933
+ # @option caption kwargs [Hash] additional arguments are applied as attributes on the caption +span+ element
934
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
935
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
936
+ # @option hint text [String] the hint text
937
+ # @option hint kwargs [Hash] additional arguments are applied as attributes to the hint
938
+ # @option kwargs [Hash] kwargs additional arguments are applied as attributes to the +input+ element
939
+ # @param form_group [Hash] configures the form group
940
+ # @option form_group classes [Array,String] sets the form group's classes
941
+ # @option form_group kwargs [Hash] additional attributes added to the form group
819
942
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
820
943
  #
821
944
  # @example A photo upload field with file type specifier and injected content
@@ -834,8 +957,8 @@ module GOVUKDesignSystemFormBuilder
834
957
  # @note Remember to set +multipart: true+ when creating a form with file
835
958
  # uploads, {https://guides.rubyonrails.org/form_helpers.html#uploading-files see
836
959
  # the Rails documentation} for more information
837
- def govuk_file_field(attribute_name, label: {}, caption: {}, hint_text: nil, form_group_classes: nil, **args, &block)
838
- Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint_text: hint_text, form_group_classes: form_group_classes, **args, &block).html
960
+ def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **kwargs, &block)
961
+ Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **kwargs, &block).html
839
962
  end
840
963
  end
841
964
  end