Extend contents list component

Introduce the ability to pass through lang and custom title to the
Contents list component.

If a title lang is not supplied, a lang attribute will not be added.
Likewise, if a custom title is not specified, the component will default
to using "Contents" as a title.

The need for this arose because in some instances (for example on world
location pages), when viewing a translation of the page, this title of
this component will be in English and not marked as such.
If a translation exists, we should use the translated string as the
title (e.g Contenu if the page is in French). Otherwise we can use the
English fallback, as long as lang="en" is specified.

CHANGELOG.md

@@ -11,6 +11,7 @@
 
 * Add language attribute to feed box ([PR #1706](https://github.com/alphagov/govuk_publishing_components/pull/1706))
 * Replace feedback component links with buttons ([PR #1699](https://github.com/alphagov/govuk_publishing_components/pull/1699)) MINOR
+* Extend contents list component ([PR #1710](https://github.com/alphagov/govuk_publishing_components/pull/1710))
 
 ## 21.66.4
 

app/views/govuk_publishing_components/components/_contents_list.html.erb

@@ -2,8 +2,9 @@
   cl_helper = GovukPublishingComponents::Presenters::ContentsListHelper.new(local_assigns)
   aria_label ||= "Contents"
   format_numbers ||= false
+  title_lang ||= false
+  title = local_assigns[:title].presence || t("components.contents_list.contents")
   hide_title ||= false
-
   brand ||= false
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
 
@@ -21,7 +22,13 @@
     }
   ) do %>
     <% unless hide_title %>
-      <h2 class="gem-c-contents-list__title"><%= t("components.contents_list.contents") %></h2>
+      <%= content_tag(
+        :h2,
+        class: "gem-c-contents-list__title",
+        lang: title_lang.presence
+      ) do %>
+        <%= title %>
+      <% end %>
     <% end %>
 
     <ol class="gem-c-contents-list__list">

app/views/govuk_publishing_components/components/docs/contents_list.yml

@@ -215,3 +215,28 @@ examples:
             text: Guidance and regulation
           - href: "#third-thing"
             text: Consultations
+  with_a_custom_title:
+    description: Override the default title of "Contents" with a custom title
+    data:
+      title: "On this page"
+      contents:
+        - href: "#first-thing"
+          text: First thing
+        - href: "#second-thing"
+          text: Second thing
+        - href: "#third-thing"
+          text: Third thing
+  with_a_custom_title_locale:
+    description: |
+      This component is often used on translated pages that don’t have a translation for the title of the contents list. This means that it could display the fallback English string if the translate method can’t find an appropriate translation. This makes sure that the lang can be set to ensure that browsers understand which parts of the page are in each language.
+
+      The lang attribute must be set to a [valid BCP47 string](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#Language_tag_syntax). A valid code can be the two or three letter language code - for example, English is en or eng, Korean is ko or kor - but if in doubt please check.
+    data:
+      title_lang: "cy"
+      contents:
+        - href: "#first-thing"
+          text: First thing
+        - href: "#second-thing"
+          text: Second thing
+        - href: "#third-thing"
+          text: Third thing

spec/components/contents_list_spec.rb

@@ -137,6 +137,16 @@ def assert_tracking_link(name, value, total = 1)
     assert_select ".gem-c-contents-list__title", text: "Cynnwys"
   end
 
+  it "applies a custom title, if one is supplied" do
+    render_component(contents: contents_list, title: "On this page")
+    assert_select ".gem-c-contents-list__title", text: "On this page"
+  end
+
+  it "adds a lang attribute to the title, if a title_lang is supplied" do
+    render_component(contents: contents_list, title_lang: "fr")
+    assert_select ".gem-c-contents-list__title[lang=\"fr\"]"
+  end
+
   it "hides the title" do
     render_component(contents: nested_contents_list, hide_title: true)
     assert_select ".gem-c-contents-list__title", false