Add secondary navigation

docs/_components/example/template.njk

@@ -8,6 +8,9 @@
 {%- endset -%}
 
 {%- set examplePath = "/examples/" + params.component -%}
+{% if params.example %}
+  {%- set examplePath = examplePath + "-" + params.example -%}
+{% endif %}
 
 {%- set previewHtml -%}
 <iframe class="app-example__frame" data-module="app-example-frame" src="{{ examplePath | url }}"></iframe>

docs/examples/secondary-navigation-with-header.njk

@@ -0,0 +1,28 @@
+---
+eleventyExcludeFromCollections: true
+layout: example.njk
+title: Secondary navigation with header
+---
+{% from "x-govuk/components/secondary-navigation/macro.njk" import xGovukSecondaryNavigation %}
+
+<span class="govuk-caption-l">Case #161351</span>
+<h1 class="govuk-heading-l">James Smith</h1>
+
+{{ xGovukSecondaryNavigation({
+  items: [{
+    text: "Overview",
+    href: "#"
+  }, {
+    text: "Contact details",
+    href: "#",
+    current: true
+  }, {
+    text: "Claims",
+    href: "#"
+  }, {
+    text: "Audit log",
+    href: "#"
+  }]
+}) }}
+
+<h2 class="govuk-heading-m">Contact details</h2>

docs/examples/secondary-navigation.njk

@@ -0,0 +1,23 @@
+---
+eleventyExcludeFromCollections: true
+layout: example.njk
+title: Secondary navigation
+---
+{% from "x-govuk/components/secondary-navigation/macro.njk" import xGovukSecondaryNavigation %}
+
+{{ xGovukSecondaryNavigation({
+  items: [{
+    text: "Overview",
+    href: "#",
+    current: true
+  }, {
+    text: "Staff list",
+    href: "#"
+  }, {
+    text: "Projects",
+    href: "#"
+  }, {
+    text: "Settings",
+    href: "#"
+  }]
+}) }}

docs/secondary-navigation.md

