fix(web): repair invalid ARIA and make search/tag pickers real comboboxes

[heyoub]

An ARIA-correctness pass over apps/web, scoped to verified defects: markup that is invalid per the ARIA spec (prohibited attributes, illegal listbox ownership, dangling references) or that withholds state assistive technology needs. No spec changes — specs/behaviors/app-shell.md already requires "All dropdowns are keyboard-navigable"; this PR brings the code into conformance. Plan record: plans/aria-correctness.md. No visual redesigns: out-of-scope-by-choice items (heading hierarchy, color contrast, document.title, motion controls, etc.) are listed in the plan's follow-ups instead of bundled here.

Headline changes

• SearchBox rebuilt as an APG combobox. It previously put aria-expanded/aria-controls on a plain search input, had a role="listbox" owning bare <p>/<div>s, hardcoded aria-selected={false}, and its results were keyboard-unreachable (Tab blurred the input and a 150 ms timeout unmounted the popup). Now: role="combobox" + aria-activedescendant, valid listbox ownership (status text outside, groups labelled), Arrow/Home/End/Enter/Escape, and the blur race replaced by swallowing mousedown on the popup. Options stay <a href> (middle-click works) but plain activation routes through useNavigate() — clicking a result no longer full-page-reloads the SPA. The print stylesheet's hook moved from the old hardcoded id (which duplicated when both header and sheet search rendered) to [data-search-dropdown].
• TagPicker rebuilt the same way — it drove a popup with no combobox ARIA at all, role="listbox" on a <ul> of unroled <li><button>s, no Escape/arrows, and its label prop was never associated with the input (affects ProjectEdit, ProfileEdit, PostHelpWantedModal). Also fixes a latent empty-popup render when allowCreate was set but the query wasn't a valid slug.
• Form errors wired to their fields — aria-invalid was set in many forms but the error text was never referenced; every audited error now has an id and a conditional aria-describedby (AddMemberModal, ProjectEdit ×5, ProjectBuzzNew ×4, PostHelpWantedModal, TagEditModal ×2, ProfileEdit ×2, MarkdownEditor). ProjectEdit's slug-availability status is now announced.

Smaller repairs

Prohibited aria-label on roleless elements (PersonAvatar → role="img", StageBadge bar → real role="progressbar", auth skeletons, spinner wrappers → role="status" + sr-only text); label-in-name mismatch on the network banner's Retry button; the always-mounted TopProgressBar hidden from AT when idle; aria-pressed on toggle filters (TagChip, Home activity row — matching the existing StageFilterRow idiom); redundant labels removed; aria-controls on the login disclosure; Page N names in Pagination; scope="col" on the sessions table; tooltip-only stage descriptions now keyboard-reachable; the skip link's suppressed focus ring restored; avatar file input labelled.

Notes for reviewers

• One behavior tension surfaced and deliberately not resolved here: the network-error banner's button says "Retry" (as app-shell.md prescribes) but its handler only dismisses. Recorded in the plan's follow-ups — it needs its own spec decision.
• New tests: SearchBox.test.tsx and TagPicker.test.tsx (keyboard paths, attribute contracts) — 11 tests.

Validation

type-check and lint clean; web tests 100/100 (25 files), shared 75/75. No apps/api, specs/, or components/ui/ files touched. This PR is independent of #154 (verified: clean merge in either order).

🤖 Generated with Claude Code

[themightychris]

Thanks @heyoub — this is a careful pass and the combobox rewrites are a real improvement. I rebased the branch onto develop (now that #154 is in — the only conflict was the dropdown's classes in SearchBox.tsx, resolved to keep both sides) and pushed a handful of fix-up commits on top of yours, all from review findings. Nothing structural; your commits are untouched.

What changed and why

• docs(specs) — app-shell.md now describes what the widget actually does: Enter with a highlighted result navigates there (otherwise submits), arrows move the highlight, Escape closes. Also settled the Retry-button contradiction you flagged in the plan (see below). Spec commit first, per the repo's spec-first rule.
• SearchBox — dropped the Home/End branches (APG leaves them to the text caret in an editable combobox); activate() blurs the input so focus does not stay parked in an emptied combobox, and the Enter fallback reuses seeAllUrl + activate(); options highlight on a guarded onMouseMove instead of onMouseEnter so async results arriving under a still pointer cannot steal a keyboard user's highlight; the inline (mobile-sheet) instance renders results in-flow with a smaller cap so they cannot hang below the sheet on short phones.
• TagPicker — after a mouse selection the input kept focus (mousedown was swallowed), so clicking it again could never reopen the list; it opens on click now. Tab-out never closed it; replaced the document-level mousedown listener with a container onBlur + relatedTarget check, tabIndex={-1} on options/listbox, and dropped the swallow (it blocked scrollbar dragging in Firefox). selectOption refocuses the input. Same onMouseMove change, plus a close() helper. Two new tests.
• TagChip — only emits aria-pressed when active is actually passed; the filter-removal chips were announcing as "toggle button, not pressed".
• StageBadge / StageProgressBar — removed the tabIndex={0} additions (a roleless focus stop per card, and two nested tooltips at once on the detail page). The description is exposed non-visually instead: sr-only text in the badge, aria-describedby on the progressbar.
• PersonAvatar — dropped the Link's aria-label; the inner role="img" already names it, so it was read twice.
• NetworkErrorBanner — Retry now retries. showError takes an optional retry callback; the query client passes one that re-fetches active queries. The header typeahead passes none (it re-runs on the next keystroke), and in that case the button reads "Dismiss", so the label is always accurate. Small test added.
• AppHeader.test.tsx — fix(web): reorder header, pad mobile sheet, repoint dead GitBook links #154's test queried the sheet search as a searchbox; it is a combobox now. Added a case for clicking a result closing the sheet.
• vitest.config.ts — testTimeout: 15000 for apps/web; several screen tests exceeded the 5 s default under full-suite load.
• plans/aria-correctness.md — validation boxes checked, Notes filled in, Follow-ups converted to the taxonomy: filed Form error ids should derive from useId (hardcoded title-error/slug-error collide across screen + modal) #164 (useId-derived form error ids) and Extract a shared combobox hook for SearchBox and TagPicker #165 (shared combobox hook).

Validation: packages/shared build, type-check, lint, and tests all clean — api 434/434, web 114/114, shared 75/75.

One thing I could not do here: a headless screenshot of the mobile sheet with results open (no data repo in the review environment). The in-flow change is reasoned through in the plan Notes; if you have a phone-sized viewport handy, a quick look would be welcome.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RdRwHvDupRLV8GuJpYKzEr