Skip to content

Commit 908d4e1

Browse files
chore(plans): record review closeout for aria-correctness
Check the validation boxes actually verified (new combobox tests, the audited aria-label/aria-invalid sets, and the full gate: type-check, lint, api 434/434, web 114/114, shared 75/75), fill in the closeout Notes (mousedown-swallow vs focus-out decision, hardcoded error ids kept, the post-#154 review pass, and that the mobile-sheet layout was reasoned rather than screenshotted), and convert the prose Follow-ups into taxonomy shapes: #164 (useId-derived form error ids) and #165 (shared combobox hook) filed and linked; the Retry contradiction is resolved in this PR. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RdRwHvDupRLV8GuJpYKzEr
1 parent 17223e0 commit 908d4e1

1 file changed

Lines changed: 79 additions & 35 deletions

File tree

‎plans/aria-correctness.md‎

Lines changed: 79 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ status: done
33
depends: []
44
specs:
55
- specs/behaviors/app-shell.md
6-
issues: []
6+
issues: [164, 165]
77
pr: 155
88
---
99

@@ -21,7 +21,10 @@ The two headline items are the site search box and the tag picker: both claim
2121
`role="listbox"` today while owning non-option children, and neither is
2222
operable from the keyboard. `specs/behaviors/app-shell.md` → Accessibility
2323
already requires "All dropdowns are keyboard-navigable", so this is code
24-
brought into conformance with an existing spec — **no spec change is needed**.
24+
brought into conformance with an existing spec. Review surfaced two places
25+
where the spec's own wording lagged the widget (Enter's behaviour with a
26+
highlighted result; what the error banner's Retry does) — those were amended
27+
in the spec first, then the code followed.
2528

2629
Out of scope by deliberate choice: heading hierarchy, colour contrast,
2730
`document.title`, motion/pause controls, breadcrumbs, `target="_blank"` cues,
@@ -58,10 +61,18 @@ pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/):
5861
- "Searching…" / "No results" moves **out** of the listbox into a sibling
5962
`role="status"` region.
6063
- "See all results" becomes the final option in the listbox.
61-
- ArrowDown/ArrowUp (wrapping), Home/End, Enter, Escape; focus never leaves
62-
the input, so the blur race is structurally gone for keyboard users. The
64+
- ArrowDown/ArrowUp (wrapping), Enter, Escape; focus never leaves the input
65+
while the popup is open, so the blur race is structurally gone for keyboard
66+
users. Home/End are left to the text caret (APG: editable combobox). The
6367
popup swallows `mousedown` so a pointer click cannot blur the input either —
64-
the 150 ms timeout is deleted rather than tuned.
68+
the 150 ms timeout is deleted rather than tuned. Activating a result blurs
69+
the input so focus returns to the page.
70+
- Options track the pointer with a guarded `onMouseMove`, not `onMouseEnter`,
71+
so results arriving under a stationary pointer cannot steal a keyboard
72+
user's highlight.
73+
- The inline (mobile-sheet) instance renders results in-flow with a smaller
74+
height cap; absolutely positioned, they hung below the sheet's fixed-height
75+
viewport on short phones.
6576
- Options stay `<a href>` (valid: `option` is an allowed role for `a[href]`)
6677
with `tabIndex={-1}`, so middle-click / "open in new tab" still work, while
6778
a plain click is intercepted and routed through `useNavigate()` instead of
@@ -81,16 +92,21 @@ PostHelpWantedModal). Reworked to the same pattern: `useId()` ties `<Label
8192
htmlFor>` to the input; `<li role="option">` become the interactive targets;
8293
ArrowDown/ArrowUp/Escape/Enter. Enter falls back to the existing
8394
exact-match → first-match → create-tag chain when no option is active, and
84-
Backspace-removes-last is preserved.
95+
Backspace-removes-last is preserved. The list closes on focus-out (container
96+
`onBlur` + `relatedTarget` check, options `tabIndex={-1}`) rather than via a
97+
document-level mousedown listener, and the input reopens it on click since a
98+
mouse selection leaves focus in place.
8599

86100
### 3. Small repairs
87101

