An open source design system that's fully customizable and agent ready
TypeScript
fix(CheckboxList): a disabled group's reason describes each checkbox (#9168)
Christopher Chedeau53c8c4a78fd1
diff --git a/.changeset/checkboxlist-disabled-reason-describes-each-checkbox.md b/.changeset/checkboxlist-disabled-reason-describes-each-checkbox.mdnew file mode 100644index 0000000000..b78aff00f0--- /dev/null+++ b/.changeset/checkboxlist-disabled-reason-describes-each-checkbox.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] CheckboxList: a group disabled with a `disabledMessage` gives that reason to each checkbox as its description (`aria-describedby`), as well as to the group, so a screen reader announces it on the focused checkbox. A row's own description comes first.++@vjeuxdiff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsxindex 0ab47ddbd2..9d1ff645c3 100644--- a/packages/core/src/CheckboxList/CheckboxList.test.tsx+++ b/packages/core/src/CheckboxList/CheckboxList.test.tsx@@ -22,6 +22,7 @@ import userEvent from '@testing-library/user-event';import {CheckboxList} from './CheckboxList';import {CheckboxListItem} from './CheckboxListItem';import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';+import {__resetInteractionModalityForTest} from '../utils/interactionModality';import {List} from '../List/List';// FieldStatus announces status messages through the persistent useAnnounce@@ -1090,6 +1091,95 @@ describe('CheckboxListItem ARIA props', () => {await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));});+ it('describes each checkbox with the reason', () => {+ renderGroup();+ const tooltip = screen.getByRole('tooltip', h);+ for (const name of ['Email', 'SMS']) {+ const checkbox = screen.getByRole('checkbox', {name});+ expect(checkbox.getAttribute('aria-describedby')?.split(' ')).toContain(+ tooltip.id,+ );+ expect(checkbox).toHaveAccessibleDescription(+ 'Notifications are managed by your administrator',+ );+ }+ });++ it("keeps a row's own description ahead of the reason", () => {+ render(+ <CheckboxList+ label="Notifications"+ value={['email']}+ onChange={() => {}}+ isDisabled+ disabledMessage="Notifications are managed by your administrator">+ <CheckboxListItem+ label="Email"+ value="email"+ description="Weekly digest"+ />+ </CheckboxList>,+ );+ const tooltip = screen.getByRole('tooltip', h);+ const checkbox = screen.getByRole('checkbox', {name: 'Email'});+ const ids = checkbox.getAttribute('aria-describedby')!.split(' ');+ expect(ids).toHaveLength(2);+ expect(ids[1]).toBe(tooltip.id);+ expect(checkbox).toHaveAccessibleDescription(+ 'Weekly digest Notifications are managed by your administrator',+ );+ });++ // spec:AST-085 FR5: a keyboard user hears the reason on the checkbox that+ // has focus.+ it('describes the focused checkbox with the reason as Tab moves through the group', async () => {+ const user = userEvent.setup();+ renderGroup();+ await user.tab();+ const email = screen.getByRole('checkbox', {name: 'Email'});+ expect(email).toHaveFocus();+ expect(email).toHaveAccessibleDescription(+ 'Notifications are managed by your administrator',+ );+ await user.tab();+ const sms = screen.getByRole('checkbox', {name: 'SMS'});+ expect(sms).toHaveFocus();+ expect(sms).toHaveAccessibleDescription(+ 'Notifications are managed by your administrator',+ );+ });++ it('opens the reason on a tap and toggles nothing', async () => {+ __resetInteractionModalityForTest();+ const onChange = vi.fn();+ renderGroup({onChange});+ const tooltip = screen.getByRole('tooltip', h);+ const sms = screen.getByRole('checkbox', {name: 'SMS'});+ // A tap, in the order a browser dispatches it.+ fireEvent.pointerEnter(sms, {pointerType: 'touch'});+ fireEvent.pointerDown(sms, {pointerType: 'touch'});+ fireEvent.pointerUp(sms, {pointerType: 'touch'});+ fireEvent.mouseEnter(sms);+ fireEvent.click(sms);+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));+ expect(onChange).not.toHaveBeenCalled();+ });++ it('adds no reason to the checkboxes of a group that is not disabled', () => {+ render(+ <CheckboxList+ label="Notifications"+ value={['email']}+ onChange={() => {}}+ disabledMessage="Notifications are managed by your administrator">+ <CheckboxListItem label="Email" value="email" />+ </CheckboxList>,+ );+ expect(screen.getByRole('checkbox', {name: 'Email'})).not.toHaveAttribute(+ 'aria-describedby',+ );+ });+it('does not render a tooltip when not disabled', () => {render(<CheckboxListdiff --git a/packages/core/src/CheckboxList/CheckboxList.tsx b/packages/core/src/CheckboxList/CheckboxList.tsxindex b2648b4843..ed0b678deb 100644--- a/packages/core/src/CheckboxList/CheckboxList.tsx+++ b/packages/core/src/CheckboxList/CheckboxList.tsx@@ -202,7 +202,9 @@ export function CheckboxList({// Disabled-reason tooltip. Applies to the whole-group disabled state. Disabled// controls swallow pointer events, so the tooltip listeners attach to the// group container and the checkboxes stay perceivable via aria-disabled- // instead of the disabled attribute. Toggling is blocked in the item.+ // instead of the disabled attribute. Toggling is blocked in the item. The+ // reason describes the group and each checkbox (see+ // CheckboxListContextValue.disabledMessageID).const showsDisabledMessage = isDisabled && !!disabledMessage;const disabledMessageTooltip = useTooltip({placement: 'above',@@ -240,6 +242,9 @@ export function CheckboxList({onChange: isCollectionMode ? handleChange : undefined,isDisabled,hasDisabledMessage: showsDisabledMessage,+ disabledMessageID: showsDisabledMessage+ ? disabledMessageTooltip.describedBy+ : undefined,isReadOnly,loadingValues,}),@@ -249,6 +254,7 @@ export function CheckboxList({handleChange,isDisabled,showsDisabledMessage,+ disabledMessageTooltip.describedBy,isReadOnly,loadingValues,],diff --git a/packages/core/src/CheckboxList/CheckboxListContext.tsx b/packages/core/src/CheckboxList/CheckboxListContext.tsxindex 791ae16d43..349c4bf2f8 100644--- a/packages/core/src/CheckboxList/CheckboxListContext.tsx+++ b/packages/core/src/CheckboxList/CheckboxListContext.tsx@@ -28,6 +28,14 @@ export interface CheckboxListContextValue {* and AT-discoverable; toggling is still blocked.*/hasDisabledMessage?: boolean;+ /**+ * The id of the group's reason tooltip while `hasDisabledMessage` is true.+ * The reason describes the group (CheckboxList FR1) and every checkbox adds+ * it to its own `aria-describedby` (FR9): a screen reader announces a+ * checkbox's description when the checkbox takes focus, which it does not+ * reliably do for a description on the group.+ */+ disabledMessageID?: string;isReadOnly: boolean;/*** Values of the items whose `changeAction` is pending. Each matching itemdiff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsxindex 591bf799d9..56ce90d9be 100644--- a/packages/core/src/CheckboxList/CheckboxListItem.tsx+++ b/packages/core/src/CheckboxList/CheckboxListItem.tsx@@ -29,6 +29,7 @@ import {ListContext} from '../List/ListContext';import {CheckboxListContext} from './CheckboxListContext';import {useTranslator} from '../i18n';import {ItemDescriptionContext} from '../Item/ItemDescriptionContext';+import {joinAriaIDs} from '../utils/inputAria';import type {ItemAlign} from '../Item';// =============================================================================@@ -153,14 +154,19 @@ export interface CheckboxListItemProps extends BaseProps<HTMLLIElement> {** This component owns `aria-describedby`, so the prop is omitted rather than* accepted and overwritten: a caller passing one would otherwise lose the id- * silently.+ * silently. After the row's description comes the group's disabled reason+ * (CheckboxList's disabledMessage), which describes each checkbox (FR9).*/function DescribedCheckboxInput(props: Omit<CheckboxInputProps, 'aria-describedby'>,) {const describedBy = use(ItemDescriptionContext);+ const reasonID = use(CheckboxListContext)?.disabledMessageID;return (- <CheckboxInput {...props} aria-describedby={describedBy ?? undefined} />+ <CheckboxInput+ {...props}+ aria-describedby={joinAriaIDs(describedBy ?? undefined, reasonID)}+ />);}diff --git a/packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts b/packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.tsindex c477436950..da71f49cf4 100644--- a/packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts+++ b/packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts@@ -74,6 +74,8 @@ interface CaseExpectation {rows: RowExpectation[];status?: {type: 'error' | 'warning' | 'success'; text: string};tooltipText?: string;+ /** The open disabled-reason tooltip describes the group and every checkbox. */+ reasonDescribesRows?: boolean;density?: 'compact' | 'balanced' | 'spacious';labelHidden?: boolean;}@@ -306,6 +308,7 @@ const CASES: AuditCase[] = [{checked: false, disabled: 'focusable'},],tooltipText: 'Notifications are managed by your administrator',+ reasonDescribesRows: true,},},{@@ -1033,6 +1036,11 @@ async function readPage(page: Page, auditCase: AuditCase) {descriptionText: text(byIds(input?.getAttribute('aria-describedby') ?? null)[0] ?? null,),+ reasonDescribed:+ tooltip != null &&+ byIds(input?.getAttribute('aria-describedby') ?? null).includes(+ tooltip as HTMLElement,+ ),hovered: row.matches(':hover'),active: row.matches(':active'),focused: input != null && document.activeElement === input,@@ -1568,6 +1576,18 @@ async function capture(browser: Browser, auditCase: AuditCase, mode: Mode) {) {stateFailures.push('expected the open disabled-reason tooltip');}+ if (auditCase.expect.reasonDescribesRows === true) {+ if (actual.rows.some(row => !row.reasonDescribed)) {+ stateFailures.push(+ 'expected the disabled reason to describe every checkbox',+ );+ }+ if (actual.tooltip?.describesGroup !== true) {+ stateFailures.push(+ 'expected the disabled reason to describe the group',+ );+ }+ }} else if (actual.tooltip != null) {stateFailures.push('unexpected visible tooltip');}