From f1bab2030659bae02e2641c7a63d3511b3293e1f Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Tue, 10 Nov 2026 18:55:27 +0700 Subject: [PATCH] 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 --- ui/src/components/PdSidebar.test.tsx | 45 ++++++++++++++++++ ui/src/components/PdSidebar.tsx | 7 ++- ui/src/screens/PdSearch.test.tsx | 70 ++++++++++++++++++++++++++++ ui/src/screens/PdSearch.tsx | 26 ++++++++++- 4 files changed, 145 insertions(+), 3 deletions(-) create mode 100644 ui/src/components/PdSidebar.test.tsx create mode 100644 ui/src/screens/PdSearch.test.tsx diff --git a/ui/src/components/PdSidebar.test.tsx b/ui/src/components/PdSidebar.test.tsx new file mode 100644 index 0000000..d372fd7 --- /dev/null +++ b/ui/src/components/PdSidebar.test.tsx @@ -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() + 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() + 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() + expect(screen.getByRole('button', { current: 'page' })).toHaveTextContent('Installed') + }) +}) diff --git a/ui/src/components/PdSidebar.tsx b/ui/src/components/PdSidebar.tsx index 9f15565..627cfbd 100644 --- a/ui/src/components/PdSidebar.tsx +++ b/ui/src/components/PdSidebar.tsx @@ -45,6 +45,9 @@ export function PdSidebar() { diff --git a/ui/src/screens/PdSearch.test.tsx b/ui/src/screens/PdSearch.test.tsx new file mode 100644 index 0000000..4149b2e --- /dev/null +++ b/ui/src/screens/PdSearch.test.tsx @@ -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() + expect(screen.getByRole('status')).toBeInTheDocument() + expect(screen.getByRole('status')).toBeEmptyDOMElement() + }) + + it('says it is searching', () => { + useIndexStore.setState({ query: 'num', searching: true }) + render() + expect(screen.getByRole('status')).toHaveTextContent('Searching…') + }) + + it('says the index is still loading', () => { + useIndexStore.setState({ ready: false }) + render() + 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() + 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() + 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() + + expect(screen.getByRole('button', { name: 'numpydoc' })).toHaveAttribute('aria-current', 'true') + expect(screen.getByRole('button', { name: 'numpy' })).not.toHaveAttribute('aria-current') + }) +}) diff --git a/ui/src/screens/PdSearch.tsx b/ui/src/screens/PdSearch.tsx index 3d795f9..1f85a65 100644 --- a/ui/src/screens/PdSearch.tsx +++ b/ui/src/screens/PdSearch.tsx @@ -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" /> -
+ {/* **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. */} +
{/* 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 ? {t('search.warming')} : null} {searching ? {t('search.searching')} : null} + {settled && hits.length > 0 ? ( + {t('search.resultCount', { count: hits.length })} + ) : null} + {/* The empty state below says this to the eye; said once more here for the region. */} + {settled && hits.length === 0 ? ( + {t('search.noResults', { query })} + ) : null}
{unavailable !== null ? ( @@ -127,7 +145,7 @@ export function PdSearch() {
) : null} - {query.trim() !== '' && hits.length === 0 && ready && !searching ? ( + {settled && hits.length === 0 ? ( ) : 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). */}