You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 908d4e1
Browse filesBrowse the repository at this point in the historyBrowse 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
- "Searching…" / "No results" moves **out** of the listbox into a sibling
59
62
`role="status"` region.
60
63
- "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
63
67
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.
65
76
- Options stay `<a href>` (valid: `option` is an allowed role for `a[href]`)
66
77
with `tabIndex={-1}`, so middle-click / "open in new tab" still work, while
67
78
a plain click is intercepted and routed through `useNavigate()` instead of
@@ -81,16 +92,21 @@ PostHelpWantedModal). Reworked to the same pattern: `useId()` ties `<Label
81
92
htmlFor>` to the input; `<lirole="option">` become the interactive targets;
82
93
ArrowDown/ArrowUp/Escape/Enter. Enter falls back to the existing
83
94
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.
85
99
86
100
### 3. Small repairs
87
101
88
102
| File | Defect | Fix |
89
-
|---|---|---|
103
+
|---|---|---|
90
104
|`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)|
92
106
|`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 |
94
110
|`TopProgressBar.tsx`| progressbar permanently exposed at 100% |`aria-hidden` when idle |
95
111
|`TagChip.tsx`, `Home.tsx`| toggle state conveyed visually only |`aria-pressed`|
96
112
|`ConnectGitHubBanner.tsx`|`aria-label` duplicates visible text | removed |
@@ -114,19 +130,19 @@ conditional `aria-describedby`, applied uniformly across `AddMemberModal`,
114
130
115
131
## Validation
116
132
117
-
-[]`SearchBox` exposes `role="combobox"` with `aria-expanded`,
133
+
-[x]`SearchBox` exposes `role="combobox"` with `aria-expanded`,
118
134
`aria-controls`, `aria-autocomplete="list"`; the listbox owns only
119
135
groups/options; status text sits outside it.
120
-
-[]`SearchBox` keyboard: type → ArrowDown moves `aria-activedescendant` →
136
+
-[x]`SearchBox` keyboard: type → ArrowDown moves `aria-activedescendant` →
121
137
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
123
139
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
125
141
`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
128
144
`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
130
146
&& npm test` clean.
131
147
132
148
## Risks
@@ -139,25 +155,53 @@ conditional `aria-describedby`, applied uniformly across `AddMemberModal`,
139
155
140
156
## Notes
141
157
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.
143
190
144
191
## Follow-ups
145
192
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
0 commit comments