govuk_design_system_formbuilder 1.2.0b1 → 1.2.2

data/lib/govuk_design_system_formbuilder/containers/check_boxes_fieldset.rb

@@ -4,10 +4,11 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Error
       include Traits::Hint
 
-      def initialize(builder, object_name, attribute_name, hint_text:, legend:, small:, classes:, &block)
+      def initialize(builder, object_name, attribute_name, hint_text:, legend:, caption:, small:, classes:, &block)
         super(builder, object_name, attribute_name, &block)
 
         @legend        = legend
+        @caption       = caption
         @hint_text     = hint_text
         @small         = small
         @classes       = classes
@@ -16,19 +17,19 @@ module GOVUKDesignSystemFormBuilder
 
       def html
         Containers::FormGroup.new(@builder, @object_name, @attribute_name).html do
-          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, described_by: [error_element.error_id, hint_element.hint_id]).html do
-            safe_join(
-              [
-                hint_element.html,
-                error_element.html,
-                Containers::CheckBoxes.new(@builder, small: @small, classes: @classes).html do
-                  @block_content
-                end
-              ]
-            )
+          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, caption: @caption, described_by: [error_element.error_id, hint_element.hint_id]).html do
+            safe_join([hint_element, error_element, checkboxes])
           end
         end
       end
+
+    private
+
+      def checkboxes
+        Containers::CheckBoxes.new(@builder, small: @small, classes: @classes).html do
+          @block_content
+        end
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/containers/fieldset.rb

@@ -3,45 +3,52 @@ module GOVUKDesignSystemFormBuilder
     class Fieldset < Base
       using PrefixableArray
 
+      include Traits::Caption
       include Traits::Localisation
 
       LEGEND_SIZES = %w(xl l m s).freeze
 
-      def initialize(builder, object_name = nil, attribute_name = nil, legend: {}, described_by: nil)
-        super(builder, object_name, attribute_name)
+      def initialize(builder, object_name = nil, attribute_name = nil, legend: {}, caption: {}, described_by: nil, &block)
+        super(builder, object_name, attribute_name, &block)
 
-        @legend         = legend_defaults.merge(legend)
         @described_by   = described_by(described_by)
         @attribute_name = attribute_name
+
+        case legend
+        when Proc
+          @legend_raw = legend.call
+        when Hash
+          @legend_options = legend_defaults.merge(legend)
+          @caption        = caption
+        else
+          fail(ArgumentError, %(legend must be a Proc or Hash))
+        end
       end
 
       def html
         content_tag('fieldset', class: fieldset_classes, aria: { describedby: @described_by }) do
-          safe_join([build_legend, yield])
+          safe_join([legend_content, (@block_content || yield)])
         end
       end
 
     private
 
-      def legend_defaults
-        {
-          hidden: false,
-          text: nil,
-          tag:  config.default_legend_tag,
-          size: config.default_legend_size
-        }
+      def legend_content
+        @legend_raw || legend
       end
 
-      def build_legend
+      def legend
         if legend_text.present?
           content_tag('legend', class: legend_classes) do
-            tag.send(@legend.dig(:tag), legend_text, class: legend_heading_classes)
+            content_tag(@legend_options.dig(:tag), class: legend_heading_classes) do
+              safe_join([caption_element, legend_text])
+            end
           end
         end
       end
 
       def legend_text
-        [@legend.dig(:text), localised_text(:legend)].compact.first
+        [@legend_options.dig(:text), localised_text(:legend)].compact.first
       end
 
       def fieldset_classes
@@ -49,17 +56,26 @@ module GOVUKDesignSystemFormBuilder
       end
 
       def legend_classes