88102
| File | Defect | Fix |
89-
|---|---|---|
103+
| --- | --- | --- |
90104
| `PersonAvatar.tsx` | `aria-label` on a roleless `<span>` (prohibited) | `role="img"` |
91-
| `StageBadge.tsx` | `aria-label` on a roleless `<div>`; progress conveyed by width only; tooltip triggers not focusable | `role="progressbar"` + value attrs; `tabIndex={0}` on both triggers |
105+
| `StageBadge.tsx` | `aria-label` on a roleless `<div>`; progress conveyed by width only; stage description tooltip-only | `role="progressbar"` + value attrs; description exposed via `sr-only` text / `aria-describedby` (no extra tab stop) |
92106
| `LoginPlaceholder.tsx`, `AccountClaim.tsx` | `aria-live` + `aria-label` on an empty roleless div announces nothing | `role="status"` + `sr-only` text, spinner `aria-hidden` |
93-
| `NetworkErrorBanner.tsx` | button reads "Retry", `aria-label` says "Dismiss error" (SC 2.5.3) | drop the `aria-label` |
107+
| `NetworkErrorBanner.tsx` | button reads "Retry", `aria-label` says "Dismiss error" (SC 2.5.3), and the handler only dismissed | drop the `aria-label`; `showError` takes a retry callback (query client re-fetches active queries); label reads "Dismiss" when there is none |
108+
| `TagChip.tsx` | `aria-pressed` on every clickable chip made filter-removal chips announce as toggles | emit it only when `active` is passed |
109+
| `PersonAvatar.tsx` | Link `aria-label` duplicated the inner `role="img"` name | drop it; the link is named by content |
94110
| `TopProgressBar.tsx` | progressbar permanently exposed at 100% | `aria-hidden` when idle |
95111
| `TagChip.tsx`, `Home.tsx` | toggle state conveyed visually only | `aria-pressed` |
96112
| `ConnectGitHubBanner.tsx` | `aria-label` duplicates visible text | removed |
@@ -114,19 +130,19 @@ conditional `aria-describedby`, applied uniformly across `AddMemberModal`,
114130

115131
## Validation
116132

