govuk_design_system_formbuilder 1.2.9 → 2.0.0b1

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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 0c6269db9ed06ab08bc6bfa1d561b88da157c4b473e4560d0de0dd8038e7f87e
4
- data.tar.gz: ded604de8c561002ae266f1b2a6ba36398947eea3dc868be2330345cd39fc6ef
3
+ metadata.gz: 52cc4abc62b3ac208e8fe2befb527b6deda60868d2094a3172d907bc0ce82654
4
+ data.tar.gz: fb0c810a65f025e226fe4dc0cee0c5b42b3b7baa499b032d6f88d4ec2fac9d54
5
5
  SHA512:
6
- metadata.gz: 5e7844dd37618342514e85bdaab2756fa2ea842545eb26e0ca42a17f95095080a78192fea747bfc829283b446f0fee16ef5f2e7a6c854615e3af90df63f982fa
7
- data.tar.gz: ab5f73b61f765ccf659f48e939593e5738d85127fd1854a59f60d749af4e0ead6255e5f15df4b4e1f930d07b4279bbfeca80c8b53302d332570fda642ad72a20
6
+ metadata.gz: 996a9f979a4eab0a16499f81cf39fdcfbd0c641dd5d2944c52be697cd6f1f8870b75c6fd4b498d3769265fa39168f7baefe36bb53255bc50a9bfcb82f06bd641
7
+ data.tar.gz: ef2f8f3eaba7ea21b2ae18a7a4ba8c181981164f36917d082ff5f2545896df17c6b27c9acab09621d3e5453013d9e5747e5f838b54bc2f2e68aed585980190d9
@@ -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 args [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
@@ -17,7 +21,9 @@ module GOVUKDesignSystemFormBuilder
17
21
  # @option caption text [String] the caption text
18
22
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
19
23
  # @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
+ # @param form_group [Hash] configures the form group
25
+ # @option form_group classes [Array,String] sets the form group's classes
26
+ # @option form_group args [Hash] additional attributes added to the form group
21
27
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
22
28
  # @return [ActiveSupport::SafeBuffer] HTML output
23
29
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -26,7 +32,7 @@ module GOVUKDesignSystemFormBuilder
26
32
  # @example A required full name field with a placeholder
27
33
  # = f.govuk_text_field :name,
28
34
  # label: { text: 'Full name' },
29
- # hint_text: 'It says it on your birth certificate',
35
+ # hint: { text: 'It says it on your birth certificate' },
30
36
  # required: true,
31
37
  # placeholder: 'Ralph Wiggum'
32
38
  #
@@ -41,14 +47,17 @@ module GOVUKDesignSystemFormBuilder
41
47
  # = f.govuk_text_field :callsign,
42
48
  # label: -> { tag.h3('Call-sign') }
43
49
  #
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
50
+ def govuk_text_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
51
+ Elements::Inputs::Text.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
46
52
  end
47
53
 
48
54
  # Generates a input of type +tel+
49
55
  #
50
56
  # @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+
57
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
58
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
59
+ # @option hint text [String] the hint text
60
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
52
61
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
53
62
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
54
63
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -60,7 +69,9 @@ module GOVUKDesignSystemFormBuilder
60
69
  # @option caption text [String] the caption text
61
70
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
62
71
  # @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+
72
+ # @param form_group [Hash] configures the form group
73
+ # @option form_group classes [Array,String] sets the form group's classes
74
+ # @option form_group args [Hash] additional attributes added to the form group
64
75
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
65
76
  # @return [ActiveSupport::SafeBuffer] HTML output
66
77
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -70,7 +81,7 @@ module GOVUKDesignSystemFormBuilder
70
81
  # @example A required phone number field with a placeholder
71
82
  # = f.govuk_phone_field :phone_number,
72
83
  # label: { text: 'UK telephone number' },
73
- # hint_text: 'Include the dialling code',
84
+ # hint: { text: 'Include the dialling code' },
74
85
  # required: true,
75
86
  # placeholder: '0123 456 789'
76
87
  #
@@ -85,14 +96,17 @@ module GOVUKDesignSystemFormBuilder
85
96
  # = f.govuk_phone_field :work_number,
86
97
  # label: -> { tag.h3('Work number') }
87
98
  #
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
99
+ def govuk_phone_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
100
+ Elements::Inputs::Phone.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
90
101
  end
91
102
 
92
103
  # Generates a input of type +email+
93
104
  #
94
105
  # @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+
106
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
107
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
108
+ # @option hint text [String] the hint text
109
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
96
110
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
97
111
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
98
112
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -104,7 +118,9 @@ module GOVUKDesignSystemFormBuilder
104
118
  # @option caption text [String] the caption text
105
119
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
106
120
  # @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+
121
+ # @param form_group [Hash] configures the form group
122
+ # @option form_group classes [Array,String] sets the form group's classes
123
+ # @option form_group args [Hash] additional attributes added to the form group
108
124
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
109
125
  # @return [ActiveSupport::SafeBuffer] HTML output
110
126
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -127,14 +143,17 @@ module GOVUKDesignSystemFormBuilder
127
143
  # = f.govuk_email_field :personal_email,
128
144
  # label: -> { tag.h3('Personal email address') }
129
145
  #
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
146
+ def govuk_email_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
147
+ Elements::Inputs::Email.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
132
148
  end
133
149
 
134
150
  # Generates a input of type +password+
135
151
  #
136
152
  # @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+
153
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
154
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
155
+ # @option hint text [String] the hint text
156
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
138
157
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
139
158
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
140
159
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -146,7 +165,9 @@ module GOVUKDesignSystemFormBuilder
146
165
  # @option caption text [String] the caption text
147
166
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
148
167
  # @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+
168
+ # @param form_group [Hash] configures the form group
169
+ # @option form_group classes [Array,String] sets the form group's classes
170
+ # @option form_group args [Hash] additional attributes added to the form group
150
171
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
151
172
  # @return [ActiveSupport::SafeBuffer] HTML output
152
173
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -168,14 +189,17 @@ module GOVUKDesignSystemFormBuilder
168
189
  # = f.govuk_password_field :passcode,
169
190
  # label: -> { tag.h3('What is your secret pass code?') }
170
191
  #
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
192
+ def govuk_password_field(attribute_name, hint: {}, label: {}, width: nil, form_group: {}, caption: {}, **args, &block)
193
+ Elements::Inputs::Password.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
173
194
  end
174
195
 
175
196
  # Generates a input of type +url+
176
197
  #
177
198
  # @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+
199
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
200
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
201
+ # @option hint text [String] the hint text
202
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
179
203
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
180
204
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
181
205
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -187,7 +211,9 @@ module GOVUKDesignSystemFormBuilder
187
211
  # @option caption text [String] the caption text
188
212
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
189
213
  # @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+
214
+ # @param form_group [Hash] configures the form group
215
+ # @option form_group classes [Array,String] sets the form group's classes
216
+ # @option form_group args [Hash] additional attributes added to the form group
191
217
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
192
218
  # @return [ActiveSupport::SafeBuffer] HTML output
193
219
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -210,14 +236,17 @@ module GOVUKDesignSystemFormBuilder
210
236
  # = f.govuk_url_field :work_website,
211
237
  # label: -> { tag.h3("Enter your company's website") }
212
238
  #
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
239
+ def govuk_url_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
240
+ Elements::Inputs::URL.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
215
241
  end
216
242
 
217
243
  # Generates a input of type +number+
218
244
  #
219
245
  # @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+
246
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
247
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
248
+ # @option hint text [String] the hint text
249
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
221
250
  # @param width [Integer,String] sets the width of the input, can be +2+, +3+ +4+, +5+, +10+ or +20+ characters
222
251
  # or +one-quarter+, +one-third+, +one-half+, +two-thirds+ or +full+ width of the container
223
252
  # @param label [Hash,Proc] configures or sets the associated label content
@@ -229,7 +258,9 @@ module GOVUKDesignSystemFormBuilder
229
258
  # @option caption text [String] the caption text
230
259
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
231
260
  # @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+
261
+ # @param form_group [Hash] configures the form group
262
+ # @option form_group classes [Array,String] sets the form group's classes
263
+ # @option form_group args [Hash] additional attributes added to the form group
233
264
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
234
265
  # @return [ActiveSupport::SafeBuffer] HTML output
235
266
  # @see https://design-system.service.gov.uk/components/text-input/ GOV.UK Text input
@@ -255,8 +286,8 @@ module GOVUKDesignSystemFormBuilder
255
286
  # = f.govuk_url_field :personal_best_over_100m,
256
287
  # label: -> { tag.h3("How many seconds does it take you to run 100m?") }
257
288
  #
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
289
+ def govuk_number_field(attribute_name, hint: {}, label: {}, caption: {}, width: nil, form_group: {}, **args, &block)
290
+ Elements::Inputs::Number.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, width: width, form_group: form_group, **args, &block).html
260
291
  end
