govuk_design_system_formbuilder 1.2.0b2 → 1.2.0b4

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,7 +17,7 @@ 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
+          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.html,

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 || build_legend
       end
 
       def build_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.html, 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,7 +18,7 @@ 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
+          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.html,

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,13 +15,14 @@ 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
+            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.html,

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
 
@@ -57,7 +58,7 @@ module GOVUKDesignSystemFormBuilder
         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_args)
         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,7 +21,7 @@ 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
+          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.html,

data/lib/govuk_design_system_formbuilder/elements/file.rb

@@ -8,10 +8,11 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Label
       include Traits::Supplemental
 
-      def initialize(builder, object_name, attribute_name, hint_text:, label:, **extra_args, &block)
+      def initialize(builder, object_name, attribute_name, hint_text:, label:, caption:, **extra_args, &block)
         super(builder, object_name, attribute_name, &block)
 
         @label      = label
+        @caption    = caption
         @hint_text  = hint_text
         @extra_args = extra_args
       end

data/lib/govuk_design_system_formbuilder/elements/label.rb

@@ -3,22 +3,30 @@ module GOVUKDesignSystemFormBuilder
     class Label < Base
       using PrefixableArray
 
+      include Traits::Caption
       include Traits::Localisation
 
-      def initialize(builder, object_name, attribute_name, text: nil, value: nil, size: nil, hidden: false, radio: false, checkbox: false, tag: nil, link_errors: true)
+      def initialize(builder, object_name, attribute_name, text: nil, value: nil, size: nil, hidden: false, radio: false, checkbox: false, tag: nil, link_errors: true, content: nil, caption: nil)
         super(builder, object_name, attribute_name)
 
-        @value          = value # used by field_id
-        @text           = label_text(text, hidden)
-        @size_class     = label_size_class(size)
-        @radio_class    = radio_class(radio)
-        @checkbox_class = checkbox_class(checkbox)
-        @tag            = tag
-        @link_errors    = link_errors
+        # content is passed in directly via a proc and overrides
+        # the other display options
+        if content
+          @content = content.call
+        else
+          @value          = value # used by field_id
+          @text           = label_text(text, hidden)
+          @size_class     = label_size_class(size)
+          @radio_class    = radio_class(radio)
+          @checkbox_class = checkbox_class(checkbox)
+          @tag            = tag
+          @link_errors    = link_errors
+          @caption        = caption
+        end
       end
 
       def html
-        return nil if @text.blank?
+        return nil if [@content, @text].all?(&:blank?)
 
         if @tag.present?
           content_tag(@tag, class: %(#{brand}-label-wrapper)) { build_label }
@@ -36,7 +44,7 @@ module GOVUKDesignSystemFormBuilder
           for: field_id(link_errors: @link_errors),
           class: %w(label).prefix(brand).push(@size_class, @weight_class, @radio_class, @checkbox_class).compact
         ) do
-          @text
+          @content || safe_join([caption_element.html, @text])
         end
       end
 

data/lib/govuk_design_system_formbuilder/elements/radios/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:, hint_text:, legend:, inline:, small:, bold_labels:, classes:, &block)
+        def initialize(builder, object_name, attribute_name, collection, value_method:, text_method:, hint_method:, hint_text:, legend:, caption:, inline:, small:, bold_labels:, classes:, &block)
           super(builder, object_name, attribute_name, &block)
 
           @collection    = collection
@@ -16,6 +16,7 @@ module GOVUKDesignSystemFormBuilder
           @inline        = inline
           @small         = small
           @legend        = legend
+          @caption       = caption
           @hint_text     = hint_text
           @classes       = classes
           @bold_labels   = hint_method.present? || bold_labels
@@ -23,7 +24,7 @@ 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
+            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.html,

data/lib/govuk_design_system_formbuilder/elements/radios/fieldset_radio_button.rb

@@ -4,6 +4,7 @@ module GOVUKDesignSystemFormBuilder
       class FieldsetRadioButton < Base
         using PrefixableArray
 
