Skip to content

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.md
new file mode 100644
index 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.
+
+@vjeux
diff --git a/packages/core/src/CheckboxList/CheckboxList.test.tsx b/packages/core/src/CheckboxList/CheckboxList.test.tsx
index 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(
<CheckboxList
diff --git a/packages/core/src/CheckboxList/CheckboxList.tsx b/packages/core/src/CheckboxList/CheckboxList.tsx
index 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.tsx
index 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 item
diff --git a/packages/core/src/CheckboxList/CheckboxListItem.tsx b/packages/core/src/CheckboxList/CheckboxListItem.tsx
index 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.ts
index 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');
}