-        size = @legend.dig(:size)
+        size = @legend_options.dig(:size)
         fail "invalid size '#{size}', must be #{LEGEND_SIZES.join(', ')}" unless size.in?(LEGEND_SIZES)
 
         [%(fieldset__legend), %(fieldset__legend--#{size})].prefix(brand).tap do |classes|
-          classes.push(%(#{brand}-visually-hidden)) if @legend.dig(:hidden)
+          classes.push(%(#{brand}-visually-hidden)) if @legend_options.dig(:hidden)
         end
       end
 
       def legend_heading_classes
         %w(fieldset__heading).prefix(brand)
       end
+
+      def legend_defaults
+        {
+          hidden: false,
+          text: nil,
+          tag:  config.default_legend_tag,
+          size: config.default_legend_size
+        }
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/containers/radio_buttons_fieldset.rb

@@ -4,12 +4,13 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Hint
       include Traits::Error
 
-      def initialize(builder, object_name, attribute_name, hint_text:, legend:, inline:, small:, classes:, &block)
+      def initialize(builder, object_name, attribute_name, hint_text:, legend:, caption:, inline:, small:, classes:, &block)
         super(builder, object_name, attribute_name)
 
         @inline        = inline
         @small         = small
         @legend        = legend
+        @caption       = caption
         @hint_text     = hint_text
         @classes       = classes
         @block_content = capture { block.call }
@@ -17,19 +18,19 @@ module GOVUKDesignSystemFormBuilder
 
       def html
         Containers::FormGroup.new(@builder, @object_name, @attribute_name).html do
-          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, described_by: [error_element.error_id, hint_element.hint_id]).html do
-            safe_join(
-              [
-                hint_element.html,
-                error_element.html,
-                Containers::Radios.new(@builder, inline: @inline, small: @small, classes: @classes).html do
-                  @block_content
-                end
-              ]
-            )
+          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, caption: @caption, described_by: [error_element.error_id, hint_element.hint_id]).html do
+            safe_join([hint_element, error_element, radios])
           end
         end
       end
+
+    private
+
+      def radios
+        Containers::Radios.new(@builder, inline: @inline, small: @small, classes: @classes).html do
+          @block_content
+        end
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/elements/caption.rb

@@ -0,0 +1,34 @@
+module GOVUKDesignSystemFormBuilder
+  module Elements
+    class Caption < Base
+      include Traits::Localisation
+
+      def initialize(builder, object_name, attribute_name, text:, size: 'm')
+        super(builder, object_name, attribute_name)
+
+        @text       = caption_text(text)
+        @size_class = caption_size_class(size)
+      end
+
+      def html
+        return nil if @text.blank?
+
+        tag.span(@text, class: @size_class)
+      end
+
+      def caption_text(override)
+        override || localised_text(:caption)
+      end
+
+      def caption_size_class(size)
+        case size
+        when 'xl' then %(#{brand}-caption-xl)
+        when 'l'  then %(#{brand}-caption-l)
+        when 'm'  then %(#{brand}-caption-m)
+        else
+          fail ArgumentError, "invalid size '#{size}', must be xl, l or m"
+        end
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection.rb

@@ -6,7 +6,7 @@ module GOVUKDesignSystemFormBuilder
         include Traits::Hint
         include Traits::Supplemental
 
-        def initialize(builder, object_name, attribute_name, collection, value_method:, text_method:, hint_method: nil, hint_text:, legend:, small:, classes:, &block)
+        def initialize(builder, object_name, attribute_name, collection, value_method:, text_method:, hint_method: nil, hint_text:, legend:, caption:, small:, classes:, &block)
           super(builder, object_name, attribute_name, &block)
 
           @collection    = collection
@@ -15,29 +15,27 @@ module GOVUKDesignSystemFormBuilder
           @hint_method   = hint_method
           @small         = small
           @legend        = legend
+          @caption       = caption
           @hint_text     = hint_text
           @classes       = classes
         end
 
         def html
           Containers::FormGroup.new(@builder, @object_name, @attribute_name).html do
-            Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, described_by: [error_id, hint_id, supplemental_id]).html do
-              safe_join(
-                [
-                  supplemental_content.html,
-                  hint_element.html,
-                  error_element.html,
-                  Containers::CheckBoxes.new(@builder, small: @small, classes: @classes).html do
-                    build_collection
-                  end
-                ]
-              )
+            Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, caption: @caption, described_by: [error_id, hint_id, supplemental_id]).html do
+              safe_join([supplemental_content, hint_element, error_element, check_boxes])
             end
           end
         end
 
       private
 
+        def check_boxes
+          Containers::CheckBoxes.new(@builder, small: @small, classes: @classes).html do
+            collection
+          end
+        end
+
         # Builds a collection of check {Elements::CheckBoxes::CheckBox}
         # @return [ActiveSupport::SafeBuffer] HTML output
         #
@@ -46,7 +44,7 @@ module GOVUKDesignSystemFormBuilder
         #   be rendered when it happens we need to work on the chance that it might, so
         #   the +link_errors+ variable is set to +true+ if this attribute has errors and
         #   always set back to +false+ after the first checkbox has been rendered
-        def build_collection
+        def collection
           link_errors = has_errors?
 
           @builder.collection_check_boxes(@attribute_name, @collection, @value_method, @text_method) do |check_box|

data/lib/govuk_design_system_formbuilder/elements/check_boxes/collection_check_box.rb

@@ -10,31 +10,33 @@ module GOVUKDesignSystemFormBuilder
         def initialize(builder, object_name, attribute_name, checkbox, hint_method = nil, link_errors: false)
           super(builder, object_name, attribute_name)
 
-          @checkbox  = checkbox
-          @item      = checkbox.object
-          @value     = checkbox.value
-          @hint_text = retrieve(@item, hint_method)
+          @checkbox    = checkbox
+          @item        = checkbox.object
+          @value       = checkbox.value
+          @hint_text   = retrieve(@item, hint_method)
           @link_errors = link_errors
         end
 
         def html
           content_tag('div', class: %(#{brand}-checkboxes__item)) do
-            safe_join(
-              [
-                @checkbox.check_box(
-                  id: field_id(link_errors: @link_errors),
-                  class: %(#{brand}-checkboxes__input),
-                  aria: { describedby: hint_id }
-                ),
-                label_element.html,
-                hint_element.html
-              ]
-            )
+            safe_join([check_box, label_element, hint_element])
           end
         end
 
       private
 
+        def check_box
+          @checkbox.check_box(**check_box_options)
+        end
+
+        def check_box_options
+          {
+            id: field_id(link_errors: @link_errors),
+            class: %(#{brand}-checkboxes__input),
+            aria: { describedby: hint_id }
+          }
+        end
+
         def label_element
           @label_element ||= Label.new(@builder, @object_name, @attribute_name, @checkbox, value: @value, link_errors: @link_errors)
         end

data/lib/govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box.rb

@@ -4,6 +4,7 @@ module GOVUKDesignSystemFormBuilder
       class FieldsetCheckBox < Base
         using PrefixableArray
 
+        include Traits::Label
         include Traits::Hint
         include Traits::Conditional
 
@@ -23,41 +24,33 @@ module GOVUKDesignSystemFormBuilder
         end
 
         def html
-          safe_join(
-            [
-              content_tag('div', class: %(#{brand}-checkboxes__item)) do
-                safe_join(
-                  [
-                    input,
-                    label_element.html,
-                    hint_element.html,
-                  ]
-                )
-              end,
-              @conditional_content
-            ]
-          )
+          safe_join([check_box, @conditional_content])
         end
 
       private
 
+        def check_box
+          content_tag('div', class: %(#{brand}-checkboxes__item)) do
+            safe_join([input, label_element, hint_element])
+          end
+        end
+
         def input
-          @builder.check_box(
-            @attribute_name,
-            {
-              id: field_id(link_errors: @link_errors),
-              class: check_box_classes,
-              multiple: @multiple,
-              aria: { describedby: hint_id },
-              data: { 'aria-controls' => @conditional_id }
-            },
-            @value,
-            false
-          )
+          @builder.check_box(@attribute_name, input_options, @value, false)
+        end
+
+        def input_options
+          {
+            id: field_id(link_errors: @link_errors),
+            class: check_box_classes,
+            multiple: @multiple,
+            aria: { describedby: hint_id },
+            data: { 'aria-controls' => @conditional_id }
+          }
         end
 
         def label_element
-          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, checkbox: true, value: @value, **@label, link_errors: @link_errors)
+          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, checkbox: true, value: @value, link_errors: @link_errors, **label_options)
         end
 
         def hint_element

data/lib/govuk_design_system_formbuilder/elements/date.rb

@@ -9,10 +9,11 @@ module GOVUKDesignSystemFormBuilder
 
       SEGMENTS = { day: '3i', month: '2i', year: '1i' }.freeze
 
-      def initialize(builder, object_name, attribute_name, legend:, hint_text:, date_of_birth: false, omit_day:, &block)
+      def initialize(builder, object_name, attribute_name, legend:, caption:, hint_text:, date_of_birth: false, omit_day:, &block)
         super(builder, object_name, attribute_name, &block)
 
         @legend        = legend
+        @caption       = caption
         @hint_text     = hint_text
         @date_of_birth = date_of_birth
         @omit_day      = omit_day
@@ -20,23 +21,20 @@ module GOVUKDesignSystemFormBuilder
 
       def html
         Containers::FormGroup.new(@builder, @object_name, @attribute_name).html do
-          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, described_by: [error_id, hint_id, supplemental_id]).html do
-            safe_join(
-              [
-                supplemental_content.html,
-                hint_element.html,
-                error_element.html,
-                content_tag('div', class: %(#{brand}-date-input)) do
-                  safe_join([day, month, year])
-                end
-              ]
-            )
+          Containers::Fieldset.new(@builder, @object_name, @attribute_name, legend: @legend, caption: @caption, described_by: [error_id, hint_id, supplemental_id]).html do
+            safe_join([supplemental_content, hint_element, error_element, date])
           end
         end
       end
 
     private
 
+      def date
+        content_tag('div', class: %(#{brand}-date-input)) do
+          safe_join([day, month, year])
+        end
+      end
+
       def omit_day?
         @omit_day
       end
@@ -44,18 +42,18 @@ module GOVUKDesignSystemFormBuilder
       def day
         return nil if omit_day?
 
-        date_input_item(:day, link_errors: true)
+        date_part_input(:day, link_errors: true)
       end
 
       def month
-        date_input_item(:month, link_errors: omit_day?)
+        date_part_input(:month, link_errors: omit_day?)
       end
 
       def year
-        date_input_item(:year, width: 4)
+        date_part_input(:year, width: 4)
       end
 
-      def date_input_item(segment, width: 2, link_errors: false)
+      def date_part_input(segment, width: 2, link_errors: false)
         value = @builder.object.try(@attribute_name).try(segment)
 
         content_tag('div', class: %w(date-input__item).prefix(brand)) do
@@ -64,14 +62,14 @@ module GOVUKDesignSystemFormBuilder
               [
                 tag.label(
                   segment.capitalize,
-                  class: date_input_label_classes,
-                  for: date_attribute_id(segment, link_errors)
+                  class: date_part_label_classes,
+                  for: date_part_attribute_id(segment, link_errors)
                 ),
 
                 tag.input(
-                  id: date_attribute_id(segment, link_errors),
-                  class: date_input_classes(width),
-                  name: date_attribute_name(segment),
+                  id: date_part_attribute_id(segment, link_errors),
+                  class: date_part_input_classes(width),
+                  name: date_part_attribute_name(segment),
                   type: 'text',
                   pattern: '[0-9]*',
                   inputmode: 'numeric',
@@ -84,21 +82,21 @@ module GOVUKDesignSystemFormBuilder
         end
       end
 
-      def date_input_classes(width)
+      def date_part_input_classes(width)
         %w(input date-input__input).prefix(brand).tap do |classes|
           classes.push(%(#{brand}-input--width-#{width}))
           classes.push(%(#{brand}-input--error)) if has_errors?
         end
       end
 
-      def date_input_label_classes
+      def date_part_label_classes
         %w(label date-input__label).prefix(brand)
       end
 
       # if the field has errors we want the govuk_error_summary to
       # be able to link to the day field. Otherwise, generate IDs
       # in the normal fashion
-      def date_attribute_id(segment, link_errors)
+      def date_part_attribute_id(segment, link_errors)
         if has_errors? && link_errors
           field_id(link_errors: link_errors)
         else
@@ -106,7 +104,7 @@ module GOVUKDesignSystemFormBuilder
         end
       end
 
-      def date_attribute_name(segment)
+      def date_part_attribute_name(segment)
         format(
           "%<object_name>s[%<attribute_name>s(%<segment>s)]",
           object_name: @object_name,