fix(a11y): say what Search is doing, and expose the tab shortcuts

Search told a screen reader nothing between a keystroke and its answer: the
index loading, a search running, how many results came back and "nothing
matches" were plain spans or not text at all. One status region carries them,
mounted from the first render so there is an earlier state for a message to
differ from. The result whose details are showing was a background colour; it
carries aria-current.

The sidebar's ^1..^9 hints were aria-hidden and at half opacity: about 2.6:1,
and the shortcut existed nowhere else. They are drawn in a token, and each tab
carries aria-keyshortcuts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Fable 5.2 committed 2026-11-10 20:01:03 +07:00
1 parent 6b70580b91
commit f1bab20306
4 files changed
+145 -3

No files matched your search

+45
View File
@@ -0,0 +1,45 @@
import { render, screen } from '@testing-library/react'
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { NAV_KEYS } from '@/components/nav'
import { PdSidebar } from '@/components/PdSidebar'
import { usePlanStore, useUiStore } from '@/stores'
import { resetStore } from '@/test/stores'
vi.mock('@/ipc', async () => {
const { ipcMock } = await import('@/test/ipc')
return ipcMock()
})
describe('PdSidebar', () => {
beforeEach(() => {
resetStore(usePlanStore)
useUiStore.setState({ nav: 'installed' })
})
it('tells assistive technology which shortcut each tab has', () => {
// The `^1`…`^9` hints are `aria-hidden`, so the shortcut was visible and nowhere else.
render(<PdSidebar />)
const tabs = screen.getAllByRole('button')
expect(tabs).toHaveLength(NAV_KEYS.length)
expect(tabs.map((tab) => tab.getAttribute('aria-keyshortcuts'))).toEqual(
NAV_KEYS.map((_, i) => `Control+${String(i + 1)}`),
)
})
it('draws the shortcut hints in a token, not at half opacity', () => {
// `opacity-50` over `text-text-dim` measured about 2.6:1 on the sidebar's background. Being
// hidden from a screen reader does not make visible text exempt from contrast.
render(<PdSidebar />)
for (const hint of screen.getAllByText(/^\^\d$/)) {
expect(hint.className).not.toMatch(/opacity-/)
expect(hint).toHaveClass('text-text-dim')
}
})
it('marks the tab that is showing', () => {
render(<PdSidebar />)
expect(screen.getByRole('button', { current: 'page' })).toHaveTextContent('Installed')
})
})
+6 -1
View File
@@ -45,6 +45,9 @@ export function PdSidebar() {
<button
type="button"
aria-current={active ? 'page' : undefined}
// The hint below is `aria-hidden`, so without this the shortcut was on screen and
// nowhere else. By position, like the shortcut itself.
aria-keyshortcuts={`Control+${String(index + 1)}`}
disabled={planBusy}
onClick={() => {
setNav(key)
@@ -63,7 +66,9 @@ export function PdSidebar() {
</span>
) : null}
</span>
<span aria-hidden="true" className="font-mono text-data opacity-50">
{/* A token, not `opacity-50`: half of `text-text-dim` measured about 2.6:1 here, and
text hidden from a screen reader is still text someone has to read. */}
<span aria-hidden="true" className="font-mono text-data text-text-dim">
{`^${index + 1}`}
</span>
</button>
+70
View File
@@ -0,0 +1,70 @@
import { render, screen, within } from '@testing-library/react'
import { beforeEach, describe, expect, it, vi } from 'vitest'
import type { Hit } from '@/ipc'
import { PdSearch } from '@/screens/PdSearch'
import { useEnvStore, usePlanStore } from '@/stores'
import { useIndexStore } from '@/stores/index-search'
import { resetStore } from '@/test/stores'
vi.mock('@/ipc', async () => {
const { ipcMock } = await import('@/test/ipc')
return ipcMock()
})
const HITS: Hit[] = [
{ name: 'numpy', display: 'numpy', kind: 'exact' },
{ name: 'numpydoc', display: 'numpydoc', kind: 'prefix' },
]
describe('what Search says without being looked at', () => {
beforeEach(() => {
vi.clearAllMocks()
resetStore(useIndexStore)
resetStore(useEnvStore)
resetStore(usePlanStore)
})
it('keeps one status region on screen from the first render', () => {
// A live region announces *changes* to itself. One that is mounted together with its first
// message has no earlier state to differ from, and most readers say nothing.
render(<PdSearch />)
expect(screen.getByRole('status')).toBeInTheDocument()
expect(screen.getByRole('status')).toBeEmptyDOMElement()
})
it('says it is searching', () => {
useIndexStore.setState({ query: 'num', searching: true })
render(<PdSearch />)
expect(screen.getByRole('status')).toHaveTextContent('Searching…')
})
it('says the index is still loading', () => {
useIndexStore.setState({ ready: false })
render(<PdSearch />)
expect(screen.getByRole('status')).toHaveTextContent('Preparing the package index…')
})
it('says how many results came back', () => {
// The list simply appeared. Nothing told a screen-reader user that the keystroke had an
// answer, or how long the answer was.
useIndexStore.setState({ query: 'num', hits: HITS })
render(<PdSearch />)
expect(screen.getByRole('status')).toHaveTextContent('2 results')
})
it('says when nothing matched, in the region as well as in the empty state', () => {
useIndexStore.setState({ query: 'zzzz', hits: [] })
render(<PdSearch />)
expect(within(screen.getByRole('status')).getByText(/nothing matches/)).toHaveClass('sr-only')
})
it('marks the result whose details are showing', () => {
// Selection was a background colour and nothing else, which forced-colors erases.
useIndexStore.setState({ query: 'num', hits: HITS, selected: 'numpydoc' })
render(<PdSearch />)
expect(screen.getByRole('button', { name: 'numpydoc' })).toHaveAttribute('aria-current', 'true')
expect(screen.getByRole('button', { name: 'numpy' })).not.toHaveAttribute('aria-current')
})
})
+24 -2
View File
@@ -52,6 +52,8 @@ export function PdSearch() {
const planResolve = usePlanStore((s) => s.resolve)
const envRow = rows.find((r) => r.interpreter === envSelected)
/** A query has been asked and answered: the list on screen is the answer to what is typed. */
const settled = query.trim() !== '' && ready && !searching
// UI-SPEC §5: the Search flow's first click is spent arriving here, so the field must already
// have focus — "Search (autofocus) → result [Add] → Install → Confirm" is 4, not 5. In the app
@@ -98,11 +100,27 @@ export function PdSearch() {
className="mt-3 shrink-0 rounded-pd border border-border bg-surface px-3 py-1.5 font-mono text-data"
/>
<div className="mt-1 flex shrink-0 items-center gap-2 text-data text-text-dim">
{/* **One status region, mounted from the first render and never removed.** These were
plain spans, so a screen reader heard nothing between a keystroke and its answer — not
that the index was loading, not that a search was running, not that it had come back
or how much it found. A live region announces changes to itself, which is why it has
to exist before the first message: one that arrives together with its text has no
earlier state to differ from. */}
<div
role="status"
className="mt-1 flex min-h-5 shrink-0 items-center gap-2 text-data text-text-dim"
>
{/* Warming is a state, not a failure: the index is 864k names and takes ~140 ms to
load, and saying so beats a field that silently returns nothing. */}
{!ready && unavailable === null ? <span>{t('search.warming')}</span> : null}
{searching ? <span>{t('search.searching')}</span> : null}
{settled && hits.length > 0 ? (
<span>{t('search.resultCount', { count: hits.length })}</span>
) : null}
{/* The empty state below says this to the eye; said once more here for the region. */}
{settled && hits.length === 0 ? (
<span className="sr-only">{t('search.noResults', { query })}</span>
) : null}
</div>
{unavailable !== null ? (
@@ -127,7 +145,7 @@ export function PdSearch() {
</div>
) : null}
{query.trim() !== '' && hits.length === 0 && ready && !searching ? (
{settled && hits.length === 0 ? (
<PdEmptyState message={t('search.noResults', { query })} hint={t('search.noResultsHint')} />
) : null}
@@ -156,6 +174,10 @@ export function PdSearch() {
onClick={() => {
void select(hit.name)
}}
// Which result the panel beside the list is about. It was a background colour
// and nothing else — unannounced, and erased by forced-colors, where
// `styles.css` outlines `aria-current` instead.
aria-current={selected === hit.name ? 'true' : undefined}
className="min-w-0 flex-1 text-left"
>
{/* The display name as PyPI spells it — data, never localized (I18N §2). */}