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:
1 parent
6b70580b91
commit
f1bab20306
4 files changed
+145
-3
No files matched your search
@@ -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')
|
||||
})
|
||||
})
|
||||
@@ -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>
|
||||
|
||||
@@ -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')
|
||||
})
|
||||
})
|
||||
@@ -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). */}
|
||||
|
||||
Reference in new issue
Block a user