From 213d76b72f66e9829fed5ba8292e6a9bc555cedf Mon Sep 17 00:00:00 2001
From: Christian Sutter <git@doublesignal.com>
Date: Thu, 19 Sep 2024 14:59:02 +0000
Subject: [PATCH] Filter section: make a11y heading prefix configurable

This shouldn't always be set, or hardcoded to "filter by" - for example,
we will have a "Sort by" section that shouldn't have a prefix at all.
---
 app/views/components/_filter_section.html.erb |  6 ++++--
 app/views/components/docs/filter_section.yml  | 13 ++++++++++---
 spec/components/filter_section_spec.rb        |  8 +++++++-
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/app/views/components/_filter_section.html.erb b/app/views/components/_filter_section.html.erb
index 7b221d3db..f90d39ec5 100644
--- a/app/views/components/_filter_section.html.erb
+++ b/app/views/components/_filter_section.html.erb
@@ -4,7 +4,7 @@
   shared_helper = GovukPublishingComponents::Presenters::SharedHelper.new(local_assigns)
   open ||= nil
   status_text ||= ""
-  heading_text ||= ""
+  visually_hidden_heading_prefix ||= ""
   heading_level ||= 2
   summary_aria_attributes ||= {}
 
@@ -16,7 +16,9 @@
 <%= tag.details(**component_helper.all_attributes) do %>
   <%= tag.summary class: "app-c-filter-section__summary", aria: summary_aria_attributes do %>
       <%= content_tag("h#{heading_level}", class: "app-c-filter-section__summary-heading") do %>
-        <span class="govuk-visually-hidden">Filter by</span>
+        <% if visually_hidden_heading_prefix.present? %>
+          <span class="govuk-visually-hidden"><%= visually_hidden_heading_prefix %></span>
+        <% end %>
         <%= heading_text %>
       <% end %>
 
diff --git a/app/views/components/docs/filter_section.yml b/app/views/components/docs/filter_section.yml
index 26cd7c070..90073dfe8 100644
--- a/app/views/components/docs/filter_section.yml
+++ b/app/views/components/docs/filter_section.yml
@@ -15,18 +15,25 @@ accessibility_criteria: |
 examples:
   default:
     data:
-      heading_text: Filter by something
+      heading_text: Some metadata field
       block: |
         <span>Filter form controls</span>
   open:
     data:
-      heading_text: Filter by something
+      heading_text: Some metadata field
       open: true
       block: |
         <span>Filter form controls open by default</span>
+  with_visually_hidden_heading_prefix:
+    description: Prefix the heading text with visually hidden text for screenreaders to make it more descriptive.
+    data:
+      heading_text: Some metadata field
+      visually_hidden_heading_prefix: Filter by
+      block: |
+        <span>Filter form controls</span>
   status_text:
     data:
-      heading_text: Filter by something
+      heading_text: Some metadata field
       status_text: 1 Selected
       block: |
         <span>Filter form controls with status text</span>
diff --git a/spec/components/filter_section_spec.rb b/spec/components/filter_section_spec.rb
index 5e0d2bb64..002428976 100644
--- a/spec/components/filter_section_spec.rb
+++ b/spec/components/filter_section_spec.rb
@@ -26,9 +26,15 @@ def render_component(locals)
     assert_select ".app-c-filter-section[open=open]"
   end
 
-  it "set section heading text with hidden context for accessibility" do
+  it "sets the heading text" do
     render_component({ heading_text: "section heading" })
 
+    assert_select ".app-c-filter-section__summary-heading", text: "section heading"
+  end
+
+  it "adds the visually hidden heading prefix if given" do
+    render_component({ heading_text: "section heading", visually_hidden_heading_prefix: "Filter by" })
+
     assert_select ".app-c-filter-section__summary-heading", include: "section heading"
     assert_select ".app-c-filter-section__summary-heading .govuk-visually-hidden", text: "Filter by"
   end