261
292
 
262
293
  # Generates a +textarea+ element with a label, optional hint. Also offers
@@ -264,7 +295,10 @@ module GOVUKDesignSystemFormBuilder
264
295
  # automatically
265
296
  #
266
297
  # @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+
298
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
299
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
300
+ # @option hint text [String] the hint text
301
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
268
302
  # @param label [Hash,Proc] configures or sets the associated label content
269
303
  # @option label text [String] the label text
270
304
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
@@ -278,7 +312,9 @@ module GOVUKDesignSystemFormBuilder
278
312
  # @param threshold [Integer] only show the +max_words+ and +max_chars+ warnings once a threshold (percentage) is reached
279
313
  # @param rows [Integer] sets the initial number of rows
280
314
  # @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+
315
+ # @param form_group [Hash] configures the form group
316
+ # @option form_group classes [Array,String] sets the form group's classes
317
+ # @option form_group args [Hash] additional attributes added to the form group
282
318
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
283
319
  # @return [ActiveSupport::SafeBuffer] HTML output
284
320
  # @see https://design-system.service.gov.uk/components/textarea/ GOV.UK text area component
@@ -304,8 +340,8 @@ module GOVUKDesignSystemFormBuilder
304
340
  # = f.govuk_text_area :instructions,
305
341
  # label: -> { tag.h3("How do you set it up?") }
