From f64f9670a5269b71e3eef41503f60dfdeb8dd858 Mon Sep 17 00:00:00 2001
From: Andy Sellick <andy.sellick@digital.cabinet-office.gov.uk>
Date: Fri, 28 Jan 2022 15:17:04 +0000
Subject: [PATCH] Add select component hint

- based on the Design system
- an optional hint attribute, with optional hint id
- the aria-describedby attribute of the select points to the hint, if an error is also present the describedby attribute includes both hint and error IDs
---
 CHANGELOG.md                                  |  6 ++-
 .../components/_select.html.erb               | 20 +++++++++-
 .../components/docs/select.yml                | 12 ++++++
 spec/components/select_spec.rb                | 37 +++++++++++++++++++
 4 files changed, 73 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff2c968a7c..4e93e3243f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,9 +7,13 @@
   useful summary for people upgrading their application, not a replication
   of the commit log.
 
+## Unreleased
+
+* Add select component hint ([PR #2594](https://github.com/alphagov/govuk_publishing_components/pull/2594))
+
 ## 28.4.0
 
-- Remove COVID CTA from contextual sidebar component (PR [#2584](https://github.com/alphagov/govuk_publishing_components/pull/2584))
+- Remove COVID CTA from contextual sidebar component ([PR #2584](https://github.com/alphagov/govuk_publishing_components/pull/2584))
 
 ## 28.3.0
 
diff --git a/app/views/govuk_publishing_components/components/_select.html.erb b/app/views/govuk_publishing_components/components/_select.html.erb
index 968d831175..b1c4b27d5c 100644
--- a/app/views/govuk_publishing_components/components/_select.html.erb
+++ b/app/views/govuk_publishing_components/components/_select.html.erb
@@ -10,12 +10,23 @@
   heading_size = false unless shared_helper.valid_heading_size?(heading_size)
   error_message ||= nil
   error_id ||= nil
+  hint ||= nil
+  hint_id ||= nil
+
+  describedby = %w[]
 
   if error_message || error_id
     error_id = "error-#{SecureRandom.hex(4)}" unless error_id
-    aria_describedby = { describedby: error_id }
+    describedby << error_id
+  end
+
+  if hint
+    hint_id = "hint-#{SecureRandom.hex(4)}" unless hint_id
+    describedby << hint_id
   end
 
+  aria_describedby = { describedby: describedby } if describedby
+
   css_classes = %w(govuk-form-group gem-c-select)
   css_classes << "govuk-form-group--error" if error_message
 
@@ -37,6 +48,13 @@
       <%= label_tag(id, label, class: label_classes) %>
     <% end %>
 
+    <% if hint %>
+      <%= render "govuk_publishing_components/components/hint", {
+        id: hint_id,
+        text: hint
+      } %>
+    <% end %>
+
     <% if error_message %>
       <%= render "govuk_publishing_components/components/error_message", {
         id: error_id,
diff --git a/app/views/govuk_publishing_components/components/docs/select.yml b/app/views/govuk_publishing_components/components/docs/select.yml
index 55268d1e63..66ccc2790d 100644
--- a/app/views/govuk_publishing_components/components/docs/select.yml
+++ b/app/views/govuk_publishing_components/components/docs/select.yml
@@ -42,6 +42,18 @@ examples:
         selected: true
       - text: 'Option three'
         value: 'option3'
+  with_hint:
+    description: When a hint is included the `aria-describedby` attribute of the select is included to point to the hint. When an error and a hint are present, that attribute includes the IDs of both the hint and the error.
+    data:
+      id: 'dropdown2-1'
+      label: 'Choose your preferred thing'
+      hint_text: 'You might need some more information here'
+      hint_id: 'optional-hint-id'
+      options:
+      - text: 'Something'
+        value: 'option1'
+      - text: 'Something else'
+        value: 'option2'
   with_tracking:
     description: 'Tracking can be enabled on the select component by passing a minimum of data_track_category and data_track_action. Other tracking attributes are optional. Note: tracking events do not currently fire within the component guide.'
     data:
diff --git a/spec/components/select_spec.rb b/spec/components/select_spec.rb
index 404744f85f..5a60ea1740 100644
--- a/spec/components/select_spec.rb
+++ b/spec/components/select_spec.rb
@@ -186,6 +186,24 @@ def component_name
     assert_select ".gem-c-select [data-another-attribute=test1][data-second-item=item1][data-option=option1]"
   end
 
+  it "renders a select box with a hint" do
+    render_component(
+      id: "mydropdown",
+      label: "attributes",
+      hint: "this is a hint",
+      hint_id: "hint_id",
+      options: [
+        {
+          value: 1,
+          text: "One",
+        },
+      ],
+    )
+
+    assert_select ".gem-c-select .govuk-hint", "this is a hint"
+    assert_select ".gem-c-select .govuk-select[aria-describedby='hint_id']"
+  end
+
   it "renders a select box in an error state" do
     render_component(
       id: "mydropdown",
@@ -222,6 +240,25 @@ def component_name
     assert_select ".govuk-select.govuk-select--error[aria-describedby=error_id]"
   end
 
+  it "applies aria-describedby if a hint and an error are present" do
+    render_component(
+      id: "mydropdown",
+      label: "attributes",
+      hint: "this is a hint",
+      hint_id: "hint_id",
+      error_id: "error_id",
+      options: [
+        {
+          value: 1,
+          text: "One",
+        },
+      ],
+    )
+
+    assert_select ".gem-c-select .govuk-hint", "this is a hint"
+    assert_select ".gem-c-select .govuk-select[aria-describedby='error_id hint_id']"
+  end
+
   it "renders a select box full width" do
     render_component(
       id: "mydropdown",