Merge pull request #2261 from x-govuk/task-list-component

Task list component

CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ### New features
 
+#### Task list component added
+
+A new component has been added which creates lists of tasks that users need to complete.
+
+Each task in the list can have a title, status, link and an optional hint. When a link is added, the whole row is clickable.
+
+This change was made in [pull request #2261: Task list component](https://github.com/alphagov/govuk-frontend/pull/2261).
+
 #### Tag design changes
 
 The design of the tag component has changed to improve accessibility and readability.

packages/govuk-frontend-review/src/views/full-page-examples/task-list/index.njk

@@ -0,0 +1,247 @@
+---
+scenario: >-
+  You want to apply for a teacher training course
+
+
+  Things to try:
+
+  1. Making sure all content is visible without overlapping on narrower screens.
+
+notes: The buttons and links on this page are not functional.
+---
+
+{# This example is based of the live "Apply for teacher training" service at: https://www.apply-for-teacher-training.service.gov.uk/candidate/application #}
+{% extends "layouts/full-page-example.njk" %}
+
+{% from "govuk/components/task-list/macro.njk" import govukTaskList %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+
+{% set pageTitle = "Apply for teacher training" %}
+{% block pageTitle %}{{ pageTitle }} - GOV.UK{% endblock %}
+
+
+{% block content %}
+  <h1 class="govuk-heading-xl govuk-!-margin-bottom-2">Your application</h1>
+  <p class="govuk-hint govuk-!-margin-bottom-8">Last saved on 15 May 2023 at 2:21pm</p>
+
+
+
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+
+      <h2 class="govuk-heading-m">Personal details</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Personal information" },
+            href: "#",
+            status: {
+              text: "Completed"
+            }
+          },
+          {
+            title: { text: "Contact information" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Courses</h2>
+      <p class="govuk-body">You can apply for up to 4 courses.</p>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Choose your courses" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Qualifications</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "English GCSE or equivalent" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "Maths GCSE or equivalent" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "A levels and other qualifications" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "Degree" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Work experience</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Work history" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "Unpaid experience" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Personal statement</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Your personal statement" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Adjustments</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Ask for support if you’re disabled" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "Interview needs" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Safeguarding</h2>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "References to be requested if you accept an offer" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          },
+          {
+            title: { text: "Declare any safeguarding issues" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      })}}
+
+      <h2 class="govuk-heading-m">Equality and diversity</h2>
+      <p class="govuk-body">Training providers will only see your answers to this section if you accept an offer from them.</p>
+      {{ govukTaskList({
+        items: [
+          {
+            title: { text: "Equality and diversity questions" },
+            href: "#",
+            status: {
+              tag: {
+                text: "Incomplete",
+                classes: "govuk-tag--blue"
+              }
+            }
+          }
+        ]
+      }) }}
+
+      <h2 class="govuk-heading-m">Check and submit</h2>
+
+      {{ govukButton({ text: "Check and submit your applicaitons"}) }}
+
+    </div>
+
+    <div class="govuk-grid-column-one-third">
+      <aside class="app-related" role="complementary">
+        <h2 class="govuk-heading-s govuk-!-margin-bottom-2" id="support-title">Get help</h2>
+
+        <ul class="govuk-list govuk-!-font-size-16">
+          <li>Call 0800 389 2500 or <a class="govuk-link" href="#">chat online</a></li>
+          <li>Monday to Friday, 8:30am to 5:30pm (except public&nbsp;holidays)</li>
+          <li>Free of charge</li>
+        </ul>
+      </aside>
+    </div>
+  </div>
+{% endblock %}

packages/govuk-frontend/src/govuk-prototype-kit/govuk-prototype-kit.config.unit.test.mjs

@@ -147,6 +147,10 @@ describe('GOV.UK Prototype Kit config', () => {
           importFrom: 'govuk/components/tag/macro.njk',
           macroName: 'govukTag'
         },
+        {
+          importFrom: 'govuk/components/task-list/macro.njk',
+          macroName: 'govukTaskList'
+        },
         {
           importFrom: 'govuk/components/textarea/macro.njk',
           macroName: 'govukTextarea'

packages/govuk-frontend/src/govuk/components/_all.scss

@@ -30,5 +30,6 @@
 @import "skip-link/index";
 @import "summary-list/index";
 @import "table/index";
+@import "task-list/index";
 @import "textarea/index";
 @import "warning-text/index";

packages/govuk-frontend/src/govuk/components/task-list/README.md

@@ -0,0 +1,15 @@
+# Task list
+
+## Installation
+
+See the [main README quick start guide](https://github.com/alphagov/govuk-frontend#quick-start) for how to install this component.
+
+## Guidance and Examples
+
+Find out when to use the task list component in your service in the [GOV.UK Design System](https://design-system.service.gov.uk/components/task-list).
+
+## Component options
+
+Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
+
+See [options table](https://design-system.service.gov.uk/components/task-list/#options-task-list-example) for details.

packages/govuk-frontend/src/govuk/components/task-list/_index.scss

@@ -0,0 +1,73 @@
+@include govuk-exports("govuk/component/task-list") {
+  $govuk-task-list-hover-colour: govuk-colour("light-grey");
+
+  .govuk-task-list {
+    @include govuk-font($size: 19);
+    margin-top: 0;
+    @include govuk-responsive-margin(6, "bottom");
+    padding: 0;
+    list-style-type: none;
+  }
+
+  // This uses table layout so that the task name and status always appear side-by-side, with the width of
+  // each 'column' being flexible depending upon the length of the task names and statuses.
+  //
+  // The position is set to 'relative' so than an absolutely-positioned transparent element box
+  // can be added within the link so that the whole row can be clickable.
+  .govuk-task-list__item {
+    display: table;
+    position: relative;
+    width: 100%;
+    margin-bottom: 0;
+    padding-top: govuk-spacing(2);
+    padding-bottom: govuk-spacing(2);
+    border-bottom: 1px solid $govuk-border-colour;
+  }
+
+  .govuk-task-list__item:first-child {
+    border-top: 1px solid $govuk-border-colour;
+  }
+
+  // This class is added to the <li> elements where the task name is a link.
+  // The background hover colour is added to help indicate that the whole row is clickable, rather
+  // than just the visible link text.
+  .govuk-task-list__item--with-link:hover {
+    background: $govuk-task-list-hover-colour;
+  }
+
+  .govuk-task-list__task-name-and-hint {
+    display: table-cell;
+    vertical-align: top;
+    @include govuk-text-colour;
+  }
+
+  .govuk-task-list__status {
+    display: table-cell;
+    padding-left: govuk-spacing(2);
+    text-align: right;
+    vertical-align: top;
+    @include govuk-text-colour;
+  }
+
+  .govuk-task-list__status--cannot-start-yet {
+    color: $govuk-secondary-text-colour;
+  }
+
+  // This adds an empty transparent box covering the whole row, including the task status and
+  // any hint text. Because this is generated within the link element, this allows the whole area
+  // to be clickable.
+  .govuk-task-list__link::after {
+    content: "";
+    display: block;
+    position: absolute;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+  }
+
+  .govuk-task-list__task_hint {
+    margin-top: govuk-spacing(1);
+    color: $govuk-secondary-text-colour;
+  }
+}

packages/govuk-frontend/src/govuk/components/task-list/_task-list.scss

@@ -0,0 +1,2 @@
+@import "../../base";
+@import "./index";

packages/govuk-frontend/src/govuk/components/task-list/accessibility.test.mjs

@@ -0,0 +1,22 @@
+import { axe, goToComponent } from 'govuk-frontend-helpers/puppeteer'
+import { getExamples } from 'govuk-frontend-lib/files'
+
+describe('/components/task-list', () => {
+  describe('component examples', () => {
+    let exampleNames
+
+    beforeAll(async () => {
+      exampleNames = Object.keys(await getExamples('task-list'))
+    })
+
+    it('passes accessibility tests', async () => {
+      for (const name of exampleNames) {
+        const exampleName = name.replace(/ /g, '-')
+
+        // Navigation to example, create report
+        await goToComponent(page, 'task-list', { exampleName })
+        await expect(axe(page)).resolves.toHaveNoViolations()
+      }
+    }, 60000)
+  })
+})