Add taxonomy list component

Wraps the highlight box and document list component in one list. This is commonly used on topic pages for taxonomy-related navigation.

CHANGELOG.md

@@ -7,6 +7,10 @@
   useful summary for people upgrading their application, not a replication
   of the commit log.
 
+## Unreleased
+
+* Adds taxonomy list component (PR #476)
+
 ## 9.12.1
 
 * Renames the publishing-app metatag to publishing-application, to be consistent with rendering-application (PR #475)

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    govuk_publishing_components (9.12.0)
+    govuk_publishing_components (9.12.1)
       govspeak (>= 5.0.3)
       govuk_app_config
       govuk_frontend_toolkit

app/assets/stylesheets/govuk_publishing_components/_all_components.scss

@@ -40,5 +40,6 @@
 @import "components/subscription-links";
 @import "components/success-alert";
 @import "components/taxonomy-navigation";
+@import "components/taxonomy-list";
 @import "components/title";
 @import "components/translation-nav";

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

@@ -64,3 +64,7 @@
 .gem-c-document-list--top-margin {
   margin-top: $gutter-two-thirds;
 }
+
+.gem-c-document-list__multi-list {
+  width: 100%;
+}

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

@@ -0,0 +1,20 @@
+.gem-c-taxonomy-list {
+  display: flex;
+  flex-wrap: wrap;
+  margin-top: $gutter-half;
+
+  @include media(tablet) {
+    margin-right: -25px;
+  }
+}
+
+.gem-c-taxonomy-list__item {
+  list-style: none;
+
+  @include media(tablet) {
+    @include box-sizing(border-box);
+    width: 33%;
+    padding-right: $gutter-one-third;
+    vertical-align: top;
+  }
+}

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

@@ -1,5 +1,7 @@
 <%
   items ||= []
+  within_multitype_list ||= false
+  within_multitype_list_class = " gem-c-document-list__multi-list" if within_multitype_list
   margin_top_class = " gem-c-document-list--top-margin" if local_assigns[:margin_top]
   margin_bottom_class = " gem-c-document-list--bottom-margin" if local_assigns[:margin_bottom]
   title_with_context_class = " gem-c-document-list__item-title--context"
@@ -8,9 +10,11 @@
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
 %>
 <% if items.any? %>
-  <ol class="gem-c-document-list<%= margin_bottom_class %><%= margin_top_class %> <%= brand_helper.brand_class %>">
+  <% unless within_multitype_list %>
+    <ol class="gem-c-document-list<%= margin_bottom_class %><%= margin_top_class %> <%= brand_helper.brand_class %>">
+  <% end %>
     <% items.each do |item| %>
-      <li class="gem-c-document-list__item">
+      <li class="gem-c-document-list__item<%= within_multitype_list_class %>">
         <%=
           link_to(
             item[:link][:text],
@@ -45,5 +49,7 @@
         <% end %>
       </li>
     <% end %>
-  </ol>
+  <% unless within_multitype_list %>
+    </ol>
+  <% end %>
 <% end %>

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

@@ -1,11 +1,14 @@
 <%
   items ||= []
   inverse ||= false
+  within_multitype_list ||= false
   inverse_class = "gem-c-highlight-boxes--inverse" if inverse
   highlight_boxes_helper = GovukPublishingComponents::Presenters::HighlightBoxesHelper.new(local_assigns)
 %>
 <% if items.any? %>
-  <ol class="gem-c-highlight-boxes" <%= "data-module=track-click" if highlight_boxes_helper.data_tracking? %>>
+  <% unless within_multitype_list %>
+    <ol class="gem-c-highlight-boxes" <%= "data-module=track-click" if highlight_boxes_helper.data_tracking? %>>
+  <% end %>
     <% items.each do |content_item| %>
       <li class="gem-c-highlight-boxes__item-wrapper">
         <div class="gem-c-highlight-boxes__item <%= inverse_class %>">
@@ -35,5 +38,7 @@
         </div>
       </li>
     <% end %>
-  </ol>
+  <% unless within_multitype_list %>
+    </ol>
+  <% end %>
 <% end %>

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

@@ -0,0 +1,30 @@
+<%
+  highlight_box ||= false
+  document_list ||= false
+  image_cards ||= false
+
+  highlight_box.merge!({within_multitype_list: true}) if highlight_box
+  document_list.merge!({within_multitype_list: true}) if document_list
+
+  taxonomy_list_helper = GovukPublishingComponents::Presenters::TaxonomyListHelper.new(image_cards)
+%>
+
+<% if highlight_box || document_list || image_cards %>
+  <ul class="gem-c-taxonomy-list" data-module="track-click">
+    <% if image_cards %>
+      <% taxonomy_list_helper.image_card_data.each do |image_card| %>
+        <li class="gem-c-taxonomy-list__item">
+          <%= render "govuk_publishing_components/components/image_card", image_card %>
+        </li>
+      <% end %>
+    <% end %>
+
+    <% if highlight_box %>
+      <%= render "govuk_publishing_components/components/highlight_boxes", highlight_box %>
+    <% end %>
+
+    <% if document_list %>
+      <%= render "govuk_publishing_components/components/document_list", document_list %>
+    <% end %>
+  </ul>
+<% end %>

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

@@ -0,0 +1,93 @@
+name: Taxonomy List
+description: Wraps the highlight box, document list and image card components in one list. This is commonly used on topic pages for links to tagged content.
+body: |
+  The [highlight box](/component-guide/highlight_boxes), [document list](/component-guide/document_list) and [image card](/component-guide/image_card) components are standalone components.
+
+  However, there are some use cases where we want to use both components to render one list of links. This is not possible when using the two components separately.
+  This component wraps these two components in one list, and applies relevant styling to get them to display appropriately together.
+accessibility_criteria: |
+  The taxonomy list should:
+
+  - Wrap all links in one list
+  - Should not be used to display links that don't belong together in one list
+shared_accessibility_criteria:
+  - link
+examples:
+  default:
+    data:
+      highlight_box:
+        inverse: true
+        items:
+        - link:
+            text: If your child is taken into care
+            path: /child-into-care
+            description: Information on what to do if your child is taken into care
+          metadata:
+            document_type: Detailed guide
+        - link:
+            text: High needs funding
+            path: /high-needs-funding
+          metadata:
+            document_type: Guide
+            public_updated_at: 2016-06-27 10:29:44
+      document_list:
+        items:
+        - link:
+            text: If your child is taken into care
+            path: /child-into-care
+          metadata:
+            document_type: Detailed guide
+        - link:
+            text: High needs funding
+            path: /high-needs-funding
+          metadata:
+            document_type: Guide
+  with_image_cards:
+    data:
+      image_cards:
+        items:
+        - link:
+            path: /not-a-page
+            text: News headline
+            heading_level: 0
+          image:
+            url: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG
+            alt: some meaningful alt text please
+            context: The Rt Hon
+        - link:
+            path: /not-a-page
+            text: News headline
+            heading_level: 0
+          image:
+            url: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG
+            alt: some meaningful alt text please
+            context: The Rt Hon
+        - link:
+            path: /not-a-page
+            text: News headline
+            heading_level: 0
+          image:
+            url: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG
+            alt: some meaningful alt text please
+            context: The Rt Hon
+        - link:
+            path: /not-a-page
+            text: News headline
+            heading_level: 0
+          image:
+            url: https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG
+            alt: some meaningful alt text please
+            context: The Rt Hon
+      document_list:
+        items:
+        - link:
+            text: If your child is taken into care
+            path: /child-into-care
+            description: What happens if your child is taken into care
+          metadata:
+            document_type: Detailed guide
+        - link:
+            text: High needs funding
+            path: /high-needs-funding
+          metadata:
+            document_type: Guide

lib/govuk_publishing_components.rb

@@ -22,6 +22,7 @@
 require "govuk_publishing_components/presenters/image_card_helper"
 require "govuk_publishing_components/presenters/organisation_logo_helper"
 require "govuk_publishing_components/presenters/highlight_boxes_helper"
+require "govuk_publishing_components/presenters/taxonomy_list_helper"
 
 require "govuk_publishing_components/app_helpers/taxon_breadcrumbs"
 require "govuk_publishing_components/app_helpers/brand_helper"

lib/govuk_publishing_components/presenters/taxonomy_list_helper.rb

@@ -0,0 +1,23 @@
+module GovukPublishingComponents
+  module Presenters
+    class TaxonomyListHelper
+      def initialize(image_cards)
+        @image_cards = image_cards
+      end
+
+      def image_card_data
+        @image_cards[:items].map do |image_card|
+          {
+            context: image_card[:image][:context],
+            href: image_card[:link][:path],
+            heading_text: image_card[:link][:text],
+            image_src: image_card[:image][:url],
+            image_alt: image_card[:image][:alt],
+            heading_level: image_card[:link][:heading_level],
+            href_data_attributes: (image_card[:link][:data_attributes] if image_card[:link][:data_attributes])
+          }
+        end
+      end
+    end
+  end
+end

spec/components/taxonomy_list_spec.rb

@@ -0,0 +1,123 @@
+require "rails_helper"
+
+describe "TaxonomyList", type: :view do
+  def component_name
+    "taxonomy_list"
+  end
+
+  it "renders nothing if no parameters are passed in" do
+    assert_empty render_component({})
+  end
+
+  it "renders highlight box links" do
+    render_component(
+      highlight_box: {
+        items: [
+          link: {
+            text: "Education, Skills and Training",
+            path: "/education",
+            description: "Everything about Education"
+          },
+          metadata: {
+            document_type: "Taxon"
+          }
+        ]
+      }
+    )
+
+    assert_select ".gem-c-taxonomy-list .gem-c-highlight-boxes__title[href='/education']", text: "Education, Skills and Training"
+    assert_select ".gem-c-taxonomy-list .gem-c-highlight-boxes__description", text: "Everything about Education"
+    assert_select ".gem-c-taxonomy-list .gem-c-highlight-boxes__metadata", text: "Taxon"
+  end
+
+  it "renders document list links" do
+    render_component(
+      document_list: {
+        items: [
+          link: {
+            text: "Student Finance",
+            path: "/student-finance",
+            description: "How to apply for student finance"
+          },
+          metadata: {
+            document_type: "Guide"
+          }
+        ]
+      }
+    )
+
+    assert_select ".gem-c-taxonomy-list .gem-c-document-list__item-title[href='/student-finance']", text: "Student Finance"
+    assert_select ".gem-c-taxonomy-list .gem-c-document-list__item-description", text: "How to apply for student finance"
+    assert_select ".gem-c-taxonomy-list .gem-c-document-list__attribute", text: "Guide"
+  end
+
+  it "renders image card links" do
+    render_component(
+      image_cards: {
+        items: [
+          {
+            link: {
+              path: "/apprenticeships",
+              text: "Apprenticeships",
+              heading_level: 0
+            },
+            image: {
+              url: "/path/to/image",
+              alt: "Apprentices working",
+            }
+          }
+        ]
+      }
+    )
+
+    assert_select ".gem-c-taxonomy-list .gem-c-image-card__title-link[href='/apprenticeships']", text: "Apprenticeships"
+    assert_select ".gem-c-taxonomy-list .gem-c-image-card__image[alt='Apprentices working']"
+    assert_select ".gem-c-taxonomy-list .gem-c-image-card__image[src='/path/to/image']"
+  end
+
+  it "renders all links within one list only" do
+    render_component(
+      document_list: {
+        items: [
+          link: {
+            text: "Student Finance",
+            path: "/student-finance",
+            description: "How to apply for student finance"
+          },
+          metadata: {
+            document_type: "Guide"
+          }
+        ]
+      },
+      highlight_box: {
+        items: [
+          link: {
+            text: "Education, Skills and Training",
+            path: "/education",
+            description: "Everything about Education"
+          },
+          metadata: {
+            document_type: "Taxon"
+          }
+        ]
+      },
+      image_cards: {
+        items: [
+          {
+            link: {
+              path: "/apprenticeships",
+              text: "Apprenticeships",
+              heading_level: 0
+            },
+            image: {
+              url: "/path/to/image",
+              alt: "Apprentices working",
+            }
+          }
+        ]
+      }
+    )
+
+    assert_select "ul.gem-c-taxonomy-list", count: 1
+  end
+end