From 0bc86cf5e65500fd86ff414d1f57c8ed6481f64d Mon Sep 17 00:00:00 2001
From: Matt Hill <matt.hill@digital.cabinet-office.gov.uk>
Date: Wed, 16 Oct 2024 12:57:52 +0100
Subject: [PATCH] New option for contents-list component: custom_title

---
 .../components/_contents_list.html.erb           |  4 +++-
 .../components/docs/contents_list.yml            | 16 ++++++++++++++++
 spec/components/contents_list_spec.rb            |  6 ++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

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 87ab4e0e99..e17b219210 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
   alternative_line_style ||= false
+  title ||= nil
   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--alternative-line-style") if alternative_line_style
+  component_helper.add_class("gem-c-contents-list--custom-title") if title
   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,7 @@
         title_fallback == "en" ? {:lang => "en",} : {}
       )
     ) do %>
-      <%= t("components.contents_list.contents") %>
+      <%= title || t("components.contents_list.contents") %>
     <% 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 73e63017aa..4930f895de 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_custom_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 with `alternative_line_style`.
+    data:
+      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 04d31c5ba5..04ed45a7c5 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, alternative_line_style: true)
     assert_select ".gem-c-contents-list--alternative-line-style"
   end
+
+  it "renders an alternate title" do
+    render_component(contents: contents_list, title: "Alternate title")
+    assert_select ".gem-c-contents-list--custom-title"
+    assert_select ".gem-c-contents-list__title", text: "Alternate title"
+  end
 end