+        include Traits::Label
         include Traits::Hint
         include Traits::Conditional
 
@@ -41,7 +42,7 @@ module GOVUKDesignSystemFormBuilder
       private
 
         def label_element
-          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, radio: true, value: @value, **@label, link_errors: @link_errors)
+          @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, radio: true, value: @value, link_errors: @link_errors, **label_args)
         end
 
         def hint_element

data/lib/govuk_design_system_formbuilder/elements/select.rb

@@ -8,7 +8,7 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Hint
       include Traits::Supplemental
 
-      def initialize(builder, object_name, attribute_name, collection, value_method:, text_method:, options: {}, html_options: {}, hint_text:, label:, &block)
+      def initialize(builder, object_name, attribute_name, collection, value_method:, text_method:, options: {}, html_options: {}, hint_text:, label:, caption:, &block)
         super(builder, object_name, attribute_name, &block)
 
         @collection    = collection
@@ -17,6 +17,7 @@ module GOVUKDesignSystemFormBuilder
         @options       = options
         @html_options  = html_options
         @label         = label
+        @caption       = caption
         @hint_text     = hint_text
       end
 

data/lib/govuk_design_system_formbuilder/elements/text_area.rb

@@ -8,10 +8,11 @@ module GOVUKDesignSystemFormBuilder
       include Traits::Label
       include Traits::Supplemental
 
-      def initialize(builder, object_name, attribute_name, hint_text:, label:, rows:, max_words:, max_chars:, threshold:, **extra_args, &block)
+      def initialize(builder, object_name, attribute_name, hint_text:, label:, caption:, rows:, max_words:, max_chars:, threshold:, **extra_args, &block)
         super(builder, object_name, attribute_name, &block)
 
         @label      = label
+        @caption    = caption
         @hint_text  = hint_text
         @extra_args = extra_args
         @max_words  = max_words

data/lib/govuk_design_system_formbuilder/traits/caption.rb

@@ -0,0 +1,24 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Caption
+    private
+
+      def caption_element
+        @caption_element ||= Elements::Caption.new(
+          @builder,
+          @object_name,
+          @attribute_name,
+          **{ text: nil }.merge({ text: caption_text, size: caption_size }.compact)
+        )
+      end
+
+      def caption_text
+        @caption&.dig(:text)
+      end
+
+      def caption_size
+        @caption&.dig(:size)
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/input.rb

@@ -1,12 +1,13 @@
 module GOVUKDesignSystemFormBuilder
   module Traits
     module Input
-      def initialize(builder, object_name, attribute_name, hint_text:, label:, width:, **extra_args, &block)
+      def initialize(builder, object_name, attribute_name, hint_text:, label:, caption:, width:, **extra_args, &block)
         super(builder, object_name, attribute_name, &block)
 
         @width          = width
         @extra_args     = extra_args
         @label          = label
+        @caption        = caption
         @hint_text      = hint_text
       end
 

data/lib/govuk_design_system_formbuilder/traits/label.rb

@@ -4,7 +4,18 @@ module GOVUKDesignSystemFormBuilder
     private
 
       def label_element
-        @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, **@label)
+        @label_element ||= Elements::Label.new(@builder, @object_name, @attribute_name, caption: @caption, **label_args)
+      end
+
+      def label_args
+        case @label
+        when Hash
+          @label
+        when Proc
+          { content: @label }
+        else
+          fail(ArgumentError, %(label must be a Proc or Hash))
+        end
       end
     end
   end

data/lib/govuk_design_system_formbuilder/traits/localisation.rb

@@ -40,6 +40,8 @@ module GOVUKDesignSystemFormBuilder
                               config.localisation_schema_hint
                             when :label
                               config.localisation_schema_label
+                            when :caption
+                              config.localisation_schema_caption
                             end
 
         (contextual_schema || config.localisation_schema_fallback).dup