Merge pull request #70 from ministryofjustice/component-side-navigation

Add side navigation component

app/views/components/README.md

@@ -10,6 +10,8 @@
 - [Header](/header)
 - [Identity bar](/identity-bar)
 - [Menu](/menu)
+- [Messages](/messages)
+- [Multi file upload](/multi-file-upload)
 - [Multi select](/multi-select)
 - [Notification badge](/notification-badge)
 - [Organisation switcher](/organisation-switcher)
@@ -20,6 +22,7 @@
 - [Progress bar](/progress-bar)
 - [Rich text editor](/rich-text-editor)
 - [Search](/search)
+- [Side navigation](/side-navigation)
 - [Sortable table](/sortable-table)
 - [Sub navigation](/sub-navigation)
 - [Tag](/tag)

app/views/components/side-navigation/index.html

@@ -0,0 +1,78 @@
+{% extends "layouts/base.html" %}
+
+{% block body %}
+
+  <div class="govuk-grid-row">
+
+    <div class="govuk-grid-column-one-half">
+
+      {{ govukBackLink({
+        text: "Back",
+        href: "../"
+      }) }}
+
+      <h1 class="govuk-heading-xl">
+        <span class="govuk-caption-xl">Components</span> Side navigation
+      </h1>
+
+      <h2 class="govuk-heading-m">Example 1</h2>
+
+      {{ mojSideNavigation({
+        label: 'Side navigation',
+        items: [{
+          text: 'Nav item 1',
+          href: '#1',
+          active: true
+        }, {
+          text: 'Nav item 2',
+          href: '#2'
+        }, {
+          text: 'Nav item 3',
+          href: '#3'
+        }]
+      }) }}
+
+      <h2 class="govuk-heading-m govuk-!-margin-top-9">Example 2</h2>
+
+      {{ mojSideNavigation({
+        label: 'Side navigation',
+        sections: [
+          {
+            heading: {
+              text: 'Section 1'
+            },
+            items: [{
+              text: 'Nav item 1.1',
+              href: '#1.1',
+              active: true
+            }, {
+              text: 'Nav item 1.2',
+              href: '#1.2'
+            }, {
+              text: 'Nav item 1.3',
+              href: '#1.3'
+            }]
+          },
+          {
+            heading: {
+              text: 'Section 2'
+            },
+            items: [{
+              text: 'Nav item 2.1',
+              href: '#2.1'
+            }, {
+              text: 'Nav item 2.2',
+              href: '#2.2'
+            }, {
+              text: 'Nav item 2.3',
+              href: '#2.3'
+            }]
+          }
+        ]
+      }) }}
+
+    </div>
+
+  </div>
+
+{% endblock %}

app/views/index.html

@@ -25,6 +25,7 @@ <h1 class="govuk-heading-l">MOJ Frontend</h1>
     <li><a href="/components/progress-bar">Progress bar</a></li>
     <li><a href="/components/rich-text-editor">Rich text editor</a></li>
     <li><a href="/components/search">Search</a></li>
+    <li><a href="/components/side-navigation">Side navigation</a></li>
     <li><a href="/components/sortable-table">Sortable table</a></li>
     <li><a href="/components/sub-navigation">Sub-navigation</a></li>
     <li><a href="/components/tag">Tag</a></li>

app/views/layouts/base.html

@@ -36,6 +36,7 @@
 {%- from "moj/components/primary-navigation/macro.njk" import mojPrimaryNavigation %}
 {%- from "moj/components/progress-bar/macro.njk" import mojProgressBar %}
 {%- from "moj/components/search/macro.njk" import mojSearch %}
+{%- from "moj/components/side-navigation/macro.njk" import mojSideNavigation %}
 {%- from "moj/components/sub-navigation/macro.njk" import mojSubNavigation %}
 {%- from "moj/components/timeline/macro.njk" import mojTimeline %}
 {%- from "moj/components/page-header-actions/macro.njk" import mojPageHeaderActions %}

src/moj/components/_all.scss