306
342
  #
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
343
+ def govuk_text_area(attribute_name, hint: {}, label: {}, caption: {}, max_words: nil, max_chars: nil, rows: 5, threshold: nil, form_group: {}, **args, &block)
344
+ Elements::TextArea.new(self, object_name, attribute_name, hint: hint, label: label, caption: caption, max_words: max_words, max_chars: max_chars, rows: rows, threshold: threshold, form_group: form_group, **args, &block).html
309
345
  end
310
346
 
311
347
  # Generates a +select+ element containing +option+ for each member in the provided collection
@@ -314,14 +350,19 @@ module GOVUKDesignSystemFormBuilder
314
350
  # @param collection [Enumerable<Object>] Options to be added to the +select+ element
315
351
  # @param value_method [Symbol] The method called against each member of the collection to provide the value
316
352
  # @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+
353
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
354
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
355
+ # @option hint text [String] the hint text
356
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
318
357
  # @option label text [String] the label text
319
358
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
320
359
  # @option label tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
321
360
  # @option label hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
322
361
  # @param options [Hash] Options hash passed through to Rails' +collection_select+ helper
323
362
  # @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+
363
+ # @param form_group [Hash] configures the form group
364
+ # @option form_group classes [Array,String] sets the form group's classes
365
+ # @option form_group args [Hash] additional attributes added to the form group
325
366
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
326
367
  # @see https://api.rubyonrails.org/classes/ActionView/Helpers/FormOptionsHelper.html#method-i-collection_select Rails collection_select (called by govuk_collection_select)
327
368
  # @return [ActiveSupport::SafeBuffer] HTML output
@@ -331,7 +372,7 @@ module GOVUKDesignSystemFormBuilder
331
372
  # @grades,
332
373
  # :id,
333
374
  # :name,
334
- # hint_text: "If you took the test more than once enter your highest grade"
375
+ # hint: { text: "If you took the test more than once enter your highest grade" }
335
376
  #
336
377
  # @example A select box with injected content
337
378
  # = f.govuk_collection_select(:favourite_colour, @colours, :id, :name) do
@@ -343,7 +384,7 @@ module GOVUKDesignSystemFormBuilder
343
384
  # = f.govuk_collection_select(:team, @teams, :id, :name) do
