Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(RadioList): a disabled group's reason describes each radio (#9169)

Christopher Chedeau701c3b2baa6a
diff --git a/.changeset/radiolist-disabled-reason-describes-each-radio.md b/.changeset/radiolist-disabled-reason-describes-each-radio.md
new file mode 100644
index 0000000000..3ce810deed
--- /dev/null
+++ b/.changeset/radiolist-disabled-reason-describes-each-radio.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] RadioList: a group disabled with a `disabledMessage` gives that reason to each radio as its description (`aria-describedby`), as well as to the radio group, so a screen reader announces it on the focused radio. A radio's own description comes first.
+
+@vjeux
diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsx
index b4d85ec31d..043de3ca41 100644
--- a/packages/core/src/RadioList/RadioList.test.tsx
+++ b/packages/core/src/RadioList/RadioList.test.tsx
@@ -24,6 +24,7 @@ import {
import {RadioList} from './RadioList';
import {RadioListItem} from './RadioListItem';
import {getForcedColorsRules} from '../__tests__/forcedColors';
+import {__resetInteractionModalityForTest} from '../utils/interactionModality';
// Mock showPopover/hidePopover (not implemented in jsdom) so the tooltip layer
// reflects its open state via a `popover-open` attribute the tests can assert.
@@ -470,6 +471,96 @@ describe('RadioList', () => {
await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
});
+ it('describes each radio with the reason, as well as the radiogroup', () => {
+ renderGroup();
+ const tooltip = screen.getByRole('tooltip', h);
+ for (const name of ['Free', 'Pro']) {
+ const radio = screen.getByRole('radio', {name});
+ expect(radio.getAttribute('aria-describedby')?.split(' ')).toContain(
+ tooltip.id,
+ );
+ expect(radio).toHaveAccessibleDescription(
+ 'Upgrade your account to change plans',
+ );
+ }
+ expect(
+ screen
+ .getByRole('radiogroup')
+ .getAttribute('aria-describedby')
+ ?.split(' '),
+ ).toContain(tooltip.id);
+ });
+
+ it("keeps a radio's own description ahead of the reason", () => {
+ render(
+ <RadioList
+ label="Plan"
+ value="free"
+ onChange={() => {}}
+ isDisabled
+ disabledMessage="Upgrade your account to change plans">
+ <RadioListItem
+ label="Free"
+ value="free"
+ description="Up to 3 projects"
+ />
+ </RadioList>,
+ );
+ const tooltip = screen.getByRole('tooltip', h);
+ const radio = screen.getByRole('radio', {name: 'Free'});
+ const ids = radio.getAttribute('aria-describedby')!.split(' ');
+ expect(ids).toHaveLength(2);
+ expect(ids[1]).toBe(tooltip.id);
+ expect(radio).toHaveAccessibleDescription(
+ 'Up to 3 projects Upgrade your account to change plans',
+ );
+ });
+
+ // spec:AST-085 FR5: a keyboard user hears the reason on the radio that
+ // takes focus.
+ it('describes the focused radio with the reason when Tab enters the group', async () => {
+ const user = userEvent.setup();
+ renderGroup();
+ await user.tab();
+ const free = screen.getByRole('radio', {name: 'Free'});
+ expect(free).toHaveFocus();
+ expect(free).toHaveAccessibleDescription(
+ 'Upgrade your account to change plans',
+ );
+ });
+
+ it('opens the reason on a tap and selects nothing', async () => {
+ __resetInteractionModalityForTest();
+ const onChange = vi.fn();
+ renderGroup({onChange});
+ const tooltip = screen.getByRole('tooltip', h);
+ const pro = screen.getByRole('radio', {name: 'Pro'});
+ // A tap, in the order a browser dispatches it.
+ fireEvent.pointerEnter(pro, {pointerType: 'touch'});
+ fireEvent.pointerDown(pro, {pointerType: 'touch'});
+ fireEvent.pointerUp(pro, {pointerType: 'touch'});
+ fireEvent.mouseEnter(pro);
+ fireEvent.click(pro);
+ await waitFor(() => expect(tooltip).toHaveAttribute('popover-open'));
+ expect(onChange).not.toHaveBeenCalled();
+ expect(pro).not.toBeChecked();
+ });
+
+ it('adds no reason to the radios of a group that is not disabled', () => {
+ render(
+ <RadioList
+ label="Plan"
+ value="free"
+ onChange={() => {}}
+ disabledMessage="Upgrade your account to change plans">
+ <RadioListItem label="Free" value="free" />
+ </RadioList>,
+ );
+ expect(screen.getByRole('radio', {name: 'Free'})).not.toHaveAttribute(
+ 'aria-describedby',
+ );
+ });
+
it('does not render a tooltip when not disabled', () => {
render(
<RadioList
diff --git a/packages/core/src/RadioList/RadioList.tsx b/packages/core/src/RadioList/RadioList.tsx
index f054fa9f7b..cc1dd1def0 100644
--- a/packages/core/src/RadioList/RadioList.tsx
+++ b/packages/core/src/RadioList/RadioList.tsx
@@ -16,6 +16,7 @@
* - /packages/cli/assets/templates/blocks/components/RadioList/ (showcase blocks)
*/
+import {RadioListReasonContext} from './RadioListReasonContext';
import {createLayerScopedContext as createContext} from '../Layer/layerScopedContext';
import React, {
useCallback,
@@ -246,7 +247,8 @@ export function RadioList({
// controls swallow pointer events, so the tooltip listeners attach to the
// radiogroup container and the radios stay perceivable via aria-disabled
// instead of the disabled attribute. Selection is blocked in the item's
- // onChange guard.
+ // onChange guard. The reason describes the radiogroup and each radio (see
+ // RadioListReasonContext).
const showsDisabledMessage = isDisabled && !!disabledMessage;
const disabledMessageTooltip = useTooltip({
placement: 'above',
@@ -426,7 +428,16 @@ export function RadioList({
controlClassName,
controlStyle,
)}>
- <RadioListContext value={contextValue}>{children}</RadioListContext>
+ <RadioListContext value={contextValue}>
+ <RadioListReasonContext
+ value={
+ showsDisabledMessage
+ ? disabledMessageTooltip.describedBy
+ : undefined
+ }>
+ {children}
+ </RadioListReasonContext>
+ </RadioListContext>
</div>
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
diff --git a/packages/core/src/RadioList/RadioListItem.tsx b/packages/core/src/RadioList/RadioListItem.tsx
index f64573055e..08ebd594f0 100644
--- a/packages/core/src/RadioList/RadioListItem.tsx
+++ b/packages/core/src/RadioList/RadioListItem.tsx
@@ -23,6 +23,8 @@ import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {RadioListContext} from './RadioList';
+import {RadioListReasonContext} from './RadioListReasonContext';
+import {joinAriaIDs} from '../utils/inputAria';
import {colorVars, radiusVars} from '../theme/tokens.stylex';
import {mergeProps, isRenderable, rtlStyles} from '../utils';
import {indicatorScope} from '../Indicator/indicator.markers.stylex';
@@ -265,6 +267,7 @@ export function RadioListItem({
// the touch press controller (pressableCoverage.test.ts).
const pressable = usePressFeedback();
const context = use(RadioListContext);
+ const disabledReasonID = use(RadioListReasonContext);
if (!context) {
throw new Error('RadioListItem must be used within an RadioList');
}
@@ -351,7 +354,12 @@ export function RadioListItem({
// exclusive — aria-labelledby would otherwise win over it.
aria-label={ariaLabel}
aria-labelledby={ariaLabel == null ? labelID : undefined}
- aria-describedby={hasDescription ? descriptionID : undefined}
+ // The item's own description, then the group's disabled reason
+ // (RadioList's disabledMessage), which describes each radio (FR5).
+ aria-describedby={joinAriaIDs(
+ hasDescription ? descriptionID : undefined,
+ disabledReasonID,
+ )}
{...stylex.props(
styles.input,
rtlStyles.centerInline('-50%'),
diff --git a/packages/core/src/RadioList/RadioListReasonContext.ts b/packages/core/src/RadioList/RadioListReasonContext.ts
new file mode 100644
index 0000000000..c4a8d4dd74
--- /dev/null
+++ b/packages/core/src/RadioList/RadioListReasonContext.ts
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file RadioListReasonContext.ts
+ * @input Uses createLayerScopedContext
+ * @output Exports RadioListReasonContext (internal; not re-exported)
+ * @position Internal to RadioList; read by RadioListItem
+ *
+ * The id of a RadioList's disabled-reason tooltip while the group is disabled
+ * with a `disabledMessage`. The reason describes the radiogroup (FR1), and
+ * each radio adds it to its own `aria-describedby` (FR5): a screen reader
+ * announces a radio's description when the radio takes focus, which it does
+ * not reliably do for a description on the radiogroup.
+ */
+
+import {createLayerScopedContext} from '../Layer/layerScopedContext';
+
+// Layer-scoped like RadioListContext: content in a layer opened from inside the
+// group is not a radio of it.
+export const RadioListReasonContext = createLayerScopedContext<
+ string | undefined
+>(undefined);
+RadioListReasonContext.displayName = 'RadioListReasonContext';
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts
index ae2d60df80..9fd150528d 100644
--- a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts
@@ -223,10 +223,12 @@ export const RADIO_GROUP_BINDING_STATES = [
{
id: 'radio-list-option-disabled-with-message',
binding: 'RadioListItem',
- summary: 'an unavailable option kept tabReachable for a group-level reason',
+ summary:
+ 'an unavailable option kept tabReachable and described by its group-level reason',
facts: optionFacts({
checked: true,
disabled: true,
+ description: 'Managed by your administrator',
operable: false,
tabReachable: true,
pointerCancellation: false,