@@ -0,0 +1,52 @@
+---
+layout: sub-navigation
+order: 5
+title: Secondary navigation
+description: Allow users to navigate between pages scoped to a section.
+---
+
+{% from "example/macro.njk" import appExample %}
+
+{{ appExample({
+  component: "secondary-navigation"
+}) }}
+
+## When to use this component
+
+Use the secondary navigation when you already have a [primary navigation](primary-navigation) and need to let users navigate between pages that are scoped to a particular section or concept.
+
+For example, if your service is a case management system, you might use the secondary navigation if there are multiple pages associated with a single case.
+
+{{ appExample({
+  component: "secondary-navigation",
+  example: "with-header"
+}) }}
+
+## When not to use this component
+
+Do not use this component for the primary sections of your service, or if a [sub-navigation](sub-navigation) would be more appropriate.
+
+You could also consider using the [tabs component](https://design-system.service.gov.uk/components/tabs/) if the amount of content in each sub-section is small.
+
+## Component options
+
+Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
+
+Some options are required for the macro to work; these are marked as “Required” in the option description.
+
+If you’re using Nunjucks macros in production with `html` options, or ones ending with `html`, you must sanitise the HTML to protect against [cross-site scripting exploits](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting).
+
+| Name           | Type   | Description                                                                                                  |
+| :------------- | :----- | :----------------------------------------------------------------------------------------------------------- |
+| **items**      | array  | **Required**. An array of navigation links within the secondary navigation. See [items](#options-for-items). |
+| **classes**    | string | Classes to add to the primary navigation container.                                                          |
+| **attributes** | object | HTML attributes (for example data attributes) to add to the primary navigation container.                    |
+
+### Options for items
+
+| Name        | Type    | Description                                                        |
+| :---------- | :------ | :----------------------------------------------------------------- |
+| **text**    | string  | **Required**. Text of the navigation link.                         |
+| **href**    | array   | **Required**. The value of the navigation link’s `href` attribute. |
+| **current** | boolean | Indicate that the item is the current page.                        |
+| **classes** | string  | Classes to add to the navigation item.                             |

eleventy.config.js

@@ -71,6 +71,7 @@ module.exports = function (eleventyConfig) {
         'docs/autocomplete.md',
         'docs/masthead.md',
         'docs/primary-navigation.md',
+        'docs/secondary-navigation.md',
         'docs/sub-navigation.md',
         'docs/related-navigation.md',
         'docs/data-attributes.md'

x-govuk/components/_all.scss

@@ -2,4 +2,5 @@
 @import "masthead/masthead";
 @import "primary-navigation/primary-navigation";
 @import "related-navigation/related-navigation";
+@import "secondary-navigation/secondary-navigation";
 @import "sub-navigation/sub-navigation";

x-govuk/components/secondary-navigation/_secondary-navigation.scss

@@ -0,0 +1,106 @@
+.x-govuk-secondary-navigation {
+  @include govuk-font(19);
+
+  @include govuk-media-query($from: tablet) {
+    display: flex;
+    overflow-x: auto;
+    padding-top: govuk-spacing(2);
+    padding-bottom: govuk-spacing(7);
+  }
+
+  @include govuk-media-query($until: tablet) {
+    display: block;
+  }
+}
+
+.x-govuk-secondary-navigation__list {
+  width: 100%;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+
+  @include govuk-media-query($from: tablet) {
+    display: flex;
+    margin: 0;
+    white-space: nowrap;
+
+    box-shadow: inset 0 -1px 0 $govuk-border-colour;
+  }
+
+  @include govuk-media-query($until: tablet) {
+    margin-bottom: govuk-spacing(4);
+  }
+}
+
+.x-govuk-secondary-navigation__list-item {
+  @include govuk-media-query($from: tablet) {
+    display: flex;
+
+    & + & {
+      margin-left: govuk-spacing(4);
+    }
+  }
+
+  a,
+  a:link,
+  a:visited {
+    background-color: inherit;
+    display: block;
+    text-decoration: none;
+
+    @include govuk-media-query($from: tablet) {
+      border-bottom: 5px solid transparent;
+      padding-bottom: govuk-spacing(3) - 5px; // Compensate for 5px border
+    }
+
+    @include govuk-media-query($until: tablet) {
+      background-color: inherit;
+      border-left: 5px solid transparent;
+      padding: govuk-spacing(2);
+    }
+  }
+
+  a:focus {
+    color: $govuk-focus-text-colour;
+    background-color: $govuk-focus-colour;
+    box-shadow:
+      0 -2px $govuk-focus-colour,
+      0 5px $govuk-focus-text-colour;
+    border-color: $govuk-focus-text-colour;
+    border-left-color: transparent;
+    position: relative;
+  }
+}
+
+.x-govuk-secondary-navigation__list-item--current {
+  a,
+  a:link,
+  a:visited {
+    border-color: $govuk-brand-colour;
+    color: $govuk-text-colour;
+  }
+
+  a:focus {
+    color: $govuk-focus-text-colour;
+    background-color: $govuk-focus-colour;
+    box-shadow:
+      0 -2px $govuk-focus-colour,
+      0 5px $govuk-focus-text-colour;
+    border-color: $govuk-focus-text-colour;
+    border-left-color: transparent;
+  }
+
+  @include govuk-media-query($until: tablet) {
+    a,
+    a:link,
+    a:visited {
+      background-color: govuk-colour("light-grey", $legacy: "grey-4");
+    }
+
+    a:focus {
+      color: $govuk-focus-text-colour;
+      background-color: $govuk-focus-colour;
+      border-color: transparent;
+    }
+  }
+}

x-govuk/components/secondary-navigation/macro.njk

@@ -0,0 +1,3 @@
+{% macro xGovukSecondaryNavigation(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}

x-govuk/components/secondary-navigation/template.njk

@@ -0,0 +1,14 @@
+<nav class="x-govuk-secondary-navigation {%- if params.classes %} {{ params.classes }}{% endif -%}" aria-label="Sub navigation" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  <ul class="x-govuk-secondary-navigation__list">
+    {% for item in params.items %}
+      <li class="x-govuk-secondary-navigation__list-item {{ "x-govuk-secondary-navigation__list-item--current" if item.current }}{% if item.classes %} {{ item.classes }}{% endif -%}">
+        <a class="govuk-link x-govuk-secondary-navigation__link govuk-link--no-visited-state" href="{{ item.href }}" {{ "aria-current=page" if item.current }}>
+          {{ item.text }}
+          {% if item.current %}
+            <span class="govuk-visually-hidden">Current page</span>
+          {% endif %}
+        </a>
+      </li>
+    {% endfor %}
+  </ul>
+</nav>