# react.form.checkbox-group

A question answered by ticking any number of checkboxes - "Which types of
waste do you transport? Select all that apply" - inside a fieldset whose
legend asks it. It is the GOV.UK Design System checkboxes component: item
hints, an "or" divider and an exclusive "None of these" option included.
`toggleValue` is the list arithmetic behind every click, a pure function you
can also use on the server.

```tsx
"use client";
import { CheckboxGroup } from "#fune/react.form.checkbox-group@^1";

<CheckboxGroup id="countries" legend="Will you travel to any of these countries?"
  hint="Select all that apply" error={errors.countries}
  values={countries} onChange={setCountries}
  options={[
    { value: "france", label: "France" },
    { value: "portugal", label: "Portugal" },
    { value: "spain", label: "Spain" },
    { value: "none", label: "No, I will not be travelling to any of these countries", divider: "or", exclusive: true },
  ]} />
```

- **onChange** is called with every ticked value after each change, not with
  the event, and always in the options' order, whatever order they were
  ticked in. With **values** it is a controlled group; with **defaultValues**
  (or neither) the component keeps the list itself and still reports it.
- **onBlur** is called, with nothing, when any box in the group loses focus,
  so a form can mark the question touched (`form.state`'s blur action).
- **toggleValue(options, values, value, checked)** is that update. The result
  holds only the options' values, once each, in their order, so a stale value
  from an old option list drops out. Ticking an `exclusive` option clears the
  others and ticking another clears it, which is what GOV.UK's
  `data-behaviour="exclusive"` does in the browser; the input carries that
  attribute too. A value that is not an option is refused.
- **Ids.** The first checkbox's id is the `id`, the rest `<id>-2`, `<id>-3`...
  as GOV.UK does, so an error summary linking to `#<id>` lands on the first
  box. Every box posts under **name** (the id when left out). An item hint is
  `<item id>-item-hint` and describes only its box.
- **The group's hint and error** are `<id>-hint` and `<id>-error`, as on
  GOV.UK; the `<fieldset>` itself has no id (`react.form.fieldset` uses the id
  only to name them), so the first checkbox can have it.
- **The error is the group's.** As on GOV.UK, the hint and error message
  describe the fieldset (announced once on entering the group), and no
  checkbox is marked `aria-invalid`: the mistake is in the answer as a whole.
- **small** gives `fune-checkboxes--small`, for filters and dense pages.
  **disabled** disables every box; an option's own `disabled` disables it.
- Option values must be unique (they are the React keys), and a group needs
  at least one option.

For one checkbox on its own ("I agree"), use `react.form.checkbox`. It is a
client component (state and change listeners), so the built file starts with
`"use client"`.

Classes: those of `react.form.fieldset`, plus `fune-checkboxes` (and
`fune-checkboxes--small`), `fune-checkbox` (one box and its label),
`fune-checkbox-input`, `fune-label fune-checkbox-label`,
`fune-hint fune-checkbox-hint`, `fune-checkboxes-divider`.

Sources: GOV.UK Design System, "Checkboxes" (item ids, item hints, the "or"
divider and the exclusive "none" option, small checkboxes, errors on the
fieldset) https://design-system.service.gov.uk/components/checkboxes/ and
"Fieldset" https://design-system.service.gov.uk/components/fieldset/.

## Notices

Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.