344
385
  # label: -> { tag.h3("Which team did you represent?") }
345
386
  #
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)
387
+ def govuk_collection_select(attribute_name, collection, value_method, text_method, options: {}, html_options: {}, hint: {}, label: {}, caption: {}, form_group: {}, &block)
347
388
  Elements::Select.new(
348
389
  self,
349
390
  object_name,
@@ -351,12 +392,12 @@ module GOVUKDesignSystemFormBuilder
351
392
  collection,
352
393
  value_method: value_method,
353
394
  text_method: text_method,
354
- hint_text: hint_text,
395
+ hint: hint,
355
396
  label: label,
356
397
  caption: caption,
357
398
  options: options,
358
399
  html_options: html_options,
359
- form_group_classes: form_group_classes,
400
+ form_group: form_group,
360
401
  &block
361
402
  ).html
362
403
  end
@@ -380,7 +421,10 @@ module GOVUKDesignSystemFormBuilder
380
421
  # @param hint_method [Symbol, Proc, nil] The method called against each member of the collection to provide the hint text.
381
422
  # When a +Proc+ is provided it must take a single argument that is a single member of the collection.
382
423
  # 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+
424
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
425
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
426
+ # @option hint text [String] the hint text
427
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
384
428
  # @param legend [Hash,Proc] options for configuring the legend
385
429
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
386
430
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
@@ -408,7 +452,7 @@ module GOVUKDesignSystemFormBuilder
408
452
  # ->(option) { option.name.upcase },
409
453
  # :description,
410
454
  # legend: { text: 'Pick your favourite colour', size: 'm' },
411
- # hint_text: 'If you cannot find the exact match choose something close',
455
+ # hint: { text: 'If you cannot find the exact match choose something close' },
412
456
  # inline: false
413
457
  #
414
458
  # @example A collection of radio buttons for grades with injected content
@@ -427,7 +471,7 @@ module GOVUKDesignSystemFormBuilder
427
471
  # :name,
428
472
  # legend: -> { tag.h3('Which category do you belong to?') }
429
473
  #
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)
474
+ def govuk_collection_radio_buttons(attribute_name, collection, value_method, text_method, hint_method = nil, hint: {}, legend: {}, caption: {}, inline: false, small: false, bold_labels: false, classes: nil, form_group: {}, &block)
431
475
  Elements::Radios::Collection.new(
432
476
  self,
433
477
  object_name,
@@ -436,14 +480,14 @@ module GOVUKDesignSystemFormBuilder
436
480
  value_method: value_method,
437
481
  text_method: text_method,
438
482
  hint_method: hint_method,
439
- hint_text: hint_text,
483
+ hint: hint,
440
484
  legend: legend,
441
485
  caption: caption,
442
486
  inline: inline,
443
487
  small: small,
444
488
  bold_labels: bold_labels,
445
489
  classes: classes,
446
- form_group_classes: form_group_classes,
490
+ form_group: form_group,
447
491
  &block
448
492
  ).html
449
493
  end
@@ -456,7 +500,10 @@ module GOVUKDesignSystemFormBuilder
456
500
  # is set to +link_errors: true+
457
501
  #
458
502
  # @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+
503
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
504
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
505
+ # @option hint text [String] the hint text
506
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
460
507
  # @param legend [Hash,Proc] options for configuring the legend
461
508
  # @param inline [Boolean] controls whether the radio buttons are displayed inline or not
462
509
  # @param small [Boolean] controls whether small radio buttons are used instead of regular-sized ones
@@ -467,7 +514,9 @@ module GOVUKDesignSystemFormBuilder
467
514
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
468
515
  # @option caption text [String] the caption text
469
516
  # @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+
517
+ # @param form_group [Hash] configures the form group
518
+ # @option form_group classes [Array,String] sets the form group's classes
519
+ # @option form_group args [Hash] additional attributes added to the form group
471
520
  # @param block [Block] a block of HTML that will be used to populate the fieldset
472
521
  # @param classes [Array,String] Classes to add to the radio button container.
473
522
  # @see https://design-system.service.gov.uk/components/radios/ GOV.UK Radios
