Timeline (#134)

* added temporary fix for focus of sign out link in gov.uk banner

* Added timeline component

* updated version number

* updated check-compatibility

* added leading 0

* Update src/components/timeline/_timeline.scss

Co-authored-by: Matthew Mascord <[email protected]>

* changing import

* Added info to the readme

Co-authored-by: Matthew Mascord <[email protected]>

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [1.30.0] - 2021-03-25
+
+### Added
+
+- Timeline component
+
 ## [1.29.0] - 2021-03-24
 
 ## Fixed
@@ -15,62 +21,62 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [1.28.0] - 2021-03-19
 
-## Fixed
+### Fixed
 
 - Package was missing LICENSE
 
 ## [1.27.0] - 2021-03-04
 
-## Added
+### Added
 
 - HMRC character count
 
 ## [1.26.2] - 2021-02-25
 
-## Fixed
+### Fixed
 
 - User research banner Welsh example missed url field
 
 ## [1.26.1] - 2021-02-23
 
-## Fixed
+### Fixed
 
 - Issue with node_modules reference in the hmrcUserResearchBanner,
 causing problems in frontend microservices using the hmrc-frontend webjar.
 
 ## [1.26.0] - 2021-02-19
 
-## Added
+### Added
 
 - HMRC user research banner
 
 ## [1.25.0] - 2021-02-17
 
-## Updated
+### Updated
 
 - Update govuk-frontend to v3.11.0
 
 ## [1.24.0] - 2021-02-08
 
-## Added
+### Added
 
 - Compiled assets now included in NPM package.
 - Refactored gulp pipeline
 
 ## [1.23.1] - 2020-12-11
 
-## Security
+### Security
 
 - Bumped ini to v1.3.5
 
 ## [1.23.0] - 2020-12-09
 
-## Changed
+### Changed
 
 - serviceId added for configuring contact-frontend for consistency with
 contact-frontend documentation, serviceCode deprecated
 
-## Fixed
+### Fixed
 
 - Fixed colour contrast for focused sign out link in gov.uk header not meeting accessibility standards
 
@@ -79,9 +85,9 @@ contact-frontend documentation, serviceCode deprecated
 ### Fixed
 
 - Accessibility issue with hmrcHeader when displayHmrcBanner set to true. Previously this
-component defined two top-level 'banner' landmarks failing accessibility tests. On advice from the 
+component defined two top-level 'banner' landmarks failing accessibility tests. On advice from the
 HMRC accessibility team, the HMRC banner has been moved inside HEADER so that screen-reader users read the
-banner as part of the overall header and can skip to the main content more easily. 
+banner as part of the overall header and can skip to the main content more easily.
 
 ## [1.21.0] - 2020-11-23
 

check-compatibility.js

@@ -14,8 +14,8 @@ if (!knownPrototypeKitNames.includes(consumerPackageJson.name)) {
 }
 
 const compatibility = {
-  1.29: {
-    'prototype-kit': ['9.12', '9.11', '9.10', '9.9', '9.8', '9.7', '9.6', '9.5', '9.4', '9.3', '9.2', '9.1', '9.0', '9.9', '9.10', '9.11', '9.12'],
+  1.30: {
+    'prototype-kit': ['9.12', '9.11', '9.10', '9.9', '9.8', '9.7', '9.6', '9.5', '9.4', '9.3', '9.2', '9.1', '9.0', '9.9', '9.10', '9.11'],
   },
   0.6: {
     'prototype-kit': ['8.12', '8.11', '8.10', '8.9', '8.8', '8.7'],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hmrc-frontend",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "description": "Design patterns for HMRC frontends",
   "scripts": {
     "start": "gulp dev",

src/components/_all.scss

@@ -11,3 +11,4 @@
 @import "status-tags-in-task-list-pages/status-tags-in-task-list-pages";
 @import "user-research-banner/user-research-banner";
 @import "character-count/character-count";
+@import "timeline/timeline";

src/components/timeline/README.md

@@ -0,0 +1,5 @@
+# Timeline
+This pattern helps users understand what has happened and when. For example, the history of a tax repayment claim.
+
+## License
+This code is open source software licensed under the [Apache 2.0 License]("http://www.apache.org/licenses/LICENSE-2.0.html").

src/components/timeline/_timeline.scss

@@ -0,0 +1,46 @@
+@import "../../../../govuk-frontend/govuk/core/typography";
+
+.hmrc-timeline {
+  $border-width: 5px;
+
+  border-left: $border-width solid govuk-colour("blue");
+  margin: 0;
+  margin-bottom: govuk-spacing(6);
+  padding: 0;
+
+  &__event {
+    @include govuk-responsive-padding(6, "bottom");
+
+    padding-left: govuk-spacing(4) - $border-width;
+    position: relative;
+    list-style: none;
+
+    &:last-child {
+      padding-bottom: 0;
+    }
+  }
+
+  &__event-title {
+    @include govuk-responsive-margin(1, "bottom");
+
+    @extend %govuk-heading-m;
+
+    &::before {
+      background-color: govuk-colour("blue");
+      content: "";
+      height: $border-width;
+      position: absolute;
+      left: 0;
+      top: 0.5em;
+      width: (govuk-spacing(4) * 0.6) - $border-width;
+    }
+  }
+
+  &__event-meta {
+    @include govuk-font($size: 19);
+    @include govuk-text-colour;
+    @include govuk-responsive-margin(3, "bottom");
+
+    display: block;
+  }
+}

src/components/timeline/macro.njk

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

src/components/timeline/template.njk

@@ -0,0 +1,13 @@
+{% if params.events | length !== 0 %}
+  <ol class="hmrc-timeline">
+    {% for event in params.events -%}
+      <li class="hmrc-timeline__event">
+        <{% if params.headingLevel %}h{{- params.headingLevel | string | trim -}}{% else %}h2{% endif %} class="hmrc-timeline__event-title">{{ event.title }}</{% if params.headingLevel %}h{{- params.headingLevel | string | trim -}}{% else %}h2{% endif %}>
+        <time class="hmrc-timeline__event-meta" {% if event.datetime %}datetime="{{event.datetime}}"{% endif %}>{{ event.time }}</time>
+        <div class="hmrc-timeline__event-content">
+          {{ event.content | safe }}
+        </div>
+      </li>
+    {%- endfor %}
+  </ol>
+{% endif %}

src/components/timeline/template.test.js

@@ -0,0 +1,90 @@
+/* eslint-env jest */
+
+const { render, getExamples } = require('../../../lib/jest-helpers');
+
+const examples = getExamples('timeline');
+
+describe('Timeline', () => {
+  describe('by default', () => {
+    const $ = render('timeline', examples.default);
+    const $timeline = $('.hmrc-timeline');
+
+    it('should not show the timeline if there are no parameters given', () => {
+      expect($timeline.length).toBe(0);
+    });
+  });
+
+  describe('with one item', () => {
+    const $ = render('timeline', examples['single-event']);
+    const $orderedList = $('ol.hmrc-timeline');
+    const $listItems = $('li.hmrc-timeline__event');
+    const $heading = $('.hmrc-timeline__event-title');
+    const $time = $('.hmrc-timeline__event-meta');
+
+    it('has the correct text', () => {
+      expect($listItems.text()).toContain('singleExampleContent1');
+    });
+
+    it('has an ordered list', () => {
+      expect($orderedList.length).toBe(1);
+    });
+
+    it('has a list of 1 item', () => {
+      expect($listItems.length).toBe(1);
+    });
+
+    it('has the default heading level', () => {
+      expect($heading.get(0).tagName).toBe('h2');
+    });
+
+    it('has the title content', () => {
+      expect($heading.text()).toBe('event one');
+    });
+
+    it('has the correct time text and datetime attribute', () => {
+      expect($time.text()).toBe('15 July 2020');
+      expect($time.attr('datetime')).toBe('2020-07-15');
+    });
+  });
+
+  describe('with a custom heading level', () => {
+    const $ = render('timeline', examples['custom-header-level']);
+    const $heading = $('.hmrc-timeline__event-title');
+
+    it('should have a different tag', () => {
+      expect($heading.get(0).tagName).toBe('h3');
+    });
+  });
+
+  describe('with no datetime parameter', () => {
+    const $ = render('timeline', examples['no-datetime-event']);
+    const $time = $('.hmrc-timeline__event-meta');
+
+    it('should not have the datetime attribute', () => {
+      expect($time.attr('datetime')).toBe(undefined);
+    });
+  });
+
+  describe('with two items', () => {
+    const $ = render('timeline', examples['multiple-events']);
+    const $listItems = $('li.hmrc-timeline__event');
+    const $headings = $('.hmrc-timeline__event-title');
+    const $times = $('.hmrc-timeline__event-meta');
+
+    it('Contains a list of 2 items', () => {
+      expect($listItems.length).toBe(2);
+    });
+
+    it('has the correct title, text, time and datetime for each list item', () => {
+      expect($headings.eq(0).text()).toBe('event one');
+      expect($times.eq(0).text()).toBe('20 July 2020');
+      expect($times.eq(0).attr('datetime')).toBe('2020-07-20');
+      expect($listItems.eq(0).text()).toContain('exampleContent1');
+
+      expect($headings.eq(1).text()).toBe('event two');
+      expect($times.eq(1).text()).toBe('21 July 2020');
+      expect($times.eq(1).attr('datetime')).toBe('2020-07-21');
+      expect($listItems.eq(1).text()).toContain('exampleContent2');
+    });
+  });
+});

src/components/timeline/timeline.yaml

@@ -0,0 +1,75 @@
+params:
+  - events:
+    type: array
+    required: true
+    description: the list of events in the timeline
+    params:
+      - title:
+        type: string
+        required: true
+        description: the name of the event
+
+      - datetime:
+        type: string
+        required: false
+        description: the machine readable date added to the datetime attribute in the time element
+
+      - time:
+        type: string
+        required: true
+        description: the human readable date
+
+      - content:
+        type: string
+        required: true
+        description: the description of the timeline event
+  - headingLevel:
+    type: integer
+    required: false
+    description: allows customisation of the heading level.
+
+examples:
+- name: default
+  description: A default example.
+  data:
+    events: []
+
+- name: custom-header-level
+  description: Events with custom header levels.
+  data:
+    headingLevel: 3
+    events:
+      - title: 'event one'
+        datetime: '2020-07-14'
+        time: '14 July 2020'
+        content: '<p class="govuk-body">exampleContent1</p>'
+
+- name: no-datetime-event
+  description: An example with no datetime.
+  data:
+    events:
+      - title: 'event one'
+        time: '15 July 2020'
+        content: '<p class="govuk-body">singleExampleContent1</p>'
+
+- name: single-event
+  description: An example with a single event.
+  data:
+    events:
+      - title: 'event one'
+        datetime: '2020-07-15'
+        time: '15 July 2020'
+        content: '<p class="govuk-body">singleExampleContent1</p>'
+
+- name: multiple-events
+  description: An example with multiple events.
+  data:
+    events:
+      - title: 'event one'
+        datetime: '2020-07-20'
+        time: '20 July 2020'
+        content: '<p class="govuk-body">exampleContent1</p>'
+      - title: 'event two'
+        datetime: '2020-07-21'
+        time: '21 July 2020'
+        content: '<p class="govuk-body">exampleContent2</p>'