Contents list add margin_bottom option

CHANGELOG.md

@@ -7,6 +7,10 @@
   useful summary for people upgrading their application, not a replication
   of the commit log.
 
+## Unreleased
+
+* Contents list add margin_bottom option ([PR #4333](https://github.com/alphagov/govuk_publishing_components/pull/4333))
+
 ## 44.6.0
 
 * Use flexbox for share links with square icons ([PR #4316](https://github.com/alphagov/govuk_publishing_components/pull/4316))

app/assets/stylesheets/govuk_publishing_components/components/_contents-list.scss

@@ -5,7 +5,6 @@
   // Always render the contents list above a
   // back to contents link
   position: relative;
-  margin: 0 0 govuk-spacing(4) 0;
   z-index: 1;
   background: govuk-colour("white");
   box-shadow: 0 20px 15px -10px govuk-colour("white");

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

@@ -1,15 +1,18 @@
-<%-
+<%
   add_gem_component_stylesheet("contents-list")
 
-  cl_helper = GovukPublishingComponents::Presenters::ContentsListHelper.new(local_assigns)
   underline_links ||= false
   format_numbers ||= false
   alternative_line_style ||= false
   title ||= nil
   brand ||= false
+  local_assigns[:aria] ||= {}
+  local_assigns[:margin_bottom] ||= 4
+
+  shared_helper = GovukPublishingComponents::Presenters::SharedHelper.new(local_assigns)
+  cl_helper = GovukPublishingComponents::Presenters::ContentsListHelper.new(local_assigns)
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
-  title_fallback = t("components.contents_list.contents", locale: I18n.locale, fallback: false, default: "en")
-  classes = %w[gem-c-contents-list]
+
   link_classes = %w[gem-c-contents-list__link govuk-link gem-print-link]
   link_classes << brand_helper.color_class
   link_classes << "govuk-link--no-underline" unless underline_links
@@ -21,15 +24,18 @@
     type: "contents list",
     index_total: cl_helper.get_index_total,
   } unless disable_ga4
-  local_assigns[:aria] ||= {}
+
   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_class(shared_helper.get_margin_bottom)
   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")
--%>
+
+  title_fallback = t("components.contents_list.contents", locale: I18n.locale, fallback: false, default: "en")
+%>
 <% if cl_helper.contents.any? %>
   <%= tag.nav(**component_helper.all_attributes) do %>
     <%= content_tag(

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

@@ -1,12 +1,11 @@
 name: Contents list
 description: Provides a list of links with options for dashes or numbering.
 body: |
-  Commonly used to lists a page’s contents with links pointing to headings within the document, but can also be used for a list of links to other pages.
+  Commonly used to list the contents of a page with links pointing to headings within the document, but can also be used for a list of links to other pages.
 
   Pass a list of contents each with an `href` and `text`. The `href` can point at the ID of a heading within the page.
 
-  Supports nesting contents one level deep, currently only used by specialist documents. When nesting the top level list items
-  display in bold.
+  Supports nesting contents one level deep, currently only used by specialist documents. When nesting the top level list items display in bold.
 
   `format_numbers` option will pull out numbers in the link text to render them as though they were the list style type. Applies to numbers at the start of text, with or without a decimal. See the [format complex numbers fixture](/component-guide/contents-list/formats_complex_numbers) for details.
 accessibility_criteria: |
@@ -36,6 +35,17 @@ examples:
           text: Second thing
         - href: "#third-thing"
           text: Third thing
+  with_bottom_margin:
+    description: The component accepts a number for margin bottom from `0` to `9` (`0px` to `60px`) using the [GOV.UK Frontend spacing scale](https://design-system.service.gov.uk/styles/spacing/#the-responsive-spacing-scale). The default margin bottom is `20px` (`govuk-spacing(4)`).
+    data:
+      margin_bottom: 9
+      contents:
+        - href: "#first-thing"
+          text: First thing
+        - href: "#second-thing"
+          text: Second thing
+        - href: "#third-thing"
+          text: Third thing
   underline_links:
     description: By default we do not underline links in this component even though this is the general approach on GOV.UK. This is because some of the examples below (particularly those with numbers) do not work well with underlined links. Instead, this option allows the links to be underlined where appropriate.
     data:

spec/components/contents_list_spec.rb

@@ -77,6 +77,19 @@ def contents_list_with_markup
     assert_select ".gem-c-contents-list__link.govuk-link--no-underline[href='#two']", text: "2. Two"
   end
 
+  it "applies default margin to the component" do
+    render_component(contents: contents_list)
+    assert_select '.gem-c-contents-list.govuk-\!-margin-bottom-4'
+  end
+
+  it "applies requested margin to the component" do
+    render_component(
+      contents: contents_list,
+      margin_bottom: 0,
+    )
+    assert_select '.gem-c-contents-list.govuk-\!-margin-bottom-0'
+  end
+
   it "renders a list of contents links containing special characters" do
     render_component(contents: contents_list_with_special_chars)