@@ -491,15 +540,18 @@ module GOVUKDesignSystemFormBuilder
491
540
  # = f.govuk_radio_button :burger_id, :regular, label: { text: 'Hamburger' }, link_errors: true
492
541
  # = f.govuk_radio_button :burger_id, :cheese, label: { text: 'Cheeseburger' }
493
542
  #
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
543
+ def govuk_radio_buttons_fieldset(attribute_name, hint: {}, legend: {}, caption: {}, inline: false, small: false, classes: nil, form_group: {}, &block)
544
+ 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
545
  end
497
546
 
498
547
  # Generates a radio button
499
548
  #
500
549
  # @note This should only be used from within a {#govuk_radio_buttons_fieldset}
501
550
  # @param attribute_name [Symbol] The name of the attribute
502
- # @param hint_text [String] the contents of the hint
551
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
552
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
553
+ # @option hint text [String] the hint text
554
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
503
555
  # @option legend text [String] the fieldset legend's text content
504
556
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
505
557
  # @option legend tag [Symbol,String] the tag used for the fieldset's header, defaults to +h1+
@@ -517,8 +569,8 @@ module GOVUKDesignSystemFormBuilder
517
569
  # = f.govuk_radio_buttons_fieldset :favourite_colour do
518
570
  # = f.govuk_radio_button :favourite_colour, :red, label: { text: 'Red' }
519
571
  #
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
572
+ def govuk_radio_button(attribute_name, value, hint: {}, label: {}, link_errors: false, &block)
573
+ Elements::Radios::FieldsetRadioButton.new(self, object_name, attribute_name, value, hint: hint, label: label, link_errors: link_errors, &block).html
522
574
  end
523
575
 
524
576
  # Inserts a text divider into a list of radio buttons
@@ -541,7 +593,10 @@ module GOVUKDesignSystemFormBuilder
541
593
  # @param text_method [Symbol] The method called against each member of the collection to provide the label text
542
594
  # @param hint_method [Symbol, Proc] The method called against each member of the collection to provide the hint text.
543
595
  # 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+
596
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
597
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
598
+ # @option hint text [String] the hint text
599
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
545
600
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
546
601
  # @param classes [Array,String] Classes to add to the checkbox container.
547
602
  # @param legend [Hash,Proc] options for configuring the legend
@@ -552,7 +607,9 @@ module GOVUKDesignSystemFormBuilder
552
607
  # @param caption [Hash] configures or sets the caption content which is inserted above the legend
553
608
  # @option caption text [String] the caption text
554
609
  # @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+
610
+ # @param form_group [Hash] configures the form group
611
+ # @option form_group classes [Array,String] sets the form group's classes
612
+ # @option form_group args [Hash] additional attributes added to the form group
556
613
  # @param block [Block] any HTML passed in will be injected into the fieldset, after the hint and before the checkboxes
557
614
  # @return [ActiveSupport::SafeBuffer] HTML output
558
615
  #
@@ -569,7 +626,7 @@ module GOVUKDesignSystemFormBuilder
569
626
  # :name,
570
627
  # :description,
571
628
  # legend: { text: 'What do you want in your sandwich?', size: 'm' },
572
- # hint_text: "If it isn't listed here, tough luck",
629
+ # hint: { text: "If it isn't listed here, tough luck" },
573
630
  # inline: false,
574
631
  # classes: 'app-overflow-scroll',
575
632
  #
@@ -589,7 +646,7 @@ module GOVUKDesignSystemFormBuilder
589
646
  # :name,
590
647
  # legend: -> { tag.h3('What kind of sandwich do you want?') }
591
648
  #
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)
649
+ 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
650
  Elements::CheckBoxes::Collection.new(
594
651
  self,
595
652
  object_name,
@@ -598,12 +655,12 @@ module GOVUKDesignSystemFormBuilder
598
655
  value_method: value_method,
599
656
  text_method: text_method,
600
657
  hint_method: hint_method,
601
- hint_text: hint_text,
658
+ hint: hint,
602
659
  legend: legend,
603
660
  caption: caption,
604
661
  small: small,
605
662
  classes: classes,
606
- form_group_classes: form_group_classes,
663
+ form_group: form_group,
607
664
  &block
608
665
  ).html
609
666
  end
