Skip to content

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

TypeScript

test(a11y): add reusable radio-group contract (#6209)

Cindy Zhangcac1b8f98be0
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
index 7e3450816f..80a178ed96 100644
--- a/apps/storybook/rtl-audit/targets.json
+++ b/apps/storybook/rtl-audit/targets.json
@@ -101,6 +101,17 @@
"inputSelector": "input[type=\"radio\"]"
}
},
+ {
+ "component": "SegmentedControl",
+ "storyId": "core-segmentedcontrol--default",
+ "dims": [
+ "D2"
+ ],
+ "selectors": {
+ "prev": "button[role=\"radio\"][data-value=\"grid\"]",
+ "next": "button[role=\"radio\"][data-value=\"table\"]"
+ }
+ },
{
"component": "Switch",
"storyId": "core-switch--default",
diff --git a/apps/storybook/stories/RadioGroupA11y.stories.tsx b/apps/storybook/stories/RadioGroupA11y.stories.tsx
new file mode 100644
index 0000000000..9668c4b731
--- /dev/null
+++ b/apps/storybook/stories/RadioGroupA11y.stories.tsx
@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioGroupA11y.stories.tsx
+ * @input Uses the shared radio-group binding inventory and render map
+ * @output One checked-in reproduction story for every radio-group contract state
+ * @position Stable real-browser fixtures required by AST-009 FR30 and AST-021.
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {RADIO_GROUP_STATE_RENDERS} from '../../../packages/core/src/RadioList/__tests__/RadioGroup.a11y.renders';
+import {RADIO_GROUP_BINDING_STATES} from '../../../packages/core/src/RadioList/__tests__/RadioGroup.a11y.states';
+
+function storyFor(id: string): StoryObj {
+ const state = RADIO_GROUP_BINDING_STATES.find(
+ candidate => candidate.id === id,
+ );
+ if (state == null) {
+ throw new Error(`no binding state "${id}" — see RadioGroup.a11y.states.ts`);
+ }
+ return {
+ name: `${state.binding} — ${state.id}`,
+ render: () => RADIO_GROUP_STATE_RENDERS[state.id](),
+ };
+}
+
+const meta: Meta = {
+ title: 'a11y/Radio group pattern',
+ tags: ['no-visual'],
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'Binding states for the shared radio-group accessibility contract.',
+ },
+ },
+ },
+};
+
+export default meta;
+
+export const RadioListGroupSelectedLtr = storyFor(
+ 'radio-list-group-selected-ltr',
+);
+export const RadioListGroupSelectedRtl = storyFor(
+ 'radio-list-group-selected-rtl',
+);
+export const RadioListGroupSelectedVertical = storyFor(
+ 'radio-list-group-selected-vertical',
+);
+export const RadioListGroupNoneSelected = storyFor(
+ 'radio-list-group-none-selected',
+);
+export const RadioListGroupRequiredInvalidDescribed = storyFor(
+ 'radio-list-group-required-invalid-described',
+);
+export const RadioListGroupDisabledWithMessage = storyFor(
+ 'radio-list-group-disabled-with-message',
+);
+export const RadioListOptionUnselectedDescribed = storyFor(
+ 'radio-list-option-unselected-described',
+);
+export const RadioListOptionSelected = storyFor('radio-list-option-selected');
+export const RadioListOptionDisabled = storyFor('radio-list-option-disabled');
+export const RadioListOptionGroupDisabled = storyFor(
+ 'radio-list-option-group-disabled',
+);
+export const RadioListOptionDisabledWithMessage = storyFor(
+ 'radio-list-option-disabled-with-message',
+);
+
+export const SegmentedGroupSelectedLtr = storyFor(
+ 'segmented-group-selected-ltr',
+);
+export const SegmentedGroupSelectedRtl = storyFor(
+ 'segmented-group-selected-rtl',
+);
+export const SegmentedGroupNoneSelected = storyFor(
+ 'segmented-group-none-selected',
+);
+export const SegmentedGroupDisabled = storyFor('segmented-group-disabled');
+export const SegmentedGroupDisabledWithMessage = storyFor(
+ 'segmented-group-disabled-with-message',
+);
+export const SegmentedOptionUnselected = storyFor(
+ 'segmented-option-unselected',
+);
+export const SegmentedOptionSelectedHiddenLabel = storyFor(
+ 'segmented-option-selected-hidden-label',
+);
+export const SegmentedOptionDisabled = storyFor('segmented-option-disabled');
+export const SegmentedOptionGroupDisabled = storyFor(
+ 'segmented-option-group-disabled',
+);
+export const SegmentedOptionGroupDisabledWithMessage = storyFor(
+ 'segmented-option-group-disabled-with-message',
+);
+
+export const MenuGroupSelected = storyFor('menu-group-selected');
+export const MenuGroupNoneSelected = storyFor('menu-group-none-selected');
+export const MenuOptionUnselectedDescribed = storyFor(
+ 'menu-option-unselected-described',
+);
+export const MenuOptionSelected = storyFor('menu-option-selected');
+export const MenuOptionDisabled = storyFor('menu-option-disabled');
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index c13bf8f4c8..56b5d3974b 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -40,6 +40,7 @@ src/
├── spoken.ts how a visible label is compared against a computed name
├── storybook.ts a static server over a built Storybook, for the browser lane
└── patterns/
+ ├── radio-group.* the radio-group pattern, same four files
├── checkbox.* the checkbox pattern, same four files
├── switch.* the switch pattern, same four files
├── button.* the button pattern, same four files
@@ -49,13 +50,21 @@ src/
## The patterns
-| Pattern | Adopted from | Bound by |
-| -------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
-| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
-| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
-| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
-| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
+| Pattern | Adopted from | Bound by |
+| -------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `radio-group` | [APG radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | RadioList, SegmentedControl; role/state portions of DropdownMenu radio items |
+| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
+| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
+| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
+| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
+| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
+
+The `radio-group` contract owns direct-group Tab entry/exit, Space, and adopted
+directional selection, including zero-selection entry. DropdownMenu radio roles
+and selection state are bound here, while its composite keyboard movement stays
+with Menu. Home and End remain component-local because the current APG radio
+pattern does not require them and no current Astryx record adopts them as shared
+behavior.
The `text-input` contract is native rather than APG-derived. It covers the
role-bearing `<input>` or `<textarea>` only; composed clear and tooltip buttons
diff --git a/internal/a11y-spec/src/harness.ts b/internal/a11y-spec/src/harness.ts
index 8225aa1134..9bafbd646c 100644
--- a/internal/a11y-spec/src/harness.ts
+++ b/internal/a11y-spec/src/harness.ts
@@ -112,7 +112,14 @@ export interface Subject {
}
/** A key an expectation can send. Spelled by intent, not by engine syntax. */
-export type Key = 'Space' | 'Enter' | 'Tab';
+export type Key =
+ | 'Space'
+ | 'Enter'
+ | 'Tab'
+ | 'ArrowLeft'
+ | 'ArrowRight'
+ | 'ArrowUp'
+ | 'ArrowDown';
/**
* A mounted binding, observed at whatever layers this runtime can honestly see.
diff --git a/internal/a11y-spec/src/harness/chromium.ts b/internal/a11y-spec/src/harness/chromium.ts
index c8f8457a9b..b2a6e0066b 100644
--- a/internal/a11y-spec/src/harness/chromium.ts
+++ b/internal/a11y-spec/src/harness/chromium.ts
@@ -81,6 +81,10 @@ const KEYS: Record<Key, string> = {
Space: ' ',
Enter: 'Enter',
Tab: 'Tab',
+ ArrowLeft: 'ArrowLeft',
+ ArrowRight: 'ArrowRight',
+ ArrowUp: 'ArrowUp',
+ ArrowDown: 'ArrowDown',
};
interface AxValue {
@@ -267,6 +271,7 @@ export function createChromiumHarness(
): Harness {
const {page, subject: locator, pointerTarget, cdp, visibleLabel} = options;
const pointerLocator = pointerTarget ?? locator;
+ const pointerTargets = new WeakMap<Subject, Locator>();
const subject: Subject = {
attribute: name => locator.getAttribute(name),
@@ -635,13 +640,14 @@ export function createChromiumHarness(
canReceivePointer: () => canReceivePointer(locator),
focus: () => locator.focus(),
};
+ pointerTargets.set(subject, pointerLocator);
const relatedSubject = (name: string): Subject => {
const related = options.related?.[name];
if (related == null) {
throw new MissingHarnessRelation('chromium', name);
}
- return {
+ const result: Subject = {
attribute: attribute => related.getAttribute(attribute),
idReferences: attribute =>
related.evaluate(
@@ -738,6 +744,8 @@ export function createChromiumHarness(
canReceivePointer: () => canReceivePointer(related),
focus: () => related.focus(),
};
+ pointerTargets.set(result, related);
+ return result;
};
return {
@@ -745,7 +753,13 @@ export function createChromiumHarness(
observes: CHROMIUM_OBSERVES,
subject: async () => subject,
related: async name => relatedSubject(name),
- click: async (_subject, options) => {
+ click: async (targetSubject, options) => {
+ const target = pointerTargets.get(targetSubject);
+ if (target == null) {
+ throw new Error(
+ 'the Chromium harness was asked to click a subject it did not create',
+ );
+ }
// Without `force`, Playwright first satisfies itself that the control is
// visible, stable, enabled, and actually receives pointer events — so an
// ordinary click here also proves a pointer could reach the control.
@@ -753,7 +767,7 @@ export function createChromiumHarness(
// a control the browser calls unavailable what it does when clicked
// anyway.
try {
- await pointerLocator.click({
+ await target.click({
force: options?.ignoreAvailability === true,
// Bounded, and short. A control a pointer cannot reach — one covered
// by something else, or clipped to nothing — otherwise sits here
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index ff11d9901d..bcb647b353 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -87,6 +87,12 @@ export {
export {CHECKBOX_PATTERN, type CheckboxStateFacts} from './patterns/checkbox';
+export {
+ RADIO_GROUP_PATTERN,
+ type RadioGroupRole,
+ type RadioGroupStateFacts,
+} from './patterns/radio-group';
+
export {SWITCH_PATTERN, type SwitchStateFacts} from './patterns/switch';
export {
diff --git a/internal/a11y-spec/src/patterns/radio-group.chromium.spec.ts b/internal/a11y-spec/src/patterns/radio-group.chromium.spec.ts
new file mode 100644
index 0000000000..cbeada1861
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/radio-group.chromium.spec.ts
@@ -0,0 +1,154 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file radio-group.chromium.spec.ts
+ * @input Uses @playwright/test, the radio-group contract and fixtures, and the Chromium harness
+ * @output Real-browser positive and mutation proof for every radio-group expectation
+ * @position Contract self-test; proves the reusable contract, not Astryx components.
+ */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {describeExpectation, requiredLayers} from '../contract';
+import {
+ CHROMIUM_OBSERVES,
+ createChromiumHarness,
+ holdMotionStill,
+} from '../harness/chromium';
+import {RADIO_GROUP_PATTERN} from './radio-group';
+import {
+ CONFORMING_RADIO_GROUP_FIXTURES,
+ expectedRadioGroupMutationFailure,
+ radioGroupFixture,
+ RADIO_GROUP_MUTATIONS,
+ RADIO_GROUP_SUBJECT_SELECTOR,
+ type RadioGroupFixture,
+} from './radio-group.fixtures';
+
+function fixturePage(html: string): string {
+ return `<!doctype html><html lang="en"><body><button type="button">Before</button>${html}<button type="button">After fixture</button></body></html>`;
+}
+
+function relatedFor(page: Page, target: RadioGroupFixture) {
+ return Object.fromEntries(
+ target.facts.optionRelations.map(name => [
+ name,
+ page.locator(`[data-a11y-related="${name}"]`),
+ ]),
+ );
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: RadioGroupFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await checkAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixturePage(target.html));
+ await holdMotionStill(page);
+ return createChromiumHarness({
+ page,
+ subject: page.locator(RADIO_GROUP_SUBJECT_SELECTOR),
+ cdp,
+ visibleLabel: target.facts.visibleLabel ? undefined : null,
+ related: relatedFor(page, target),
+ });
+ },
+ });
+ return run.results;
+}
+
+function resultFor(
+ observed: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const found = observed.find(result => result.expectation === id);
+ if (found == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return found;
+}
+
+test.describe('radio-group contract — conforming fixtures', () => {
+ for (const id of CONFORMING_RADIO_GROUP_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, radioGroupFixture(id));
+ const notPassing = observed.filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ );
+ expect(
+ notPassing.map(
+ result => `${result.expectation}: ${result.detail ?? ''}`,
+ ),
+ ).toEqual([]);
+ });
+ }
+});
+
+test('every expectation passes against at least one conforming fixture', async ({
+ page,
+}) => {
+ test.setTimeout(2 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const withoutPass: string[] = [];
+ for (const expectation of RADIO_GROUP_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ let passed = false;
+ for (const id of CONFORMING_RADIO_GROUP_FIXTURES) {
+ const [result] = await results(page, cdp, radioGroupFixture(id), [
+ expectation.id,
+ ]);
+ if (result?.status === 'pass') {
+ passed = true;
+ break;
+ }
+ }
+ if (!passed) {
+ withoutPass.push(expectation.id);
+ }
+ }
+ expect(withoutPass).toEqual([]);
+});
+
+test.describe('radio-group contract — deliberately violating fixtures', () => {
+ for (const [expectationId, fixtures] of Object.entries(
+ RADIO_GROUP_MUTATIONS,
+ )) {
+ const expectation = RADIO_GROUP_PATTERN.expectations.find(
+ candidate => candidate.id === expectationId,
+ );
+
+ for (const fixtureId of fixtures) {
+ test(`${expectationId} rejects ${fixtureId}`, async ({page}) => {
+ const target = radioGroupFixture(fixtureId);
+ const cdp = await page.context().newCDPSession(page);
+ const result = resultFor(
+ await results(page, cdp, target, [expectationId]),
+ expectationId,
+ );
+ expect(result.status).toBe('fail');
+ expect(result.detail).toBe(
+ expectedRadioGroupMutationFailure(expectationId, target.id),
+ );
+ if (expectation != null) {
+ expect(result.description).toBe(describeExpectation(expectation));
+ }
+ });
+ }
+ }
+});
diff --git a/internal/a11y-spec/src/patterns/radio-group.fixtures.ts b/internal/a11y-spec/src/patterns/radio-group.fixtures.ts
new file mode 100644
index 0000000000..3164f0287d
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/radio-group.fixtures.ts
@@ -0,0 +1,658 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file radio-group.fixtures.ts
+ * @input Uses ./radio-group (RadioGroupStateFacts)
+ * @output Plain-HTML conforming and deliberately violating radio-group fixtures
+ * @position Mutation proof for the reusable contract; no Astryx component code.
+ */
+
+import type {RadioGroupStateFacts} from './radio-group';
+
+const SUBJECT_ATTRIBUTE = 'data-a11y-subject';
+export const RADIO_GROUP_SUBJECT_SELECTOR = `[${SUBJECT_ATTRIBUTE}]`;
+
+export interface RadioGroupFixture {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: RadioGroupStateFacts;
+ readonly html: string;
+}
+
+function groupFacts(
+ overrides: Partial<RadioGroupStateFacts> = {},
+): RadioGroupStateFacts {
+ return {
+ part: 'group',
+ role: 'radiogroup',
+ checked: null,
+ selection: null,
+ optionRelations: [],
+ selectedOption: null,
+ disabled: null,
+ description: null,
+ required: false,
+ invalid: false,
+ operable: false,
+ tabReachable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ pointerCancellation: false,
+ visibleLabel: false,
+ movement: 'horizontal-ltr',
+ ...overrides,
+ };
+}
+
+function optionFacts(
+ overrides: Partial<RadioGroupStateFacts> = {},
+): RadioGroupStateFacts {
+ return {
+ part: 'option',
+ role: 'radio',
+ checked: false,
+ selection: null,
+ optionRelations: [],
+ selectedOption: null,
+ disabled: false,
+ description: null,
+ required: false,
+ invalid: false,
+ operable: false,
+ tabReachable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ pointerCancellation: false,
+ visibleLabel: true,
+ movement: 'none',
+ ...overrides,
+ };
+}
+
+export const RADIO_GROUP_FIXTURES: readonly RadioGroupFixture[] = [
+ {
+ id: 'conforming-radio-option',
+ summary: 'an unchecked direct radio option',
+ facts: optionFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false">Standard</div>`,
+ },
+ {
+ id: 'conforming-radio-option-checked',
+ summary: 'a checked direct radio option',
+ facts: optionFacts({checked: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="true">Standard</div>`,
+ },
+ {
+ id: 'conforming-radio-option-disabled',
+ summary: 'an unavailable direct radio option',
+ facts: optionFacts({disabled: true, operable: false, tabReachable: false}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" aria-disabled="true">Standard</div>`,
+ },
+ {
+ id: 'conforming-menu-radio-option',
+ summary: 'an unchecked radio option inside a menu',
+ facts: optionFacts({role: 'menuitemradio', tabReachable: false}),
+ html: `<div role="menu"><div role="group" aria-label="Sort by"><div ${SUBJECT_ATTRIBUTE} role="menuitemradio" aria-checked="false">Newest</div></div></div>`,
+ },
+ {
+ id: 'conforming-pointer-option',
+ summary: 'an operable radio option whose selection happens on click',
+ facts: optionFacts({
+ operable: true,
+ tabReachable: true,
+ pointerCancellation: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" tabindex="0" onclick="this.setAttribute('aria-checked','true')">Standard</div>`,
+ },
+ {
+ id: 'conforming-group',
+ summary: 'a named direct radio group',
+ facts: groupFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-menu-group',
+ summary: 'a named group of radio menu items',
+ facts: groupFacts({role: 'group', movement: 'none'}),
+ html: `<div role="menu"><div ${SUBJECT_ATTRIBUTE} role="group" aria-label="Sort by"><div role="menuitemradio" aria-checked="true">Newest</div><div role="menuitemradio" aria-checked="false">Oldest</div></div></div>`,
+ },
+ {
+ id: 'conforming-described-group',
+ summary: 'a radio group with attached supporting text',
+ facts: groupFacts({description: 'Choose one delivery speed.'}),
+ html: `<p id="hint">Choose one delivery speed.</p><div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-describedby="hint"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-required-group',
+ summary: 'a radio group that declares the required choice',
+ facts: groupFacts({required: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-required="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-invalid-group',
+ summary: 'a radio group exposed as being in error',
+ facts: groupFacts({invalid: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-invalid="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-disabled-group',
+ summary: 'an unavailable radio group exposed as disabled',
+ facts: groupFacts({disabled: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-disabled="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-group-one-selected',
+ summary: 'a radio group with exactly its declared option selected',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-group-none-selected',
+ summary: 'a radio group that intentionally starts with no option selected',
+ facts: groupFacts({
+ selection: 'none',
+ optionRelations: ['first', 'second'],
+ selectedOption: null,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="false">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'conforming-focus-selected',
+ summary:
+ 'a native radio group entered at its selected option and left as one Tab stop',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ pointerSelection: true,
+ arrowSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><label><input data-a11y-related="first" type="radio" name="delivery" checked>Standard</label><label><input data-a11y-related="second" type="radio" name="delivery">Express</label></div><button type="button">After</button>`,
+ },
+ {
+ id: 'conforming-focus-none-selected',
+ summary: 'an unselected native radio group entered at its first option',
+ facts: groupFacts({
+ selection: 'none',
+ optionRelations: ['first', 'second'],
+ selectedOption: null,
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ pointerSelection: true,
+ arrowSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><label><input data-a11y-related="first" type="radio" name="delivery">Standard</label><label><input data-a11y-related="second" type="radio" name="delivery">Express</label></div><button type="button">After</button>`,
+ },
+ {
+ id: 'conforming-arrow-rtl',
+ summary:
+ 'a right-to-left horizontal radio group with logical arrow movement',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ arrowSelection: true,
+ movement: 'horizontal-rtl',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} dir="rtl" role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0" onkeydown="if (event.key === 'ArrowLeft') { this.setAttribute('aria-checked','false'); const next=this.nextElementSibling; next.setAttribute('aria-checked','true'); next.focus(); }">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1" onkeydown="if (event.key === 'ArrowRight') { this.setAttribute('aria-checked','false'); const previous=this.previousElementSibling; previous.setAttribute('aria-checked','true'); previous.focus(); }">Express</div></div>`,
+ },
+ {
+ id: 'conforming-arrow-vertical',
+ summary: 'a vertical radio group with down and up arrow movement',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ arrowSelection: true,
+ movement: 'vertical',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0" onkeydown="if (event.key === 'ArrowDown') { this.setAttribute('aria-checked','false'); const next=this.nextElementSibling; next.setAttribute('aria-checked','true'); next.focus(); }">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1" onkeydown="if (event.key === 'ArrowUp') { this.setAttribute('aria-checked','false'); const previous=this.previousElementSibling; previous.setAttribute('aria-checked','true'); previous.focus(); }">Express</div></div>`,
+ },
+ {
+ id: 'conforming-pointer-group',
+ summary:
+ 'a radio group whose pointer selection can move to an alternative and back',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ pointerSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><label><input data-a11y-related="first" type="radio" name="delivery" checked>Standard</label><label><input data-a11y-related="second" type="radio" name="delivery">Express</label></div>`,
+ },
+ {
+ id: 'violating-group-role',
+ summary:
+ 'a single-choice set exposed as a toolbar instead of its adopted group role',
+ facts: groupFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="toolbar" aria-label="Delivery"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-unnamed',
+ summary: 'a radio group with no accessible name',
+ facts: groupFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-description-dangling',
+ summary: 'a described radio group whose relationship points to nothing',
+ facts: groupFacts({description: 'Choose one delivery speed.'}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-describedby="missing"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-description-empty',
+ summary:
+ 'a described radio group whose relationship resolves to empty text',
+ facts: groupFacts({description: 'Choose one delivery speed.'}),
+ html: `<p id="hint"></p><div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-describedby="hint"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-required-group-unexposed',
+ summary: 'a required radio group with no required-state declaration',
+ facts: groupFacts({required: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-required-group-overexposed',
+ summary: 'an optional radio group falsely declared required',
+ facts: groupFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-required="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-invalid-group-unexposed',
+ summary: 'a radio group in error with no invalid-state exposure',
+ facts: groupFacts({invalid: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-invalid-group-overexposed',
+ summary: 'a valid radio group falsely exposed as invalid',
+ facts: groupFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-invalid="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-disabled-unexposed',
+ summary: 'an unavailable radio group exposed as available',
+ facts: groupFacts({disabled: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-disabled-overexposed',
+ summary: 'an available radio group falsely exposed as unavailable',
+ facts: groupFacts({disabled: false}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery" aria-disabled="true"><div role="radio" aria-checked="true">Standard</div><div role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-option-role',
+ summary: 'a direct radio option exposed as a checkbox',
+ facts: optionFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="checkbox" aria-checked="false">Standard</div>`,
+ },
+ {
+ id: 'violating-option-unnamed',
+ summary: 'a radio option with no accessible name',
+ facts: optionFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false"></div>`,
+ },
+ {
+ id: 'violating-option-name-mismatch',
+ summary: 'a radio option whose accessible name replaces its visible label',
+ facts: optionFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" aria-label="Express">Standard</div>`,
+ },
+ {
+ id: 'violating-option-state-mismatch',
+ summary: 'a selected radio option exposed as unchecked',
+ facts: optionFacts({checked: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false">Standard</div>`,
+ },
+ {
+ id: 'violating-option-disabled-unexposed',
+ summary: 'an unavailable radio option exposed as available',
+ facts: optionFacts({disabled: true, operable: false, tabReachable: false}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false">Standard</div>`,
+ },
+ {
+ id: 'violating-option-disabled-overexposed',
+ summary: 'an available radio option falsely exposed as unavailable',
+ facts: optionFacts(),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" aria-disabled="true">Standard</div>`,
+ },
+ {
+ id: 'violating-group-two-selected',
+ summary: 'a radio group exposing two selected options',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true">Standard</div><div data-a11y-related="second" role="radio" aria-checked="true">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-wrong-selected',
+ summary:
+ 'a radio group selecting a different option from the binding state',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="false">Standard</div><div data-a11y-related="second" role="radio" aria-checked="true">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-unexpected-selection',
+ summary: 'a zero-selection radio group exposing one option selected',
+ facts: groupFacts({
+ selection: 'none',
+ optionRelations: ['first', 'second'],
+ selectedOption: null,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-group-wrong-entry',
+ summary: 'a radio group whose sole tab stop is not its selected option',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ tabReachable: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="-1">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="0">Express</div></div><button type="button">After</button>`,
+ },
+ {
+ id: 'violating-group-keyboard-trap',
+ summary: 'a radio group that swallows the Tab key used to leave it',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ tabReachable: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0" onkeydown="if (event.key === 'Tab') event.preventDefault()">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div><button type="button">After</button>`,
+ },
+ {
+ id: 'violating-space-inert',
+ summary: 'a focused radio option that ignores Space',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div>`,
+ },
+ {
+ id: 'violating-space-one-way',
+ summary:
+ 'a native radio group that can select the alternate but cannot return',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><label><input data-a11y-related="first" type="radio" name="delivery" checked onkeydown="if (event.key === ' ') event.preventDefault()">Standard</label><label><input data-a11y-related="second" type="radio" name="delivery">Express</label></div>`,
+ },
+ {
+ id: 'violating-arrow-inert',
+ summary: 'a radio group whose selected option ignores the forward arrow',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ arrowSelection: true,
+ movement: 'horizontal-ltr',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div>`,
+ },
+ {
+ id: 'violating-arrow-one-way',
+ summary: 'a radio group that moves forward but cannot move back',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ tabReachable: true,
+ arrowSelection: true,
+ movement: 'horizontal-ltr',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true" tabindex="0" onkeydown="if (event.key === 'ArrowRight') { this.setAttribute('aria-checked','false'); const next=this.nextElementSibling; next.setAttribute('aria-checked','true'); next.focus(); }">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div>`,
+ },
+ {
+ id: 'violating-space-from-none-inert',
+ summary: 'an unselected radio group whose first option ignores Space',
+ facts: groupFacts({
+ selection: 'none',
+ optionRelations: ['first', 'second'],
+ selectedOption: null,
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="false" tabindex="0">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div>`,
+ },
+ {
+ id: 'violating-arrow-from-none-inert',
+ summary:
+ 'an unselected radio group whose first option ignores the forward arrow',
+ facts: groupFacts({
+ selection: 'none',
+ optionRelations: ['first', 'second'],
+ selectedOption: null,
+ operable: true,
+ tabReachable: true,
+ arrowSelection: true,
+ movement: 'horizontal-ltr',
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="false" tabindex="0">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" tabindex="-1">Express</div></div>`,
+ },
+ {
+ id: 'violating-pointer-down-selection',
+ summary: 'a radio option that selects on pointer down before release',
+ facts: optionFacts({
+ operable: true,
+ tabReachable: true,
+ pointerCancellation: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" tabindex="0" onpointerdown="this.setAttribute('aria-checked','true')">Standard</div>`,
+ },
+ {
+ id: 'violating-pointer-inert',
+ summary: 'a radio group whose alternative ignores pointer activation',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ pointerSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false">Express</div></div>`,
+ },
+ {
+ id: 'violating-pointer-one-way',
+ summary:
+ 'a radio group whose pointer can select an alternative but not return',
+ facts: groupFacts({
+ selection: 'one',
+ optionRelations: ['first', 'second'],
+ selectedOption: 'first',
+ operable: true,
+ pointerSelection: true,
+ }),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radiogroup" aria-label="Delivery"><div data-a11y-related="first" role="radio" aria-checked="true">Standard</div><div data-a11y-related="second" role="radio" aria-checked="false" onclick="this.setAttribute('aria-checked','true'); this.previousElementSibling.setAttribute('aria-checked','false')">Express</div></div>`,
+ },
+ {
+ id: 'violating-option-disabled-operable',
+ summary: 'an unavailable radio option that still changes when clicked',
+ facts: optionFacts({disabled: true, operable: false, tabReachable: true}),
+ html: `<div ${SUBJECT_ATTRIBUTE} role="radio" aria-checked="false" aria-disabled="true" tabindex="0" onclick="this.setAttribute('aria-checked','true')">Standard</div>`,
+ },
+];
+
+export const CONFORMING_RADIO_GROUP_FIXTURES: readonly string[] =
+ RADIO_GROUP_FIXTURES.filter(candidate =>
+ candidate.id.startsWith('conforming-'),
+ ).map(candidate => candidate.id);
+
+export function radioGroupFixture(id: string): RadioGroupFixture {
+ const found = RADIO_GROUP_FIXTURES.find(candidate => candidate.id === id);
+ if (found == null) {
+ throw new Error(`unknown radio-group fixture "${id}"`);
+ }
+ return found;
+}
+
+export const RADIO_GROUP_MUTATIONS: Readonly<
+ Record<string, readonly string[]>
+> = {
+ 'radio-group.group.role-exposed': ['violating-group-role'],
+ 'radio-group.group.name-exposed': ['violating-group-unnamed'],
+ 'radio-group.description.resolvable': [
+ 'violating-group-description-dangling',
+ ],
+ 'radio-group.description.exposed': ['violating-group-description-empty'],
+ 'radio-group.required.declared': ['violating-required-group-unexposed'],
+ 'radio-group.required.not-declared': ['violating-required-group-overexposed'],
+ 'radio-group.invalid.exposed': ['violating-invalid-group-unexposed'],
+ 'radio-group.invalid.not-exposed': ['violating-invalid-group-overexposed'],
+ 'radio-group.group.availability-exposed': [
+ 'violating-group-disabled-unexposed',
+ 'violating-group-disabled-overexposed',
+ ],
+ 'radio-group.option.role-exposed': ['violating-option-role'],
+ 'radio-group.option.name-exposed': ['violating-option-unnamed'],
+ 'radio-group.name.matches-visible-label': ['violating-option-name-mismatch'],
+ 'radio-group.option.state-exposed': ['violating-option-state-mismatch'],
+ 'radio-group.option.availability-exposed': [
+ 'violating-option-disabled-unexposed',
+ 'violating-option-disabled-overexposed',
+ ],
+ 'radio-group.selection.exposed': [
+ 'violating-group-two-selected',
+ 'violating-group-wrong-selected',
+ 'violating-group-unexpected-selection',
+ ],
+ 'radio-group.focus.entry-and-exit': [
+ 'violating-group-wrong-entry',
+ 'violating-group-keyboard-trap',
+ ],
+ 'radio-group.selection.space-round-trip': [
+ 'violating-space-inert',
+ 'violating-space-one-way',
+ ],
+ 'radio-group.selection.arrow-round-trip': [
+ 'violating-arrow-inert',
+ 'violating-arrow-one-way',
+ ],
+ 'radio-group.selection.space-from-none': ['violating-space-from-none-inert'],
+ 'radio-group.selection.arrow-from-none': ['violating-arrow-from-none-inert'],
+ 'radio-group.option.survives-aborted-press': [
+ 'violating-pointer-down-selection',
+ ],
+ 'radio-group.selection.pointer-round-trip': [
+ 'violating-pointer-inert',
+ 'violating-pointer-one-way',
+ ],
+ 'radio-group.option.inoperable': ['violating-option-disabled-operable'],
+};
+
+const MUTATION_FAILURES: Readonly<Record<string, string>> = {
+ 'radio-group.group.role-exposed:violating-group-role':
+ 'this binding adopts the radiogroup role for its group, but the browser reports "toolbar"',
+ 'radio-group.group.name-exposed:violating-group-unnamed':
+ 'the browser computes no accessible name for this single-choice group',
+ 'radio-group.description.resolvable:violating-group-description-dangling':
+ 'aria-describedby points at "missing", which resolves to nothing',
+ 'radio-group.description.exposed:violating-group-description-empty':
+ 'the binding expects the description "Choose one delivery speed.", but the browser computes no accessible description',
+ 'radio-group.required.declared:violating-required-group-unexposed':
+ 'this group is required, but it does not declare aria-required="true"',
+ 'radio-group.required.not-declared:violating-required-group-overexposed':
+ 'this group is not required, but it declares aria-required="true"',
+ 'radio-group.invalid.exposed:violating-invalid-group-unexposed':
+ 'this group is in error, but the browser does not report it as invalid',
+ 'radio-group.invalid.not-exposed:violating-invalid-group-overexposed':
+ 'this group is valid, but the browser reports it as invalid',
+ 'radio-group.group.availability-exposed:violating-group-disabled-unexposed':
+ 'the binding declares this radio group unavailable, but the browser reports it available',
+ 'radio-group.group.availability-exposed:violating-group-disabled-overexposed':
+ 'the binding declares this radio group available, but the browser reports it unavailable',
+ 'radio-group.option.role-exposed:violating-option-role':
+ 'this binding adopts the radio role for its option, but the browser reports "checkbox"',
+ 'radio-group.option.name-exposed:violating-option-unnamed':
+ 'the browser computes no accessible name for this radio option',
+ 'radio-group.name.matches-visible-label:violating-option-name-mismatch':
+ 'the visible label reads "Standard" but the browser computes the accessible name as "Express"',
+ 'radio-group.option.state-exposed:violating-option-state-mismatch':
+ 'this state declares the radio option selected, but the browser reports it unselected',
+ 'radio-group.option.availability-exposed:violating-option-disabled-unexposed':
+ 'the binding declares this radio option unavailable, but the browser reports it available',
+ 'radio-group.option.availability-exposed:violating-option-disabled-overexposed':
+ 'the binding declares this radio option available, but the browser reports it unavailable',
+ 'radio-group.selection.exposed:violating-group-two-selected':
+ 'this state declares exactly one selected option, but the browser exposes 2 selected options',
+ 'radio-group.selection.exposed:violating-group-wrong-selected':
+ 'this state declares "first" selected, but the browser exposes "second" selected',
+ 'radio-group.selection.exposed:violating-group-unexpected-selection':
+ 'this state declares no selected option, but the browser exposes "first" selected',
+ 'radio-group.focus.entry-and-exit:violating-group-wrong-entry':
+ 'Tab entered the radio group at "second" instead of its selected option "first"',
+ 'radio-group.focus.entry-and-exit:violating-group-keyboard-trap':
+ 'Tab did not leave the radio group, so a keyboard user is trapped inside it',
+ 'radio-group.selection.space-round-trip:violating-space-inert':
+ 'pressing Space on "second" left it unselected, so the keyboard cannot choose that option',
+ 'radio-group.selection.space-round-trip:violating-space-one-way':
+ 'pressing Space selected "second", but pressing Space on "first" did not restore the original selection',
+ 'radio-group.selection.arrow-round-trip:violating-arrow-inert':
+ 'pressing ArrowRight from "first" did not move focus and selection to "second"',
+ 'radio-group.selection.arrow-round-trip:violating-arrow-one-way':
+ 'pressing ArrowRight moved to "second", but pressing ArrowLeft did not restore "first"',
+ 'radio-group.selection.space-from-none:violating-space-from-none-inert':
+ 'pressing Space on the first option of an unselected group left it unselected',
+ 'radio-group.selection.arrow-from-none:violating-arrow-from-none-inert':
+ 'pressing ArrowRight from the first option of an unselected group did not move focus and selection to "second"',
+ 'radio-group.option.survives-aborted-press:violating-pointer-down-selection':
+ 'pressing the radio option and releasing away from it still selected it, so the choice cannot be taken back before release',
+ 'radio-group.selection.pointer-round-trip:violating-pointer-inert':
+ 'clicking "second" left it unselected, so a pointer cannot choose that option',
+ 'radio-group.selection.pointer-round-trip:violating-pointer-one-way':
+ 'clicking "second" selected it, but clicking "first" did not restore the original selection',
+ 'radio-group.option.inoperable:violating-option-disabled-operable':
+ 'the user is not meant to change this radio option, but clicking it selected it',
+};
+
+export function expectedRadioGroupMutationFailure(
+ expectation: string,
+ target: string,
+): string {
+ const detail = MUTATION_FAILURES[`${expectation}:${target}`];
+ if (detail == null) {
+ throw new Error(
+ `no expected radio-group failure detail for ${expectation} against ${target}`,
+ );
+ }
+ return detail;
+}
diff --git a/internal/a11y-spec/src/patterns/radio-group.jsdom.test.ts b/internal/a11y-spec/src/patterns/radio-group.jsdom.test.ts
new file mode 100644
index 0000000000..931597183c
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/radio-group.jsdom.test.ts
@@ -0,0 +1,171 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file radio-group.jsdom.test.ts
+ * @input Uses the radio-group contract, fixtures, jsdom harness, and checker
+ * @output DOM-layer positive/negative proof and honest unrun results
+ * @position Contract self-test; proves the contract rather than any component.
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {
+ citeSource,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+} from '../contract';
+import {createJsdomHarness, JSDOM_OBSERVES} from '../harness/jsdom';
+import {RADIO_GROUP_PATTERN} from './radio-group';
+import {
+ CONFORMING_RADIO_GROUP_FIXTURES,
+ expectedRadioGroupMutationFailure,
+ radioGroupFixture,
+ RADIO_GROUP_MUTATIONS,
+ RADIO_GROUP_SUBJECT_SELECTOR,
+ type RadioGroupFixture,
+} from './radio-group.fixtures';
+
+const observableHere = RADIO_GROUP_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+afterEach(() => {
+ document.body.replaceChildren();
+});
+
+async function resultsFor(target: RadioGroupFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const result = await checkAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(RADIO_GROUP_SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${target.id}" marks no subject element`);
+ }
+ return createJsdomHarness({
+ subject,
+ related: Object.fromEntries(
+ target.facts.optionRelations.map(name => {
+ const related = container.querySelector(
+ `[data-a11y-related="${name}"]`,
+ );
+ if (related == null) {
+ throw new Error(
+ `fixture "${target.id}" marks no related option "${name}"`,
+ );
+ }
+ return [name, related];
+ }),
+ ),
+ });
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return result.results;
+}
+
+function resultFor(
+ results: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const found = results.find(result => result.expectation === id);
+ if (found == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return found;
+}
+
+describe('radio-group contract — completeness', () => {
+ it('answers every checklist dimension', () => {
+ expect(unansweredDimensions(RADIO_GROUP_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation a deliberately violating fixture', () => {
+ const missing = RADIO_GROUP_PATTERN.expectations
+ .filter(
+ expectation =>
+ (RADIO_GROUP_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id);
+ expect(missing).toEqual([]);
+ });
+
+ it('has an expectation for every mutation entry', () => {
+ const ids = new Set(
+ RADIO_GROUP_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(
+ Object.keys(RADIO_GROUP_MUTATIONS).filter(id => !ids.has(id)),
+ ).toEqual([]);
+ });
+
+ it('names every fixture recorded as a mutation', () => {
+ for (const fixtures of Object.values(RADIO_GROUP_MUTATIONS)) {
+ for (const id of fixtures) {
+ expect(() => radioGroupFixture(id)).not.toThrow();
+ }
+ }
+ });
+});
+
+describe('radio-group contract — jsdom evidence boundary', () => {
+ it('runs DOM expectations and reports higher layers as unrun', async () => {
+ const results = await resultsFor(radioGroupFixture('conforming-group'));
+ expect(results.some(result => result.status === 'unrun')).toBe(true);
+ expect(results.filter(result => result.status === 'fail')).toEqual([]);
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = RADIO_GROUP_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_RADIO_GROUP_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply)',
+ async name => {
+ const result = resultFor(await resultsFor(radioGroupFixture(name)), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((RADIO_GROUP_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = resultFor(await resultsFor(radioGroupFixture(name)), id);
+ expect(result.status, `${id} against ${name}`).toBe('fail');
+ expect(result.detail ?? '').toBe(
+ expectedRadioGroupMutationFailure(id, name),
+ );
+ },
+ );
+
+ it('carries its id and primary source into failure output', async () => {
+ const [fixtureId] = RADIO_GROUP_MUTATIONS[id] ?? [];
+ if (fixtureId == null) {
+ throw new Error(`no mutation fixture for ${id}`);
+ }
+ const result = resultFor(
+ await resultsFor(radioGroupFixture(fixtureId)),
+ id,
+ );
+ expect(result.description).toContain(id);
+ expect(result.description).toContain(citeSource(expectation.sources[0]));
+ expect(result.description).toBe(describeExpectation(expectation));
+ });
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/radio-group.ts b/internal/a11y-spec/src/patterns/radio-group.ts
new file mode 100644
index 0000000000..9ec1b90047
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/radio-group.ts
@@ -0,0 +1,1227 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file radio-group.ts
+ * @input Uses ../contract (definePattern and the expectation vocabulary)
+ * @output RADIO_GROUP_PATTERN and RadioGroupStateFacts
+ * @position Reusable accessibility contract for a radio group and its options.
+ *
+ * The contract covers direct radio groups and the role/state portion of radio
+ * choices inside menus. Menu-owned movement, focus, activation, and dismissal
+ * stay with the Menu pattern. Component callbacks, form participation,
+ * composition, and styling stay in component-local tests.
+ */
+
+import {
+ definePattern,
+ type ApgRequirement,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+import type {Key} from '../harness';
+import {saysInOrder, spokenWords} from '../spoken';
+
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/radio/';
+
+const APG_SINGLE_SELECTION: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'A radio group is a set of checkable buttons, known as radio buttons, where no more than one of the buttons can be checked at a time.',
+ url: APG_URL,
+};
+const APG_SPACE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'Space checks the focused radio button if it is not already checked.',
+ url: `${APG_URL}#keyboardinteraction`,
+};
+const APG_TAB_ENTRY: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'Tab and Shift + Tab move focus into and out of the radio group; entry targets the checked button, or the first button when none is checked.',
+ url: `${APG_URL}#keyboardinteraction`,
+};
+const APG_ARROW_SELECTION: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'Right/Down move focus to and check the next radio button; Left/Up do the same for the previous radio button, with wrapping at each end.',
+ url: `${APG_URL}#keyboardinteraction`,
+};
+const APG_GROUP_ROLE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'The radio buttons are contained in or owned by an element with role radiogroup.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_OPTION_ROLE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement: 'Each radio button element has role radio.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_SELECTION_STATE: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'A checked radio has aria-checked set to true, and an unchecked radio has aria-checked set to false.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_OPTION_NAME: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'Each radio is labelled by its content, a visible label referenced by aria-labelledby, or aria-label.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_GROUP_NAME: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'The radiogroup has a visible label referenced by aria-labelledby or a label specified with aria-label.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+const APG_DESCRIPTION: ApgRequirement = {
+ standard: 'apg',
+ pattern: 'radio',
+ requirement:
+ 'Additional information about the radio group or a radio button is referenced by that element with aria-describedby.',
+ url: `${APG_URL}#wai-ariaroles,states,andproperties`,
+};
+
+const WCAG_1_3_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '1.3.1',
+ name: 'Info and Relationships',
+ level: 'A',
+ url: `${UNDERSTANDING}/info-and-relationships.html`,
+};
+const WCAG_2_1_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.1.1',
+ name: 'Keyboard',
+ level: 'A',
+ url: `${UNDERSTANDING}/keyboard.html`,
+};
+const WCAG_2_1_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.1.2',
+ name: 'No Keyboard Trap',
+ level: 'A',
+ url: `${UNDERSTANDING}/no-keyboard-trap.html`,
+};
+const WCAG_2_4_3: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.4.3',
+ name: 'Focus Order',
+ level: 'A',
+ url: `${UNDERSTANDING}/focus-order.html`,
+};
+const WCAG_2_5_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.5.2',
+ name: 'Pointer Cancellation',
+ level: 'A',
+ url: `${UNDERSTANDING}/pointer-cancellation.html`,
+};
+const WCAG_2_5_3: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.5.3',
+ name: 'Label in Name',
+ level: 'A',
+ url: `${UNDERSTANDING}/label-in-name.html`,
+};
+const WCAG_3_3_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '3.3.2',
+ name: 'Labels or Instructions',
+ level: 'A',
+ url: `${UNDERSTANDING}/labels-or-instructions.html`,
+};
+const WCAG_4_1_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: `${UNDERSTANDING}/name-role-value.html`,
+};
+
+export type RadioGroupRole = 'radiogroup' | 'group' | 'radio' | 'menuitemradio';
+
+export interface RadioGroupStateFacts {
+ readonly part: 'group' | 'option';
+ readonly role: RadioGroupRole;
+ readonly checked: boolean | null;
+ readonly selection: 'none' | 'one' | null;
+ /** Relation names for every option in a group-level fixture or binding. */
+ readonly optionRelations: readonly string[];
+ /** The one relation expected to be selected, or null for a zero-selection state. */
+ readonly selectedOption: string | null;
+ readonly disabled: boolean | null;
+ readonly description: string | null;
+ readonly required: boolean;
+ readonly invalid: boolean;
+ readonly operable: boolean;
+ /** Whether the option or an option in the group is expected in page Tab order. */
+ readonly tabReachable: boolean;
+ /** Whether this direct group owns Space selection rather than delegating it. */
+ readonly spaceSelection: boolean;
+ /** Whether this group owns pointer selection rather than delegating it. */
+ readonly pointerSelection: boolean;
+ /** Whether this direct group owns directional selection rather than delegating it. */
+ readonly arrowSelection: boolean;
+ /** Whether this option owns direct pointer cancellation rather than delegating it. */
+ readonly pointerCancellation: boolean;
+ readonly visibleLabel: boolean;
+ readonly movement: 'none' | 'horizontal-ltr' | 'horizontal-rtl' | 'vertical';
+}
+
+function sameWords(actual: string, expected: string): boolean {
+ const actualWords = spokenWords(actual);
+ const expectedWords = spokenWords(expected);
+ return (
+ actualWords.length === expectedWords.length &&
+ actualWords.every((word, index) => word === expectedWords[index])
+ );
+}
+
+function movementKeys(
+ movement: RadioGroupStateFacts['movement'],
+): readonly [Key, Key] {
+ switch (movement) {
+ case 'horizontal-ltr':
+ return ['ArrowRight', 'ArrowLeft'];
+ case 'horizontal-rtl':
+ return ['ArrowLeft', 'ArrowRight'];
+ case 'vertical':
+ return ['ArrowDown', 'ArrowUp'];
+ case 'none':
+ throw new Error(
+ 'arrow movement ran for a state owned by another pattern',
+ );
+ }
+}
+
+export const RADIO_GROUP_PATTERN: PatternContract<RadioGroupStateFacts> =
+ definePattern<RadioGroupStateFacts>({
+ pattern: 'radio-group',
+ url: 'https://www.w3.org/WAI/ARIA/apg/patterns/radio/',
+ scope:
+ 'A named single-choice group and its radio-bearing options expose their adopted roles, selection, availability, and supporting relationships; direct radio groups preserve one-stop keyboard entry and selection movement while menu movement stays with Menu.',
+ expectations: [
+ {
+ id: 'radio-group.group.role-exposed',
+ outcome:
+ 'The browser exposes the group role this single-choice composition adopts, so its options are presented as one related set.',
+ sources: [WCAG_1_3_1, WCAG_4_1_2, APG_GROUP_ROLE],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates the group container',
+ test: facts => facts.part === 'group',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {role} = await subject.computed();
+ if (role !== facts.role) {
+ throw new Error(
+ role == null
+ ? `the browser exposes no role for this ${facts.role} group`
+ : `this binding adopts the ${facts.role} role for its group, but the browser reports "${role}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.role-exposed',
+ outcome:
+ 'The browser exposes the radio-bearing role this option adopts, so the user knows it belongs to a single-choice set.',
+ sources: [WCAG_1_3_1, WCAG_4_1_2, APG_OPTION_ROLE],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates one option in the group',
+ test: facts => facts.part === 'option',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {role} = await subject.computed();
+ if (role !== facts.role) {
+ throw new Error(
+ role == null
+ ? `the browser exposes no role for this ${facts.role} option`
+ : `this binding adopts the ${facts.role} role for its option, but the browser reports "${role}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.name-exposed',
+ outcome:
+ 'Each radio option has an accessible name, so the user can identify the choice before selecting it.',
+ sources: [WCAG_3_3_2, WCAG_4_1_2, APG_OPTION_NAME],
+ covers: ['4.1.2-name-role-value', '3.3.2-labels-or-instructions'],
+ appliesWhen: {
+ condition: 'the binding designates one option in the group',
+ test: facts => facts.part === 'option',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {name} = await subject.computed();
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this radio option',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.name.matches-visible-label',
+ outcome:
+ 'The accessible name contains the visible label, so a speech-input user can say the option or group they can read.',
+ sources: [WCAG_2_5_3],
+ covers: ['2.5.3-label-in-name'],
+ appliesWhen: {
+ condition: 'the binding renders the radio group pattern',
+ test: () => true,
+ },
+ evidenceLayer: 'accessibility-tree',
+ alsoNeeds: ['real-browser'],
+ enforcement: 'required',
+ run: async ({subject, notApplicable}) => {
+ const visible = await subject.visibleLabelText();
+ if (visible == null) {
+ return notApplicable(
+ 'this state renders no label a person can read, so there are no visible words for speech input',
+ );
+ }
+ const {name} = await subject.computed();
+ if (!saysInOrder(spokenWords(name), spokenWords(visible))) {
+ throw new Error(
+ `the visible label reads "${visible}" but the browser computes the accessible name as "${name}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.state-exposed',
+ outcome:
+ 'The browser exposes whether each radio option is selected, and that state matches the binding.',
+ sources: [WCAG_4_1_2, APG_SELECTION_STATE],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates one option in the group',
+ test: facts => facts.part === 'option',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ if (facts.checked == null) {
+ throw new Error(
+ 'option-state expectation ran without a declared checked state',
+ );
+ }
+ const {checked} = await subject.computed();
+ const expected = facts.checked ? 'true' : 'false';
+ if (checked !== expected) {
+ throw new Error(
+ checked == null
+ ? 'the browser exposes no selected state for this radio option'
+ : `this state declares the radio option ${facts.checked ? 'selected' : 'unselected'}, but the browser reports it ${checked === 'true' ? 'selected' : 'unselected'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.exposed',
+ outcome:
+ 'The group exposes no more than one selected option, and the selected option matches the binding state.',
+ sources: [
+ WCAG_1_3_1,
+ WCAG_4_1_2,
+ APG_SINGLE_SELECTION,
+ APG_SELECTION_STATE,
+ ],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition:
+ 'the binding designates a group state and names every option relation',
+ test: facts => facts.part === 'group' && facts.selection != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ const selected: string[] = [];
+ for (const relation of facts.optionRelations) {
+ const {checked} = await (
+ await harness.related(relation)
+ ).computed();
+ if (checked === 'true') {
+ selected.push(relation);
+ } else if (checked !== 'false') {
+ throw new Error(
+ `the browser exposes no selected state for option relation "${relation}"`,
+ );
+ }
+ }
+
+ if (facts.selection === 'none') {
+ if (selected.length > 0) {
+ throw new Error(
+ `this state declares no selected option, but the browser exposes ${selected.map(name => `"${name}"`).join(', ')} selected`,
+ );
+ }
+ return;
+ }
+
+ if (selected.length !== 1) {
+ throw new Error(
+ `this state declares exactly one selected option, but the browser exposes ${selected.length} selected options`,
+ );
+ }
+ if (selected[0] !== facts.selectedOption) {
+ throw new Error(
+ `this state declares "${facts.selectedOption}" selected, but the browser exposes "${selected[0]}" selected`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.focus.entry-and-exit',
+ outcome:
+ 'Tab enters a direct radio group at its selected option, or its first option when none is selected, and Tab again leaves the group.',
+ sources: [WCAG_2_1_1, WCAG_2_1_2, WCAG_2_4_3, APG_TAB_ENTRY],
+ covers: [
+ '2.1.1-keyboard',
+ '2.1.2-no-keyboard-trap',
+ '2.4.3-focus-order',
+ ],
+ appliesWhen: {
+ condition:
+ 'the binding designates a direct radio group that participates in page Tab order',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.tabReachable &&
+ facts.selection != null,
+ },
+ evidenceLayer: 'real-browser',
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ await harness.resetFocus();
+ for (
+ let step = 0;
+ step < 10 && !(await subject.containsFocus());
+ step += 1
+ ) {
+ await harness.press('Tab');
+ }
+ if (!(await subject.containsFocus())) {
+ throw new Error(
+ '10 presses of Tab from the start of the document never entered the radio group',
+ );
+ }
+
+ const focused: string[] = [];
+ for (const relation of facts.optionRelations) {
+ if (await (await harness.related(relation)).isFocused()) {
+ focused.push(relation);
+ }
+ }
+ const expected = facts.selectedOption ?? facts.optionRelations[0];
+ if (focused.length !== 1 || focused[0] !== expected) {
+ throw new Error(
+ `Tab entered the radio group at ${focused.length === 0 ? 'no named option' : focused.map(name => `"${name}"`).join(', ')} instead of ${facts.selectedOption == null ? `its first option "${expected}"` : `its selected option "${expected}"`}`,
+ );
+ }
+
+ await harness.press('Tab');
+ if (await subject.containsFocus()) {
+ throw new Error(
+ 'Tab did not leave the radio group, so a keyboard user is trapped inside it',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.space-round-trip',
+ outcome:
+ 'Space selects a focused unselected option, and selecting the original option restores the starting choice.',
+ sources: [WCAG_2_1_1, APG_SPACE],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'an operable direct radio group starts with exactly one selected option and at least one alternative',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.spaceSelection &&
+ facts.selection === 'one' &&
+ facts.selectedOption != null &&
+ facts.optionRelations.some(
+ relation => relation !== facts.selectedOption,
+ ),
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ const originalName = facts.selectedOption;
+ const alternateName = facts.optionRelations.find(
+ relation => relation !== originalName,
+ );
+ if (originalName == null || alternateName == null) {
+ throw new Error(
+ 'Space expectation ran without an original and alternate option',
+ );
+ }
+ const original = await harness.related(originalName);
+ const alternate = await harness.related(alternateName);
+
+ await alternate.focus();
+ await harness.press('Space');
+ const alternateAfter = await alternate.computed();
+ const originalAfter = await original.computed();
+ if (
+ alternateAfter.checked !== 'true' ||
+ originalAfter.checked !== 'false'
+ ) {
+ throw new Error(
+ `pressing Space on "${alternateName}" left it ${alternateAfter.checked === 'true' ? 'selected' : 'unselected'}, so the keyboard cannot choose that option`,
+ );
+ }
+
+ await original.focus();
+ await harness.press('Space');
+ const originalBack = await original.computed();
+ const alternateBack = await alternate.computed();
+ if (
+ originalBack.checked !== 'true' ||
+ alternateBack.checked !== 'false'
+ ) {
+ throw new Error(
+ `pressing Space selected "${alternateName}", but pressing Space on "${originalName}" did not restore the original selection`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.arrow-round-trip',
+ outcome:
+ 'The adopted directional arrows move focus and selection to an adjacent option and back without losing either state.',
+ sources: [WCAG_2_1_1, APG_ARROW_SELECTION],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'an operable direct radio group adopts horizontal or vertical arrow movement and starts with one selected option',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.arrowSelection &&
+ facts.selection === 'one' &&
+ facts.optionRelations.length > 1,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ const originalName = facts.selectedOption;
+ if (originalName == null) {
+ throw new Error(
+ 'arrow expectation ran without a selected option relation',
+ );
+ }
+ const originalIndex = facts.optionRelations.indexOf(originalName);
+ const nextName =
+ facts.optionRelations[
+ (originalIndex + 1) % facts.optionRelations.length
+ ];
+ if (originalIndex < 0 || nextName == null) {
+ throw new Error(
+ 'arrow expectation ran without a complete option order',
+ );
+ }
+ const [forwardKey, backwardKey] = movementKeys(facts.movement);
+ const original = await harness.related(originalName);
+ const next = await harness.related(nextName);
+
+ await original.focus();
+ await harness.press(forwardKey);
+ const nextAfter = await next.computed();
+ const originalAfter = await original.computed();
+ if (
+ !(await next.isFocused()) ||
+ nextAfter.checked !== 'true' ||
+ originalAfter.checked !== 'false'
+ ) {
+ throw new Error(
+ `pressing ${forwardKey} from "${originalName}" did not move focus and selection to "${nextName}"`,
+ );
+ }
+
+ await harness.press(backwardKey);
+ const originalBack = await original.computed();
+ const nextBack = await next.computed();
+ if (
+ !(await original.isFocused()) ||
+ originalBack.checked !== 'true' ||
+ nextBack.checked !== 'false'
+ ) {
+ throw new Error(
+ `pressing ${forwardKey} moved to "${nextName}", but pressing ${backwardKey} did not restore "${originalName}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.space-from-none',
+ outcome:
+ 'When no option starts selected, Space selects the first option that receives group entry focus.',
+ sources: [WCAG_2_1_1, APG_SPACE, APG_TAB_ENTRY],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'an operable direct radio group starts with no selected option and owns Space selection',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.spaceSelection &&
+ facts.selection === 'none' &&
+ facts.optionRelations.length > 0,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ const firstName = facts.optionRelations[0];
+ if (firstName == null) {
+ throw new Error(
+ 'Space-from-none expectation ran without a first option relation',
+ );
+ }
+ const first = await harness.related(firstName);
+ await first.focus();
+ await harness.press('Space');
+ if ((await first.computed()).checked !== 'true') {
+ throw new Error(
+ 'pressing Space on the first option of an unselected group left it unselected',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.arrow-from-none',
+ outcome:
+ 'When no option starts selected, the adopted forward arrow moves from the entry option and selects the next option.',
+ sources: [WCAG_2_1_1, APG_ARROW_SELECTION, APG_TAB_ENTRY],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'an operable direct radio group starts with no selected option and owns directional selection',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.arrowSelection &&
+ facts.selection === 'none' &&
+ facts.optionRelations.length > 1,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'required',
+ run: async ({harness, facts}) => {
+ const firstName = facts.optionRelations[0];
+ const nextName = facts.optionRelations[1];
+ if (firstName == null || nextName == null) {
+ throw new Error(
+ 'arrow-from-none expectation ran without first and next option relations',
+ );
+ }
+ const [forwardKey] = movementKeys(facts.movement);
+ const first = await harness.related(firstName);
+ const next = await harness.related(nextName);
+ await first.focus();
+ await harness.press(forwardKey);
+ const firstAfter = await first.computed();
+ const nextAfter = await next.computed();
+ if (
+ !(await next.isFocused()) ||
+ firstAfter.checked !== 'false' ||
+ nextAfter.checked !== 'true'
+ ) {
+ throw new Error(
+ `pressing ${forwardKey} from the first option of an unselected group did not move focus and selection to "${nextName}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.availability-exposed',
+ outcome:
+ 'Each radio option exposes whether it is available, without presenting an unavailable choice as actionable or an available choice as disabled.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding designates one option in the group',
+ test: facts => facts.part === 'option',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {disabled} = await subject.computed();
+ if (disabled !== facts.disabled) {
+ throw new Error(
+ `the binding declares this radio option ${facts.disabled ? 'unavailable' : 'available'}, but the browser reports it ${disabled ? 'unavailable' : 'available'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.survives-aborted-press',
+ outcome:
+ 'A press released away from an operable radio option leaves the selection unchanged, so an accidental press can be taken back.',
+ sources: [WCAG_2_5_2],
+ covers: ['2.5.2-pointer-cancellation'],
+ appliesWhen: {
+ condition: 'this option is operable by pointer',
+ test: facts => facts.part === 'option' && facts.pointerCancellation,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ const before = (await subject.computed()).checked;
+ await harness.abortedPress(subject);
+ const after = (await subject.computed()).checked;
+ if (after !== before) {
+ throw new Error(
+ 'pressing the radio option and releasing away from it still selected it, so the choice cannot be taken back before release',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.selection.pointer-round-trip',
+ outcome:
+ 'A pointer selects an alternative option, and selecting the original option restores the starting choice.',
+ sources: [APG_SINGLE_SELECTION, WCAG_4_1_2],
+ wcagOutcome:
+ 'The selected state exposed under 4.1.2 stays synchronized with the state the user changes.',
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition:
+ 'an operable group starts with exactly one selected option and at least one alternative',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.pointerSelection &&
+ facts.selection === 'one' &&
+ facts.selectedOption != null &&
+ facts.optionRelations.some(
+ relation => relation !== facts.selectedOption,
+ ),
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'advisory',
+ advisoryBecause:
+ 'APG defines the selected-state invariant but does not independently require pointer activation, and no current Astryx radio-group record adopts pointer selection as a gate.',
+ run: async ({harness, facts}) => {
+ const originalName = facts.selectedOption;
+ const alternateName = facts.optionRelations.find(
+ relation => relation !== originalName,
+ );
+ if (originalName == null || alternateName == null) {
+ throw new Error(
+ 'pointer expectation ran without an original and alternate option',
+ );
+ }
+ const original = await harness.related(originalName);
+ const alternate = await harness.related(alternateName);
+
+ await harness.click(alternate);
+ const alternateAfter = await alternate.computed();
+ const originalAfter = await original.computed();
+ if (
+ alternateAfter.checked !== 'true' ||
+ originalAfter.checked !== 'false'
+ ) {
+ throw new Error(
+ `clicking "${alternateName}" left it ${alternateAfter.checked === 'true' ? 'selected' : 'unselected'}, so a pointer cannot choose that option`,
+ );
+ }
+
+ await harness.click(original);
+ const originalBack = await original.computed();
+ const alternateBack = await alternate.computed();
+ if (
+ originalBack.checked !== 'true' ||
+ alternateBack.checked !== 'false'
+ ) {
+ throw new Error(
+ `clicking "${alternateName}" selected it, but clicking "${originalName}" did not restore the original selection`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.option.inoperable',
+ outcome:
+ 'A radio option the binding marks inoperable does not change through pointer or owned keyboard input.',
+ sources: [APG_SINGLE_SELECTION, WCAG_4_1_2],
+ wcagOutcome:
+ 'The selected state exposed under 4.1.2 does not claim a change the unavailable option did not accept.',
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this radio option is not meant to change',
+ test: facts => facts.part === 'option' && !facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'advisory',
+ advisoryBecause:
+ 'The standards require accurate exposed state, but no current Astryx radio-group record adopts inertness for every unavailable option as a universal gate.',
+ run: async ({harness, subject, facts}) => {
+ const before = (await subject.computed()).checked;
+ await harness.click(subject, {ignoreAvailability: true});
+ const afterClick = (await subject.computed()).checked;
+ if (afterClick !== before) {
+ throw new Error(
+ `the user is not meant to change this radio option, but clicking it ${afterClick === 'true' ? 'selected' : 'unselected'} it`,
+ );
+ }
+ if (!facts.tabReachable || facts.role !== 'radio') {
+ return;
+ }
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ return;
+ }
+ await harness.press('Space');
+ const afterSpace = (await subject.computed()).checked;
+ if (afterSpace !== before) {
+ throw new Error(
+ `the user is not meant to change this radio option, but pressing Space ${afterSpace === 'true' ? 'selected' : 'unselected'} it`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.group.name-exposed',
+ outcome:
+ 'The single-choice group has an accessible name, so the user knows what decision its options belong to.',
+ sources: [WCAG_3_3_2, WCAG_4_1_2, APG_GROUP_NAME],
+ covers: ['4.1.2-name-role-value', '3.3.2-labels-or-instructions'],
+ appliesWhen: {
+ condition: 'the binding designates the group container',
+ test: facts => facts.part === 'group',
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {name} = await subject.computed();
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this single-choice group',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.description.resolvable',
+ outcome:
+ 'Every piece of supporting text the group or option points at exists, so its explanation is not silently dropped.',
+ sources: [WCAG_1_3_1, APG_DESCRIPTION],
+ covers: ['1.3.1-info-and-relationships'],
+ appliesWhen: {
+ condition: 'the binding renders supporting text for this state',
+ test: facts => facts.description != null,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const expected = facts.description;
+ if (expected == null) {
+ throw new Error(
+ 'description expectation ran without expected text',
+ );
+ }
+ const attribute = await subject.attribute('aria-describedby');
+ const ids = (attribute ?? '').split(/\s+/).filter(Boolean);
+ if (ids.length === 0) {
+ throw new Error(
+ 'the binding renders supporting text for this state, but the subject has no aria-describedby relationship',
+ );
+ }
+ const targets = await subject.idReferences('aria-describedby');
+ const dangling = ids.filter((_, index) => targets[index] == null);
+ if (dangling.length > 0) {
+ throw new Error(
+ `aria-describedby points at ${dangling.map(id => `"${id}"`).join(', ')}, which ${dangling.length === 1 ? 'resolves' : 'resolve'} to nothing`,
+ );
+ }
+ const attached = targets
+ .filter((text): text is string => text != null)
+ .join(' ')
+ .replace(/\s+/g, ' ')
+ .trim();
+ if (attached !== expected) {
+ throw new Error(
+ `the binding expects the description "${expected}", but aria-describedby resolves to "${attached}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.description.exposed',
+ outcome:
+ 'The browser exposes the intended supporting text as the group or option description, not only as nearby markup.',
+ sources: [WCAG_4_1_2, APG_DESCRIPTION],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding renders supporting text for this state',
+ test: facts => facts.description != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const expected = facts.description;
+ if (expected == null) {
+ throw new Error(
+ 'description expectation ran without expected text',
+ );
+ }
+ const {description} = await subject.computed();
+ if (!sameWords(description, expected)) {
+ throw new Error(
+ description.trim() === ''
+ ? `the binding expects the description "${expected}", but the browser computes no accessible description`
+ : `the binding expects the description "${expected}", but the browser computes "${description}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.required.declared',
+ outcome:
+ 'A radio group that requires a choice declares that requirement for accessibility consumers.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this direct radio group requires a choice',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.required,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if ((await subject.attribute('aria-required')) !== 'true') {
+ throw new Error(
+ 'this group is required, but it does not declare aria-required="true"',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.required.not-declared',
+ outcome:
+ 'A radio group that does not require a choice does not expose a false required state.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this direct radio group does not require a choice',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ !facts.required,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if ((await subject.attribute('aria-required')) === 'true') {
+ throw new Error(
+ 'this group is not required, but it declares aria-required="true"',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.invalid.exposed',
+ outcome:
+ 'A radio group in error is exposed as invalid, so the user can identify the choice that needs attention.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this direct radio group is in error',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ facts.invalid,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if (!(await subject.computed()).invalid) {
+ throw new Error(
+ 'this group is in error, but the browser does not report it as invalid',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.invalid.not-exposed',
+ outcome: 'A valid radio group does not expose a false invalid state.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'this direct radio group is valid',
+ test: facts =>
+ facts.part === 'group' &&
+ facts.role === 'radiogroup' &&
+ !facts.invalid,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if ((await subject.computed()).invalid) {
+ throw new Error(
+ 'this group is valid, but the browser reports it as invalid',
+ );
+ }
+ },
+ },
+ {
+ id: 'radio-group.group.availability-exposed',
+ outcome:
+ 'When a binding exposes availability on the radio group itself, the browser reports that exact state.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition:
+ 'the binding designates a group whose availability is exposed on the group node',
+ test: facts => facts.part === 'group' && facts.disabled != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {disabled} = await subject.computed();
+ if (disabled !== facts.disabled) {
+ throw new Error(
+ `the binding declares this radio group ${facts.disabled ? 'unavailable' : 'available'}, but the browser reports it ${disabled ? 'unavailable' : 'available'}`,
+ );
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'the binding component and caller content',
+ verifiedBy:
+ 'component suites for decorative indicators and caller-content review, plus the repository axe audit',
+ reason:
+ 'The contract observes group and option semantics; each adopter owns the graphics and content rendered around those nodes.',
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'the binding component and composing form or menu',
+ verifiedBy:
+ 'component DOM tests for labels, descriptions, field status, and menu containment outside the bound subjects',
+ reason:
+ 'This contract covers group/option roles, selected relationships, and authored descriptions; surrounding form and menu structure stays with its composition owner.',
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'the binding component and composing page',
+ verifiedBy: 'component DOM-order tests and page-level review',
+ reason:
+ 'The reading order around the group and any rich option content depends on the concrete component and page composition.',
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'the composing form and caller content',
+ verifiedBy:
+ 'form integration review when a choice collects information about the user',
+ reason:
+ 'Radio groups choose among caller-defined values and do not themselves assign the autocomplete purposes listed by the criterion.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'the binding component and theme',
+ verifiedBy: 'the repository visual gate and component review',
+ reason:
+ 'Whether selection is conveyed by color alone is a rendered-pixel fact, not a semantic-tree result.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'the binding component and theme',
+ verifiedBy: 'the repository axe audit and visual gate',
+ reason:
+ 'Text contrast depends on resolved colors over each adopter’s actual background.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'the binding component and theme',
+ verifiedBy: 'the repository axe audit and visual gate',
+ reason:
+ 'Radio indicators, selected surfaces, boundaries, and focus indicators require rendered-color measurement.',
+ },
+ '2.1.1-keyboard': {
+ owner: 'the Menu pattern, the binding component, and caller content',
+ verifiedBy:
+ 'menu keyboard suites plus component-local tests for optional or component-specific commands',
+ reason:
+ 'This contract covers direct radio-group entry, Space, and adopted arrow movement. Menuitemradio movement and activation belong to Menu, and caller-composed controls keep their own keyboard contracts.',
+ coversRemainderOnly: true,
+ },
+ '2.1.2-no-keyboard-trap': {
+ owner: 'the Menu pattern and composing page',
+ verifiedBy:
+ 'menu focus/dismissal suites and page-level sequential-focus review',
+ reason:
+ 'This contract proves Tab can leave a direct radio group; menu composites and surrounding page focus remain with their owners.',
+ coversRemainderOnly: true,
+ },
+ '2.4.2-page-titled': {
+ owner: 'the page',
+ verifiedBy: 'page-level review',
+ reason:
+ 'A radio group rendered in isolation does not own the document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'the Menu pattern and composing page',
+ verifiedBy:
+ 'menu focus suites and page-level review of focus before and after the group',
+ reason:
+ 'This contract proves the direct group entry target and one-stop exit; the larger sequence and menu composite order remain outside it.',
+ coversRemainderOnly: true,
+ },
+ '2.4.4-link-purpose': {
+ owner: 'caller content',
+ verifiedBy: 'review of any links composed into option content',
+ reason: 'The adopted radio-group pattern has no link part.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'caller content and component review',
+ verifiedBy:
+ 'content review of group labels, option labels, and instructions',
+ reason:
+ 'This contract proves names exist and visible words remain in those names; whether the wording describes the choice is a content judgement.',
+ },
+ '2.4.7-focus-visible': {
+ owner:
+ 'architecture:interaction-modality, the binding component, and the theme',
+ verifiedBy: 'component focus-ring tests and the repository visual gate',
+ reason:
+ 'A visible focus indicator is a painted result owned by each adopter’s actual focus surface.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'the composing page or overlay',
+ verifiedBy: 'real-browser layout and overlay review',
+ reason:
+ 'Whether focused radio content is obscured depends on surrounding authored content.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'the binding component and caller-composed interactive content',
+ verifiedBy:
+ 'component pointer suites for any target outside the bound radio option',
+ reason:
+ 'This contract proves cancellation on the radio option itself; nested or enlarged component surfaces retain their own pointer behavior.',
+ coversRemainderOnly: true,
+ },
+ '2.5.3-label-in-name': {
+ owner: 'the binding component and caller content',
+ verifiedBy:
+ 'component-specific label tests and content review for visible words outside the bound label',
+ reason:
+ 'This contract compares the bound group or option name with its rendered label; caller-composed adjacent text remains outside the semantic label relation.',
+ coversRemainderOnly: true,
+ },
+ '2.5.8-target-size': {
+ owner: 'the binding component and composing page',
+ verifiedBy:
+ 'real-browser geometry measurement with neighbouring-target spacing and manual exception review',
+ reason:
+ 'Target-size applicability depends on rendered geometry and neighbouring targets in the concrete composition.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'the page',
+ verifiedBy: 'page-level review',
+ reason:
+ 'A component rendered in isolation does not own the document language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'the caller',
+ verifiedBy:
+ 'integration review of navigation or page rewrites caused by the selection callback',
+ reason:
+ 'The contract keeps focus and selection coherent inside the group; any wider context change caused by the caller is outside the component.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'the design system and composing application',
+ verifiedBy:
+ 'cross-component and cross-page review of equivalent single-choice functions',
+ reason:
+ 'Consistency is a comparison across usages, not a property one isolated binding can establish.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'the binding component',
+ verifiedBy: 'component status-message tests and visible-text review',
+ reason:
+ 'This contract verifies invalid-state exposure; the textual identification of an error is composed around the group.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'the binding component and caller content',
+ verifiedBy:
+ 'component tests for persistent visible labels and content review for instructions needed to make the choice',
+ reason:
+ 'This contract proves accessible names exist; visual persistence and instructional sufficiency remain presentation and content outcomes.',
+ coversRemainderOnly: true,
+ },
+ '4.1.2-name-role-value': {
+ owner:
+ 'the binding component and separate contracts for composed parts',
+ verifiedBy:
+ 'component-specific tests for states and values not owned by radio-group semantics',
+ reason:
+ 'This contract covers group/option role, name, selection, availability, requiredness, invalidity, and descriptions; component-specific busy, form, and composed-control states stay local.',
+ coversRemainderOnly: true,
+ },
+ '4.1.3-status-messages': {
+ owner: 'the binding component and AST-009 for any claimed announcement',
+ verifiedBy:
+ 'component status-message tests plus real-AT evidence when the claim is about spoken or braille output',
+ reason:
+ 'Validation and async status messages are composed around the group, and their announcement is not observable in this contract.',
+ },
+ 'apg-interaction': {
+ owner: 'the Menu pattern and each binding’s current component contract',
+ verifiedBy:
+ 'menu keyboard suites and component-local tests for any optional interaction the owner adopts',
+ reason:
+ 'This contract covers direct-group Space and directional arrows. DropdownMenu radio movement belongs to Menu. Home and End are not required by the APG radio-group pattern and no current Astryx record adopts them as shared radio-group behavior.',
+ coversRemainderOnly: true,
+ },
+ 'forced-colors': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ 'component forced-colors suites and manual Windows High Contrast review',
+ reason:
+ 'Forced-colors output is a paint result rather than semantic or interaction evidence.',
+ },
+ 'reduced-motion': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ 'component transition tests and the repository visual gate under reduced motion',
+ reason:
+ 'Motion is a rendered result over time and is not intrinsic to radio-group semantics.',
+ },
+ 'at-facing-strings': {
+ owner: 'the binding component',
+ verifiedBy:
+ 'the repository i18n catalog check and review of component-authored accessibility strings',
+ reason:
+ 'Translation is a source-level concern that rendered semantics alone cannot distinguish.',
+ },
+ },
+ });
diff --git a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
index 3c051b28c2..56b01167f2 100644
--- a/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenuSelectable.test.tsx
@@ -3,14 +3,14 @@
/**
* @file DropdownMenuSelectable.test.tsx
* @input vitest, @testing-library/react, DropdownMenu + selectable items
- * @output Unit tests for DropdownMenuCheckboxItem / RadioGroup / RadioItem (#3829)
- * @position Component-local callback and composition coverage; shared checkbox
- * role, name, state, and interaction outcomes live in the reusable contract.
+ * @output Component-local callback, composition, and marker styling tests for
+ * DropdownMenuCheckboxItem / RadioGroup / RadioItem (#3829)
+ * @position Shared checkbox and radio-group role, name, state, and interaction
+ * outcomes live in their reusable contracts; Menu retains navigation.
*/
import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen} from '@testing-library/react';
-import {useState} from 'react';
import userEvent from '@testing-library/user-event';
import {DropdownMenu} from './DropdownMenu';
import {DropdownMenuCheckboxItem} from './DropdownMenuCheckboxItem';
@@ -120,61 +120,6 @@ describe('DropdownMenuCheckboxItem', () => {
});
describe('DropdownMenuRadioGroup / RadioItem', () => {
- it('keeps option-2 unchecked until it is activated', async () => {
- const user = userEvent.setup();
-
- function RadioPreview() {
- const [value, setValue] = useState('option-1');
- return (
- <DropdownMenu button={{label: 'Sort'}}>
- <DropdownMenuRadioGroup
- value={value}
- onChange={setValue}
- label="Radio group">
- <DropdownMenuRadioItem value="option-2" label="Option 2" />
- </DropdownMenuRadioGroup>
- </DropdownMenu>
- );
- }
-
- render(<RadioPreview />);
- await user.click(screen.getByRole('button', {name: /Sort/}));
-
- const option = screen.getByRole('menuitemradio', {
- name: 'Option 2',
- hidden: true,
- });
- expect(option).toHaveAttribute('aria-checked', 'false');
-
- await user.click(option);
- expect(option).toHaveAttribute('aria-checked', 'true');
- });
-
- it('renders a named group with radios reflecting the selected value', async () => {
- const user = userEvent.setup();
- render(
- <DropdownMenu button={{label: 'Sort'}}>
- <DropdownMenuRadioGroup
- value="newest"
- onChange={() => {}}
- label="Sort by">
- <DropdownMenuRadioItem value="newest" label="Newest" />
- <DropdownMenuRadioItem value="oldest" label="Oldest" />
- </DropdownMenuRadioGroup>
- </DropdownMenu>,
- );
- await user.click(screen.getByRole('button', {name: /Sort/}));
- expect(
- screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
- ).toHaveAttribute('aria-checked', 'true');
- expect(
- screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
- ).toHaveAttribute('aria-checked', 'false');
- expect(
- screen.getByRole('group', {name: 'Sort by', hidden: true}),
- ).toBeInTheDocument();
- });
-
it('renders the shared radio indicator in the menu marker', async () => {
const user = userEvent.setup();
render(
@@ -236,24 +181,6 @@ describe('DropdownMenuRadioGroup / RadioItem', () => {
expect(onChange).toHaveBeenCalledWith('oldest');
});
- it('names the group from the required label prop', async () => {
- const user = userEvent.setup();
- render(
- <DropdownMenu button={{label: 'Sort'}}>
- <DropdownMenuRadioGroup
- value="newest"
- onChange={() => {}}
- label="Sort by">
- <DropdownMenuRadioItem value="newest" label="Newest" />
- </DropdownMenuRadioGroup>
- </DropdownMenu>,
- );
- await user.click(screen.getByRole('button', {name: /Sort/}));
- expect(
- screen.getByRole('group', {name: 'Sort by', hidden: true}),
- ).toBeInTheDocument();
- });
-
it('throws when a radio item is used outside a group', () => {
const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
expect(() =>
diff --git a/packages/core/src/RadioList/RadioList.test.tsx b/packages/core/src/RadioList/RadioList.test.tsx
index 84049903bf..97e0e43b53 100644
--- a/packages/core/src/RadioList/RadioList.test.tsx
+++ b/packages/core/src/RadioList/RadioList.test.tsx
@@ -3,8 +3,11 @@
/**
* @file RadioList.test.tsx
* @input Uses vitest, @testing-library/react, RadioList, RadioListItem
- * @output Unit tests for RadioList and RadioListItem behavior
- * @position Testing; validates RadioList.tsx and RadioListItem.tsx implementation
+ * @output Component-specific callback, form, composition, layout, and styling
+ * tests. Shared radio-group role, name, state, focus, and interaction outcomes
+ * live in __tests__/RadioGroup.a11y.test.tsx and its Chromium twin.
+ * @position Component-owned regression tests that do not duplicate the reusable
+ * radio-group contract.
*
* SYNC: When RadioList.tsx or RadioListItem.tsx changes, update tests to match new behavior
*/
@@ -64,29 +67,6 @@ describe('RadioList', () => {
expect(screen.getAllByRole('radio')).toHaveLength(3);
});
- it('renders radiogroup role', () => {
- render(
- <RadioList label="Preference" value="" onChange={() => {}}>
- <RadioListItem label="Option A" value="a" />
- </RadioList>,
- );
- expect(screen.getByRole('radiogroup')).toBeInTheDocument();
- });
-
- it('selects the correct radio based on value prop', () => {
- render(
- <RadioList label="Preference" value="b" onChange={() => {}}>
- <RadioListItem label="Option A" value="a" />
- <RadioListItem label="Option B" value="b" />
- <RadioListItem label="Option C" value="c" />
- </RadioList>,
- );
- const radios = screen.getAllByRole('radio');
- expect(radios[0]).not.toBeChecked();
- expect(radios[1]).toBeChecked();
- expect(radios[2]).not.toBeChecked();
- });
-
it('calls onChange with value string when clicking a radio', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -132,18 +112,6 @@ describe('RadioList', () => {
expect(handleChange).toHaveBeenCalledWith('b');
});
- it('disables all radios when group isDisabled is true', () => {
- render(
- <RadioList label="Preference" value="" onChange={() => {}} isDisabled>
- <RadioListItem label="Option A" value="a" />
- <RadioListItem label="Option B" value="b" />
- </RadioList>,
- );
- const radios = screen.getAllByRole('radio');
- expect(radios[0]).toBeDisabled();
- expect(radios[1]).toBeDisabled();
- });
-
it('does not call onChange when group is disabled', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -163,18 +131,6 @@ describe('RadioList', () => {
expect(handleChange).not.toHaveBeenCalled();
});
- it('disables individual item when item isDisabled is true', () => {
- render(
- <RadioList label="Preference" value="" onChange={() => {}}>
- <RadioListItem label="Option A" value="a" />
- <RadioListItem label="Option B" value="b" isDisabled />
- </RadioList>,
- );
- const radios = screen.getAllByRole('radio');
- expect(radios[0]).not.toBeDisabled();
- expect(radios[1]).toBeDisabled();
- });
-
it('does not call onChange when individual item is disabled', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -251,22 +207,6 @@ describe('RadioList', () => {
expect(screen.getByText('Great choice!')).toBeInTheDocument();
});
- it('sets aria-invalid on radiogroup when status is error', () => {
- render(
- <RadioList
- label="Preference"
- value=""
- onChange={() => {}}
- status={{type: 'error', message: 'Required'}}>
- <RadioListItem label="Option A" value="a" />
- </RadioList>,
- );
- expect(screen.getByRole('radiogroup')).toHaveAttribute(
- 'aria-invalid',
- 'true',
- );
- });
-
it('renders startContent', () => {
render(
<RadioList label="Preference" value="" onChange={() => {}}>
@@ -398,59 +338,7 @@ describe('RadioList', () => {
expect(screen.getAllByRole('radio')).toHaveLength(2);
});
- it('sets aria-required on radiogroup when isRequired is true', () => {
- render(
- <RadioList label="Preference" value="" onChange={() => {}} isRequired>
- <RadioListItem label="Option A" value="a" />
- </RadioList>,
- );
- expect(screen.getByRole('radiogroup')).toHaveAttribute(
- 'aria-required',
- 'true',
- );
- });
-
describe('focus management (no-selection tab stop)', () => {
- it('keeps focus on the selected radio when a value is selected', () => {
- render(
- <RadioList label="Preference" value="b" onChange={() => {}}>
- <RadioListItem label="Option A" value="a" />
- <RadioListItem label="Option B" value="b" />
- <RadioListItem label="Option C" value="c" />
- </RadioList>,
- );
- const selected = screen.getByLabelText('Option B');
- // A selected value provides a deterministic native tab stop; focusing it
- // must not be redirected elsewhere.
- selected.focus();
- expect(selected).toHaveFocus();
- });
-
- it('redirects to the first radio when focus enters an unselected group forward', () => {
- render(
- <>
- <button type="button">before</button>
- <RadioList label="Preference" value="" onChange={() => {}}>
- <RadioListItem label="Option A" value="a" />
- <RadioListItem label="Option B" value="b" />
- <RadioListItem label="Option C" value="c" />
- </RadioList>
- </>,
- );
- const radios = screen.getAllByRole('radio');
- const outside = screen.getByText('before');
- outside.focus();
- // Forward entry: the browser lands on a leading radio; the group keeps the
- // first radio as the deterministic tab stop.
- radios[0].focus();
- expect(radios[0]).toHaveFocus();
-
- // Landing on a middle radio from outside is normalized to the first.
- outside.focus();
- radios[1].focus();
- expect(radios[0]).toHaveFocus();
- });
-
it('redirects to the last radio when focus enters an unselected group backward', () => {
render(
<>
@@ -570,21 +458,6 @@ describe('RadioList', () => {
expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
});
- it('keeps radios focusable via aria-disabled when a reason is provided', () => {
- renderGroup();
- for (const radio of screen.getAllByRole('radio', h)) {
- expect(radio).not.toBeDisabled();
- expect(radio).toHaveAttribute('aria-disabled', 'true');
- }
- });
-
- it('links the reason tooltip from the group via aria-describedby', () => {
- renderGroup();
- const group = screen.getByRole('radiogroup');
- const tooltip = screen.getByRole('tooltip', h);
- expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
- });
-
it('blocks selection while focusable-disabled', () => {
const onChange = vi.fn();
renderGroup({onChange});
@@ -592,18 +465,6 @@ describe('RadioList', () => {
fireEvent.click(pro);
expect(onChange).not.toHaveBeenCalled();
});
-
- it('keeps radios natively disabled when disabled without a reason', () => {
- render(
- <RadioList label="Plan" value="free" onChange={() => {}} isDisabled>
- <RadioListItem label="Free" value="free" />
- <RadioListItem label="Pro" value="pro" />
- </RadioList>,
- );
- for (const radio of screen.getAllByRole('radio', h)) {
- expect(radio).toBeDisabled();
- }
- });
});
describe('form participation', () => {
it('submits the selected value under htmlName', () => {
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..7400160348
--- /dev/null
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.chromium.spec.ts
@@ -0,0 +1,255 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioGroup.a11y.chromium.spec.ts
+ * @input Uses the shared radio-group contract, Chromium harness, checked-in stories, inventory, and exact known failures
+ * @output Real-browser and accessibility-tree evidence for every current bound radio-group part
+ * @position Browser lane required by AST-013; it makes no real-AT claim.
+ */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {
+ RADIO_GROUP_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ formatReport,
+ neverExercised,
+ summarize,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {RADIO_GROUP_KNOWN_FAILURES} from './RadioGroup.a11y.known-failures';
+import {
+ RADIO_GROUP_BINDING_STATES,
+ type RadioGroupBindingRow,
+ type RadioGroupBindingState,
+} from './RadioGroup.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+ return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+function subjectFor(page: Page, state: RadioGroupBindingRow): Locator {
+ return page
+ .locator('#storybook-root')
+ .getByRole(state.facts.role, {
+ name: state.subjectName,
+ includeHidden: true,
+ })
+ .first();
+}
+
+function relatedFor(
+ page: Page,
+ state: RadioGroupBindingRow,
+): Readonly<Record<string, Locator>> {
+ const metadata = state as RadioGroupBindingState;
+ return Object.fromEntries(
+ Object.entries(metadata.relations ?? {}).map(([relation, option]) => [
+ relation,
+ page
+ .locator('#storybook-root')
+ .getByRole(option.role, {name: option.name, includeHidden: true})
+ .first(),
+ ]),
+ );
+}
+
+async function mountState(
+ page: Page,
+ state: RadioGroupBindingRow,
+): Promise<void> {
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ await holdMotionStill(page);
+ const root = page.locator('#storybook-root');
+ if ((state as RadioGroupBindingState).opensMenu === true) {
+ await root.getByRole('button', {name: 'Sort options'}).click();
+ }
+ await subjectFor(page, state).waitFor({state: 'attached'});
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: RadioGroupBindingRow,
+): Promise<BindingResult> {
+ let mounted = false;
+ return checkAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+ mount: async () => {
+ if (!mounted || state.facts.selection === 'none') {
+ await mountState(page, state);
+ mounted = true;
+ }
+ return createChromiumHarness({
+ page,
+ subject: subjectFor(page, state),
+ cdp,
+ visibleLabel: state.facts.visibleLabel ? undefined : null,
+ related: relatedFor(page, state),
+ });
+ },
+ });
+}
+
+test('every binding fact matches the rendered semantic state', async ({
+ page,
+}) => {
+ test.setTimeout(4 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const wrong: string[] = [];
+
+ for (const state of RADIO_GROUP_BINDING_STATES) {
+ await mountState(page, state);
+ const harness = createChromiumHarness({
+ page,
+ subject: subjectFor(page, state),
+ cdp,
+ related: relatedFor(page, state),
+ });
+ const subject = await harness.subject();
+ const computed = await subject.computed();
+
+ if (computed.role !== state.facts.role) {
+ wrong.push(
+ `${state.id}: declares role=${state.facts.role}, browser exposes ${computed.role}`,
+ );
+ }
+ if (
+ state.facts.checked != null &&
+ computed.checked !== (state.facts.checked ? 'true' : 'false')
+ ) {
+ wrong.push(
+ `${state.id}: declares checked=${state.facts.checked}, browser exposes ${computed.checked}`,
+ );
+ }
+ if (
+ state.facts.disabled != null &&
+ computed.disabled !== state.facts.disabled
+ ) {
+ wrong.push(
+ `${state.id}: declares disabled=${state.facts.disabled}, browser exposes ${computed.disabled}`,
+ );
+ }
+ const description =
+ computed.description.trim() === '' ? null : computed.description;
+ if (description !== state.facts.description) {
+ wrong.push(
+ `${state.id}: declares description=${JSON.stringify(state.facts.description)}, browser exposes ${JSON.stringify(description)}`,
+ );
+ }
+ const required =
+ (await subject.attribute('required')) != null ||
+ (await subject.attribute('aria-required')) === 'true';
+ if (required !== state.facts.required) {
+ wrong.push(
+ `${state.id}: declares required=${state.facts.required}, page exposes ${required}`,
+ );
+ }
+ if (computed.invalid !== state.facts.invalid) {
+ wrong.push(
+ `${state.id}: declares invalid=${state.facts.invalid}, browser exposes ${computed.invalid}`,
+ );
+ }
+
+ await harness.resetFocus();
+ let reachedByTab = false;
+ for (let step = 0; step < 10 && !reachedByTab; step += 1) {
+ await harness.press('Tab');
+ reachedByTab =
+ state.facts.part === 'group'
+ ? await subject.containsFocus()
+ : await subject.isFocused();
+ }
+ if (reachedByTab !== state.facts.tabReachable) {
+ wrong.push(
+ `${state.id}: declares tabReachable=${state.facts.tabReachable}, page exposes ${reachedByTab}`,
+ );
+ }
+ }
+
+ expect(wrong).toEqual([]);
+});
+
+test('every expectation is exercised by at least one bound state', async ({
+ page,
+}) => {
+ test.setTimeout(6 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of RADIO_GROUP_BINDING_STATES) {
+ let mounted = false;
+ results.push(
+ await checkAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+ mount: async () => {
+ if (!mounted || state.facts.selection === 'none') {
+ await mountState(page, state);
+ mounted = true;
+ }
+ return createChromiumHarness({
+ page,
+ subject: subjectFor(page, state),
+ cdp,
+ visibleLabel: state.facts.visibleLabel ? undefined : null,
+ related: relatedFor(page, state),
+ });
+ },
+ }),
+ );
+ }
+ expect(neverExercised(results)).toEqual([]);
+ expect(unmatchedKnownFailures(RADIO_GROUP_KNOWN_FAILURES, results)).toEqual(
+ [],
+ );
+});
+
+for (const state of RADIO_GROUP_BINDING_STATES) {
+ test(`${state.binding} [${state.id}] — ${state.summary}`, async ({page}) => {
+ test.setTimeout(3 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(RADIO_GROUP_PATTERN, [result]);
+ // eslint-disable-next-line no-console -- the report is this run's artifact
+ console.log(formatReport(report));
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+}
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.known-failures.ts b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.known-failures.ts
new file mode 100644
index 0000000000..adad43e66b
--- /dev/null
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.known-failures.ts
@@ -0,0 +1,12 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioGroup.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Exact public-safe radio-group migration failures
+ * @position AST-021 debt records; operational ownership remains outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const RADIO_GROUP_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [];
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.renders.tsx b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.renders.tsx
new file mode 100644
index 0000000000..0b97774fcd
--- /dev/null
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.renders.tsx
@@ -0,0 +1,232 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file RadioGroup.a11y.renders.tsx
+ * @input Uses every current Astryx radio-group adopter and the checked state inventory
+ * @output Consumer-realistic render functions shared by jsdom and Storybook
+ * @position Binding fixture layer; callbacks, form behavior, composition, and styling stay local.
+ */
+
+import {useState, type ReactElement} from 'react';
+import {
+ DropdownMenu,
+ DropdownMenuRadioGroup,
+ DropdownMenuRadioItem,
+} from '../../DropdownMenu';
+import {SegmentedControl, SegmentedControlItem} from '../../SegmentedControl';
+import {RadioList, RadioListItem} from '../index';
+import type {RadioGroupStateId} from './RadioGroup.a11y.states';
+
+function RadioListFixture({
+ initial = 'standard',
+ orientation = 'horizontal',
+ direction = 'ltr',
+ description,
+ isRequired = false,
+ isInvalid = false,
+ isDisabled = false,
+ disabledMessage,
+ disabledOption,
+}: {
+ initial?: string;
+ orientation?: 'horizontal' | 'vertical';
+ direction?: 'ltr' | 'rtl';
+ description?: string;
+ isRequired?: boolean;
+ isInvalid?: boolean;
+ isDisabled?: boolean;
+ disabledMessage?: string;
+ disabledOption?: 'express';
+}) {
+ const [value, setValue] = useState(initial);
+ return (
+ <div dir={direction}>
+ <RadioList
+ label="Delivery speed"
+ description={description}
+ value={value}
+ onChange={setValue}
+ orientation={orientation}
+ isRequired={isRequired}
+ isDisabled={isDisabled}
+ disabledMessage={disabledMessage}
+ status={
+ isInvalid
+ ? {type: 'error', message: 'Please select an option.'}
+ : undefined
+ }>
+ <RadioListItem
+ label="Standard"
+ value="standard"
+ description={
+ description == null ? undefined : 'Arrives in three to five days'
+ }
+ />
+ <RadioListItem
+ label="Express"
+ value="express"
+ isDisabled={disabledOption === 'express'}
+ />
+ <RadioListItem label="Overnight" value="overnight" />
+ </RadioList>
+ </div>
+ );
+}
+
+function SegmentedFixture({
+ initial = 'list',
+ direction = 'ltr',
+ isDisabled = false,
+ disabledMessage,
+ disabledOption,
+ hideSelectedLabel = false,
+}: {
+ initial?: string;
+ direction?: 'ltr' | 'rtl';
+ isDisabled?: boolean;
+ disabledMessage?: string;
+ disabledOption?: 'grid';
+ hideSelectedLabel?: boolean;
+}) {
+ const [value, setValue] = useState(initial);
+ return (
+ <div dir={direction}>
+ <SegmentedControl
+ value={value}
+ onChange={setValue}
+ label="View mode"
+ isDisabled={isDisabled}
+ disabledMessage={disabledMessage}>
+ <SegmentedControlItem
+ value="list"
+ label="List"
+ isLabelHidden={hideSelectedLabel}
+ icon={
+ hideSelectedLabel ? <span aria-hidden="true">≡</span> : undefined
+ }
+ />
+ <SegmentedControlItem
+ value="grid"
+ label="Grid"
+ isDisabled={disabledOption === 'grid'}
+ />
+ <SegmentedControlItem value="table" label="Table" />
+ </SegmentedControl>
+ </div>
+ );
+}
+
+function MenuRadioFixture({
+ initial = 'newest',
+ described = false,
+ disabledOption,
+}: {
+ initial?: string;
+ described?: boolean;
+ disabledOption?: 'oldest';
+}) {
+ const [value, setValue] = useState<string | undefined>(initial || undefined);
+ return (
+ <DropdownMenu button={{label: 'Sort options'}}>
+ <DropdownMenuRadioGroup
+ value={value}
+ onChange={setValue}
+ label="Sort by"
+ hasCloseOnSelect={false}>
+ <DropdownMenuRadioItem value="newest" label="Newest" />
+ <DropdownMenuRadioItem
+ value="oldest"
+ label="Oldest"
+ description={described ? 'Oldest items first' : undefined}
+ isDisabled={disabledOption === 'oldest'}
+ />
+ <DropdownMenuRadioItem value="popular" label="Most viewed" />
+ </DropdownMenuRadioGroup>
+ </DropdownMenu>
+ );
+}
+
+export type RadioGroupStateRender = () => ReactElement;
+
+export const RADIO_GROUP_STATE_RENDERS: Record<
+ RadioGroupStateId,
+ RadioGroupStateRender
+> = {
+ 'radio-list-group-selected-ltr': () => <RadioListFixture />,
+ 'radio-list-group-selected-rtl': () => <RadioListFixture direction="rtl" />,
+ 'radio-list-group-selected-vertical': () => (
+ <RadioListFixture orientation="vertical" />
+ ),
+ 'radio-list-group-none-selected': () => (
+ <RadioListFixture initial="" orientation="vertical" />
+ ),
+ 'radio-list-group-required-invalid-described': () => (
+ <RadioListFixture
+ initial=""
+ orientation="vertical"
+ description="Choose a delivery speed."
+ isRequired
+ isInvalid
+ />
+ ),
+ 'radio-list-group-disabled-with-message': () => (
+ <RadioListFixture
+ isDisabled
+ disabledMessage="Managed by your administrator"
+ orientation="vertical"
+ />
+ ),
+ 'radio-list-option-unselected-described': () => (
+ <RadioListFixture
+ initial="express"
+ description="Choose a delivery speed."
+ />
+ ),
+ 'radio-list-option-selected': () => <RadioListFixture />,
+ 'radio-list-option-disabled': () => (
+ <RadioListFixture disabledOption="express" />
+ ),
+ 'radio-list-option-group-disabled': () => (
+ <RadioListFixture isDisabled orientation="vertical" />
+ ),
+ 'radio-list-option-disabled-with-message': () => (
+ <RadioListFixture
+ isDisabled
+ disabledMessage="Managed by your administrator"
+ orientation="vertical"
+ />
+ ),
+
+ 'segmented-group-selected-ltr': () => <SegmentedFixture />,
+ 'segmented-group-selected-rtl': () => <SegmentedFixture direction="rtl" />,
+ 'segmented-group-none-selected': () => (
+ <SegmentedFixture initial="not-an-option" />
+ ),
+ 'segmented-group-disabled': () => <SegmentedFixture isDisabled />,
+ 'segmented-group-disabled-with-message': () => (
+ <SegmentedFixture
+ isDisabled
+ disabledMessage="Choose a project to switch views"
+ />
+ ),
+ 'segmented-option-unselected': () => <SegmentedFixture />,
+ 'segmented-option-selected-hidden-label': () => (
+ <SegmentedFixture hideSelectedLabel />
+ ),
+ 'segmented-option-disabled': () => <SegmentedFixture disabledOption="grid" />,
+ 'segmented-option-group-disabled': () => <SegmentedFixture isDisabled />,
+ 'segmented-option-group-disabled-with-message': () => (
+ <SegmentedFixture
+ isDisabled
+ disabledMessage="Choose a project to switch views"
+ />
+ ),
+
+ 'menu-group-selected': () => <MenuRadioFixture />,
+ 'menu-group-none-selected': () => <MenuRadioFixture initial="" />,
+ 'menu-option-unselected-described': () => <MenuRadioFixture described />,
+ 'menu-option-selected': () => <MenuRadioFixture />,
+ 'menu-option-disabled': () => <MenuRadioFixture disabledOption="oldest" />,
+};
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts
new file mode 100644
index 0000000000..ae2d60df80
--- /dev/null
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.states.ts
@@ -0,0 +1,503 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file RadioGroup.a11y.states.ts
+ * @input Uses RadioGroupStateFacts from @astryxdesign/a11y-spec
+ * @output The AST-021 binding inventory for every current radio-group part, representative states, and explicit exclusions
+ * @position Data-only inventory shared by jsdom, Storybook, and Chromium bindings.
+ */
+
+import type {RadioGroupStateFacts} from '@astryxdesign/a11y-spec';
+
+export type RadioGroupBinding =
+ | 'RadioList'
+ | 'RadioListItem'
+ | 'SegmentedControl'
+ | 'SegmentedControlItem'
+ | 'DropdownMenuRadioGroup'
+ | 'DropdownMenuRadioItem';
+
+export interface RadioGroupRelation {
+ readonly role: 'radio' | 'menuitemradio';
+ readonly name: string;
+}
+
+export interface RadioGroupBindingState {
+ readonly id: string;
+ readonly binding: RadioGroupBinding;
+ readonly summary: string;
+ readonly facts: RadioGroupStateFacts;
+ readonly subjectName: string | RegExp;
+ readonly relations?: Readonly<Record<string, RadioGroupRelation>>;
+ readonly storyId: string;
+ readonly opensMenu?: boolean;
+}
+
+export type RadioGroupBindingRow = (typeof RADIO_GROUP_BINDING_STATES)[number];
+export type RadioGroupStateId =
+ (typeof RADIO_GROUP_BINDING_STATES)[number]['id'];
+
+const DIRECT_RELATIONS = {
+ first: {role: 'radio', name: 'Standard'},
+ second: {role: 'radio', name: 'Express'},
+ third: {role: 'radio', name: 'Overnight'},
+} as const;
+
+const MENU_RELATIONS = {
+ first: {role: 'menuitemradio', name: 'Newest'},
+ second: {role: 'menuitemradio', name: 'Oldest'},
+ third: {role: 'menuitemradio', name: 'Most viewed'},
+} as const;
+
+function groupFacts(
+ overrides: Partial<RadioGroupStateFacts> = {},
+): RadioGroupStateFacts {
+ return {
+ part: 'group',
+ role: 'radiogroup',
+ checked: null,
+ selection: 'one',
+ optionRelations: ['first', 'second', 'third'],
+ selectedOption: 'first',
+ disabled: false,
+ description: null,
+ required: false,
+ invalid: false,
+ operable: true,
+ tabReachable: true,
+ spaceSelection: true,
+ pointerSelection: true,
+ arrowSelection: true,
+ pointerCancellation: false,
+ visibleLabel: true,
+ movement: 'horizontal-ltr',
+ ...overrides,
+ };
+}
+
+function optionFacts(
+ overrides: Partial<RadioGroupStateFacts> = {},
+): RadioGroupStateFacts {
+ return {
+ part: 'option',
+ role: 'radio',
+ checked: false,
+ selection: null,
+ optionRelations: [],
+ selectedOption: null,
+ disabled: false,
+ description: null,
+ required: false,
+ invalid: false,
+ operable: true,
+ tabReachable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ pointerCancellation: true,
+ visibleLabel: true,
+ movement: 'none',
+ ...overrides,
+ };
+}
+
+const story = (id: string) => `a11y-radio-group-pattern--${id}`;
+
+export const RADIO_GROUP_BINDING_STATES = [
+ {
+ id: 'radio-list-group-selected-ltr',
+ binding: 'RadioList',
+ summary: 'a horizontal LTR group with one selected option',
+ facts: groupFacts(),
+ subjectName: 'Delivery speed',
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-selected-ltr'),
+ },
+ {
+ id: 'radio-list-group-selected-rtl',
+ binding: 'RadioList',
+ summary: 'a horizontal RTL group with logical arrow movement',
+ facts: groupFacts({movement: 'horizontal-rtl'}),
+ subjectName: 'Delivery speed',
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-selected-rtl'),
+ },
+ {
+ id: 'radio-list-group-selected-vertical',
+ binding: 'RadioList',
+ summary: 'a vertical group with down/up arrow movement',
+ facts: groupFacts({movement: 'vertical'}),
+ subjectName: 'Delivery speed',
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-selected-vertical'),
+ },
+ {
+ id: 'radio-list-group-none-selected',
+ binding: 'RadioList',
+ summary: 'a group that starts with no selected option',
+ facts: groupFacts({
+ selection: 'none',
+ selectedOption: null,
+ movement: 'vertical',
+ }),
+ subjectName: 'Delivery speed',
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-none-selected'),
+ },
+ {
+ id: 'radio-list-group-required-invalid-described',
+ binding: 'RadioList',
+ summary: 'a required invalid group with helper and error text',
+ facts: groupFacts({
+ selection: 'none',
+ selectedOption: null,
+ description: 'Choose a delivery speed. Please select an option.',
+ required: true,
+ invalid: true,
+ movement: 'vertical',
+ }),
+ subjectName: /Delivery speed/,
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-required-invalid-described'),
+ },
+ {
+ id: 'radio-list-group-disabled-with-message',
+ binding: 'RadioList',
+ summary: 'a disabled group whose reason is attached to the group',
+ facts: groupFacts({
+ disabled: null,
+ description: 'Managed by your administrator',
+ operable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ movement: 'vertical',
+ }),
+ subjectName: 'Delivery speed',
+ relations: DIRECT_RELATIONS,
+ storyId: story('radio-list-group-disabled-with-message'),
+ },
+ {
+ id: 'radio-list-option-unselected-described',
+ binding: 'RadioListItem',
+ summary: 'an available unselected option with supporting text',
+ facts: optionFacts({description: 'Arrives in three to five days'}),
+ subjectName: 'Standard',
+ storyId: story('radio-list-option-unselected-described'),
+ },
+ {
+ id: 'radio-list-option-selected',
+ binding: 'RadioListItem',
+ summary: 'the selected option in a direct group',
+ facts: optionFacts({checked: true, tabReachable: true}),
+ subjectName: 'Standard',
+ storyId: story('radio-list-option-selected'),
+ },
+ {
+ id: 'radio-list-option-disabled',
+ binding: 'RadioListItem',
+ summary: 'an individually disabled option outside the tab sequence',
+ facts: optionFacts({
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ pointerCancellation: false,
+ }),
+ subjectName: 'Express',
+ storyId: story('radio-list-option-disabled'),
+ },
+ {
+ id: 'radio-list-option-group-disabled',
+ binding: 'RadioListItem',
+ summary: 'an option disabled by its group without a tabReachable reason',
+ facts: optionFacts({
+ checked: true,
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ pointerCancellation: false,
+ }),
+ subjectName: 'Standard',
+ storyId: story('radio-list-option-group-disabled'),
+ },
+ {
+ id: 'radio-list-option-disabled-with-message',
+ binding: 'RadioListItem',
+ summary: 'an unavailable option kept tabReachable for a group-level reason',
+ facts: optionFacts({
+ checked: true,
+ disabled: true,
+ operable: false,
+ tabReachable: true,
+ pointerCancellation: false,
+ }),
+ subjectName: 'Standard',
+ storyId: story('radio-list-option-disabled-with-message'),
+ },
+
+ {
+ id: 'segmented-group-selected-ltr',
+ binding: 'SegmentedControl',
+ summary: 'a horizontal LTR segmented choice with one selected option',
+ facts: groupFacts({visibleLabel: false}),
+ subjectName: 'View mode',
+ relations: {
+ first: {role: 'radio', name: 'List'},
+ second: {role: 'radio', name: 'Grid'},
+ third: {role: 'radio', name: 'Table'},
+ },
+ storyId: story('segmented-group-selected-ltr'),
+ },
+ {
+ id: 'segmented-group-selected-rtl',
+ binding: 'SegmentedControl',
+ summary: 'a horizontal RTL segmented choice with logical arrow movement',
+ facts: groupFacts({visibleLabel: false, movement: 'horizontal-rtl'}),
+ subjectName: 'View mode',
+ relations: {
+ first: {role: 'radio', name: 'List'},
+ second: {role: 'radio', name: 'Grid'},
+ third: {role: 'radio', name: 'Table'},
+ },
+ storyId: story('segmented-group-selected-rtl'),
+ },
+ {
+ id: 'segmented-group-none-selected',
+ binding: 'SegmentedControl',
+ summary: 'a segmented choice whose controlled value matches no option',
+ facts: groupFacts({
+ selection: 'none',
+ selectedOption: null,
+ visibleLabel: false,
+ }),
+ subjectName: 'View mode',
+ relations: {
+ first: {role: 'radio', name: 'List'},
+ second: {role: 'radio', name: 'Grid'},
+ third: {role: 'radio', name: 'Table'},
+ },
+ storyId: story('segmented-group-none-selected'),
+ },
+ {
+ id: 'segmented-group-disabled',
+ binding: 'SegmentedControl',
+ summary: 'a disabled segmented group outside the tab sequence',
+ facts: groupFacts({
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ visibleLabel: false,
+ }),
+ subjectName: 'View mode',
+ relations: {
+ first: {role: 'radio', name: 'List'},
+ second: {role: 'radio', name: 'Grid'},
+ third: {role: 'radio', name: 'Table'},
+ },
+ storyId: story('segmented-group-disabled'),
+ },
+ {
+ id: 'segmented-group-disabled-with-message',
+ binding: 'SegmentedControl',
+ summary:
+ 'a disabled segmented group with an attached reason and one tab stop',
+ facts: groupFacts({
+ disabled: true,
+ description: 'Choose a project to switch views',
+ operable: false,
+ spaceSelection: false,
+ pointerSelection: false,
+ arrowSelection: false,
+ visibleLabel: false,
+ }),
+ subjectName: 'View mode',
+ relations: {
+ first: {role: 'radio', name: 'List'},
+ second: {role: 'radio', name: 'Grid'},
+ third: {role: 'radio', name: 'Table'},
+ },
+ storyId: story('segmented-group-disabled-with-message'),
+ },
+ {
+ id: 'segmented-option-unselected',
+ binding: 'SegmentedControlItem',
+ summary: 'an available unselected segment with a visible label',
+ facts: optionFacts(),
+ subjectName: 'Grid',
+ storyId: story('segmented-option-unselected'),
+ },
+ {
+ id: 'segmented-option-selected-hidden-label',
+ binding: 'SegmentedControlItem',
+ summary: 'a selected icon-only segment named programmatically',
+ facts: optionFacts({
+ checked: true,
+ tabReachable: true,
+ visibleLabel: false,
+ }),
+ subjectName: 'List',
+ storyId: story('segmented-option-selected-hidden-label'),
+ },
+ {
+ id: 'segmented-option-disabled',
+ binding: 'SegmentedControlItem',
+ summary: 'an individually disabled segment',
+ facts: optionFacts({
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ pointerCancellation: false,
+ }),
+ subjectName: 'Grid',
+ storyId: story('segmented-option-disabled'),
+ },
+ {
+ id: 'segmented-option-group-disabled',
+ binding: 'SegmentedControlItem',
+ summary:
+ 'a selected segment disabled by its group and removed from Tab order',
+ facts: optionFacts({
+ checked: true,
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ pointerCancellation: false,
+ }),
+ subjectName: 'List',
+ storyId: story('segmented-option-group-disabled'),
+ },
+ {
+ id: 'segmented-option-group-disabled-with-message',
+ binding: 'SegmentedControlItem',
+ summary:
+ 'a selected unavailable segment kept tabReachable for the group reason',
+ facts: optionFacts({
+ checked: true,
+ disabled: true,
+ operable: false,
+ tabReachable: true,
+ pointerCancellation: false,
+ }),
+ subjectName: 'List',
+ storyId: story('segmented-option-group-disabled-with-message'),
+ },
+
+ {
+ id: 'menu-group-selected',
+ binding: 'DropdownMenuRadioGroup',
+ summary: 'a named menu-radio group with one selected option',
+ facts: groupFacts({
+ role: 'group',
+ disabled: null,
+ tabReachable: false,
+ spaceSelection: false,
+ arrowSelection: false,
+ visibleLabel: false,
+ movement: 'none',
+ }),
+ subjectName: 'Sort by',
+ relations: MENU_RELATIONS,
+ storyId: story('menu-group-selected'),
+ opensMenu: true,
+ },
+ {
+ id: 'menu-group-none-selected',
+ binding: 'DropdownMenuRadioGroup',
+ summary: 'a named menu-radio group with no selected option',
+ facts: groupFacts({
+ role: 'group',
+ selection: 'none',
+ selectedOption: null,
+ disabled: null,
+ tabReachable: false,
+ spaceSelection: false,
+ arrowSelection: false,
+ visibleLabel: false,
+ movement: 'none',
+ }),
+ subjectName: 'Sort by',
+ relations: MENU_RELATIONS,
+ storyId: story('menu-group-none-selected'),
+ opensMenu: true,
+ },
+ {
+ id: 'menu-option-unselected-described',
+ binding: 'DropdownMenuRadioItem',
+ summary:
+ 'an unselected menu radio whose secondary text participates in its name',
+ facts: optionFacts({role: 'menuitemradio', tabReachable: false}),
+ subjectName: /Oldest\s*Oldest items first/,
+ storyId: story('menu-option-unselected-described'),
+ opensMenu: true,
+ },
+ {
+ id: 'menu-option-selected',
+ binding: 'DropdownMenuRadioItem',
+ summary: 'a selected radio item inside an opened menu',
+ facts: optionFacts({
+ role: 'menuitemradio',
+ checked: true,
+ tabReachable: false,
+ }),
+ subjectName: 'Newest',
+ storyId: story('menu-option-selected'),
+ opensMenu: true,
+ },
+ {
+ id: 'menu-option-disabled',
+ binding: 'DropdownMenuRadioItem',
+ summary: 'an unavailable radio item inside an opened menu',
+ facts: optionFacts({
+ role: 'menuitemradio',
+ disabled: true,
+ operable: false,
+ tabReachable: false,
+ pointerCancellation: false,
+ }),
+ subjectName: 'Oldest',
+ storyId: story('menu-option-disabled'),
+ opensMenu: true,
+ },
+] as const satisfies ReadonlyArray<RadioGroupBindingState>;
+
+export const RADIO_GROUP_EXCLUSIONS = [
+ {
+ owner: 'SelectableCard in independent or multi-select composition',
+ classification: 'preserved',
+ reason:
+ 'SelectableCard exposes a native checkbox and is already bound to the checkbox contract; visual card selection does not by itself make the control a radio.',
+ },
+ {
+ owner: 'SelectableCard in caller-managed single-select composition',
+ classification: 'needs-human',
+ reason:
+ 'The public API has no role-aware single-select mode or group owner. Adopting radio semantics would require an API and ownership decision, so this migration does not reinterpret the existing checkbox.',
+ },
+ {
+ owner: 'DropdownMenu and ContextMenu radio-item movement',
+ classification: 'out-of-scope',
+ reason:
+ 'Menu owns composite focus, arrows, typeahead, activation, and dismissal. ContextMenu re-exports the same DropdownMenu radio parts, so a duplicate binding would test one implementation twice.',
+ },
+ {
+ owner: 'TabMenu overflow choices',
+ classification: 'out-of-scope',
+ reason:
+ 'TabMenu emits menuitemradio inside its menu-owned overflow navigation; it is not a standalone radio-group part.',
+ },
+ {
+ owner: 'Pagination dots',
+ classification: 'out-of-scope',
+ reason:
+ 'Pagination dots are buttons in a named group with aria-current page semantics, not radio or radiogroup nodes.',
+ },
+ {
+ owner: 'Home and End keyboard shortcuts',
+ classification: 'out-of-scope',
+ reason:
+ 'The APG radio-group pattern does not require Home or End, and no current Astryx record adopts those optional shortcuts as a shared radio-group contract.',
+ },
+] as const;
diff --git a/packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx
new file mode 100644
index 0000000000..54b179dea6
--- /dev/null
+++ b/packages/core/src/RadioList/__tests__/RadioGroup.a11y.test.tsx
@@ -0,0 +1,217 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file RadioGroup.a11y.test.tsx
+ * @input Uses the shared radio-group contract and complete binding inventory
+ * @output DOM-layer binding evidence for direct and menu radio-group parts
+ * @position Fast migration lane; browser-owned outcomes remain explicitly unrun.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+ RADIO_GROUP_PATTERN,
+ checkAccessibilitySpec,
+ createJsdomHarness,
+ expectAccessibilitySpec,
+ summarize,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {RADIO_GROUP_KNOWN_FAILURES} from './RadioGroup.a11y.known-failures';
+import {RADIO_GROUP_STATE_RENDERS} from './RadioGroup.a11y.renders';
+import {
+ RADIO_GROUP_BINDING_STATES,
+ RADIO_GROUP_EXCLUSIONS,
+ type RadioGroupBindingRow,
+} from './RadioGroup.a11y.states';
+
+function subjectFor(state: RadioGroupBindingRow): Element {
+ return screen.getByRole(state.facts.role, {
+ name: state.subjectName,
+ hidden: true,
+ });
+}
+
+async function expectState(state: RadioGroupBindingRow): Promise<void> {
+ await expectAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+ render: () => {
+ render(RADIO_GROUP_STATE_RENDERS[state.id]());
+ },
+ subject: () => subjectFor(state),
+ cleanup,
+ });
+}
+
+async function checkState(state: RadioGroupBindingRow): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: RADIO_GROUP_PATTERN,
+ binding: state.binding,
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+ mount: async () => {
+ render(RADIO_GROUP_STATE_RENDERS[state.id]());
+ return createJsdomHarness({subject: subjectFor(state)});
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('the shared radio-group pattern, jsdom lane', () => {
+ it.each(
+ RADIO_GROUP_BINDING_STATES.map(
+ state =>
+ [`${state.binding} [${state.id}]`, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectState(state);
+ });
+
+ it('runs the DOM layer and reports higher layers as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of RADIO_GROUP_BINDING_STATES) {
+ results.push(await checkState(state));
+ }
+ const report = summarize(RADIO_GROUP_PATTERN, results);
+ expect(report.counts.pass).toBeGreaterThan(0);
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ expect(unmatchedKnownFailures(RADIO_GROUP_KNOWN_FAILURES, results)).toEqual(
+ [],
+ );
+ });
+});
+
+describe('the radio-group binding inventory', () => {
+ it('names a distinct checked-in story for every state', () => {
+ const ids = RADIO_GROUP_BINDING_STATES.map(state => state.storyId);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it('binds every current direct and menu radio-group part', () => {
+ const bound = new Set(
+ RADIO_GROUP_BINDING_STATES.map(state => state.binding),
+ );
+ expect([...bound].sort()).toEqual([
+ 'DropdownMenuRadioGroup',
+ 'DropdownMenuRadioItem',
+ 'RadioList',
+ 'RadioListItem',
+ 'SegmentedControl',
+ 'SegmentedControlItem',
+ ]);
+ });
+
+ it('records role-conditional and delegated surfaces explicitly', () => {
+ expect(
+ RADIO_GROUP_EXCLUSIONS.map(({owner, classification}) => ({
+ owner,
+ classification,
+ })),
+ ).toEqual([
+ {
+ owner: 'SelectableCard in independent or multi-select composition',
+ classification: 'preserved',
+ },
+ {
+ owner: 'SelectableCard in caller-managed single-select composition',
+ classification: 'needs-human',
+ },
+ {
+ owner: 'DropdownMenu and ContextMenu radio-item movement',
+ classification: 'out-of-scope',
+ },
+ {
+ owner: 'TabMenu overflow choices',
+ classification: 'out-of-scope',
+ },
+ {
+ owner: 'Pagination dots',
+ classification: 'out-of-scope',
+ },
+ {
+ owner: 'Home and End keyboard shortcuts',
+ classification: 'out-of-scope',
+ },
+ ]);
+ expect(RADIO_GROUP_EXCLUSIONS.every(row => row.reason.length > 0)).toBe(
+ true,
+ );
+ });
+
+ it('locks interaction ownership instead of letting bindings opt out', () => {
+ const wrong: string[] = [];
+ for (const state of RADIO_GROUP_BINDING_STATES) {
+ const facts = state.facts;
+ if (facts.part === 'group' && facts.role === 'radiogroup') {
+ for (const fact of [
+ 'spaceSelection',
+ 'pointerSelection',
+ 'arrowSelection',
+ ] as const) {
+ if (facts[fact] !== facts.operable) {
+ wrong.push(
+ `${state.id}: direct-group ${fact}=${facts[fact]} but operable=${facts.operable}`,
+ );
+ }
+ }
+ if (facts.arrowSelection && facts.movement === 'none') {
+ wrong.push(`${state.id}: owns arrows without a movement model`);
+ }
+ } else if (facts.part === 'group') {
+ if (
+ facts.spaceSelection ||
+ facts.arrowSelection ||
+ facts.movement !== 'none'
+ ) {
+ wrong.push(`${state.id}: menu-owned keyboard behavior leaked in`);
+ }
+ if (facts.pointerSelection !== facts.operable) {
+ wrong.push(
+ `${state.id}: menu pointerSelection=${facts.pointerSelection} but operable=${facts.operable}`,
+ );
+ }
+ } else {
+ if (
+ facts.spaceSelection ||
+ facts.pointerSelection ||
+ facts.arrowSelection
+ ) {
+ wrong.push(`${state.id}: option row claims group-level interaction`);
+ }
+ if (facts.pointerCancellation !== facts.operable) {
+ wrong.push(
+ `${state.id}: pointerCancellation=${facts.pointerCancellation} but operable=${facts.operable}`,
+ );
+ }
+ }
+ }
+ expect(wrong).toEqual([]);
+ });
+
+ it('locks which bindings expose a visible label for the bound subject', () => {
+ const wrong = RADIO_GROUP_BINDING_STATES.filter(state => {
+ const expected =
+ state.binding !== 'SegmentedControl' &&
+ state.binding !== 'DropdownMenuRadioGroup' &&
+ state.id !== 'segmented-option-selected-hidden-label';
+ return state.facts.visibleLabel !== expected;
+ }).map(state => state.id);
+ expect(wrong).toEqual([]);
+ });
+
+ it('renders exactly one named subject for every state', () => {
+ for (const state of RADIO_GROUP_BINDING_STATES) {
+ render(RADIO_GROUP_STATE_RENDERS[state.id]());
+ expect(subjectFor(state), state.id).toBeTruthy();
+ cleanup();
+ }
+ });
+});
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.test.tsx b/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
index 669e9e7ece..32c645cd76 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
+++ b/packages/core/src/SegmentedControl/SegmentedControl.test.tsx
@@ -3,8 +3,11 @@
/**
* @file SegmentedControl.test.tsx
* @input Uses vitest, @testing-library/react, SegmentedControl components
- * @output Unit tests for SegmentedControl and SegmentedControlItem
- * @position Testing; validates SegmentedControl component implementation
+ * @output Component-specific callback, composition, layout, optional-key, and
+ * styling tests. Shared radio-group role, name, state, focus, and adopted
+ * interactions live in RadioList/__tests__/RadioGroup.a11y.*.
+ * @position Component-owned regression tests that do not duplicate the reusable
+ * radio-group contract.
*
* SYNC: When SegmentedControl components change, update tests to match new behavior
*/
@@ -47,41 +50,6 @@ beforeEach(() => {
});
describe('SegmentedControl', () => {
- it('renders a radiogroup with radio buttons', () => {
- render(
- <SegmentedControl value="grid" onChange={() => {}} label="View mode">
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
-
- expect(screen.getByRole('radiogroup')).toBeInTheDocument();
- expect(screen.getByRole('radiogroup')).toHaveAttribute(
- 'aria-label',
- 'View mode',
- );
- expect(screen.getByRole('radio', {name: 'Grid'})).toBeInTheDocument();
- expect(screen.getByRole('radio', {name: 'List'})).toBeInTheDocument();
- });
-
- it('marks selected item with aria-checked', () => {
- render(
- <SegmentedControl value="grid" onChange={() => {}} label="View mode">
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
-
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
- 'aria-checked',
- 'true',
- );
- expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
- 'aria-checked',
- 'false',
- );
- });
-
it('calls onChange when an item is clicked', async () => {
const user = userEvent.setup();
const handleChange = vi.fn();
@@ -230,49 +198,6 @@ describe('SegmentedControl', () => {
expect(labelStyle.textOverflow).toBe('ellipsis');
});
- it('uses roving tabindex — selected item has tabIndex 0, others -1', () => {
- render(
- <SegmentedControl value="list" onChange={() => {}} label="View mode">
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- <SegmentedControlItem value="table" label="Table" />
- </SegmentedControl>,
- );
-
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
- 'tabIndex',
- '-1',
- );
- expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
- 'tabIndex',
- '0',
- );
- expect(screen.getByRole('radio', {name: 'Table'})).toHaveAttribute(
- 'tabIndex',
- '-1',
- );
- });
-
- it('keeps a tab stop when the value matches no item (tab-stop repair)', () => {
- render(
- <SegmentedControl
- value="nonexistent"
- onChange={() => {}}
- label="View mode">
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- <SegmentedControlItem value="table" label="Table" />
- </SegmentedControl>,
- );
-
- // No item is selected, but the group must remain Tab-reachable: the first
- // enabled radio is promoted to tabIndex=0.
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
- 'tabIndex',
- '0',
- );
- });
-
it('promotes the first enabled item when the value matches no item and the first is disabled', () => {
render(
<SegmentedControl
@@ -360,7 +285,6 @@ describe('SegmentedControl keyboard navigation', () => {
await user.keyboard('{ArrowRight}');
expect(handleChange).toHaveBeenCalledWith('list');
- expect(screen.getByRole('radio', {name: 'List'})).toHaveFocus();
});
it('navigates with ArrowLeft and selects', async () => {
@@ -379,7 +303,6 @@ describe('SegmentedControl keyboard navigation', () => {
await user.keyboard('{ArrowLeft}');
expect(handleChange).toHaveBeenCalledWith('grid');
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveFocus();
});
it('wraps around from last to first with ArrowRight', async () => {
@@ -398,7 +321,6 @@ describe('SegmentedControl keyboard navigation', () => {
await user.keyboard('{ArrowRight}');
expect(handleChange).toHaveBeenCalledWith('grid');
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveFocus();
});
it('wraps around from first to last with ArrowLeft', async () => {
@@ -417,7 +339,6 @@ describe('SegmentedControl keyboard navigation', () => {
await user.keyboard('{ArrowLeft}');
expect(handleChange).toHaveBeenCalledWith('table');
- expect(screen.getByRole('radio', {name: 'Table'})).toHaveFocus();
});
it('Home key focuses first item', async () => {
@@ -460,59 +381,6 @@ describe('SegmentedControl keyboard navigation', () => {
});
describe('SegmentedControl disabled state', () => {
- it('marks entire group as disabled', () => {
- render(
- <SegmentedControl
- value="grid"
- onChange={() => {}}
- label="View mode"
- isDisabled>
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
-
- expect(screen.getByRole('radiogroup')).toHaveAttribute(
- 'aria-disabled',
- 'true',
- );
- });
-
- it('removes the tab stop from the selected item when the group is disabled (navigation-13)', () => {
- render(
- <SegmentedControl
- value="grid"
- onChange={() => {}}
- label="View mode"
- isDisabled>
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
- // Selected segment must not be a focusable-but-dead tab stop when disabled.
- const selected = screen.getByRole('radio', {name: 'Grid'});
- expect(selected).toHaveAttribute('tabIndex', '-1');
- expect(selected).toHaveAttribute('aria-disabled', 'true');
- // No enabled segment is tabbable either.
- expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
- 'tabIndex',
- '-1',
- );
- });
-
- it('removes the tab stop from an individually disabled selected item', () => {
- render(
- <SegmentedControl value="grid" onChange={() => {}} label="View mode">
- <SegmentedControlItem value="grid" label="Grid" isDisabled />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
- expect(screen.getByRole('radio', {name: 'Grid'})).toHaveAttribute(
- 'tabIndex',
- '-1',
- );
- });
-
it('does not call onChange when group is disabled', async () => {
const user = userEvent.setup({pointerEventsCheck: 0});
const handleChange = vi.fn();
@@ -543,11 +411,6 @@ describe('SegmentedControl disabled state', () => {
</SegmentedControl>,
);
- expect(screen.getByRole('radio', {name: 'List'})).toHaveAttribute(
- 'aria-disabled',
- 'true',
- );
-
await user.click(screen.getByRole('radio', {name: 'List'}));
expect(handleChange).not.toHaveBeenCalled();
});
@@ -634,20 +497,6 @@ describe('SegmentedControl disabled state', () => {
expect(screen.queryByRole('tooltip', h)).not.toBeInTheDocument();
});
- it('keeps the selected segment focusable when a reason is provided', () => {
- renderControl();
- const selected = screen.getByRole('radio', {name: 'Grid', hidden: true});
- expect(selected).toHaveAttribute('aria-disabled', 'true');
- expect(selected).toHaveAttribute('tabindex', '0');
- });
-
- it('links the reason tooltip from the group via aria-describedby', () => {
- renderControl();
- const group = screen.getByRole('radiogroup');
- const tooltip = screen.getByRole('tooltip', h);
- expect(group.getAttribute('aria-describedby')).toContain(tooltip.id);
- });
-
it('blocks selection while focusable-disabled', () => {
const onChange = vi.fn();
renderControl({onChange});
@@ -655,22 +504,6 @@ describe('SegmentedControl disabled state', () => {
fireEvent.click(list);
expect(onChange).not.toHaveBeenCalled();
});
-
- it('drops all segments from the tab order when disabled without a reason', () => {
- render(
- <SegmentedControl
- value="grid"
- onChange={() => {}}
- label="View mode"
- isDisabled>
- <SegmentedControlItem value="grid" label="Grid" />
- <SegmentedControlItem value="list" label="List" />
- </SegmentedControl>,
- );
- for (const radio of screen.getAllByRole('radio', h)) {
- expect(radio).toHaveAttribute('tabindex', '-1');
- }
- });
});
});