fix(a11y): name dialogs by their heading, and four smaller things
A PdDialog's name was an aria-label holding what it was about, so a screen reader announced "numpy, dialog" and then "Cancel": the question being asked was on screen and never spoken. It is named by its visible heading, followed by what it is about, and described by its body. The legal gate replaces the whole shell, declares itself modal, and had no focus inside it. Its heading takes focus on arrival, as a screen's does. A package row's focus ring was drawn 2px outside a row that is absolutely positioned in a scroller and stacked against its neighbours, so three sides of it were clipped or painted over. It sits inside the row, in every mode rather than only in forced-colors. The dock bay's remove button was a bare glyph about 8px wide. It is 24px each way. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
1 parent
885bca416c
commit
d016b80014
6 files changed
+63
-8
No files matched your search
@@ -26,10 +26,17 @@
|
||||
* double-submitted and the user keeps reading what they were reading.
|
||||
*/
|
||||
|
||||
import { useEffect, useRef } from 'react'
|
||||
import { useEffect, useId, useRef } from 'react'
|
||||
|
||||
interface PdDialogProps {
|
||||
/** Accessible name — the package or operation the dialog is about. */
|
||||
/**
|
||||
* What the dialog is about — the package, the interpreter, the cache.
|
||||
*
|
||||
* Spoken after the heading, as part of the dialog's name. It used to *be* the name, as an
|
||||
* `aria-label`, so a screen reader announced "numpy, dialog" and then "Cancel": the question
|
||||
* being asked was on screen and never said. A caller whose heading already says it passes the
|
||||
* same string for both, and it is said once.
|
||||
*/
|
||||
label: string
|
||||
/** Heading text, already localized. */
|
||||
title: string
|
||||
@@ -55,6 +62,8 @@ export function PdDialog({
|
||||
}: PdDialogProps) {
|
||||
const ref = useRef<HTMLDialogElement>(null)
|
||||
const cancelRef = useRef<HTMLButtonElement>(null)
|
||||
const titleId = useId()
|
||||
const bodyId = useId()
|
||||
|
||||
useEffect(() => {
|
||||
const el = ref.current
|
||||
@@ -72,7 +81,10 @@ export function PdDialog({
|
||||
return (
|
||||
<dialog
|
||||
ref={ref}
|
||||
aria-label={label}
|
||||
// Named by its visible heading and described by its body, so opening it says what is being
|
||||
// asked and what it will do — not only which button has focus.
|
||||
aria-labelledby={titleId}
|
||||
aria-describedby={bodyId}
|
||||
// Esc reaches this rather than closing the element behind our back, so cancelling always
|
||||
// goes through the same path as the button.
|
||||
onCancel={(e) => {
|
||||
@@ -84,8 +96,13 @@ export function PdDialog({
|
||||
// top-left corner. Seen in the installed build; jsdom computes no layout to show it.
|
||||
className="m-auto max-w-lg rounded-pd border border-border bg-surface p-6 text-text backdrop:bg-bg/80"
|
||||
>
|
||||
<h2 className="text-accent">{title}</h2>
|
||||
<div className="mt-3 text-data">{children}</div>
|
||||
<h2 id={titleId} className="text-accent">
|
||||
{title}
|
||||
{label === title ? null : <span className="sr-only">{`: ${label}`}</span>}
|
||||
</h2>
|
||||
<div id={bodyId} className="mt-3 text-data">
|
||||
{children}
|
||||
</div>
|
||||
<div className="mt-4 flex flex-wrap gap-2">
|
||||
{/* First, and focused: UI-SPEC §7. The safe answer must be the one a reflex reaches. */}
|
||||
<button
|
||||
|
||||
@@ -58,7 +58,9 @@ export function PdDockBay({
|
||||
onRemove(item.name)
|
||||
}}
|
||||
aria-label={t('search.remove', { pkg: item.name })}
|
||||
className="shrink-0 text-data text-text-dim"
|
||||
// 24 px each way: with no padding this was a bare glyph about 8 px wide, under
|
||||
// WCAG 2.5.8's minimum target and the smallest thing in the app to hit.
|
||||
className="min-h-6 min-w-6 shrink-0 rounded-pd text-data text-text-dim hover:bg-surface"
|
||||
>
|
||||
{'✕'}
|
||||
</button>
|
||||
|
||||
@@ -33,6 +33,14 @@ describe('PdLegalGate', () => {
|
||||
vi.mocked(openUrl).mockResolvedValue(undefined)
|
||||
})
|
||||
|
||||
it('puts focus on its heading when it takes the screen', () => {
|
||||
// The gate replaces the whole shell and says it is modal, and nothing inside it had focus:
|
||||
// the first thing a keyboard or screen-reader user met on first run was silence, then the
|
||||
// first link. The shell focuses a screen's heading on arrival; this is the same move.
|
||||
render(<PdLegalGate />)
|
||||
expect(screen.getByRole('heading', { level: 1 })).toHaveFocus()
|
||||
})
|
||||
|
||||
describe('first run', () => {
|
||||
it('lists all five documents and opens each on GitHub', () => {
|
||||
render(<PdLegalGate />)
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
*/
|
||||
|
||||
import { getCurrentWindow } from '@tauri-apps/api/window'
|
||||
import { useState } from 'react'
|
||||
import { useEffect, useRef, useState } from 'react'
|
||||
import { useTranslation } from 'react-i18next'
|
||||
|
||||
import { LEGAL_DOCUMENTS } from '@/components/legal'
|
||||
@@ -39,6 +39,11 @@ export function PdLegalGate({
|
||||
const error = useLegalStore((s) => s.error)
|
||||
const [checked, setChecked] = useState(false)
|
||||
const { open, failed: openFailed } = useOpenExternal()
|
||||
const heading = useRef<HTMLHeadingElement>(null)
|
||||
|
||||
useEffect(() => {
|
||||
heading.current?.focus()
|
||||
}, [])
|
||||
|
||||
return (
|
||||
<div
|
||||
@@ -48,7 +53,11 @@ export function PdLegalGate({
|
||||
className="fixed inset-0 z-50 flex items-center justify-center bg-bg/95 p-6"
|
||||
>
|
||||
<div className="max-h-full w-full max-w-2xl overflow-auto rounded-pd border border-border bg-surface p-6">
|
||||
<h1 id="legal-title" className="font-mono text-accent">
|
||||
{/* Focused on arrival. The gate replaces the whole shell and declares itself modal, and
|
||||
nothing inside it had focus — on first run a keyboard or screen-reader user met
|
||||
silence, then the first link. The shell focuses a screen's heading when it changes
|
||||
(`App.tsx`); the gate is rendered instead of the shell, so it does the same itself. */}
|
||||
<h1 id="legal-title" ref={heading} tabIndex={-1} className="font-mono text-accent">
|
||||
{t('legal.title')}
|
||||
</h1>
|
||||
|
||||
|
||||
@@ -44,6 +44,17 @@ describe('PdUninstallDialog', () => {
|
||||
expect(screen.getByText('scipy 1.11.4 requires numpy<1.28.0,>=1.21.6')).toBeInTheDocument()
|
||||
})
|
||||
|
||||
it('is named by its heading and by what it is about, and described by its body', () => {
|
||||
// The name was the package alone — a reader heard "numpy, dialog" and then "Cancel", with the
|
||||
// question the dialog asks never spoken. A dialog is named by its visible heading; what it is
|
||||
// about follows, and the body is its description.
|
||||
setup(BREAKING)
|
||||
|
||||
expect(dialog()).toHaveAccessibleName(/^This removal breaks other packages.*numpy/)
|
||||
expect(dialog()).toHaveAccessibleDescription(/pandas 2\.1\.4 requires numpy/)
|
||||
expect(dialog()).not.toHaveAttribute('aria-label')
|
||||
})
|
||||
|
||||
it('focuses Cancel, and renders it first', () => {
|
||||
// UI-SPEC §7: destructive confirms "require the dialog's default focus to be Cancel".
|
||||
setup(BREAKING)
|
||||
|
||||
@@ -91,6 +91,14 @@
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
/* A package row's ring sits inside it. Rows are absolutely positioned inside a scroller and
|
||||
* stacked edge to edge, so a ring drawn 2px outside one is clipped by the scroller at both
|
||||
* ends and painted over by the row below — three sides of the ring a keyboard user steers by.
|
||||
* This was in the forced-colors block alone, where the same clipping had been noticed. */
|
||||
[role='row']:focus-visible {
|
||||
outline-offset: -2px;
|
||||
}
|
||||
|
||||
/* UI-SPEC §2: prefers-reduced-motion is respected. */
|
||||
@media (prefers-reduced-motion: reduce) {
|
||||
*,
|
||||
|
||||
Reference in new issue
Block a user