Standalone labels

guide/content/introduction/labels-captions-hints-and-legends.slim

@@ -76,6 +76,16 @@ dl.govuk-summary-list
         can enforce consistency between the label's <code>for</code> attribute
         and the associated form element.
 
+== render('/partials/example.*',
+  caption: 'Separate labels',
+  code: text_field_with_standalone_label,
+  start_headings_at_level: 3) do
+
+  markdown:
+    There are occasions where placing the label above an input won't work. We can
+    do this by suppressing the default label with `label: nil` and manually adding
+    the label elsewhere by calling the `govuk_label` helper directly.
+
 hr.govuk-section-break.govuk-section-break--xl.govuk-section-break--visible
 
 h2.govuk-heading-l Captions

guide/content/stylesheets/application.scss

@@ -65,6 +65,10 @@ $govuk-page-width: 1100px;
   }
 }
 
+.two-columns {
+  columns: 2;
+}
+
 .branded-background {
   background: govuk-colour(blue);
 }

guide/lib/examples/labels_captions_hints_and_legends.rb

@@ -20,6 +20,14 @@ def text_field_with_label_proc
       SNIPPET
     end
 
+    def text_field_with_standalone_label
+      <<~SNIPPET
+        .two-columns
+          = f.govuk_label :crayons_or_felt_tips, text: "Do you prefer crayons or felt tip pens?"
+          = f.govuk_text_field :crayons_or_felt_tips, label: nil
+      SNIPPET
+    end
+
     def text_field_with_caption
       <<~SNIPPET
         = f.govuk_text_field :favourite_shade_of_grey,

guide/lib/helpers/person.rb

@@ -86,7 +86,8 @@ class Person
     :favourite_shade_of_purple,
     :favourite_shade_of_grey,
     :favourite_primary_colour,
-    :least_favourite_colour
+    :least_favourite_colour,
+    :crayons_or_felt_tips
   )
 
   # errors

lib/govuk_design_system_formbuilder/builder.rb

@@ -2,6 +2,20 @@ module GOVUKDesignSystemFormBuilder
   module Builder
     delegate :config, to: GOVUKDesignSystemFormBuilder
 
+    # Generates a form label without a form group or input
+    # @param text [String] the label text
+    # @param size [String] the size of the label font, can be +xl+, +l+, +m+, +s+ or nil
+    # @param tag [Symbol,String] the label's wrapper tag, intended to allow labels to act as page headings
+    # @param hidden [Boolean] control the visability of the label. Hidden labels will stil be read by screenreaders
+    # @param kwargs [Hash] additional arguments are applied as attributes on the +label+ element
+    #
+    # @example A standalone label for the name field
+    #   = f.govuk_label :name, text: 'Full name', size: 'l', caption: { text: 'It must match your driving licence' }
+    #
+    def govuk_label(attribute_name, text: nil, size: nil, hidden: false, tag: nil, caption: nil, **kwargs)
+      GOVUKDesignSystemFormBuilder::Elements::Label.new(self, object_name, attribute_name, text:, size:, hidden:, tag:, caption:, **kwargs).html
+    end
+
     # Generates a input of type +text+
     #
     # @param attribute_name [Symbol] The name of the attribute

spec/govuk_design_system_formbuilder/builder/label_spec.rb

@@ -0,0 +1,75 @@
+describe GOVUKDesignSystemFormBuilder::FormBuilder do
+  include_context 'setup builder'
+
+  describe '#govuk_password_field' do
+    let(:custom_label_text) { "What's your name?" }
+    let(:method) { :govuk_label }
+    let(:attribute) { :name }
+    let(:args) { [method, attribute] }
+    let(:kwargs) { { text: custom_label_text } }
+
+    subject { builder.send(*args, **kwargs) }
+
+    specify 'renders a label with the right custom text' do
+      expect(subject).to have_tag('label', text: custom_label_text, with: { class: 'govuk-label' })
+    end
+
+    context 'when a caption is provided' do
+      let(:kwargs) { { caption: { text: 'A very nice caption' } } }
+
+      specify 'the caption is rendered inside the label' do
+        expect(subject).to have_tag('label') do
+          with_tag('span', with: { class: 'govuk-caption-m' }, text: 'A very nice caption')
+        end
+      end
+    end
+
+    describe 'sizes' do
+      {
+        's' => 'govuk-label--s',
+        'm' => 'govuk-label--m',
+        'l' => 'govuk-label--l',
+        'xl' => 'govuk-label--xl'
+      }.each do |size, expected_class|
+        context "when size: '#{size}'" do
+          let(:size) { size }
+          let(:kwargs) { { size: } }
+
+          subject { builder.send(*args, **kwargs) }
+
+          specify "the label has class #{expected_class}" do
+            expect(subject).to have_tag('label', with: { class: expected_class }, text: 'Name')
+          end
+        end
+      end
+    end
+
+    context 'when hidden' do
+      let(:kwargs) { { hidden: true } }
+
+      specify 'the label is hidden' do
+        expect(subject).to have_tag('label') do
+          with_tag('span', with: { class: 'govuk-visually-hidden' }, text: 'Name')
+        end
+      end
+    end
+
+    context 'when tag overridden' do
+      let(:kwargs) { { tag: 'h4' } }
+
+      specify "the label is wrapped in the supplied element with class 'govuk-label-wrapper'" do
+        expect(subject).to have_tag('h4', with: { class: 'govuk-label-wrapper' }) do
+          with_tag('label', with: { class: 'govuk-label' }, text: 'Name')
+        end
+      end
+    end
+
+    context 'when extra arguments are supplied' do
+      let(:kwargs) { { lang: 'de', data: { positive: 'yes' } } }
+
+      specify 'the label is rendered with the extra HTML attributes present' do
+        expect(subject).to have_tag('label', text: 'Name', with: { class: 'govuk-label', lang: 'de', 'data-positive' => 'yes' })
+      end
+    end
+  end
+end