Add list component

 - This is a direct port of the list component from GOV.UK Frontend / Design
   System with no extra styles added.
 - Imported SCSS from GOV.UK Frontend
 - Added documentation with examples of the different permutations
 - Added tests
 - Updated changelog

CHANGELOG.md

@@ -10,6 +10,7 @@
 ## Unreleased
 
 * Fix search component label accessibility ([PR #1594](https://github.com/alphagov/govuk_publishing_components/pull/1594))
+* Add list component ([PR #1595](https://github.com/alphagov/govuk_publishing_components/pull/1595))
 
 ## 21.57.1
 

app/assets/stylesheets/govuk_publishing_components/components/_list.scss

@@ -0,0 +1 @@
+@import "govuk/components/list/list";

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

@@ -0,0 +1,26 @@
+<%
+  id ||= nil
+  extra_spacing ||= nil
+  list_type ||= "unordered"
+  visible_counters ||= nil
+  items ||= []
+  aria_label ||= nil
+
+  classes = %w(gem-c-list govuk-list)
+  classes << "govuk-list--bullet" if visible_counters && list_type === "unordered"
+  classes << "govuk-list--number" if visible_counters && list_type === "number"
+  classes << "govuk-list--spaced" if extra_spacing
+
+  # Default list type is unordered list.
+  list_tag = "ul"
+
+  # Set to ordered list to override default.
+  list_tag = "ol" if list_type === "number"
+%>
+<% if items.any? %>
+  <%= content_tag list_tag, class: classes, id: id, "aria-label": aria_label do %>
+    <% items.each do |item| %>
+      <li><%= sanitize(item) %></li>
+    <% end %>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,64 @@
+name: List
+description: A list - unordered or ordered, with or without counters / bullet points.
+body: |
+  This is an ordered or unordered list, with or without visible bullets / numbers.
+
+  The `items` parameter can include HTML to display - such as links or another
+  list. This HTML can either be directly coded or come from another component.
+accessibility_criteria: |
+  The list must:
+
+  - inform the user how many items are in the list
+  - convey the content structure
+  - indicate the current page when contents span different pages, and not link to itself
+
+  The list may:
+
+  - include an `aria-label` to contextualise the list if helpful
+govuk_frontend_components:
+  - list
+examples:
+  default:
+    description: "The default is an unordered list with no bullet points or numbers."
+    data: &default-example-data
+      items:
+      - "Tony’s Chocolonely"
+      - '<a href="https://en.wikipedia.org/wiki/Cherry_Ripe_(chocolate_bar)" rel="noopener" class="govuk-link">Cherry Ripe</a>'
+      - "Snickers"
+      - "Chomp"
+      - "Penguin"
+      - "Boost"
+  unordered_list_with_aria-label:
+    description: "A list with an aria-label"
+    data:
+      aria_label: "A list of delicious chocolate bars."
+      <<: *default-example-data
+  unordered_list_with_bullet_points:
+    description: "An unordered list with visible bullet points."
+    data:
+      visible_counters: true
+      <<: *default-example-data
+  ordered_list_without_numbers:
+    description: "This is an ordered list where the numbers aren't visible."
+    data:
+      list_type: "number"
+      <<: *default-example-data
+  ordered_list_with_numbers:
+    description: |
+      This is an ordered list with the numbers visible.
+    data:
+      list_type: "number"
+      visible_counters: true
+      <<: *default-example-data
+  with_extra_spacing:
+    description: |
+      Increases the amount of spacing between the list items.
+    data:
+      extra_spacing: true
+      <<: *default-example-data
+  with_id_attribute:
+    description: |
+      Sets the `id` on the `ul` or `ol` element.
+    data:
+      id: 'super-fantastic-chocolate-list'
+      <<: *default-example-data

spec/components/list_spec.rb

@@ -0,0 +1,101 @@
+require "rails_helper"
+
+describe "List", type: :view do
+  def component_name
+    "list"
+  end
+
+  it "does not render anything if no data is passed" do
+    test_data = {}
+
+    assert_empty render_component(test_data)
+  end
+
+  it "does not render anything if nothing is in the items array" do
+    test_data = { items: [] }
+
+    assert_empty render_component(test_data)
+  end
+
+  it "renders an unordered list by default" do
+    render_component(
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ul.govuk-list li", text: "Test item"
+    assert_select "ul.govuk-list li:nth-child(2)", text: "Another test item"
+  end
+
+  it "adds an aria-label" do
+    render_component(
+      aria_label: "An aria-label to give this context.",
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ul[aria-label]"
+    assert_select "ul[aria-label='An aria-label to give this context.']"
+  end
+
+  it "renders an ordered list" do
+    render_component(
+      list_type: "number",
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ol.govuk-list li", text: "Test item"
+    assert_select "ol.govuk-list li:nth-child(2)", text: "Another test item"
+  end
+
+  it "renders an unordered list with visible bullets" do
+    render_component(
+      visible_counters: true,
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ul.govuk-list--bullet li", text: "Test item"
+    assert_select "ul.govuk-list--bullet li:nth-child(2)", text: "Another test item"
+  end
+
+  it "renders an ordered list with visible counters" do
+    render_component(
+      list_type: "number",
+      visible_counters: true,
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ol.govuk-list--number li", text: "Test item"
+    assert_select "ol.govuk-list--number li:nth-child(2)", text: "Another test item"
+  end
+
+  it "adds extra spacing to each list item" do
+    render_component(
+      extra_spacing: true,
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ul.govuk-list--spaced li", text: "Test item"
+    assert_select "ul.govuk-list--spaced li:nth-child(2)", text: "Another test item"
+  end
+
+  it "adds an `id` correctly" do
+    render_component(
+      id: "this-is-a-test-id",
+      items: ["Test item", "Another test item"],
+    )
+
+    assert_select "ul#this-is-a-test-id li", text: "Test item"
+    assert_select "ul#this-is-a-test-id li:nth-child(2)", text: "Another test item"
+  end
+
+  it "adds links within a list" do
+    render_component(
+      items: [
+        "<a href='https://example.com/'>Test item</a>",
+        "<a href='https://example.com/'>Another test item</a>",
+      ],
+    )
+
+    assert_select "ul.govuk-list li a", text: "Test item"
+    assert_select "ul.govuk-list li:nth-child(2) a", text: "Another test item"
+  end
+end