Merge pull request #92 from nhsuk/timeline

timeline component

docs/assets/css/app.scss

@@ -1,24 +1,24 @@
 // Import all of the NHS.UK frontend core styles
-@import "node_modules/nhsuk-frontend/packages/core/all.scss";
+@import "node_modules/nhsuk-frontend/packages/core/all";
 
 // Import specific components that we need from nhsuk-frontend
-@import "node_modules/nhsuk-frontend/packages/components/skip-link/skip-link.scss";
-@import "node_modules/nhsuk-frontend/packages/components/header/header.scss";
-@import "node_modules/nhsuk-frontend/packages/components/hero/hero.scss";
-@import "node_modules/nhsuk-frontend/packages/components/tabs/tabs.scss";
-@import "node_modules/nhsuk-frontend/packages/components/breadcrumb/breadcrumb.scss";
+@import "node_modules/nhsuk-frontend/packages/components/breadcrumb/breadcrumb";
+@import "node_modules/nhsuk-frontend/packages/components/skip-link/skip-link";
+@import "node_modules/nhsuk-frontend/packages/components/header/header";
+@import "node_modules/nhsuk-frontend/packages/components/hero/hero";
+@import "node_modules/nhsuk-frontend/packages/components/tabs/tabs";
 
 @import "node_modules/prismjs/themes/prism";
 
 // Import all styles from the NHS App frontend library
-@import "src/all.scss";
+@import "src/all";
 
 // Import all styles specific for the design system docs
 @import "docs/assets/css/components/side-navigation";
