govuk_design_system_formbuilder 0.9.8 → 2.0.0

data/lib/govuk_design_system_formbuilder/elements/submit.rb

@@ -1,7 +1,9 @@
 module GOVUKDesignSystemFormBuilder
   module Elements
-    class Submit < GOVUKDesignSystemFormBuilder::Base
-      def initialize(builder, text, warning:, secondary:, prevent_double_click:, validate:, &block)
+    class Submit < Base
+      using PrefixableArray
+
+      def initialize(builder, text, warning:, secondary:, classes:, prevent_double_click:, validate:, disabled:, &block)
         fail ArgumentError, 'buttons can be warning or secondary' if warning && secondary
 
         @builder              = builder
@@ -9,52 +11,60 @@ module GOVUKDesignSystemFormBuilder
         @prevent_double_click = prevent_double_click
         @warning              = warning
         @secondary            = secondary
+        @classes              = classes
         @validate             = validate
+        @disabled             = disabled
         @block_content        = capture { block.call } if block_given?
       end
 
       def html
-        content_tag('div', class: %w(govuk-form-group)) do
-          safe_join(
-            [
-              @builder.submit(
-                @text,
-                class: %w(govuk-button).push(
-                  warning_class,
-                  secondary_class,
-                  padding_class(@block_content.present?)
-                ).compact,
-                **extra_args
-              ),
-              @block_content
-            ]
-          )
-        end
+        safe_join([submit, @block_content])
       end
 
     private
 
-      def warning_class
-        'govuk-button--warning' if @warning
-      end
-
-      def secondary_class
-        'govuk-button--secondary' if @secondary
+      def submit
+        @builder.submit(@text, class: classes, **options)
       end
 
-      def padding_class(content_present)
-        'govuk-!-margin-right-1' if content_present
+      def classes
+        %w(button)
+          .prefix(brand)
+          .push(warning_class, secondary_class, disabled_class, padding_class, custom_classes)
+          .flatten
+          .compact
       end
 
