Add step by step navigation component (#81)

simonwhatley · Jun 9, 2020 · 78668ad · 78668ad
1 parent 4a1991c
commit 78668ad
Show file tree

Hide file tree

Showing 9 changed files with 1,284 additions and 0 deletions.
diff --git a/app/views/components/step-by-step-navigation/index.html b/app/views/components/step-by-step-navigation/index.html
@@ -0,0 +1,240 @@
+{% extends "layouts/base.html" %}
+
+{% block pageTitle %}
+  Step by step navigation component – GOV.UK Publishing Frontend
+{% endblock %}
+
+{% block pageScripts %}
+<script src="/public/javascripts/components/step-by-step-navigation/step-by-step-navigation.js"></script>
+<script type="text/javascript">
+  var $element1 = $('#step-by-step-navigation-1');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element1);
+
+  var $element2 = $('#step-by-step-navigation-2');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element2);
+
+  var $element3 = $('#step-by-step-navigation-3');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element3);
+
+  var $element4 = $('#step-by-step-navigation-4');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element4);
+
+  var $element5 = $('#step-by-step-navigation-5');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element5);
+</script>
+{% endblock %}
+
+{% block beforeContent %}
+{{ govukBackLink({
+  text: "Back",
+  href: "../"
+}) }}
+{% endblock %}
+
+{% block content %}
+
+<div class="govuk-grid-row">
+  <div class="govuk-grid-column-two-thirds">
+    <h1 class="govuk-heading-xl">
+      <span class="govuk-caption-xl">Components</span>
+      Step by step navigation
+    </h1>
+
+    <p class="govuk-body-1">A series of expanding/collapsing steps designed to navigate a user through a process.</p>
+
+    <p class="govuk-body"><a class="govuk-link" href="https://live-stuff.herokuapp.com/document-types/step-by-step-nav">View a list of live step by steps</a></p>
+
+    <p class="govuk-body"><a class="govuk-link" href="https://components.publishing.service.gov.uk/component-guide/step_by_step_nav">GOV.UK component guide</a></p>
+
+    <p class="govuk-body"><a class="govuk-link" href="https://github.com/simonwhatley/govuk-publishing-frontend/tree/master/src/govuk-pub/components/step-by-step-navigation">View the Nunjucks macro options on GitHub</a></p>
+
+    <h2 class="govuk-heading-l">Examples</h2>
+
+    <h3 class="govuk-heading-m">Example 1</h3>
+
+    {{ govukPubStepByStepNavigation({
+      id: 'step-by-step-navigation-1',
+      steps: [{
+        heading: {
+          text: 'Step 1'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        },
+        {
+          text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+        }]
+      },
+      {
+        heading: {
+          text: 'Step 2'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }],
+        logic: 'and'
+      },
+      {
+        heading: {
+          text: 'Step 3'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      }]
+    }) }}
+
+    <h3 class="govuk-heading-m govuk-!-margin-top-9">Example 2</h3>
+
+    <p class="govuk-body">With an optional step</p>
+
+    {{ govukPubStepByStepNavigation({
+      id: 'step-by-step-navigation-2',
+      steps: [{
+        heading: {
+          text: 'Step 1'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        },
+        {
+          text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+        }]
+      },
+      {
+        heading: {
+          text: 'Step 2'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }],
+        logic: 'or'
+      },
+      {
+        heading: {
+          text: 'Step 3'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      }]
+    }) }}
+
+    <h3 class="govuk-heading-m govuk-!-margin-top-9">Example 3</h3>
+
+    <p class="govuk-body">With a step open by default</p>
+
+    {{ govukPubStepByStepNavigation({
+      id: 'step-by-step-navigation-3',
+      steps: [{
+        heading: {
+          text: 'Step 1 (Open by default)'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        },
+        {
+          text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+        }],
+        expanded: true
+      },
+      {
+        heading: {
+          text: 'Step 2'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      },
+      {
+        heading: {
+          text: 'Step 3'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      }]
+    }) }}
+
+    <h3 class="govuk-heading-m govuk-!-margin-top-9">Example 4</h3>
+
+    <p class="govuk-body">With an active step</p>
+
+    {{ govukPubStepByStepNavigation({
+      id: 'step-by-step-navigation-4',
+      steps: [{
+        heading: {
+          text: 'Step 1'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        },
+        {
+          text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+        }],
+        active: true
+      },
+      {
+        heading: {
+          text: 'Step 2'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }],
+        logic: 'or'
+      },
+      {
+        heading: {
+          text: 'Step 3'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      }]
+    }) }}
+
+    <h3 class="govuk-heading-m govuk-!-margin-top-9">Example 5</h3>
+
+    <p class="govuk-body">Small step by step for use in a sidebar</p>
+
+    {{ govukPubStepByStepNavigation({
+      id: 'step-by-step-navigation-5',
+      small: true,
+      steps: [{
+        heading: {
+          text: 'Step 1'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        },
+        {
+          text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+        }]
+      },
+      {
+        heading: {
+          text: 'Step 2'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      },
+      {
+        heading: {
+          text: 'Step 3'
+        },
+        contents: [{
+          text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+        }]
+      }]
+    }) }}
+
+  </div>
+</div>
+
+{% endblock %}
diff --git a/app/views/index.html b/app/views/index.html
@@ -23,6 +23,7 @@ <h2 class="govuk-heading-m">Components</h2>
       <li><a href="./components/print-link">Print link</a></li>
       <li><a href="./components/related-navigation">Related navigation</a></li>
       <li><a href="./components/share-links">Share links</a></li>
