From 58dd55eaa2d3f0ee22e22521b7e89136d0329ec3 Mon Sep 17 00:00:00 2001
From: Peter Yates <peter.yates@graphia.co.uk>
Date: Sun, 21 Jul 2024 19:55:15 +0100
Subject: [PATCH] Add example that separates label and input

This is quite an advanced use which will stretch the Design System to
the limit. HTML has long-supported placing labels far from the
corresponding input, even outside the form altogether. The risk here is
that error messages now will be placed by the input, which has a strong
likelihood of breaking layouts.

Still, I'm sure some people will find a use for this.

Fixes #477
---
 .../labels-captions-hints-and-legends.slim             | 10 ++++++++++
 guide/content/stylesheets/application.scss             |  4 ++++
 .../lib/examples/labels_captions_hints_and_legends.rb  |  8 ++++++++
 guide/lib/helpers/person.rb                            |  3 ++-
 4 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/guide/content/introduction/labels-captions-hints-and-legends.slim b/guide/content/introduction/labels-captions-hints-and-legends.slim
index 0f8e89fd..1ea3c4fb 100644
--- a/guide/content/introduction/labels-captions-hints-and-legends.slim
+++ b/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
diff --git a/guide/content/stylesheets/application.scss b/guide/content/stylesheets/application.scss
index cf545702..89ffba14 100644
--- a/guide/content/stylesheets/application.scss
+++ b/guide/content/stylesheets/application.scss
@@ -65,6 +65,10 @@ $govuk-page-width: 1100px;
   }
 }
 
+.two-columns {
+  columns: 2;
+}
+
 .branded-background {
   background: govuk-colour(blue);
 }
diff --git a/guide/lib/examples/labels_captions_hints_and_legends.rb b/guide/lib/examples/labels_captions_hints_and_legends.rb
index 6ae24492..e78e2763 100644
--- a/guide/lib/examples/labels_captions_hints_and_legends.rb
+++ b/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,
diff --git a/guide/lib/helpers/person.rb b/guide/lib/helpers/person.rb
index d5b695a5..0ebeaae6 100644
--- a/guide/lib/helpers/person.rb
+++ b/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