@@ -614,7 +671,10 @@ module GOVUKDesignSystemFormBuilder
614
671
  # is set to +link_errors: true+
615
672
  #
616
673
  # @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+
674
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
675
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
676
+ # @option hint text [String] the hint text
677
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
618
678
  # @param small [Boolean] controls whether small check boxes are used instead of regular-sized ones
619
679
  # @param legend [Hash,Proc] options for configuring the legend
620
680
  # @option legend text [String] the fieldset legend's text content
@@ -625,7 +685,9 @@ module GOVUKDesignSystemFormBuilder
625
685
  # @option caption text [String] the caption text
626
686
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
627
687
  # @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+
688
+ # @param form_group [Hash] configures the form group
689
+ # @option form_group classes [Array,String] sets the form group's classes
690
+ # @option form_group args [Hash] additional attributes added to the form group
629
691
  # @param block [Block] a block of HTML that will be used to populate the fieldset
630
692
  # @return [ActiveSupport::SafeBuffer] HTML output
631
693
  #
@@ -639,17 +701,17 @@ module GOVUKDesignSystemFormBuilder
639
701
  # = f.govuk_check_box :desired_filling, :lemonade, label: { text: 'Lemonade' }, link_errors: true
640
702
  # = f.govuk_check_box :desired_filling, :fizzy_orange, label: { text: 'Fizzy orange' }
641
703
  #
642
- def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint_text: {}, small: false, classes: nil, form_group_classes: nil, &block)
704
+ def govuk_check_boxes_fieldset(attribute_name, legend: {}, caption: {}, hint: {}, small: false, classes: nil, form_group: {}, &block)
643
705
  Containers::CheckBoxesFieldset.new(
644
706
  self,
645
707
  object_name,
646
708
  attribute_name,
647
- hint_text: hint_text,
709
+ hint: hint,
648
710
  legend: legend,
649
711
  caption: caption,
650
712
  small: small,
651
713
  classes: classes,
652
- form_group_classes: form_group_classes,
714
+ form_group: form_group,
653
715
  &block
654
716
  ).html
655
717
  end
@@ -658,8 +720,10 @@ module GOVUKDesignSystemFormBuilder
658
720
  #
659
721
  # @param attribute_name [Symbol] The name of the attribute
660
722
  # @param value [Boolean,String,Symbol,Integer] The value of the checkbox when it is checked
661
- # @param unchecked_value [Boolean,String,Symbol,Integer] The value of the checkbox when it is unchecked
662
- # @param hint_text [String] the contents of the hint
723
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
724
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
725
+ # @option hint text [String] the hint text
726
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
663
727
  # @param link_errors [Boolean] controls whether this radio button should be linked to from {#govuk_error_summary}
664
728
  # @option label text [String] the label text
665
729
  # @option label size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
@@ -675,16 +739,15 @@ module GOVUKDesignSystemFormBuilder
675
739
  # multiple: false,
676
740
  # link_errors: true,
677
741
  # label: { text: 'Do you agree with our terms and conditions?' },
678
- # hint_text: 'You will not be able to proceed unless you do'
742
+ # hint: { text: 'You will not be able to proceed unless you do' }
679
743
  #
