# react.form.error-summary

The GOV.UK Design System error summary: a box at the top of the page headed
"There is a problem", listing every error on the page, each a link to the
field it is about. It takes focus when it appears, so a keyboard or screen
reader user who has just pressed "Continue" lands on it and hears what to
fix. `errorSummaryItems` builds its list from the `fields` map the
`validate-*` capabilities return (field name to message).

```tsx
"use client";
import { ErrorSummary, errorSummaryItems } from "#fune/react.form.error-summary@^1";
import { validateRegistration } from "#fune/auth.validate-registration@^1";
import { validateDateParts } from "#fune/form.date-parts@^1";

const check = validateRegistration(email, password, name, policy);
const dob = validateDateParts(dobParts, "Date of birth", { today, timing: "past", notBefore: null, notAfter: null });
const fields = { ...check.fields, ...(dob.message ? { dob: dob.message } : {}) };

<ErrorSummary items={errorSummaryItems(fields, ["name", "email", "password", "dob"], { dob: `dob-${dob.fields[0]}` })} />
```

## errorSummaryItems(fields, order, targets)

- **Order**: the fields named in `order` first, in that order, so the summary
  reads in the same order as the form; then any other field in `fields`, in
  the map's order, so an error is never lost because the order forgot it. A
  name listed twice appears once; a name with no error is skipped.
- **Links** are `"#" + id`. The id is the field name, unless `targets` gives
  another: GOV.UK links an error about a date to its first box in error, so
  with `react.form.date-input` and `form.date-parts` pass
  `{ dob: "dob-" + check.fields[0] }` ("dob-month" for a missing month,
  "dob-day" when the whole date is in error).
- An empty message is not an error. An id that is empty or contains a space
  throws, since it could not be linked to.
- The text is the message as given: GOV.UK asks for the same wording in the
  summary as beside the field, which passing the same map to both ensures.

## ErrorSummary

- `items` from `errorSummaryItems` (or written by hand). With none it renders
  nothing, so it can stay on the page permanently.
- `title` defaults to GOV.UK's required "There is a problem"; `description`
  adds a line above the list.
- The box has `tabindex="-1"` and takes focus when it appears and again
  whenever the list of errors changes (a second failed submit);
  `disableAutoFocus` turns that off. The inner `role="alert"` announces it.
- A link, clicked, moves focus to the field and scrolls its question into
  view (the fieldset's legend for a box inside one, else the field's label),
  as GOV.UK's script does. A link whose target is not on the page is left to
  the browser.
- Focus and scrolling are effects, so it is a client component
  (`"use client"`).

**What the vectors cover**: the markup of every state, and
`errorSummaryItems` in full. Moving focus on arrival and on a click needs a
browser; the harness renders on the server with no DOM, so focus is not
tested by it.

Also follow GOV.UK's validation pattern: put "Error: " at the start of the
page's `<title>` while there are errors.

Classes: `fune-error-summary`, `fune-error-summary-title`,
`fune-error-summary-body`, `fune-error-summary-list`.

Sources: GOV.UK Design System, "Error summary"
https://design-system.service.gov.uk/components/error-summary/ (markup, the
"There is a problem" heading, linking to a date input's first field in error)
and the "Validation" pattern
https://design-system.service.gov.uk/patterns/validation/.