-      def extra_args
+      def options
         {
           formnovalidate: !@validate,
+          disabled: @disabled,
           data: {
-            module: 'govuk-button',
-            'prevent-double-click' => @prevent_double_click
+            module: %(#{brand}-button),
+            'prevent-double-click': @prevent_double_click
           }.select { |_k, v| v.present? }
         }
       end
+
+      def warning_class
+        %(#{brand}-button--warning) if @warning
+      end
+
+      def secondary_class
+        %(#{brand}-button--secondary) if @secondary
+      end
+
+      def padding_class
+        %(#{brand}-!-margin-right-1) if @block_content
+      end
+
+      def disabled_class
+        %(#{brand}-button--disabled) if @disabled
+      end
+
+      def custom_classes
+        Array.wrap(@classes)
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/elements/text_area.rb

@@ -1,54 +1,98 @@
 module GOVUKDesignSystemFormBuilder
   module Elements
     class TextArea < Base
-      def initialize(builder, object_name, attribute_name, hint_text:, label:, rows:, max_words:, max_chars:, threshold:, **extra_args, &block)
+      using PrefixableArray
+
+      include Traits::Error
+      include Traits::Hint
+      include Traits::Label
+      include Traits::Supplemental
+
+      def initialize(builder, object_name, attribute_name, hint:, label:, caption:, rows:, max_words:, max_chars:, threshold:, form_group:, **kwargs, &block)
         super(builder, object_name, attribute_name, &block)
-        @label      = label
-        @hint_text  = hint_text
-        @extra_args = extra_args
-        @max_words  = max_words
-        @max_chars  = max_chars
-        @threshold  = threshold
-        @rows       = rows
+
+        @label           = label
+        @caption         = caption
+        @hint            = hint
+        @max_words       = max_words
+        @max_chars       = max_chars
+        @threshold       = threshold
+        @rows            = rows
+        @form_group      = form_group
+        @html_attributes = kwargs
       end
 
       def html
-        Containers::CharacterCount.new(@builder, max_words: @max_words, max_chars: @max_chars, threshold: @threshold).html do
-          Containers::FormGroup.new(@builder, @object_name, @attribute_name).html do
-            safe_join(
-              [
-                [label_element, hint_element, error_element, supplemental_content].map(&:html),
-                @builder.text_area(
-                  @attribute_name,
-                  id: field_id(link_errors: true),
-                  class: govuk_textarea_classes,
-                  aria: {
-                    describedby: described_by(
-                      hint_id,
-                      error_id,
-                      supplemental_id
-                    )
-                  },
-                  **@extra_args.merge(rows: @rows)
-                )
-              ].flatten.compact
-            )
+        Containers::CharacterCount.new(@builder, **character_count_options).html do
+          Containers::FormGroup.new(@builder, @object_name, @attribute_name, **@form_group).html do
+            safe_join([label_element, supplemental_content, hint_element, error_element, text_area, limit_description])
           end
         end
       end
 
     private
 
-      def govuk_textarea_classes
-        %w(govuk-textarea).tap do |classes|
-          classes.push('govuk-textarea--error') if has_errors?
-          classes.push('govuk-js-character-count') if limit?
+      def character_count_options
+        { max_words: @max_words, max_chars: @max_chars, threshold: @threshold }
+      end
+
+      def text_area
+        @builder.text_area(@attribute_name, **options, **@html_attributes)
+      end
+
+      def classes
+        %w(textarea).prefix(brand).tap do |classes|
+          classes.push(%(#{brand}-textarea--error))    if has_errors?
+          classes.push(%(#{brand}-js-character-count)) if limit?
         end
       end
 
+      def options
+        {
+          id: field_id(link_errors: true),
+          class: classes,
+          rows: @rows,
+          aria: { describedby: described_by(hint_id, error_id, supplemental_id, limit_description_id) },
+        }
+      end
+
+      # Provides an id for use by the textual description of character and word limits.
+      #
+      # @note In order for the GOV.UK Frontend JavaScript to pick up this associated field
+      #   it has to have the same id as the text area with the additional suffix of '-info'
+      def limit_id
+        [field_id(link_errors: true), 'info'].join('-')
+      end
+
       def limit?
+        limit_quantity.present?
+      end
+
+      def limit_quantity
         @max_words || @max_chars
       end
+
+      def limit_type
+        @max_words.present? ? 'words' : 'characters'
+      end
+
+      def limit_description
+        return nil unless limit?
+
+        tag.span(id: limit_id, class: limit_description_classes, aria: { live: 'polite' }) do
+          "You can enter up to #{limit_quantity} #{limit_type}"
+        end
+      end
+
+      def limit_description_classes
+        %w(hint character-count__message).prefix(brand)
+      end
+
+      def limit_description_id
+        return nil unless limit?
+
+        limit_id
+      end
     end
   end
 end

data/lib/govuk_design_system_formbuilder/traits/caption.rb

@@ -0,0 +1,15 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Caption
+    private
+
+      def caption_element
+        @caption_element ||= Elements::Caption.new(@builder, @object_name, @attribute_name, **caption_options)
+      end
+
+      def caption_options
+        @caption
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/collection_item.rb

@@ -0,0 +1,16 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module CollectionItem
+    private
+
+      def retrieve(item, method)
+        case method
+        when Symbol, String
+          item.send(method)
+        when Proc
+          capture { method.call(item) }
+        end
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/conditional.rb

@@ -0,0 +1,17 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Conditional
+    private
+
+      def conditional_id
+        build_id('conditional')
+      end
+
+      def wrap_conditional(block)
+        tag.div(class: conditional_classes, id: conditional_id) do
+          capture { block.call }
+        end
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/error.rb

@@ -0,0 +1,17 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Error
+      def error_id
+        return nil unless has_errors?
+
+        build_id('error')
+      end
+
+    private
+
+      def error_element
+        @error_element ||= Elements::ErrorMessage.new(@builder, @object_name, @attribute_name)
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/hint.rb

@@ -0,0 +1,30 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Hint
+      def hint_id
+        return nil unless hint_element.active?
+
+        build_id('hint')
+      end
+
+    private
+
+      def hint_element
+        @hint_element ||= Elements::Hint.new(@builder, @object_name, @attribute_name, **hint_content)
+      end
+
+      def hint_content
+        case @hint
+        when NilClass
+          {}
+        when Hash
+          @hint
+        when Proc
+          { content: @hint }
+        else
+          fail(ArgumentError, %(hint must be a Proc or Hash))
+        end
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/input.rb

@@ -0,0 +1,105 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Input
+      def initialize(builder, object_name, attribute_name, hint:, label:, caption:, prefix_text:, suffix_text:, width:, form_group:, **kwargs, &block)
+        super(builder, object_name, attribute_name, &block)
+
+        @width           = width
+        @label           = label
+        @caption         = caption
+        @hint            = hint
+        @prefix_text     = prefix_text
+        @suffix_text     = suffix_text
+        @html_attributes = kwargs
+        @form_group      = form_group
+      end
+
+      def html
+        Containers::FormGroup.new(@builder, @object_name, @attribute_name, **@form_group).html do
+          safe_join([label_element, supplemental_content, hint_element, error_element, content])
+        end
+      end
+
+    private
+
+      def content
+        if affixed?
+          affixed_input
+        else
+          input
+        end
+      end
+
+      def affixed_input
+        content_tag('div', class: %(#{brand}-input__wrapper)) do
+          safe_join([prefix, input, suffix])
+        end
+      end
+
+      def input
+        @builder.send(builder_method, @attribute_name, **options, **@html_attributes)
+      end
+
+      def affixed?
+        [@prefix_text, @suffix_text].any?
+      end
+
+      def options
+        {
+          id: field_id(link_errors: true),
+          class: classes,
+          aria: { describedby: described_by(hint_id, error_id, supplemental_id) }
+        }
+      end
+
+      def classes
+        [%(#{brand}-input)].push(width_classes, error_classes).compact
+      end
+
+      def error_classes
+        %(#{brand}-input--error) if has_errors?
+      end
+
+      def width_classes
+        return if @width.blank?
+
+        case @width
+
+          # fixed (character) widths
+        when 20 then %(#{brand}-input--width-20)
+        when 10 then %(#{brand}-input--width-10)
+        when 5  then %(#{brand}-input--width-5)
+        when 4  then %(#{brand}-input--width-4)
+        when 3  then %(#{brand}-input--width-3)
+        when 2  then %(#{brand}-input--width-2)
+
+          # fluid widths
+        when 'full'           then %(#{brand}-!-width-full)
+        when 'three-quarters' then %(#{brand}-!-width-three-quarters)
+        when 'two-thirds'     then %(#{brand}-!-width-two-thirds)
+        when 'one-half'       then %(#{brand}-!-width-one-half)
+        when 'one-third'      then %(#{brand}-!-width-one-third)
+        when 'one-quarter'    then %(#{brand}-!-width-one-quarter)
+
+        else fail(ArgumentError, "invalid width '#{@width}'")
+        end
+      end
+
+      def prefix
+        return nil if @prefix_text.blank?
+
+        tag.span(@prefix_text, class: %(#{brand}-input__prefix), **affix_options)
+      end
+
+      def suffix
+        return nil if @suffix_text.blank?
+
+        tag.span(@suffix_text, class: %(#{brand}-input__suffix), **affix_options)
+      end
+
+      def affix_options
+        { aria: { hidden: true } }
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/label.rb

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

data/lib/govuk_design_system_formbuilder/traits/localisation.rb

@@ -0,0 +1,51 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Localisation
+    private
+
+      def localised_text(context)
+        return unless @object_name.present? && @attribute_name.present?
+
+        localise(context) || localise_html(context)
+      end
+
+      def localise(context)
+        I18n.translate(schema(context), default: nil)
+      end
+
+      def localise_html(context)
+        I18n.translate("#{schema(context)}_html", default: nil).try(:html_safe)
+      end
+
+      def schema(context)
+        schema_root(context)
+          .push(*schema_path)
+          .map { |e| e == :__context__ ? context : e }
+          .join('.')
+      end
+
+      def schema_path
+        if @value.present?
+          [@object_name, "#{@attribute_name}_options", @value]
+        else
+          [@object_name, @attribute_name]
+        end
+      end
+
+      def schema_root(context)
+        contextual_schema = case context
+                            when :legend
+                              config.localisation_schema_legend
+                            when :hint
+                              config.localisation_schema_hint
+                            when :label
+                              config.localisation_schema_label
+                            when :caption
+                              config.localisation_schema_caption
+                            end
+
+        (contextual_schema || config.localisation_schema_fallback).dup
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/traits/supplemental.rb

@@ -0,0 +1,17 @@
+module GOVUKDesignSystemFormBuilder
+  module Traits
+    module Supplemental
+      def supplemental_id
+        return nil if @block_content.blank?
+
+        build_id('supplemental')
+      end
+
+    private
+
+      def supplemental_content
+        @supplemental_content ||= Containers::Supplemental.new(@builder, @object_name, @attribute_name, @block_content)
+      end
+    end
+  end
+end

data/lib/govuk_design_system_formbuilder/version.rb

@@ -1,3 +1,3 @@
 module GOVUKDesignSystemFormBuilder
-  VERSION = '0.9.8'.freeze
+  VERSION = '2.0.0'.freeze
 end

data/lib/govuk_design_system_formbuilder.rb

@@ -1,53 +1,98 @@
-require 'govuk_design_system_formbuilder/version'
-require 'govuk_design_system_formbuilder/builder'
-require 'govuk_design_system_formbuilder/base'
-
-require 'govuk_design_system_formbuilder/elements/hint'
-require 'govuk_design_system_formbuilder/elements/label'
-require 'govuk_design_system_formbuilder/elements/date'
-require 'govuk_design_system_formbuilder/elements/select'
-require 'govuk_design_system_formbuilder/elements/submit'
-require 'govuk_design_system_formbuilder/elements/text_area'
-require 'govuk_design_system_formbuilder/elements/file'
-
-require 'govuk_design_system_formbuilder/elements/inputs/base'
-require 'govuk_design_system_formbuilder/elements/inputs/email'
-require 'govuk_design_system_formbuilder/elements/inputs/number'
-require 'govuk_design_system_formbuilder/elements/inputs/phone'
-require 'govuk_design_system_formbuilder/elements/inputs/text'
-require 'govuk_design_system_formbuilder/elements/inputs/url'
-
-require 'govuk_design_system_formbuilder/elements/radios/collection'
-require 'govuk_design_system_formbuilder/elements/radios/collection_radio_button'
-require 'govuk_design_system_formbuilder/elements/radios/fieldset_radio_button'
-
-require 'govuk_design_system_formbuilder/elements/check_boxes/collection'
-require 'govuk_design_system_formbuilder/elements/check_boxes/collection_check_box'
-require 'govuk_design_system_formbuilder/elements/check_boxes/fieldset_check_box'
-require 'govuk_design_system_formbuilder/elements/check_boxes/label'
-require 'govuk_design_system_formbuilder/elements/check_boxes/hint'
-
-require 'govuk_design_system_formbuilder/elements/error_message'
-require 'govuk_design_system_formbuilder/elements/error_summary'
-
-require 'govuk_design_system_formbuilder/containers/check_boxes_fieldset'
-require 'govuk_design_system_formbuilder/containers/form_group'
-require 'govuk_design_system_formbuilder/containers/fieldset'
-require 'govuk_design_system_formbuilder/containers/radios'
-require 'govuk_design_system_formbuilder/containers/radio_buttons_fieldset'
-require 'govuk_design_system_formbuilder/containers/check_boxes'
-require 'govuk_design_system_formbuilder/containers/character_count'
-require 'govuk_design_system_formbuilder/containers/supplemental'
+require 'active_support/configurable'
+
+[%w(traits *.rb), %w(*.rb), %w(elements ** *.rb), %w(containers ** *.rb)]
+  .flat_map { |matcher| Dir.glob(File.join(__dir__, 'govuk_design_system_formbuilder', *matcher)) }
+  .each { |file| require file }
 
 module GOVUKDesignSystemFormBuilder
+  include ActiveSupport::Configurable
+
+  # @!group Defaults
+
+  # Default form builder configuration
+  #
+  # * +:brand+ sets the value used to prefix all classes, used to allow the
+  #   builder to be branded for alternative (similar) design systems.
+  #
+  # * +:default_caption_size+ controls the default size of caption text.
+  #   Can be either +xl+, +l+ or +m+.
+  #
+  # * +:default_legend_size+ controls the default size of legend text.
+  #   Can be either +xl+, +l+, +m+ or +s+.
+  #
+  # * +:default_legend_tag+ controls the default tag that legends are
+  #   wrapped in. Defaults to +h1+.
+  #
+  # * +:default_submit_button_text+ sets the value assigned to +govuk_submit+,
+  #   defaults to 'Continue'.
+  #
+  # * +:default_submit_button_text+ sets the text used to divide the last radio
+  #   button in radio button fieldsets. As per the GOV.UK Design System spec,
+  #   it defaults to 'or'.
+  #
+  # * +:default_error_summary_title+ sets the text used in error summary
+  #   blocks. As per the GOV.UK Design System spec, it defaults to
+  #   'There is a problem'.
+  #
+  # * +:localisation_schema_fallback+ sets the prefix elements for the array
+  #   used to build the localisation string. The final two elements are always
+  #   are the object name and attribute name. The _special_ value +__context__+,
+  #   is used as a placeholder for the context (label, fieldset or hint).
+  #
+  # * +:localisation_schema_legend+, +:localisation_schema_hint+ and
+  #   +:localisation_schema_label+ each override the schema root for their
+  #   particular context, allowing them to be independently customised.
+  # ===
+  DEFAULTS = {
+    brand: 'govuk',
+
+    default_legend_size: 'm',
+    default_legend_tag: 'h1',
+    default_caption_size: 'm',
+    default_submit_button_text: 'Continue',
+    default_radio_divider_text: 'or',
+    default_error_summary_title: 'There is a problem',
+
+    localisation_schema_fallback: %i(helpers __context__),
+    localisation_schema_label: nil,
+    localisation_schema_hint: nil,
+    localisation_schema_legend: nil,
+    localisation_schema_caption: nil
+  }.freeze
+
+  DEFAULTS.each_key { |k| config_accessor(k) { DEFAULTS[k] } }
+  # @!endgroup
+
+  class << self
+    # Configure the form builder in the usual manner. All of the
+    # keys in {DEFAULTS} can be configured as per the example below
+    #
+    # @example
+    #   GOVUKDesignSystemFormBuilder.configure do |conf|
+    #     conf.default_legend_size = 'xl'
+    #     conf.default_error_summary_title = 'OMG'
+    #   end
+    def configure
+      yield(config)
+    end
+
+    # Resets each of the configurable values to its default
+    #
+    # @note This method is only really intended for use to clean up
+    #   during testing
+    def reset!
+      configure do |c|
+        DEFAULTS.each { |k, v| c.send("#{k}=", v) }
+      end
+    end
+  end
+
   class FormBuilder < ActionView::Helpers::FormBuilder
-    delegate :content_tag, :tag, :safe_join, :safe_concat, :capture, :link_to, :raw, to: :@template
+    delegate :content_tag, :tag, :safe_join, :link_to, :capture, to: :@template
 
     include GOVUKDesignSystemFormBuilder::Builder
   end
 
   # Disable Rails' div.field_with_error wrapper
-  ActionView::Base.field_error_proc = Proc.new do |html_tag, _instance|
-    html_tag.html_safe
-  end
+  ActionView::Base.field_error_proc = ->(html_tag, _instance) { html_tag }
 end