680
- def govuk_check_box(attribute_name, checked_value, unchecked_value = false, hint_text: nil, label: {}, link_errors: false, multiple: true, &block)
744
+ def govuk_check_box(attribute_name, value, hint: {}, label: {}, link_errors: false, multiple: true, &block)
681
745
  Elements::CheckBoxes::FieldsetCheckBox.new(
682
746
  self,
683
747
  object_name,
684
748
  attribute_name,
685
- checked_value,
686
- unchecked_value,
687
- hint_text: hint_text,
749
+ value,
750
+ hint: hint,
688
751
  label: label,
689
752
  link_errors: link_errors,
690
753
  multiple: multiple,
@@ -728,7 +791,10 @@ module GOVUKDesignSystemFormBuilder
728
791
  # of {https://bugs.ruby-lang.org/issues/5988 this} bug, so incorrect dates like +2019-09-31+ will
729
792
  # be 'rounded' up to +2019-10-01+.
730
793
  # @param attribute_name [Symbol] The name of the attribute
731
- # @param hint_text [String] the contents of the hint
794
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
795
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
796
+ # @option hint text [String] the hint text
797
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
732
798
  # @param legend [Hash,Proc] options for configuring the legend
733
799
  # @option legend text [String] the fieldset legend's text content
734
800
  # @option legend size [String] the size of the fieldset legend font, can be +xl+, +l+, +m+ or +s+
@@ -738,7 +804,9 @@ module GOVUKDesignSystemFormBuilder
738
804
  # @option caption text [String] the caption text
739
805
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
740
806
  # @param omit_day [Boolean] do not render a day input, only capture month and year
741
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
807
+ # @param form_group [Hash] configures the form group
808
+ # @option form_group classes [Array,String] sets the form group's classes
809
+ # @option form_group args [Hash] additional attributes added to the form group
742
810
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input group
743
811
  # @param date_of_birth [Boolean] if +true+ {https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values birth date auto completion attributes}
744
812
  # will be added to the inputs
@@ -750,7 +818,7 @@ module GOVUKDesignSystemFormBuilder
750
818
  # @example A regular date input with a legend, hint and injected content
751
819
  # = f.govuk_date_field :starts_on,
752
820
  # legend: { 'When does your event start?' },
753
- # hint_text: 'Leave this field blank if you don't know exactly' } do
821
+ # hint: { text: 'Leave this field blank if you don't know exactly' } do
754
822
  #
755
823
  # p.govuk-inset-text
756
824
  # | If you don't fill this in you won't be eligable for a refund
@@ -758,8 +826,8 @@ module GOVUKDesignSystemFormBuilder
758
826
  # @example A date input with legend supplied as a proc
759
827
  # = f.govuk_date_field :finishes_on,
760
828
  # legend: -> { tag.h3('Which category do you belong to?') }
761
- def govuk_date_field(attribute_name, hint_text: nil, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group_classes: nil, &block)
762
- 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
829
+ def govuk_date_field(attribute_name, hint: {}, legend: {}, caption: {}, date_of_birth: false, omit_day: false, form_group: {}, &block)
830
+ 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
763
831
  end
764
832
 
765
833
  # Generates a summary of errors in the form, each linking to the corresponding
@@ -815,9 +883,14 @@ module GOVUKDesignSystemFormBuilder
815
883
  # @param caption [Hash] configures or sets the caption content which is inserted above the label
816
884
  # @option caption text [String] the caption text
817
885
  # @option caption size [String] the size of the caption, can be +xl+, +l+ or +m+. Defaults to +m+
818
- # @param hint_text [String] The content of the hint. No hint will be injected if left +nil+
886
+ # @param hint [Hash,Proc] The content of the hint. No hint will be added if 'text' is left +nil+. When a +Proc+ is
887
+ # supplied the hint will be wrapped in a +div+ instead of a +span+
888
+ # @option hint text [String] the hint text
889
+ # @option hint args [Hash] additional arguments are applied as attributes to the hint
819
890
  # @option args [Hash] args additional arguments are applied as attributes to the +input+ element
820
- # @param form_group_classes [Array,String] Classes to add to the surrounding +form-group+
891
+ # @param form_group [Hash] configures the form group
892
+ # @option form_group classes [Array,String] sets the form group's classes
893
+ # @option form_group args [Hash] additional attributes added to the form group
821
894
  # @param block [Block] arbitrary HTML that will be rendered between the hint and the input
822
895
  #
823
896
  # @example A photo upload field with file type specifier and injected content
@@ -836,8 +909,8 @@ module GOVUKDesignSystemFormBuilder
836
909
  # @note Remember to set +multipart: true+ when creating a form with file
837
910
  # uploads, {https://guides.rubyonrails.org/form_helpers.html#uploading-files see
838
911
  # the Rails documentation} for more information
839
- def govuk_file_field(attribute_name, label: {}, caption: {}, hint_text: nil, form_group_classes: nil, **args, &block)
840
- 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
912
+ def govuk_file_field(attribute_name, label: {}, caption: {}, hint: {}, form_group: {}, **args, &block)
913
+ Elements::File.new(self, object_name, attribute_name, label: label, caption: caption, hint: hint, form_group: form_group, **args, &block).html
841
914
  end
842
915
  end
843
916
  end