-@import "docs/assets/css/tabs.scss";
-@import "docs/assets/css/content.scss";
-@import "docs/assets/css/example.scss";
-@import "docs/assets/css/utilities.scss";
+@import "docs/assets/css/tabs";
+@import "docs/assets/css/content";
+@import "docs/assets/css/example";
+@import "docs/assets/css/utilities";
 
 // Add correct spacing around code highlighter and content
 pre {

docs/components/timeline.md

@@ -0,0 +1,58 @@
+---
+layout: layouts/component.njk
+title: Timeline
+description: Use timelines to help people understand a process and what will happen next.
+tags:
+  - component
+---
+
+{% example "timeline/timeline-inactive.njk" %}
+
+## When to use
+
+Use timelines to show users:
+
+- what has happened so far
+- the point they are currently at
+- what will be coming next
+
+## When not to use
+
+Do not use timelines to give lots of detailed information about every stage of a process. Instead, think about how you can give this information to users in context, at the relevant points in their journey. Timelines are meant to help users understand the broad steps of a process, rather than the finer details.
+
+## How to use
+
+In a timeline you can use nodes (dots), lines and text to explain processes and timings.
+
+{% example "timeline/timeline-active.njk" %}
+
+### Nodes
+
+Nodes can be:
+
+- white with a grey outline (a smaller dot)
+- blue (a larger dot)
+
+Use blue nodes to show that a step is already completed.
+
+### Text
+
+Each node should have an accompanying heading that describes which step the process it represents.
+
+Below each heading, use body text to give further details about that step. This could include a date or a short description.
+
+## Accessibility
+
+We want to do further research to understand how screen reader users find timelines, and how much timelines help them to get their bearings.
+
+## Research
+
+Our user research has found that in general, users:
+
+- find timelines helpful for getting their bearings during a process
+- are familiar with timelines from other apps and websites they use
+- find it helpful that timelines give a visual representation of the process
+
+Some research suggests that users expect timelines to be dynamic, updating as they make progress. Bear in mind that static timelines may not always meet user expectations.
+
+We would like to better understand whether users associate the length of a line between two nodes with the amount of time that stage will take. You may want to standardise the length of lines between nodes, or test what users understand about timings if you do include differing lengths.

docs/examples/timeline/timeline-active.njk

@@ -0,0 +1,27 @@
+---
+layout: layouts/example.njk
+title: Timeline active
+figmaLink: [insert link to Figma file here]
+vueLink: [insert link to Vue component library here]
+---
+
+{% from "timeline/macro.njk" import timeline %}
+
+{{ timeline({
+  items: [
+    {
+      headingText: "Date referred",
+      isPastItem: true,
+      text: "8 June 2024"
+    },
+    {
+      headingText: "Current status",
+      active: true,
+      text: "Waiting for treatment"
+    },
+    {
+      headingText: "Estimated treatment start date",
+      text: "September 2024"
+    }
+  ]
+}) }}

docs/examples/timeline/timeline-inactive.njk

@@ -0,0 +1,22 @@
+---
+layout: layouts/example.njk
+title: Timeline active
+figmaLink: [insert link to Figma file here]
+vueLink: [insert link to Vue component library here]
+---
+
+{% from "timeline/macro.njk" import timeline %}
+
+{{ timeline({
+  items: [
+    {
+      headingText: "Await approval",
+      text: "The request will either be approved or rejected. If rejected please contact your Healthcare Professional.",
+      active: true
+    },
+    {
+      headingText: "GP Approval Process",
+      text: "Once approved, it can take 3 to 5 working days for a nominated pharmacy to prepare your prescription."
+    }
+  ]
+}) }}

src/all.scss

@@ -1,10 +1,11 @@
-@import "node_modules/nhsuk-frontend/packages/core/tools/all.scss";
-@import "node_modules/nhsuk-frontend/packages/core/settings/all.scss";
+@import "node_modules/nhsuk-frontend/packages/core/tools/all";
+@import "node_modules/nhsuk-frontend/packages/core/settings/all";
 
 // styles
 @import "styles/typography";
 
 // components
-@import "./components/card/card.scss";
-@import "./components/tag/tag.scss";
-@import "./components/badge/badge";
+@import "components/badge/badge";
+@import "components/card/card";
+@import "components/tag/tag";
+@import "components/timeline/timeline";

src/components/timeline/_timeline.scss

@@ -0,0 +1,108 @@
+$timeline-badge-size-mobile: 16px;
+$timeline-badge-small-size-mobile: 12px;
+$timeline-border-width: 2px;
+
+@function dot-size($size) {
+  @if $size == "default" {
+    @return $timeline-badge-size-mobile;
+  } @else if $size == "small" {
+    @return $timeline-badge-small-size-mobile;
+  }
+}
+
+@function dot-ml($size) {
+  @return - calc(($size / 2) + ($timeline-border-width / 2));
+}
+
+@function dot-mt-tablet($margin) {
+  @return $margin - 1px;
+}
+
+@mixin nhsapp-timeline-badge($size) {
+  $mt: 4px;
+  $mt-small: 6px;
+
+  height: dot-size($size);
+  width: dot-size($size);
+
+  margin-left: dot-ml(dot-size($size));
+  margin-top: if($size == "default", $mt, $mt-small);
+  margin-right: if($size == "default", nhsuk-spacing(4), nhsuk-spacing(4) + 2px);
+
+  @include mq($from: tablet) {
+    $tablet: dot-size($size) + 4px;
+
+    @debug $tablet;
+
+    height: $tablet;
+    margin-left: dot-ml($tablet);
+    margin-top: if($size == "default", dot-mt-tablet($mt), dot-mt-tablet($mt-small));
+    width: $tablet;
+  }
+}
+
+.nhsapp-timeline {
+  @include nhsuk-responsive-margin(5, "bottom");
+  @include nhsuk-responsive-padding(2, "top");
+
+  list-style: none;
+  padding: 0;
+
+  &__item {
+    @include nhsuk-responsive-padding(5, "bottom");
+
+    display: flex;
+    margin-bottom: 0;
+    margin-left: 12px;
+    margin-top: -6px;
+    position: relative;
+
+    &:last-child {
+      padding: 0;
+
+      &:before {
+        border: none;
+      }
+    }
+
+    &:before {
+      border-left: $timeline-border-width solid $color_nhsuk-grey-3;
+      bottom: 0;
+      content: "";
+      display: block;
+      left: -$timeline-border-width;
+      position: absolute;
+      top: nhsuk-spacing(2);
+      width: $timeline-border-width;
+    }
+
+    &--past {
+      &:before {
+        border-color: $color_nhsuk-blue;
+      }
+    }
+  }
+
+  &__badge {
+    flex-shrink: 0;
+    z-index: 1;
+
+    @include nhsapp-timeline-badge("default");
+
+    &--small {
+      @include nhsapp-timeline-badge("small");
+    }
+  }
+
+  &__header {
+    @include nhsuk-typography-responsive(19);
+    font-weight: normal;
+    margin-bottom: 0;
+  }
+
+  &__description {
+    @include nhsuk-typography-responsive(16);
+    margin-bottom: 0;
+    padding-top: 0;
+  }
+}

src/components/timeline/macro.njk

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

src/components/timeline/timeline.njk

@@ -0,0 +1,31 @@
+{% macro _timelineItem(params, item) %}
+  {% set headingLevel = params.headingLevel if params.headingLevel else 3 %}
+  {% set headingBold = 'nhsuk-u-font-weight-bold' if item.active else '' %}
+  {% set isPastItem = 'nhsapp-timeline__item--past' if item.isPastItem else '' %}
+
+  <li class="nhsapp-timeline__item {{ isPastItem | trim }}">
+    {% if item.active or item.isPastItem %}
+      <svg class="nhsapp-timeline__badge" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="28" height="28" viewBox="0 0 28 28">
+        <circle cx="14" cy="14" r="13" fill="#005EB8"/>
+      </svg>
+    {% else %}
+      <svg class="nhsapp-timeline__badge nhsapp-timeline__badge--small" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 14 14">
+        <circle cx="7" cy="7" r="6" fill="white" stroke="#AEB7BD" stroke-width="2"/>
+      </svg>
+    {% endif %}
+    <div class="nhsapp-timeline__content">
+      <h{{ headingLevel }} class="nhsapp-timeline__header {{ headingBold }}">{{ item.headingText }}</h{{ headingLevel }}>
+      {% if item.html %}
+        {{ item.html | safe | trim }}
+      {% elif item.text %}
+        <p class="nhsapp-timeline__description">{{ item.text }}</p>
+      {% endif %}
+    </div>
+  </li>
+{% endmacro %}
+
+<ol class="nhsapp-timeline">
+  {% for item in params.items %}
+    {% if item %}{{ _timelineItem(params, item) }}{% endif %}
+  {% endfor %}
+</ol>