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)
+ })
+})