117-
- [ ] `SearchBox` exposes `role="combobox"` with `aria-expanded`,
133+
- [x] `SearchBox` exposes `role="combobox"` with `aria-expanded`,
118134
`aria-controls`, `aria-autocomplete="list"`; the listbox owns only
119135
groups/options; status text sits outside it.
120-
- [ ] `SearchBox` keyboard: type → ArrowDown moves `aria-activedescendant` →
136+
- [x] `SearchBox` keyboard: type → ArrowDown moves `aria-activedescendant` →
121137
Enter navigates to the active option; Escape closes.
122-
- [ ] `TagPicker` label is associated with its input; ArrowDown + Enter
138+
- [x] `TagPicker` label is associated with its input; ArrowDown + Enter
123139
selects an option; Escape closes; Backspace-removes-last still works.
124-
- [ ] New tests `apps/web/tests/SearchBox.test.tsx` and
140+
- [x] New tests `apps/web/tests/SearchBox.test.tsx` and
125141
`apps/web/tests/TagPicker.test.tsx` cover the above.
126-
- [ ] No `aria-label` remains on a roleless generic element in the audited set.
127-
- [ ] Every audited `aria-invalid` control references its error text via
142+
- [x] No `aria-label` remains on a roleless generic element in the audited set.
143+
- [x] Every audited `aria-invalid` control references its error text via
128144
`aria-describedby`.
129-
- [ ] `npm run -w packages/shared build && npm run type-check && npm run lint
145+
- [x] `npm run -w packages/shared build && npm run type-check && npm run lint
130146
&& npm test` clean.
131147

132148
## Risks
@@ -139,25 +155,53 @@ conditional `aria-describedby`, applied uniformly across `AddMemberModal`,
139155

140156
## Notes
141157

142-
_(filled in at closeout)_
158+
- **Mousedown swallow vs. focus-out.** `SearchBox` keeps the
159+
`onMouseDown={preventDefault}` on its popup and closes on input blur — the
160+
options are `<a href>`s and focus should stay in the input until a result is
161+
chosen. `TagPicker` went the other way after review: container `onBlur` with
162+
a `relatedTarget` check, `tabIndex={-1}` on the listbox and options, and no
163+
swallow, because the swallow blocked scrollbar dragging in Firefox and kept
164+
the input focused so a second click could never reopen the list. The two
165+
widgets now differ here; see the combobox-hook follow-up.
166+
- **Hardcoded error ids kept.** The `aria-describedby` wiring in §4 uses
167+
literal ids (`title-error`, `slug-error`, …). They collide when a screen and
168+
a modal that share one are mounted together. Left as-is to keep this PR
169+
attribute-level; tracked as a follow-up.
170+
- **Review pass (post-#154 rebase).** Home/End removed from `SearchBox`
171+
(APG: editable combobox leaves them to the caret); `activate()` blurs the
172+
input; option highlight moves on guarded `onMouseMove`; inline results
173+
render in-flow so the mobile sheet can scroll them; `TagChip` only emits
174+
`aria-pressed` when `active` is passed; `StageBadge`/`StageProgressBar`
175+
lost their `tabIndex={0}` in favour of `sr-only` / `aria-describedby`
176+
descriptions; `PersonAvatar`'s link label dropped (double announcement);
177+
the error banner's Retry now re-fetches active queries and reads
178+
"Dismiss" when there is nothing to retry. `specs/behaviors/app-shell.md`
179+
was amended first for the Enter/arrow-key contract and the Retry
180+
semantics. `apps/web` `testTimeout` raised to 15 s — several screen tests
181+
exceeded 5 s under full-suite load.
182+
- **Mobile-sheet layout was reasoned, not screenshotted.** No API/data repo
183+
was available in the review environment for a headless check; the in-flow
184+
change follows from the sheet being a fixed-height flex column whose nav
185+
has `min-h-0 overflow-y-auto`, so an in-flow, self-scrolling results box
186+
(`max-h-64`) stays inside the viewport while the nav yields height.
187+
- The AppHeader test from #154 queried the sheet search as a `searchbox`;
188+
it is a `combobox` now, and a second case covers clicking a result closing
189+
the sheet via #154's `location.key` mechanism.
143190

144191
## Follow-ups
145192

146-
- **Spec↔code contradiction, surfaced not patched — the 5xx banner's "Retry"
147-
button does not retry.** `NetworkErrorBanner`'s button calls `clearError()`
148-
and nothing else: it dismisses the banner. Its visible text says "Retry" and
149-
`specs/behaviors/app-shell.md:162` prescribes `[Retry]`, so spec and label
150-
agree with each other and both disagree with the code. This plan only
151-
removed the `aria-label="Dismiss error"` that contradicted the visible name
152-
(SC 2.5.3) — note that the removed label was the one place the code admitted
153-
what the button actually does. Resolving the contradiction is a behavior
154-
question, not an ARIA one: either the banner gains a real retry (re-issuing
155-
the failed call, which the context does not currently retain) or the spec and
156-
label change to "Dismiss". Needs its own spec decision and plan; do not
157-
settle it by renaming one side.
158-
- The audit surfaced further categories that are **not** ARIA-correctness
159-
defects and were deliberately excluded here — heading hierarchy, colour
160-
contrast, `document.title`, motion/pause controls, breadcrumbs,
161-
`target="_blank"` cues, toolbar semantics, repeated button names, and
162-
`CardTitle` semantics. The coordinator holds the full audit report; these
163-
want their own triage and plan.
193+
- Issue [#164](https://github.com/CodeForPhilly/codeforphilly-ng/issues/164) —
194+
form error ids should derive from `useId()`; the hardcoded `title-error` /
195+
`slug-error` ids collide when a screen and a modal are mounted together.
196+
- Issue [#165](https://github.com/CodeForPhilly/codeforphilly-ng/issues/165) —
197+
extract a shared combobox hook for `SearchBox` / `TagPicker`; the two
198+
hand-rolled copies have already diverged on close-on-blur handling.
199+
- The 5xx banner's "Retry" spec↔code contradiction recorded at the original
200+
closeout was resolved in review: spec amended first, a real retry wired
201+
(re-fetch active queries), and the label reads "Dismiss" when nothing can be
202+
retried. Nothing outstanding.
203+
- Tracked as: the wider audit categories deliberately excluded here — heading
204+
hierarchy, colour contrast, `document.title`, motion/pause controls,
205+
breadcrumbs, `target="_blank"` cues, toolbar semantics, repeated button
206+
names, `CardTitle` semantics. The coordinator holds the full audit report;
207+
these want their own triage and plan.

0 commit comments

Comments
 (0)