From d691f820b234766bfd57e885c2c93255d8eec1e2 Mon Sep 17 00:00:00 2001
From: Christian Sutter <git@doublesignal.com>
Date: Tue, 8 Oct 2024 15:54:31 +0000
Subject: [PATCH] Document list: Add option for equal item spacing

The items in a document list currently have slightly more padding above
the separator than below. For the new design for GOV.UK Search, we want
the spacing above and below the separator to be equal.
---
 CHANGELOG.md                                  |  1 +
 .../components/_document-list.scss            |  7 ++++++
 .../components/_document_list.html.erb        |  1 +
 .../components/docs/document_list.yml         | 22 +++++++++++++++++++
 spec/components/document_list_spec.rb         | 16 ++++++++++++++
 5 files changed, 47 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ce5c86fcd1..0d7197309a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@
 * Update attachment link accessibility guidance ([PR #4278](https://github.com/alphagov/govuk_publishing_components/pull/4278))
 * Global print link class ([PR #4275](https://github.com/alphagov/govuk_publishing_components/pull/4275))
 * Add component wrapper to devolved nations component ([PR #4281](https://github.com/alphagov/govuk_publishing_components/pull/4281))
+* Document list: Add option for equal item spacing ([PR #4293](https://github.com/alphagov/govuk_publishing_components/pull/4293))
 
 ## 43.5.0
 
diff --git a/app/assets/stylesheets/govuk_publishing_components/components/_document-list.scss b/app/assets/stylesheets/govuk_publishing_components/components/_document-list.scss
index 25d4513d42..8cd41edf04 100644
--- a/app/assets/stylesheets/govuk_publishing_components/components/_document-list.scss
+++ b/app/assets/stylesheets/govuk_publishing_components/components/_document-list.scss
@@ -35,6 +35,13 @@
   }
 }
 
+.gem-c-document-list--equal-item-spacing {
+  .gem-c-document-list__item {
+    margin-top: govuk-spacing(3);
+    padding-top: govuk-spacing(3);
+  }
+}
+
 .gem-c-document-list__item-title--context {
   margin-right: govuk-spacing(2);
 
diff --git a/app/views/govuk_publishing_components/components/_document_list.html.erb b/app/views/govuk_publishing_components/components/_document_list.html.erb
index bd7c2cb5cc..4d08283857 100644
--- a/app/views/govuk_publishing_components/components/_document_list.html.erb
+++ b/app/views/govuk_publishing_components/components/_document_list.html.erb
@@ -9,6 +9,7 @@
   component_helper.add_class("gem-c-document-list")
   component_helper.add_class("gem-c-document-list--no-top-border") if local_assigns[:remove_top_border]
   component_helper.add_class("gem-c-document-list--no-top-border-first-child") if local_assigns[:remove_top_border_from_first_child]
+  component_helper.add_class("gem-c-document-list--equal-item-spacing") if local_assigns[:equal_item_spacing]
   component_helper.add_class(shared_helper.get_margin_bottom)
 
   extra_link_classes = "govuk-link--no-underline" if local_assigns[:remove_underline]
diff --git a/app/views/govuk_publishing_components/components/docs/document_list.yml b/app/views/govuk_publishing_components/components/docs/document_list.yml
index 3a19929ab7..f3aacec4a4 100644
--- a/app/views/govuk_publishing_components/components/docs/document_list.yml
+++ b/app/views/govuk_publishing_components/components/docs/document_list.yml
@@ -244,6 +244,28 @@ examples:
         metadata:
           public_updated_at: 2017-07-19 15:01:48
           document_type: 'Statistical data set'
+  with_equal_item_spacing:
+    description: |
+      The new search UI has consistently equal spacing between items in the document list, instead
+      of the original larger bottom padding.
+    data:
+      equal_item_spacing: true
+      items:
+      - link:
+          text: 'Become an apprentice'
+          path: '/become-an-apprentice'
+          description: 'Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.'
+          full_size_description: true
+      - link:
+          text: 'Become a journeyman'
+          path: '/become-a-journeyman'
+          description: 'Becoming a journeyman - what to expect, what to take, pay and training, making an application, complaining about being a journeyman.'
+          full_size_description: true
+      - link:
+          text: 'Become enlightened'
+          path: '/become-enlightened'
+          description: 'Becoming enlightened - what to expect, what to take, pay and training, making an application, complaining about being enlightened.'
+          full_size_description: true
   highlighted_result:
     description: Highlight one or more of the items in the list. This is used on finders to provide a 'top result' for a search. The `highlight_text` parameter is optional.
     data:
diff --git a/spec/components/document_list_spec.rb b/spec/components/document_list_spec.rb
index 49df3d9cc3..459a12225e 100644
--- a/spec/components/document_list_spec.rb
+++ b/spec/components/document_list_spec.rb
@@ -316,6 +316,22 @@ def component_name
     assert_select ".gem-c-document-list.gem-c-document-list--no-top-border-first-child"
   end
 
+  it "renders items with equal spacing" do
+    render_component(
+      equal_item_spacing: true,
+      items: [
+        {
+          link: {
+            text: "Link Title",
+            path: "/link/path",
+          },
+        },
+      ],
+    )
+
+    assert_select ".gem-c-document-list.gem-c-document-list--equal-item-spacing"
+  end
+
   it "highlights items" do
     render_component(
       items: [