@@ -1,3 +1,4 @@
+@import "action-bar/action-bar";
 @import "add-another/add-another";
 @import "badge/badge";
 @import "banner/banner";
@@ -11,16 +12,16 @@
 @import "multi-select/multi-select";
 @import "notification-badge/notification-badge";
 @import "organisation-switcher/organisation-switcher";
+@import "page-header-actions/page-header-actions";
 @import "pagination/pagination";
 @import "password-reveal/password-reveal";
 @import "primary-navigation/primary-navigation";
 @import "progress-bar/progress-bar";
 @import "rich-text-editor/rich-text-editor";
-@import "timeline/timeline";
-@import "search/search";
 @import "search-toggle/search-toggle";
+@import "search/search";
+@import "side-navigation/side-navigation";
 @import "sortable-table/sortable-table";
 @import "sub-navigation/sub-navigation";
 @import "tag/tag";
-@import "page-header-actions/page-header-actions";
-@import "action-bar/action-bar";
+@import "timeline/timeline";

src/moj/components/side-navigation/README.md

@@ -0,0 +1,67 @@
+# Side navigation
+
+- [Guidance](https://moj-design-system.herokuapp.com/components/side-navigation)
+- [Preview](https://moj-frontend.herokuapp.com/components/side-navigation)
+
+## Example
+
+```
+{{ mojSideNavigation({
+  label: 'Side navigation',
+  items: [{
+    text: 'Nav item 1',
+    href: '#1',
+    active: true
+  }, {
+    text: 'Nav item 2',
+    href: '#2'
+  }, {
+    text: 'Nav item 3',
+    href: '#3'
+  }]
+}) }}
+```
+
+## Arguments
+
+This component accepts the following arguments.
+
+### Container
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|label|string|No|The `aria-label` to add to the navigation container.|
+|items|array|Yes|An array of navigation item objects. See [items](#items).|
+|sections|array|No|An array of navigation section objects. See [sections](#sections).|
+|classes|string|No|Classes to add to the `nav` container.|
+|attributes|object|No|HTML attributes (for example data attributes) to add to the `nav` container.|
+
+### Sections
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|items|array|Yes|An array of navigation item objects. See [items](#items).|
+|heading|object|Yes|See [heading](#headings)|
+
+#### Headings
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|headingLevel|numeric|No|A number for the heading level. Defaults to 4 (`<h4>`)|
+|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.|
+|classes|string|No|Classes to add to the heading.|
+|attributes|object|No|HTML attributes (for example data attributes) to add to the navigation item anchor.|
+
+### Items
+
+|Name|Type|Required|Description|
+|---|---|---|---|
+|href|string|Yes|URL of the navigation item anchor. Both href and text attributes for navigation items need to be provided to create an item.|
+|text|string|Yes|If `html` is set, this is not required. Text to use within the anchor. 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 anchor. If `html` is provided, the `text` argument will be ignored.|
+|active|boolean|No|Flag to mark the navigation item as active or not. Defaults to `false`.|
+|attributes|object|No|HTML attributes (for example data attributes) to add to the navigation item anchor.|
+
+
+*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).*

src/moj/components/side-navigation/_side-navigation.scss

@@ -0,0 +1,125 @@
+/* ==========================================================================
+   #SIDE NAVIGATION
+   ========================================================================== */
+
+.moj-side-navigation {
+  @include govuk-font(16);
+
+  @include govuk-media-query($until: tablet) {
+    display: flex;
+    overflow-x: scroll;
+  }
+
+  @include govuk-media-query($from: tablet) {
+    display: block;
+    padding: govuk-spacing(4) 0 0;
+  }
+
+}
+
+.moj-side-navigation__title {
+  @include govuk-font($size: 19);
+  color: govuk-colour("dark-grey");
+  font-weight: normal;
+  margin: 0;
+  padding: govuk-spacing(2);
+  padding-left: govuk-spacing(2) + 4px;
+
+  @include govuk-media-query($until: tablet) {
+    display: none;
+  }
+
+}
+
+.moj-side-navigation__list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+
+  @include govuk-media-query($until: tablet) {
+    display: flex;
+    margin: 0;
+    white-space: nowrap;
+  }
+
+  @include govuk-media-query($from: tablet) {
+    margin-bottom: govuk-spacing(4);
+  }
+}
+
+.moj-side-navigation__item {
+
+  @include govuk-media-query($until: tablet) {
+    display: flex;
+  }
+
+  a,
+  a:link,
+  a:visited {
+    background-color: inherit;
+    color: govuk-colour("blue");
+    display: block;
+    text-decoration: none;
+
+    @include govuk-media-query($until: tablet) {
+      border-bottom: 4px solid transparent;
+      padding: govuk-spacing(3);
+      padding-bottom: govuk-spacing(3) - 4px; // Compensate for 4px border
+    }
+
+    @include govuk-media-query($from: tablet) {
+      background-color: inherit;
+      border-left: 4px solid transparent;
+      padding: govuk-spacing(2);
+    }
+
+
+  }
+
+  a:hover {
+    border-color: govuk-colour("light-blue");
+  }
+
+  a:focus {
+    color: $govuk-focus-text-colour;
+    background-color: $govuk-focus-colour;
+    box-shadow: 0 -2px $govuk-focus-colour, 0 4px $govuk-focus-text-colour;
+    border-color: $govuk-focus-text-colour;
+    border-left-color: transparent;
+    position: relative;
+  }
+
+}
+
+.moj-side-navigation__item--active {
+
+  a:link,
+  a:visited {
+    border-color: govuk-colour("blue");
+    color: govuk-colour("blue");
+    font-weight: bold;
+  }
+
+  a:focus {
+    color: $govuk-focus-text-colour;
+    background-color: $govuk-focus-colour;
+    box-shadow: 0 -2px $govuk-focus-colour, 0 4px $govuk-focus-text-colour;
+    border-color: $govuk-focus-text-colour;
+    border-left-color: transparent;
+  }
+
+  @include govuk-media-query($from: tablet) {
+    a:link,
+    a:visited {
+      background-color: govuk-colour("light-grey");
+    }
+
+    a:focus {
+      color: $govuk-focus-text-colour;
+      background-color: $govuk-focus-colour;
+      border-color: transparent;
+    }
+  }
+
+
+}

src/moj/components/side-navigation/macro.njk

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

src/moj/components/side-navigation/template.njk

@@ -0,0 +1,28 @@
+<nav class="moj-side-navigation {{- ' ' + params.classes if params.classes }}" {%- if (params.label) %} aria-label="{{ params.label }}"{% endif %} {% for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  {%- if params.sections %}
+    {%- for section in params.sections %}
+      <h{{ section.heading.headingLevel | default(4) }} class="moj-side-navigation__title {{- ' ' + section.heading.classes if section.heading.classes }}"{% for attribute, value in section.heading.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+        {{- section.heading.html | safe if section.heading.html else section.heading.text -}}
+      </h{{ section.heading.headingLevel | default(4) }}>
+      <ul class="moj-side-navigation__list">
+        {%- for item in section.items %}
+          <li class="moj-side-navigation__item{% if item.active %} moj-side-navigation__item--active{% endif %}"{% for attribute, value in item.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+            <a href="{{ item.href }}"{% if item.active %} aria-current="location"{% endif %}>
+              {{- item.html | safe if item.html else item.text -}}
+            </a>
+          </li>
+        {% endfor -%}
+      </ul>
+    {% endfor -%}
+  {% else %}
+    <ul class="moj-side-navigation__list">
+      {%- for item in params.items %}
+        <li class="moj-side-navigation__item{% if item.active %} moj-side-navigation__item--active{% endif %}"{% for attribute, value in item.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+          <a href="{{ item.href }}"{% if item.active %} aria-current="location"{% endif %}>
+            {{- item.html | safe if item.html else item.text -}}
+          </a>
+        </li>
+      {% endfor -%}
+    </ul>
+  {% endif -%}
+</nav>