+      <li><a href="./components/step-by-step-navigation">Step by step navigation</a></li>
       <li><a href="./components/subscription-links">Subscription links</a></li>
     </ul>
 

diff --git a/app/views/layouts/base.html b/app/views/layouts/base.html
@@ -33,6 +33,7 @@
 {%- from "govuk-pub/components/print-link/macro.njk" import govukPubPrintLink %}
 {%- from "govuk-pub/components/related-navigation/macro.njk" import govukPubRelatedNavigation %}
 {%- from "govuk-pub/components/share-links/macro.njk" import govukPubShareLinks %}
+{%- from "govuk-pub/components/step-by-step-navigation/macro.njk" import govukPubStepByStepNavigation %}
 {%- from "govuk-pub/components/subscription-links/macro.njk" import govukPubSubscriptionLinks %}
 
 <!DOCTYPE html>

diff --git a/src/govuk-pub/components/_all.scss b/src/govuk-pub/components/_all.scss
@@ -8,4 +8,5 @@
 @import "print-link/print-link";
 @import "related-navigation/related-navigation";
 @import "share-links/share-links";
+@import "step-by-step-navigation/step-by-step-navigation";
 @import "subscription-links/subscription-links";
diff --git a/src/govuk-pub/components/step-by-step-navigation/README.md b/src/govuk-pub/components/step-by-step-navigation/README.md
@@ -0,0 +1,135 @@
+# Step by step navigation
+
+Displays a series of expanding/collapsing steps designed to navigate a user through a process.
+
+Step by step navigation shows a sequence of steps towards a specific goal, such as ‘learning to drive’. Each step can contain one or more links to pages. User research suggested that each step should be collapsed by default so that users are not overwhelmed with information.
+
+If JavaScript is disabled the step by step navigation expands fully. All of the functionality (including the icons and aria attributes) are added using JavaScript.
+
+This component is based on the accordion component in collections.
+
+[Preview the component](https://govuk-publishing-frontend.herokuapp.com/components/step-by-step-navigation/)
+
+[View a list of live step by steps](https://live-stuff.herokuapp.com/document-types/step-by-step-nav)
+
+## Example usage
+
+**Macro**
+```
+{{ govukPubStepByStepNavigation({
+  id: 'step-by-step-navigation',
+  steps: [{
+    heading: {
+      text: 'Step 1'
+    },
+    contents: [{
+      text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+    },
+    {
+      text: 'Vivamus nec pharetra ipsum. Duis euismod augue nisl, sit amet dictum velit malesuada at.'
+    }],
+    active: true
+  },
+  {
+    heading: {
+      text: 'Step 2'
+    },
+    contents: [{
+      text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+    }],
+    logic: 'and'
+  },
+  {
+    heading: {
+      text: 'Step 3'
+    },
+    contents: [{
+      text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
+    }]
+  }]
+}) }}
+```
+
+**JavaScript**
+```html
+<script src="/public/javascripts/step-by-step-navigation.js"></script>
+<script type="text/javascript">
+  var $element = $('#step-by-step-navigation');
+  var stepByStepNavigation = new GOVUK.Modules.StepByStepNavigation();
+  stepByStepNavigation.start($element);
+</script>
+```
+
+## Accessibility acceptance criteria
+
+The step by step navigation must:
+
+- indicate to users that each step can be expanded and collapsed
+- inform the user when a step has been expanded or collapsed
+- be usable with a keyboard
+- allow users to show or hide all steps at once
+- inform the user which step a link belongs to
+- inform the user which step the current page is in
+- be readable when only the text of the page is zoomed - achieved for the numbers and logic elements by their text being wrapped in several elements that give them a white background and ensure the text when zoomed expands to the left, not to the right, where it would obscure the step titles
+
+The show/hide all button only needs to list the first panel id in the aria-controls attribute, rather than all of them.
+
+Step headings must use a button element:
+
+- so that steps can be toggled with the space and enter keys
+- so that steps can’t be opened in a new tab or window
+
+When JavaScript is unavailable the component must:
+
+- be fully expanded
+- not be marked as expandable
+
+Links in the component must:
+
+- accept focus
+- be focusable with a keyboard
+- be usable with a keyboard
+- indicate when they have focus
+- change in appearance when touched (in the touch-down state)
+- change in appearance when hovered
+- be usable with touch
+- be usable with [voice commands](https://www.w3.org/WAI/perspectives/voice.html)
+- have visible text
+
+## Arguments
+
+This component accepts the following arguments.
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|id|string|No||
+|steps|array|Yes||
+|small|boolean|No||
+|attributes|object|No|HTML attributes (for example data attributes) to add to the container.|
+
+### Steps
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|heading|object|Yes||
+|contents|array|Yes||
+|active|boolean|No||
+|logic|string|No||
+
+#### Heading
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|text|string|Yes|If `html` is set, this is not required. Text to use within the heading. If `html` is provided, the `text` argument will be ignored.|
+|html|string|Yes|If `text` is set, this is not required. HTML to use within the heading. If `html` is provided, the `text` argument will be ignored.|
+|headingLevel|numeric|No|A number for the heading level. Defaults to 2 (`<h2>`)|
+
+#### Content
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|text|string|Yes|If `html` is set, this is not required. Text to use within the content. If `html` is provided, the `text` argument will be ignored.|
+|html|string|Yes|If `text` is set, this is not required. HTML to use within the content. If `html` is provided, the `text` argument will be ignored.|
+
+
+*Warning: If you’re using Nunjucks macros in production be aware that using HTML arguments, or ones ending with `.html` can be at risk from [cross-site scripting](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks. More information about security vulnerabilities can be found in the [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#user-defined-templates-warning).*