agama-project / agama / 28202176186

83%

push

github

fix(web): improve accessibility of the software patterns selection (#3667)

**TL;DR:** The pattern categories are now exposed as real, accessible
sections (groups) labelled by their heading, so the category a pattern
belongs to is conveyed programmatically instead of only visually.

## The long story

This came out of QA testing the patterns selection page
(`software/patterns/select`): some patterns showed up with the same
display name under different categories (**most likely a
patterns-definition issue**), and it was hard to tell which one was the
right one to pick, the one the tester was actually after, because
nothing indicated which category each entry belonged to. A real
screen-reader user could face the same ambiguity.

Looking into it surfaced that the categories were rendered as visual
headings only, not as real, navigable sections: a screen reader user got
headings to jump between but no programmatic grouping tying a category
to its checkboxes. Exposing each category as a labelled group makes the
intended pattern identifiable by its category and closes the underlying
accessibility gap. Along the way we also hardened the checkbox ids so
that even patterns sharing the exact same name (not just the same
display name) across categories cannot break the markup.

## Changes

### Semantic groups (a11y)

- Each category is wrapped in a `section` with `role="group"` and
`aria-labelledby` pointing at its heading. This is the ARIA equivalent
of a `fieldset`/`legend` for a set of related form controls, and it is
announced when entering the category's checkboxes. `role="group"`
(rather than a `region` landmark) keeps the landmark list clean while
heading navigation still works.
- The `h3` headings are preserved.

### Unique checkbox ids

- The checkbox derived its DOM id, its label's `htmlFor` target, and its
React key from the pattern name. If the backend lists the same pattern
name under more than one category, those collide (duplicate ids make
every l... (continued)

4883 of 6817 branches covered (71.63%)

Branch coverage included in aggregate %.

2 of 2 new or added lines in 1 file covered. (100.0%)

25403 of 29652 relevant lines covered (85.67%)

124.24 hits per line