# TaskList

> Navigation rail for a long form done in parts, in any order and over several sessions: each part with its status, the open part with its steps.

- Status: alpha
- Group: navigation
- Page: https://www.digitaltableteur.com/design-system/components/task-list
- Contract: https://www.digitaltableteur.com/contracts/v1/TaskList.contract.json

## When to use

Navigation rail for a long form done in parts, in any order and over several sessions: each part with its status, the open part with its steps.

## When not to use

- Do not use it for a short linear flow that must be done in order; a simple "Step 2 of 3" caption is enough there.
- Do not show a status nobody can act on; "Cannot start yet" is for a part that depends on another.

## Look-alikes

The contract names no look-alike with a deciding condition.

## Props

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `tasks` | `TaskListTask[]` | none | Tasks in order. Each has id, label, status, an optional hint and steps, and `unnumbered` to leave a closing task such as "Check and submit" without a number. | Yes |
| `label` | `string` | none | Accessible name of the navigation landmark, for example "Intake parts". | Yes |
| `currentTaskId` | `string` | none | The task the person is working on; its steps are listed. | No |
| `currentStepId` | `string` | none | The step on screen, marked with aria-current="step". | No |
| `onSelect` | `(taskId: string, stepId?: string) => void` | none | Called when a task or step is chosen. Every task can be opened, so past steps stay reachable (Baymard: people click step indicators to go back). Tasks with status "cannotStart" are not interactive. | No |
| `statusLabels` | `Partial<Record<TaskListStatus, string>>` | none | Overrides the translated status words. | No |
| `className` | `string` | none | Merged onto the nav element. | No |

## Variants

No variant dimensions and no props with a fixed set of values.

## Invalid combinations

The contract records no invalid combinations.

## Keyboard

| Key | Behaviour |
| --- | --- |
| Tab | Moves through the parts and the open part's steps in order. |
| Enter / Space | Opens the focused part or step. |

## Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST | ARIA: Renders a <nav> landmark named by `label`. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: The step on screen carries aria-current="step"; with no step, the open part does. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Each part's status (and hint) describes its button through aria-describedby. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: Completed steps add a visually hidden "done"; the check icon is decorative. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The accessibility tree (role, name, state) matches the committed snapshot for every required story. | Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | Every documented keyboard interaction works as specified. | Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2. |

## Install and import

- In-repo only. TaskList is not exported from `@digitaltableteur/react`, so there is no public import path.
- Alpha components are internal and never exported.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/TaskList.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/task-list.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.