From b51dd71f68e2c1241d73d8c37289b1eebefe0ec2 Mon Sep 17 00:00:00 2001
From: Matt Hill <matt.hill@digital.cabinet-office.gov.uk>
Date: Tue, 15 Oct 2024 14:58:37 +0100
Subject: [PATCH] New option for contents-list component: alternate_title

---
 .../components/_contents-list.scss               |  6 ++++++
 .../components/_contents_list.html.erb           |  8 +++++++-
 .../components/docs/contents_list.yml            | 16 ++++++++++++++++
 spec/components/contents_list_spec.rb            |  6 ++++++
 4 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/app/assets/stylesheets/govuk_publishing_components/components/_contents-list.scss b/app/assets/stylesheets/govuk_publishing_components/components/_contents-list.scss
index f40852befa..1483d228c4 100644
--- a/app/assets/stylesheets/govuk_publishing_components/components/_contents-list.scss
+++ b/app/assets/stylesheets/govuk_publishing_components/components/_contents-list.scss
@@ -95,6 +95,12 @@
   }
 }
 
+.gem-c-contents-list--alternate-title {
+  .gem-c-contents-list__title {
+    margin-bottom: govuk-spacing(3);
+  }
+}
+
 @include govuk-media-query($media-type: print) {
   // Override default browser indentation
   .gem-c-contents-list__list,
diff --git a/app/views/govuk_publishing_components/components/_contents_list.html.erb b/app/views/govuk_publishing_components/components/_contents_list.html.erb
index a180b781b0..b283e3b60c 100644
--- a/app/views/govuk_publishing_components/components/_contents_list.html.erb
+++ b/app/views/govuk_publishing_components/components/_contents_list.html.erb
@@ -5,6 +5,7 @@
   underline_links ||= false
   format_numbers ||= false
   alternate_active ||= false
+  alternate_title ||= ""
   brand ||= false
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
   title_fallback = t("components.contents_list.contents", locale: I18n.locale, fallback: false, default: "en")
@@ -24,6 +25,7 @@
   component_helper = GovukPublishingComponents::Presenters::ComponentWrapperHelper.new(local_assigns)
   component_helper.add_class("gem-c-contents-list #{brand_helper.brand_class}")
   component_helper.add_class("gem-c-contents-list--alternate-active") if alternate_active
+  component_helper.add_class("gem-c-contents-list--alternate-title") if alternate_title.present?
   component_helper.add_data_attribute({ module: "ga4-link-tracker" }) unless disable_ga4
   component_helper.add_aria_attribute({ label: t("components.contents_list.contents") }) unless local_assigns[:aria][:label]
   component_helper.add_role("navigation")
@@ -35,7 +37,11 @@
         title_fallback == "en" ? {:lang => "en",} : {}
       )
     ) do %>
-      <%= t("components.contents_list.contents") %>
+      <% if alternate_title.empty? %>
+        <%= t("components.contents_list.contents") %>
+      <% else %>
+        <%= alternate_title %>
+      <% end %>
     <% end %>
 
     <ol class="gem-c-contents-list__list">
diff --git a/app/views/govuk_publishing_components/components/docs/contents_list.yml b/app/views/govuk_publishing_components/components/docs/contents_list.yml
index 95540c2c8b..377a43e370 100644
--- a/app/views/govuk_publishing_components/components/docs/contents_list.yml
+++ b/app/views/govuk_publishing_components/components/docs/contents_list.yml
@@ -209,6 +209,22 @@ examples:
           text: Fourth page title link
         - href: "#fifth-thing"
           text: Fifth page title link
+  with_alternate_title:
+    description: With this option, the 'Contents' title is replaced with the supplied alternate title. This should only be used when using this component as a navigation element on landing pages. Typically used in conjunction with the `alternate_active` option.
+    data:
+      alternate_title: "An alternate title"
+      contents:
+        - href: "#first-thing"
+          text: First page title link
+        - href: "#second-thing"
+          text: Second page title link
+        - href: "#third-thing"
+          text: Third page title link
+          active: true
+        - href: "#fourth-thing"
+          text: Fourth page title link
+        - href: "#fifth-thing"
+          text: Fifth page title link
   without_ga4_tracking:
     description: Disables GA4 link tracking on the list. Tracking is enabled by default.
     data:
diff --git a/spec/components/contents_list_spec.rb b/spec/components/contents_list_spec.rb
index ce83a1b65f..1f412521f2 100644
--- a/spec/components/contents_list_spec.rb
+++ b/spec/components/contents_list_spec.rb
@@ -248,4 +248,10 @@ def contents_list_with_markup
     render_component(contents: contents_list, alternate_active: true)
     assert_select ".gem-c-contents-list--alternate-active"
   end
+
+  it "renders an alternate title" do
+    render_component(contents: contents_list, alternate_title: "Alternate title")
+    assert_select ".gem-c-contents-list--alternate-title"
+    assert_select ".gem-c-contents-list__title", text: "Alternate title"
+  end
 end