Skip to content

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

TypeScript

test(a11y): add Combobox semantic contract (#6886)

Cindy Zhange199fa45426d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7eca9425b4..66cff2406a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2011,6 +2011,60 @@ jobs:
retention-days: 30
if-no-files-found: warn
+ # The combobox contract's accessible name and its popup and
+ # active-descendant relationships are accessibility-tree facts that jsdom
+ # cannot observe. Run the contract's own fixture proof and the Selector
+ # binding whenever the PR scope names Selector, or the contract or its
+ # audit story changes. Its own --output directory; the JSON report is the
+ # head-bound record, uploaded next.
+ - name: Run Combobox accessibility contract
+ id: combobox-contract
+ if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+ env:
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ PLAYWRIGHT_JSON_OUTPUT_FILE: combobox-contract/report.json
+ run: |
+ should_run=false
+ COMPONENTS=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)
+ case ",${COMPONENTS}," in
+ *,core/Selector,*) should_run=true ;;
+ esac
+ # The contract belongs to no package, so compare the file names the
+ # PR changes since its merge base.
+ # The helper comes from the base, since an older PR head lacks it.
+ # Exit 1 means out of scope; 0 in scope; 2 unknown, so run.
+ scope=2
+ helper="$(mktemp)"
+ if git fetch --quiet --no-tags --depth=1 origin "$BASE_SHA" \
+ && git show "$BASE_SHA:.github/scripts/pr-scope-touches.sh" > "$helper"; then
+ scope=0
+ bash "$helper" "$BASE_SHA" \
+ '^(internal/a11y-spec/src/patterns/combobox|apps/storybook/stories/ComboboxA11y)' || scope=$?
+ fi
+ if [ "$scope" != 1 ]; then
+ should_run=true
+ fi
+ echo "should_run=${should_run}" >> "$GITHUB_OUTPUT"
+ if [ "$should_run" != true ]; then
+ echo "Selector and the combobox contract are not in PR scope; skipping combobox evidence."
+ exit 0
+ fi
+ pnpm exec playwright test \
+ internal/a11y-spec/src/patterns/combobox.chromium.spec.ts \
+ packages/core/src/Selector/__tests__/Selector.combobox.a11y.chromium.spec.ts \
+ --project chromium \
+ --reporter list,json \
+ --output combobox-contract-output
+
+ - name: Upload Combobox accessibility contract evidence
+ if: ${{ !cancelled() && steps.combobox-contract.outputs.should_run == 'true' }}
+ uses: actions/upload-artifact@v7
+ with:
+ name: combobox-contract-evidence-${{ needs.build-storybook.outputs.short_hash }}
+ path: combobox-contract/
+ retention-days: 30
+ if-no-files-found: warn
+
# The Schedule time grid owns scroll geometry — pinned header and gutter
# alignment under classic scrollbars, inline scroll ownership, keyboard
# reach and its focus ring — none of which exists in jsdom. Every
diff --git a/apps/storybook/stories/ComboboxA11y.stories.tsx b/apps/storybook/stories/ComboboxA11y.stories.tsx
new file mode 100644
index 0000000000..ac3313074e
--- /dev/null
+++ b/apps/storybook/stories/ComboboxA11y.stories.tsx
@@ -0,0 +1,75 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Checked-in browser fixtures for Selector's Combobox contract binding. */
+
+import {expect, userEvent, waitFor, within} from 'storybook/test';
+import type {Meta, StoryObj} from '@storybook/react';
+import {Selector} from '@astryxdesign/core/Selector';
+
+const meta: Meta<typeof Selector> = {
+ title: 'a11y/Combobox pattern',
+ component: Selector,
+ tags: ['no-visual'],
+ parameters: {layout: 'centered'},
+ decorators: [
+ Story => (
+ <div style={{width: 280}}>
+ <Story />
+ </div>
+ ),
+ ],
+ args: {
+ label: 'Fruit',
+ options: [
+ {value: 'apple', label: 'Apple'},
+ {value: 'banana', label: 'Banana'},
+ ],
+ onChange: () => {},
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof Selector>;
+
+export const SelectorClosed: Story = {};
+export const SelectorOpen: Story = {
+ play: async ({canvasElement}) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(canvas.getByRole('combobox', {name: 'Fruit'}));
+ await expect(canvas.getByRole('combobox', {name: 'Fruit'})).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ },
+};
+export const SelectorReadOnly: Story = {
+ args: {isReadOnly: true, value: 'apple'},
+};
+export const SelectorBusy: Story = {
+ args: {isLoading: true},
+};
+export const SelectorSheetOpen: Story = {
+ args: {presentation: 'bottom-sheet'},
+ play: async ({canvasElement}) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(canvas.getByRole('combobox', {name: 'Fruit'}));
+ const page = within(canvasElement.ownerDocument.body);
+ await expect(
+ await page.findByRole('dialog', {name: 'Fruit'}),
+ ).toBeVisible();
+ },
+};
+export const SelectorSearchActive: Story = {
+ args: {hasSearch: true},
+ play: async ({canvasElement}) => {
+ const canvas = within(canvasElement);
+ await userEvent.click(canvas.getByRole('button', {name: /Fruit/}));
+ const page = within(canvasElement.ownerDocument.body);
+ const search = await page.findByRole('combobox', {name: 'Search options'});
+ await waitFor(() => expect(search).toHaveFocus());
+ await userEvent.keyboard('{ArrowDown}');
+ await waitFor(() =>
+ expect(search).toHaveAttribute('aria-activedescendant'),
+ );
+ },
+};
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index c0dc1de4ff..97ead2badc 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -59,6 +59,7 @@ src/
├── slider.* a thumb's role, name, values, text, orientation, and arrow/Page/Home/End keys (RTL-mirrored arrows)
├── accordion.* a group's header role and name, panel state, single-expansion collapse, page Tab order
├── breadcrumb.* landmark, list-trail, current-page, and separator semantics
+ ├── combobox.* control identity, state, popup, and active-descendant semantics
├── landmark.* one component-owned landmark region's role, name, and content boundary
└── link.* one available link's role, name, current state, focus, and activation
```
@@ -81,6 +82,7 @@ src/
| `disclosure` | [APG Disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) | Standalone Collapsible triggers and their controlled content |
| `accordion` | [APG Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) required parts | CollapsibleGroup headers: button role and name, expanded state, controlled panel, Enter/Space, single-expansion sibling collapse, page Tab order, no arrow-key movement (single-expansion collapse, grouped Tab order, no arrow movement are advisory until `component:CollapsibleGroup` AR4 is current) |
| `breadcrumb` | WCAG 2.2 semantics; [APG Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) as context | Breadcrumbs landmarks, list trails, current-page state, and separators |
+| `combobox` | WCAG 2.2 + [WAI-ARIA 1.2 Combobox](https://www.w3.org/TR/wai-aria-1.2/#combobox); APG as context | Selector trigger identity, state, popup, and active-descendant relationships |
| `landmark` | WCAG 2.2 semantics; [APG Landmark Regions](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/) as context | LayoutHeader, LayoutContent, LayoutFooter, and LayoutPanel caller-declared landmarks |
| `slider` | [APG Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) role, values, name, orientation and keys | Slider thumbs: role, name, now/min/max, value text, orientation, arrows (RTL-mirrored), Page, Home/End, disabled keeps value |
| `treeview` | [APG Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) structure and keyboard model | TreeList rows: tree/treeitem/group, aria-expanded, level/position, one Tab stop, Up/Down, Right/Left (RTL-mirrored), Home/End, Enter or Space, typeahead |
@@ -122,6 +124,17 @@ no-current-page opt-out. Link, action-button, and sibling-menu semantics stay
with their own patterns; the APG Breadcrumb page remains context because no
current Astryx record adopts it as an additional required gate.
+The combobox contract owns the named control, expanded/busy/read-only state,
+its relationship to a rendered popup, and a declared active descendant. Its
+first Selector binding covers closed, open, read-only, busy, and bottom-sheet
+trigger states plus the search input with an active option. While a binding's
+own modal dialog popup makes the combobox inert, the browser correctly leaves it
+out of the accessibility tree, so the identity expectation does not apply there.
+Popup contents keep the existing listbox contract. `spec:AST-020/FR15` adopts
+the APG Combobox required parts, including Tab plus Enter or Space activation,
+wherever a part plays the combobox role; each adopter's record names them and its
+interaction suites verify the keyboard and selection parts.
+
The landmark contract owns one component-owned landmark region: the role the
binding declares, the label it declares, and the content the region bounds. It
reports the APG unique-label principle for same-role peers as advisory because
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index 52200dfcfb..6768e03677 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -134,6 +134,12 @@ export {
type BreadcrumbStateFacts,
} from './patterns/breadcrumb';
+export {
+ COMBOBOX_PATTERN,
+ type ComboboxPopupRole,
+ type ComboboxStateFacts,
+} from './patterns/combobox';
+
export {
LANDMARK_PATTERN,
type LandmarkRole,
diff --git a/internal/a11y-spec/src/patterns/combobox.chromium.spec.ts b/internal/a11y-spec/src/patterns/combobox.chromium.spec.ts
new file mode 100644
index 0000000000..357bcdbb02
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/combobox.chromium.spec.ts
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Real-browser positive and mutation proof for the Combobox contract. */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {describeExpectation, requiredLayers} from '../contract';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {
+ CHROMIUM_OBSERVES,
+ createChromiumHarness,
+ holdMotionStill,
+} from '../harness/chromium';
+import {COMBOBOX_PATTERN} from './combobox';
+import {
+ COMBOBOX_ACTIVE_SELECTOR,
+ COMBOBOX_MUTATIONS,
+ COMBOBOX_POPUP_SELECTOR,
+ COMBOBOX_SUBJECT_SELECTOR,
+ CONFORMING_COMBOBOX_FIXTURES,
+ comboboxFixture,
+ type ComboboxFixture,
+} from './combobox.fixtures';
+
+function fixturePage(html: string): string {
+ return `<!doctype html><html lang="en"><body>${html}</body></html>`;
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: ComboboxFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await checkAccessibilitySpec({
+ spec: COMBOBOX_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixturePage(target.html));
+ // A modal popup fixture opens as a real modal so the browser makes the
+ // combobox behind it inert, as a modal sheet does.
+ await page.evaluate(() => {
+ for (const dialog of document.querySelectorAll<HTMLDialogElement>(
+ 'dialog[data-combobox-show-modal]',
+ )) {
+ dialog.showModal();
+ }
+ });
+ await holdMotionStill(page);
+ const related: Record<string, Locator> = {};
+ const popup = page.locator(COMBOBOX_POPUP_SELECTOR);
+ if ((await popup.count()) > 0) {
+ related.popup = popup;
+ }
+ const active = page.locator(COMBOBOX_ACTIVE_SELECTOR);
+ if ((await active.count()) > 0) {
+ related['active-descendant'] = active;
+ }
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: page.locator(COMBOBOX_SUBJECT_SELECTOR),
+ related,
+ });
+ },
+ });
+ return run.results;
+}
+
+test.describe('Combobox contract — conforming fixtures', () => {
+ for (const id of CONFORMING_COMBOBOX_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, comboboxFixture(id));
+ expect(
+ observed
+ .filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ )
+ .map(result => `${result.expectation}: ${result.detail ?? ''}`),
+ ).toEqual([]);
+ });
+ }
+});
+
+test.describe('Combobox contract — deliberately violating fixtures', () => {
+ for (const expectation of COMBOBOX_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ for (const fixtureId of COMBOBOX_MUTATIONS[expectation.id] ?? []) {
+ test(`${describeExpectation(expectation)} — fails against ${fixtureId}`, async ({
+ page,
+ }) => {
+ const cdp = await page.context().newCDPSession(page);
+ const [result] = await results(page, cdp, comboboxFixture(fixtureId), [
+ expectation.id,
+ ]);
+ expect(result?.status, result?.detail ?? 'no result').toBe('fail');
+ expect(result?.detail ?? '').not.toBe('');
+ });
+ }
+ }
+});
diff --git a/internal/a11y-spec/src/patterns/combobox.fixtures.ts b/internal/a11y-spec/src/patterns/combobox.fixtures.ts
new file mode 100644
index 0000000000..cf872e8e53
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/combobox.fixtures.ts
@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Semantic HTML fixtures and one-outcome mutations for the Combobox contract. */
+
+import type {ComboboxStateFacts} from './combobox';
+
+export const COMBOBOX_SUBJECT_SELECTOR = '[data-combobox-subject]';
+export const COMBOBOX_POPUP_SELECTOR = '[data-combobox-popup]';
+export const COMBOBOX_ACTIVE_SELECTOR = '[data-combobox-active]';
+
+export interface ComboboxFixture {
+ readonly id: string;
+ readonly html: string;
+ readonly facts: ComboboxStateFacts;
+}
+
+const openFacts: ComboboxStateFacts = {
+ name: 'Fruit',
+ expanded: true,
+ popupRole: 'listbox',
+ popupVisible: true,
+ activeDescendant: true,
+ readOnly: false,
+ busy: false,
+ inertUnderOwnModal: false,
+};
+
+const closedFacts: ComboboxStateFacts = {
+ ...openFacts,
+ expanded: false,
+ popupVisible: false,
+ activeDescendant: false,
+};
+
+const fixtures: Readonly<Record<string, ComboboxFixture>> = {
+ 'conforming-open-input': {
+ id: 'conforming-open-input',
+ facts: openFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-list" aria-haspopup="listbox" aria-activedescendant="apple" aria-busy="false"><div data-combobox-popup id="fruit-list" role="listbox" aria-label="Fruit choices"><div data-combobox-active id="apple" role="option" aria-selected="false">Apple</div></div>',
+ },
+ 'conforming-closed-input': {
+ id: 'conforming-closed-input',
+ facts: closedFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="false">',
+ },
+ 'conforming-readonly-button': {
+ id: 'conforming-readonly-button',
+ facts: {
+ ...closedFacts,
+ name: 'Assigned owner',
+ readOnly: true,
+ },
+ html: '<button data-combobox-subject role="combobox" aria-label="Assigned owner" aria-expanded="false" aria-readonly="true">Alice</button>',
+ },
+ 'conforming-busy-input': {
+ id: 'conforming-busy-input',
+ facts: {...closedFacts, busy: true},
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="false" aria-busy="true">',
+ },
+ 'conforming-modal-sheet-button': {
+ id: 'conforming-modal-sheet-button',
+ facts: {
+ ...openFacts,
+ popupRole: 'dialog',
+ activeDescendant: false,
+ inertUnderOwnModal: true,
+ },
+ html: '<button data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-sheet" aria-haspopup="dialog">Apple</button><dialog data-combobox-popup data-combobox-show-modal id="fruit-sheet" aria-label="Fruit"><div role="listbox" aria-label="Fruit choices"><div role="option" aria-selected="true">Apple</div></div></dialog>',
+ },
+ 'inert-claim-without-modal-dialog': {
+ id: 'inert-claim-without-modal-dialog',
+ facts: {...openFacts, activeDescendant: false, inertUnderOwnModal: true},
+ html: '<input data-combobox-subject role="button" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-list" aria-haspopup="listbox"><div data-combobox-popup id="fruit-list" role="listbox"><div role="option">Apple</div></div>',
+ },
+ 'wrong-role': {
+ id: 'wrong-role',
+ facts: closedFacts,
+ html: '<input data-combobox-subject role="button" aria-label="Fruit" aria-expanded="false">',
+ },
+ 'missing-name': {
+ id: 'missing-name',
+ facts: closedFacts,
+ html: '<input data-combobox-subject role="combobox" aria-expanded="false">',
+ },
+ 'open-exposed-collapsed': {
+ id: 'open-exposed-collapsed',
+ facts: openFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="false" aria-controls="fruit-list" aria-haspopup="listbox" aria-activedescendant="apple"><div data-combobox-popup id="fruit-list" role="listbox"><div data-combobox-active id="apple" role="option">Apple</div></div>',
+ },
+ 'broken-popup-reference': {
+ id: 'broken-popup-reference',
+ facts: openFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="missing-list" aria-haspopup="listbox" aria-activedescendant="apple"><div data-combobox-popup id="fruit-list" role="listbox"><div data-combobox-active id="apple" role="option">Apple</div></div>',
+ },
+ 'wrong-popup-kind': {
+ id: 'wrong-popup-kind',
+ facts: {...openFacts, popupRole: 'dialog', activeDescendant: false},
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-dialog" aria-haspopup="listbox"><div data-combobox-popup id="fruit-dialog" role="dialog" aria-label="Fruit choices"></div>',
+ },
+ 'broken-active-reference': {
+ id: 'broken-active-reference',
+ facts: openFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-list" aria-haspopup="listbox" aria-activedescendant="missing-option"><div data-combobox-popup id="fruit-list" role="listbox"><div data-combobox-active id="apple" role="option">Apple</div></div>',
+ },
+ 'active-outside-popup': {
+ id: 'active-outside-popup',
+ facts: openFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="true" aria-controls="fruit-list" aria-haspopup="listbox" aria-activedescendant="apple"><div data-combobox-popup id="fruit-list" role="listbox"></div><div data-combobox-active id="apple" role="option">Apple</div>',
+ },
+ 'readonly-missing-state': {
+ id: 'readonly-missing-state',
+ facts: {...closedFacts, name: 'Assigned owner', readOnly: true},
+ html: '<button data-combobox-subject role="combobox" aria-label="Assigned owner" aria-expanded="false">Alice</button>',
+ },
+ 'readonly-retains-surface': {
+ id: 'readonly-retains-surface',
+ facts: {...closedFacts, name: 'Assigned owner', readOnly: true},
+ html: '<button data-combobox-subject role="combobox" aria-label="Assigned owner" aria-expanded="false" aria-readonly="true" aria-controls="owners" aria-activedescendant="alice">Alice</button>',
+ },
+ 'busy-state-omitted': {
+ id: 'busy-state-omitted',
+ facts: {...closedFacts, busy: true},
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="false">',
+ },
+ 'idle-exposed-busy': {
+ id: 'idle-exposed-busy',
+ facts: closedFacts,
+ html: '<input data-combobox-subject role="combobox" aria-label="Fruit" aria-expanded="false" aria-busy="true">',
+ },
+};
+
+export const CONFORMING_COMBOBOX_FIXTURES = [
+ 'conforming-open-input',
+ 'conforming-closed-input',
+ 'conforming-readonly-button',
+ 'conforming-busy-input',
+ 'conforming-modal-sheet-button',
+] as const;
+
+export const COMBOBOX_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
+ 'combobox.identity.named': [
+ 'wrong-role',
+ 'missing-name',
+ 'inert-claim-without-modal-dialog',
+ ],
+ 'combobox.state.expanded': ['open-exposed-collapsed'],
+ 'combobox.popup.relationship': ['broken-popup-reference', 'wrong-popup-kind'],
+ 'combobox.active-descendant.owned': [
+ 'broken-active-reference',
+ 'active-outside-popup',
+ ],
+ 'combobox.state.readonly-closed': [
+ 'readonly-missing-state',
+ 'readonly-retains-surface',
+ ],
+ 'combobox.state.busy': ['busy-state-omitted', 'idle-exposed-busy'],
+};
+
+export function comboboxFixture(id: string): ComboboxFixture {
+ const fixture = fixtures[id];
+ if (fixture == null) {
+ throw new Error(`unknown Combobox fixture: ${id}`);
+ }
+ return fixture;
+}
diff --git a/internal/a11y-spec/src/patterns/combobox.jsdom.test.ts b/internal/a11y-spec/src/patterns/combobox.jsdom.test.ts
new file mode 100644
index 0000000000..45e26e8995
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/combobox.jsdom.test.ts
@@ -0,0 +1,164 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Contract self-tests for Combobox DOM expectations and completeness. */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {
+ citeSource,
+ describeExpectation,
+ requiredLayers,
+ unansweredDimensions,
+} from '../contract';
+import {checkAccessibilitySpec, type ExpectationResult} from '../check';
+import {JSDOM_OBSERVES, createJsdomHarness} from '../harness/jsdom';
+import {COMBOBOX_PATTERN} from './combobox';
+import {
+ COMBOBOX_ACTIVE_SELECTOR,
+ COMBOBOX_MUTATIONS,
+ COMBOBOX_POPUP_SELECTOR,
+ COMBOBOX_SUBJECT_SELECTOR,
+ CONFORMING_COMBOBOX_FIXTURES,
+ comboboxFixture,
+ type ComboboxFixture,
+} from './combobox.fixtures';
+
+afterEach(() => document.body.replaceChildren());
+
+async function resultsFor(target: ComboboxFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const run = await checkAccessibilitySpec({
+ spec: COMBOBOX_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(COMBOBOX_SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${target.id}" is missing its combobox`);
+ }
+ const related: Record<string, Element> = {};
+ const popup = container.querySelector(COMBOBOX_POPUP_SELECTOR);
+ if (popup != null) {
+ related.popup = popup;
+ }
+ const active = container.querySelector(COMBOBOX_ACTIVE_SELECTOR);
+ if (active != null) {
+ related['active-descendant'] = active;
+ }
+ return createJsdomHarness({subject, related});
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return run.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;
+}
+
+const observableHere = COMBOBOX_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+describe('Combobox contract — completeness', () => {
+ it('answers every completeness dimension', () => {
+ expect(unansweredDimensions(COMBOBOX_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation at least one deliberately violating fixture', () => {
+ expect(
+ COMBOBOX_PATTERN.expectations
+ .filter(
+ expectation =>
+ (COMBOBOX_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id),
+ ).toEqual([]);
+ });
+
+ it('has an expectation for every mutation it records', () => {
+ const ids = new Set(
+ COMBOBOX_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(Object.keys(COMBOBOX_MUTATIONS).filter(id => !ids.has(id))).toEqual(
+ [],
+ );
+ });
+});
+
+describe('Combobox contract — identity applicability under a modal popup', () => {
+ it('skips identity only while its own modal dialog popup makes the combobox inert', async () => {
+ const modal = resultFor(
+ await resultsFor(comboboxFixture('conforming-modal-sheet-button')),
+ 'combobox.identity.named',
+ );
+ expect(modal.status).toBe('not-applicable');
+
+ const claimWithoutModal = resultFor(
+ await resultsFor(comboboxFixture('inert-claim-without-modal-dialog')),
+ 'combobox.identity.named',
+ );
+ expect(claimWithoutModal.status).not.toBe('not-applicable');
+ });
+});
+
+describe('Combobox contract — the jsdom harness stays within its evidence boundary', () => {
+ it('runs DOM expectations and reports accessibility-tree expectations as unrun', async () => {
+ const results = await resultsFor(comboboxFixture('conforming-open-input'));
+ expect(results.some(result => result.status === 'pass')).toBe(true);
+ const unrun = results.filter(result => result.status === 'unrun');
+ expect(unrun).toHaveLength(1);
+ expect(unrun[0]?.missingLayers).toContain('accessibility-tree');
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = COMBOBOX_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_COMBOBOX_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply to it)',
+ async name => {
+ const result = resultFor(await resultsFor(comboboxFixture(name)), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((COMBOBOX_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = resultFor(await resultsFor(comboboxFixture(name)), id);
+ expect(result.status, `${id} against ${name}`).toBe('fail');
+ expect(result.detail ?? '').not.toBe('');
+ },
+ );
+
+ it('carries its id and primary source into every result description', async () => {
+ const target = comboboxFixture(
+ COMBOBOX_MUTATIONS[id]?.[0] ?? CONFORMING_COMBOBOX_FIXTURES[0],
+ );
+ const result = resultFor(await resultsFor(target), id);
+ expect(result.description).toContain(id);
+ expect(result.description).toContain(citeSource(expectation.sources[0]));
+ expect(describeExpectation(expectation)).toBe(result.description);
+ });
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/combobox.ts b/internal/a11y-spec/src/patterns/combobox.ts
new file mode 100644
index 0000000000..a66a67eb3c
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/combobox.ts
@@ -0,0 +1,464 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file combobox.ts
+ * @input Uses the shared accessibility-contract vocabulary
+ * @output COMBOBOX_PATTERN and ComboboxStateFacts
+ * @position Reusable semantic contract for the combobox control and its active popup relation.
+ * Popup contents and binding-specific selection policy retain their own owners.
+ *
+ * Required outcomes come from WCAG 2.2 A/AA, WAI-ARIA 1.2, and the current
+ * Astryx read-only selection-input contract. `spec:AST-020/FR15` adopts the
+ * APG Combobox required parts, including Tab plus Enter or Space activation,
+ * wherever a part plays the combobox role; each adopter's record names them and
+ * its own interaction suites verify the keyboard parts. This contract encodes
+ * the semantic parts only.
+ */
+
+import {
+ definePattern,
+ type AstryxRecord,
+ type PatternContract,
+ type WcagCriterion,
+ type WebStandardRequirement,
+} from '../contract';
+
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
+
+function wcag(
+ id: string,
+ name: string,
+ level: 'A' | 'AA',
+ slug: string,
+): WcagCriterion {
+ return {
+ standard: 'wcag',
+ id,
+ name,
+ level,
+ url: `${UNDERSTANDING}/${slug}.html`,
+ };
+}
+
+const WCAG_1_3_1 = wcag(
+ '1.3.1',
+ 'Info and Relationships',
+ 'A',
+ 'info-and-relationships',
+);
+const WCAG_4_1_2 = wcag('4.1.2', 'Name, Role, Value', 'A', 'name-role-value');
+
+const ARIA_CONTROLS: WebStandardRequirement = {
+ standard: 'web-standard',
+ specification: 'WAI-ARIA 1.2',
+ requirement:
+ "When a combobox's popup is displayed, authors MUST ensure the aria-controls attribute on the combobox element is set to a value that refers to the popup element.",
+ url: 'https://www.w3.org/TR/wai-aria-1.2/#combobox',
+};
+
+const ARIA_ACTIVE_DESCENDANT: WebStandardRequirement = {
+ standard: 'web-standard',
+ specification: 'WAI-ARIA 1.2',
+ requirement:
+ 'The value of aria-activedescendant is an ID reference to an owned element.',
+ url: 'https://www.w3.org/TR/wai-aria-1.2/#aria-activedescendant',
+};
+
+const AST_011_READ_ONLY: AstryxRecord = {
+ standard: 'astryx',
+ id: 'spec:AST-011',
+ clause: 'FR4',
+ requirement:
+ 'The focusable read-only value MUST retain `combobox` semantics, expose `aria-readonly="true"` and `aria-expanded="false"`, and preserve its accessible name and rendered value. It MUST NOT expose `aria-controls` or `aria-activedescendant` when no selection surface exists.',
+ url: 'https://github.com/facebook/astryx/blob/f0355e3a4c9ddacb71e4cc9ca045619b76ae3c35/docs/specs/AST-011/spec.md#L47-L51',
+};
+
+export type ComboboxPopupRole = 'listbox' | 'tree' | 'grid' | 'dialog';
+
+export interface ComboboxStateFacts {
+ /** Exact accessible name the binding supplies. */
+ readonly name: string;
+ /** Whether the binding's selection surface is currently open. */
+ readonly expanded: boolean;
+ /** Semantic role of the popup the binding owns. */
+ readonly popupRole: ComboboxPopupRole;
+ /** Whether that popup is currently rendered and available. */
+ readonly popupVisible: boolean;
+ /** Whether the binding declares one active descendant in the popup. */
+ readonly activeDescendant: boolean;
+ /** Whether the current value is intentionally non-editable. */
+ readonly readOnly: boolean;
+ /** Whether the component's option source or value transition is pending. */
+ readonly busy: boolean;
+ /**
+ * Whether the binding's own open modal dialog popup makes the combobox inert,
+ * so the browser correctly leaves it out of the accessibility tree until the
+ * popup closes.
+ */
+ readonly inertUnderOwnModal: boolean;
+}
+
+const ALWAYS = {
+ condition: 'the binding renders a combobox control',
+ test: () => true,
+};
+
+export const COMBOBOX_PATTERN: PatternContract<ComboboxStateFacts> =
+ definePattern<ComboboxStateFacts>({
+ pattern: 'combobox',
+ url: 'https://www.w3.org/TR/wai-aria-1.2/#combobox',
+ scope:
+ 'The named combobox control, its expanded/busy/read-only state, and its relationship to a currently rendered popup and active descendant. Popup contents and interaction policy remain separate owners.',
+ expectations: [
+ {
+ id: 'combobox.identity.named',
+ outcome:
+ 'The browser exposes one named combobox so a person can find and distinguish the selection control.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition:
+ 'the combobox is in the accessibility tree: no open modal dialog popup of its own makes it inert',
+ test: facts =>
+ !(
+ facts.inertUnderOwnModal &&
+ facts.popupVisible &&
+ facts.popupRole === 'dialog'
+ ),
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {role, name} = await subject.computed();
+ if (role !== 'combobox') {
+ throw new Error(
+ `the browser exposes ${role == null ? 'no role' : `"${role}"`} instead of combobox`,
+ );
+ }
+ if (name !== facts.name) {
+ throw new Error(
+ `the combobox should be named "${facts.name}", but the browser computes ${name === '' ? 'no name' : `"${name}"`}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'combobox.state.expanded',
+ outcome:
+ 'The combobox exposes whether its current selection surface is open.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const expanded = await subject.attribute('aria-expanded');
+ if (expanded !== String(facts.expanded)) {
+ throw new Error(
+ `the combobox is ${facts.expanded ? 'open' : 'closed'} but aria-expanded is ${expanded ?? 'absent'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'combobox.popup.relationship',
+ outcome:
+ 'An open combobox identifies the popup it controls and its popup kind.',
+ sources: [WCAG_1_3_1, ARIA_CONTROLS],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the selection surface is rendered',
+ test: facts => facts.popupVisible,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ const popup = await harness.related('popup');
+ if (!(await harness.references(subject, 'aria-controls', popup))) {
+ throw new Error(
+ 'aria-controls does not reference the rendered combobox popup',
+ );
+ }
+ const hasPopup = await subject.attribute('aria-haspopup');
+ if (
+ facts.popupRole === 'listbox'
+ ? hasPopup !== null && hasPopup !== 'listbox'
+ : hasPopup !== facts.popupRole
+ ) {
+ throw new Error(
+ `the combobox popup is ${facts.popupRole} but aria-haspopup is ${hasPopup ?? 'absent'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'combobox.active-descendant.owned',
+ outcome:
+ 'When DOM focus stays on the combobox, its active descendant resolves inside the current popup.',
+ sources: [WCAG_1_3_1, ARIA_ACTIVE_DESCENDANT],
+ covers: ['1.3.1-info-and-relationships', '4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding declares an active descendant',
+ test: facts => facts.activeDescendant,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ const popup = await harness.related('popup');
+ const active = await harness.related('active-descendant');
+ if (
+ !(await harness.references(
+ subject,
+ 'aria-activedescendant',
+ active,
+ ))
+ ) {
+ throw new Error(
+ 'aria-activedescendant does not reference the declared active option',
+ );
+ }
+ if (!(await harness.contains(popup, active))) {
+ throw new Error(
+ 'the declared active descendant is not contained by the combobox popup',
+ );
+ }
+ },
+ },
+ {
+ id: 'combobox.state.readonly-closed',
+ outcome:
+ 'A read-only value keeps its combobox identity while exposing no active selection surface.',
+ sources: [AST_011_READ_ONLY, WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding is read-only',
+ test: facts => facts.readOnly,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ if ((await subject.attribute('aria-readonly')) !== 'true') {
+ throw new Error(
+ 'the read-only combobox does not expose aria-readonly="true"',
+ );
+ }
+ if ((await subject.attribute('aria-expanded')) !== 'false') {
+ throw new Error(
+ 'the read-only combobox is not exposed as collapsed',
+ );
+ }
+ if ((await subject.attribute('aria-controls')) != null) {
+ throw new Error(
+ 'the read-only combobox still exposes aria-controls',
+ );
+ }
+ if ((await subject.attribute('aria-activedescendant')) != null) {
+ throw new Error(
+ 'the read-only combobox still exposes aria-activedescendant',
+ );
+ }
+ },
+ },
+ {
+ id: 'combobox.state.busy',
+ outcome:
+ 'The combobox exposes whether its option source or value transition is pending.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const busy = await subject.attribute('aria-busy');
+ if (
+ facts.busy ? busy !== 'true' : busy !== null && busy !== 'false'
+ ) {
+ throw new Error(
+ `the combobox is ${facts.busy ? 'busy' : 'idle'} but aria-busy is ${busy ?? 'absent'}`,
+ );
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'Binding option content and composed Icon/Indicator owners',
+ verifiedBy:
+ 'Component icon tests, content review, and repository axe checks',
+ reason:
+ 'The combobox control relationship does not determine the alternative text or decorative treatment of caller-rendered content.',
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'Popup pattern and binding-specific field composition',
+ verifiedBy:
+ 'Popup/listbox contracts, component tests, and axe content-model checks',
+ reason:
+ 'This contract checks the combobox-to-popup and active-descendant relationships; labels, descriptions, groups, and popup contents keep their own owners.',
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'Binding component and composing page',
+ verifiedBy:
+ 'Component DOM-order tests and page-level reading-order review',
+ reason:
+ 'The semantic relationship does not choose visual or reading order for the field, popup, or surrounding content.',
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'Form callsite and binding input props',
+ verifiedBy: 'Form-purpose and autocomplete review',
+ reason:
+ 'Only a caller knows whether a combobox collects a standardized personal-information purpose.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'Binding component, option-state owner, and active theme',
+ verifiedBy: 'Rendered state review and visual regression checks',
+ reason: 'Programmatic state does not prove a non-color visual cue.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'Binding component and active theme',
+ verifiedBy: 'Rendered contrast audit',
+ reason: 'Text contrast requires resolved pixels and backdrop.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'Binding component, popup owner, and active theme',
+ verifiedBy:
+ 'Rendered control, state, and focus-indicator contrast review',
+ reason:
+ 'Semantic state does not measure painted boundaries or indicators.',
+ },
+ '2.1.1-keyboard': {
+ owner: 'Current binding component authority',
+ verifiedBy:
+ 'Binding-specific keyboard suites and real-browser interaction tests',
+ reason:
+ 'spec:AST-020/FR15 adopts Tab plus Enter or Space activation wherever a part plays the combobox role; button triggers, editable inputs, anchored popups, and modal sheets reach it differently, so each adopter record names its keyboard parts and its interaction suites verify them.',
+ },
+ '2.1.2-no-keyboard-trap': {
+ owner: 'Binding popup, Layer, and dismissal owners',
+ verifiedBy: 'Real-browser Tab, Escape, close, and focus-return tests',
+ reason:
+ 'Entry and exit depend on the active presentation and popup lifecycle.',
+ },
+ '2.4.2-page-titled': {
+ owner: 'Page shell',
+ verifiedBy: 'Page-level title review',
+ reason: 'A combobox does not own the document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'Binding component and composing page',
+ verifiedBy: 'Real-browser sequential-focus review',
+ reason:
+ 'Focus order depends on field composition and popup presentation.',
+ },
+ '2.4.4-link-purpose': {
+ owner: 'Link and caller content',
+ verifiedBy: 'Navigation-owner tests and content review',
+ reason:
+ 'A combobox selects or filters values rather than defining link purpose.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'Caller label content and field owner',
+ verifiedBy: 'Content review of visible labels and instructions',
+ reason:
+ 'This contract proves the exact declared accessible name, not whether its wording describes the intended purpose.',
+ },
+ '2.4.7-focus-visible': {
+ owner:
+ 'Binding component, interaction-modality architecture, and active theme',
+ verifiedBy: 'Rendered keyboard-focus review',
+ reason: 'Focus-indicator paint requires visual evidence.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'Popup host and application layout',
+ verifiedBy: 'Constrained-viewport real-browser focus review',
+ reason:
+ 'Occlusion depends on presentation geometry and surrounding layout.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'Binding interaction owner',
+ verifiedBy: 'Real-browser press, abort, and release tests',
+ reason:
+ 'This semantic contract does not activate the control or its options.',
+ },
+ '2.5.3-label-in-name': {
+ owner: 'Binding rendering and caller-provided visible label',
+ verifiedBy: 'Visible-label versus computed-name browser review',
+ reason:
+ 'An exact computed name does not prove that it contains independently rendered visible text.',
+ },
+ '2.5.8-target-size': {
+ owner: 'Binding component and composition',
+ verifiedBy: 'Rendered target geometry and WCAG exception review',
+ reason: 'Target size and spacing cannot be proved from semantic state.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'Page shell and localization provider',
+ verifiedBy: 'Document-language checks',
+ reason: 'A combobox does not own the document language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'Binding selection owner and application response',
+ verifiedBy: 'Component callback tests and end-to-end task review',
+ reason:
+ 'This contract exposes state without deciding what selection changes do in the application.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'Design system and caller content',
+ verifiedBy: 'Cross-control design and content review',
+ reason:
+ 'Consistency is a property of repeated controls, not one binding.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'Field-status and binding validation owners',
+ verifiedBy: 'Component error-state tests and rendered content review',
+ reason:
+ 'The generic combobox relationship does not define validation errors.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'Field and caller content',
+ verifiedBy: 'Component label/instruction tests and form review',
+ reason:
+ 'A computed accessible name does not prove persistent visible instructions.',
+ },
+ '4.1.2-name-role-value': {
+ owner:
+ 'Popup contents, option pattern, and binding-specific value/validation owners',
+ verifiedBy: 'Their reusable contracts and focused component tests',
+ reason:
+ 'This contract encodes combobox identity, open/busy/read-only state, and active relationships; popup item state, rendered value, and validation retain their owners.',
+ coversRemainderOnly: true,
+ },
+ '4.1.3-status-messages': {
+ owner: 'Binding result-feedback and status-message owners',
+ verifiedBy:
+ 'Live-region/status tests and AST-009 for spoken timing claims',
+ reason:
+ 'Busy exposure is state on the control; result counts, empty messages, and announcement timing are separate outcomes.',
+ },
+ 'apg-interaction': {
+ owner: 'Current authority for each Astryx combobox adopter',
+ verifiedBy:
+ 'Binding-specific interaction suites and exact current component records',
+ reason:
+ 'spec:AST-020/FR15 decides which APG Combobox parts an adopter takes from the role its part plays; the adopter record names them and its interaction suites verify the interaction parts.',
+ },
+ 'forced-colors': {
+ owner: 'Binding component, popup contents, and active theme',
+ verifiedBy: 'Rendered forced-colors review',
+ reason: 'Semantic exposure does not prove forced-colors paint.',
+ },
+ 'reduced-motion': {
+ owner: 'Binding popup and layer owners',
+ verifiedBy: 'Component motion tests and rendered reduced-motion review',
+ reason:
+ 'The semantic contract adds no motion and cannot measure transitions.',
+ },
+ 'at-facing-strings': {
+ owner: 'Binding localization and caller-provided labels',
+ verifiedBy:
+ 'Catalog checks and localized component tests; AST-009 for speech claims',
+ reason:
+ 'The contract verifies declared text without claiming spoken wording, order, or timing.',
+ },
+ },
+ });
diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.md
index 8946ebdd0d..050ce75c12 100644
--- a/packages/core/src/Selector/Selector.spec.md
+++ b/packages/core/src/Selector/Selector.spec.md
@@ -16,6 +16,8 @@ verified_by:
packages/core/src/Selector/Selector.source-build.test.mjs,
packages/core/src/Selector/__tests__/Selector.listbox.a11y.test.tsx,
packages/core/src/Selector/__tests__/Listbox.a11y.chromium.spec.ts,
+ packages/core/src/Selector/__tests__/Selector.combobox.a11y.test.tsx,
+ packages/core/src/Selector/__tests__/Selector.combobox.a11y.chromium.spec.ts,
apps/storybook/stories/Selector.stories.tsx,
.github/scripts/story-play-guard.js,
]
@@ -329,17 +331,18 @@ new theming target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |
-| FR2 | placement and selected-item geometry tests | default, explicit, RTL, transformed entry | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |
-| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |
-| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |
-| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates; the exact unnamed no-search sheet state remains known debt | `audit:Selector/accessibility` |
-| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |
-| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |
-| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |
-| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |
+| FR2 | placement and selected-item geometry tests | default, explicit, RTL, transformed entry | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |
+| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |
+| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |
+| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates; the exact unnamed no-search sheet state remains known debt | `audit:Selector/accessibility` |
+| FR5, FR6, AR1, AR2 (anchored), AR4 | `Selector.combobox.a11y.test.tsx` and `Selector.combobox.a11y.chromium.spec.ts` against the shared Combobox contract | closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's `aria-controls` naming the inner listbox remains exact known debt | `audit:Selector/accessibility` |
+| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |
+| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |
+| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |
+| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |
## Decision log
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index 5b9b78bb7b..dc32eda138 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -991,7 +991,10 @@ describe('Selector', () => {
expect(screen.getByRole('combobox', h)).toBeInTheDocument();
});
- it('wires the search input as the combobox with activedescendant (comboboxes-4)', async () => {
+ // The search input's expanded state, popup relationship, and active option
+ // are bound to the shared Combobox contract (Selector.combobox.a11y.test.tsx,
+ // search-active); this keeps only the Selector-specific wiring.
+ it('moves combobox semantics to the list-autocomplete search input (comboboxes-4)', async () => {
const user = userEvent.setup();
render(
<Selector
@@ -1008,12 +1011,6 @@ describe('Selector', () => {
await user.click(triggerBtn);
const search = screen.getByRole('combobox', h);
expect(search).toHaveAttribute('aria-autocomplete', 'list');
- expect(search).toHaveAttribute('aria-expanded', 'true');
- expect(search).toHaveAttribute('aria-controls');
- // ArrowDown moves the highlight; the search input reports it via
- // aria-activedescendant (previously silent on the trigger).
- await user.keyboard('{ArrowDown}');
- expect(search).toHaveAttribute('aria-activedescendant');
});
it('PageDown/PageUp jump the highlight to the last/first filtered option', async () => {
@@ -1352,7 +1349,6 @@ describe('Selector', () => {
<Selector label="Fruit" options={[]} onChange={() => {}} isLoading />,
);
const trigger = screen.getByRole('combobox', {name: 'Fruit'});
- expect(trigger).toHaveAttribute('aria-busy', 'true');
expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
await user.click(trigger);
diff --git a/packages/core/src/Selector/__tests__/Combobox.a11y.known-failures.ts b/packages/core/src/Selector/__tests__/Combobox.a11y.known-failures.ts
new file mode 100644
index 0000000000..6a66a129e2
--- /dev/null
+++ b/packages/core/src/Selector/__tests__/Combobox.a11y.known-failures.ts
@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Combobox.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Current public-safe Selector Combobox binding failures
+ * @position AST-021 debt records; operational ownership remains outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const SELECTOR_COMBOBOX_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+ {
+ expectation: 'combobox.popup.relationship',
+ binding: 'Selector.trigger',
+ state: 'sheet-open',
+ evidenceLayer: 'dom',
+ failureEquals:
+ 'aria-controls does not reference the rendered combobox popup',
+ standardsReference:
+ 'WAI-ARIA 1.2 combobox: aria-controls refers to the displayed popup element; WCAG 2.2 1.3.1 Info and Relationships (Level A)',
+ userImpact:
+ 'On touch screens the trigger announces that it opens a dialog, but its controls relationship points past that dialog to the list inside it, so assistive technology that follows the relationship reaches the list without the sheet that hosts it.',
+ reason:
+ 'The trigger declares the sheet dialog as its popup kind while aria-controls names the inner listbox. Pointing both at one popup changes Selector runtime semantics under AR1, which needs its own decision; this test-only binding records the gap.',
+ },
+];
diff --git a/packages/core/src/Selector/__tests__/Combobox.a11y.states.ts b/packages/core/src/Selector/__tests__/Combobox.a11y.states.ts
new file mode 100644
index 0000000000..2fd50936dc
--- /dev/null
+++ b/packages/core/src/Selector/__tests__/Combobox.a11y.states.ts
@@ -0,0 +1,145 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * Explicit Selector states bound to the reusable Combobox contract, plus the
+ * states that stay out of it and why.
+ */
+
+import type {ComboboxStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface SelectorComboboxScenario {
+ readonly id:
+ 'closed' | 'open' | 'read-only' | 'busy' | 'sheet-open' | 'search-active';
+ /** `trigger` is the Selector button; `search` is the popup's search input. */
+ readonly binding: 'Selector.trigger' | 'Selector.search';
+ readonly storyId: string;
+ readonly open: boolean;
+ /** Move the highlight to the first option from the search input. */
+ readonly highlightFirst?: boolean;
+ readonly props: {
+ readonly isReadOnly?: boolean;
+ readonly isLoading?: boolean;
+ readonly value?: string;
+ readonly presentation?: 'bottom-sheet';
+ readonly hasSearch?: boolean;
+ };
+ readonly facts: ComboboxStateFacts;
+}
+
+const baseFacts: ComboboxStateFacts = {
+ name: 'Fruit',
+ expanded: false,
+ popupRole: 'listbox',
+ popupVisible: false,
+ activeDescendant: false,
+ readOnly: false,
+ busy: false,
+ inertUnderOwnModal: false,
+};
+
+export const SELECTOR_COMBOBOX_SCENARIOS: ReadonlyArray<SelectorComboboxScenario> =
+ [
+ {
+ id: 'closed',
+ binding: 'Selector.trigger',
+ storyId: 'a11y-combobox-pattern--selector-closed',
+ open: false,
+ props: {},
+ facts: baseFacts,
+ },
+ {
+ id: 'open',
+ binding: 'Selector.trigger',
+ storyId: 'a11y-combobox-pattern--selector-open',
+ open: true,
+ props: {},
+ facts: {
+ ...baseFacts,
+ expanded: true,
+ popupVisible: true,
+ activeDescendant: true,
+ },
+ },
+ {
+ id: 'read-only',
+ binding: 'Selector.trigger',
+ storyId: 'a11y-combobox-pattern--selector-read-only',
+ open: false,
+ props: {isReadOnly: true, value: 'apple'},
+ facts: {...baseFacts, readOnly: true},
+ },
+ {
+ id: 'busy',
+ binding: 'Selector.trigger',
+ storyId: 'a11y-combobox-pattern--selector-busy',
+ open: false,
+ props: {isLoading: true},
+ facts: {...baseFacts, busy: true},
+ },
+ {
+ // AR1: the touch presentation's popup is a modal dialog that contains
+ // the listbox, and the trigger declares aria-haspopup="dialog".
+ id: 'sheet-open',
+ binding: 'Selector.trigger',
+ storyId: 'a11y-combobox-pattern--selector-sheet-open',
+ open: true,
+ props: {presentation: 'bottom-sheet'},
+ facts: {
+ ...baseFacts,
+ expanded: true,
+ popupRole: 'dialog',
+ popupVisible: true,
+ activeDescendant: true,
+ // The modal sheet makes the trigger inert, so the browser leaves it
+ // out of the accessibility tree until the sheet closes.
+ inertUnderOwnModal: true,
+ },
+ },
+ {
+ // With hasSearch, focus moves into the popup's search input, which owns
+ // the combobox role and reports the highlighted option.
+ id: 'search-active',
+ binding: 'Selector.search',
+ storyId: 'a11y-combobox-pattern--selector-search-active',
+ open: true,
+ highlightFirst: true,
+ props: {hasSearch: true},
+ facts: {
+ ...baseFacts,
+ name: 'Search options',
+ expanded: true,
+ popupVisible: true,
+ activeDescendant: true,
+ },
+ },
+ ];
+
+/** Selector states that change a combobox outcome but are not bound here. */
+export const SELECTOR_COMBOBOX_EXCLUSIONS = [
+ {
+ owner: 'Selector trigger with hasSearch',
+ reason:
+ 'Editable search mode moves combobox semantics to the popup search input, bound as Selector.search; the trigger is not a combobox in that mode.',
+ },
+ {
+ owner: 'Selector search input inside the bottom sheet',
+ reason:
+ 'The search input keeps the semantics bound in search-active; the sheet changes only its modal host, which the modal-dialog owner covers.',
+ },
+ {
+ owner: 'Selector interaction suites',
+ reason:
+ 'Keyboard activation, arrow/Home/End/typeahead movement, Escape, Tab, and selection policy are verified by Selector.test.tsx (AR3); this contract encodes semantics only.',
+ },
+ {
+ owner: 'Disabled and disabledMessage triggers',
+ reason:
+ 'Availability state belongs to the disabled-state owners; this contract has no disabled expectation.',
+ },
+ {
+ owner:
+ 'MultiSelector, Typeahead, Tokenizer, PowerSearch, ComplexSelector, CommandPalette',
+ reason:
+ 'Later bounded adopters; this first binding is limited to Selector.',
+ },
+] as const;
diff --git a/packages/core/src/Selector/__tests__/Selector.combobox.a11y.chromium.spec.ts b/packages/core/src/Selector/__tests__/Selector.combobox.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..c151e0538e
--- /dev/null
+++ b/packages/core/src/Selector/__tests__/Selector.combobox.a11y.chromium.spec.ts
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Chromium accessibility-tree and relationship proof for Selector's Combobox binding. */
+
+import {expect, test, type Locator, type Page} from '@playwright/test';
+import {
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {createChromiumHarness} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {COMBOBOX_PATTERN} from '@astryxdesign/a11y-spec';
+import {
+ SELECTOR_COMBOBOX_SCENARIOS,
+ type SelectorComboboxScenario,
+} from './Combobox.a11y.states';
+import {SELECTOR_COMBOBOX_KNOWN_FAILURES} from './Combobox.a11y.known-failures';
+
+let storybook: StaticServer;
+const observedResults: BindingResult[] = [];
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+ expect(
+ unmatchedKnownFailures(SELECTOR_COMBOBOX_KNOWN_FAILURES, observedResults),
+ ).toEqual([]);
+});
+
+async function awaitScenario(
+ page: Page,
+ scenario: SelectorComboboxScenario,
+): Promise<void> {
+ if (!scenario.open) {
+ return;
+ }
+ await expect(page.getByRole('listbox')).toBeVisible();
+ if (scenario.highlightFirst) {
+ await expect(
+ page.getByRole('combobox', {name: scenario.facts.name}),
+ ).toHaveAttribute('aria-activedescendant', /.+/);
+ }
+}
+
+for (const scenario of SELECTOR_COMBOBOX_SCENARIOS) {
+ test(`Selector Combobox contract — ${scenario.id}`, async ({page}) => {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${scenario.storyId}&viewMode=story`,
+ {waitUntil: 'load'},
+ );
+ await awaitScenario(page, scenario);
+
+ // A modal sheet makes the trigger inert, so find it among hidden nodes too.
+ const subject = page.getByRole('combobox', {
+ name: scenario.facts.name,
+ includeHidden: true,
+ });
+ if (
+ scenario.binding === 'Selector.trigger' &&
+ scenario.facts.popupVisible
+ ) {
+ // AR1: the trigger names the popup kind its presentation renders.
+ await expect(subject).toHaveAttribute(
+ 'aria-haspopup',
+ scenario.facts.popupRole,
+ );
+ }
+ const related: Record<string, Locator> = {};
+ if (scenario.facts.popupVisible) {
+ related.popup =
+ scenario.facts.popupRole === 'dialog'
+ ? page.getByRole('dialog', {name: 'Fruit'})
+ : page.getByRole('listbox');
+ }
+ if (scenario.facts.activeDescendant) {
+ related['active-descendant'] = page.getByRole('option', {name: 'Apple'});
+ }
+ const cdp = await page.context().newCDPSession(page);
+ const run = await checkAccessibilitySpec({
+ spec: COMBOBOX_PATTERN,
+ binding: scenario.binding,
+ state: scenario.id,
+ facts: scenario.facts,
+ knownFailures: SELECTOR_COMBOBOX_KNOWN_FAILURES,
+ mount: async () => createChromiumHarness({page, cdp, subject, related}),
+ });
+ observedResults.push(run);
+
+ expect(formatFailures(blockingResults([run]))).toBe('');
+ expect(
+ run.results
+ .filter(result => result.status === 'unrun')
+ .map(result => `${result.expectation}: ${result.detail ?? ''}`),
+ ).toEqual([]);
+ });
+}
diff --git a/packages/core/src/Selector/__tests__/Selector.combobox.a11y.test.tsx b/packages/core/src/Selector/__tests__/Selector.combobox.a11y.test.tsx
new file mode 100644
index 0000000000..f6d1e5845b
--- /dev/null
+++ b/packages/core/src/Selector/__tests__/Selector.combobox.a11y.test.tsx
@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Selector's first binding to the reusable Combobox semantic contract. */
+
+import {cleanup, render, screen, waitFor, within} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {describe, expect, it} from 'vitest';
+import {
+ COMBOBOX_PATTERN,
+ expectAccessibilitySpec,
+} from '@astryxdesign/a11y-spec';
+import {Selector} from '../Selector';
+import {installListboxDialogStubs} from './Listbox.a11y.dom';
+import {
+ SELECTOR_COMBOBOX_EXCLUSIONS,
+ SELECTOR_COMBOBOX_SCENARIOS,
+ type SelectorComboboxScenario,
+} from './Combobox.a11y.states';
+import {SELECTOR_COMBOBOX_KNOWN_FAILURES} from './Combobox.a11y.known-failures';
+
+installListboxDialogStubs();
+
+const hidden = {hidden: true} as const;
+
+function subjectFor(scenario: SelectorComboboxScenario): HTMLElement {
+ return screen.getByRole('combobox', {...hidden, name: scenario.facts.name});
+}
+
+describe('Selector Combobox semantic binding', () => {
+ it.each(SELECTOR_COMBOBOX_SCENARIOS)('$id', async scenario => {
+ await expectAccessibilitySpec({
+ spec: COMBOBOX_PATTERN,
+ binding: scenario.binding,
+ state: scenario.id,
+ facts: scenario.facts,
+ knownFailures: SELECTOR_COMBOBOX_KNOWN_FAILURES,
+ render: async () => {
+ render(
+ <Selector
+ label="Fruit"
+ options={[
+ {value: 'apple', label: 'Apple'},
+ {value: 'banana', label: 'Banana'},
+ ]}
+ onChange={() => {}}
+ {...scenario.props}
+ />,
+ );
+ if (!scenario.open) {
+ return;
+ }
+ const user = userEvent.setup();
+ await user.click(
+ scenario.props.hasSearch
+ ? screen.getByRole('button', {name: /Fruit/})
+ : screen.getByRole('combobox', {name: 'Fruit'}),
+ );
+ await screen.findByRole('listbox', hidden);
+ if (scenario.highlightFirst) {
+ const search = subjectFor(scenario);
+ await waitFor(() => expect(search).toHaveFocus());
+ await user.keyboard('{ArrowDown}');
+ }
+ },
+ subject: () => subjectFor(scenario),
+ related: () => {
+ const related: Record<string, Element> = {};
+ if (!scenario.facts.popupVisible) {
+ return related;
+ }
+ const listbox = screen.getByRole('listbox', hidden);
+ if (scenario.binding === 'Selector.trigger') {
+ // AR1: the trigger names the popup kind its presentation renders.
+ expect(subjectFor(scenario)).toHaveAttribute(
+ 'aria-haspopup',
+ scenario.facts.popupRole,
+ );
+ }
+ related.popup =
+ scenario.facts.popupRole === 'dialog'
+ ? screen.getByRole('dialog', {...hidden, name: 'Fruit'})
+ : listbox;
+ if (scenario.facts.activeDescendant) {
+ expect(
+ subjectFor(scenario).getAttribute('aria-activedescendant'),
+ ).not.toBeNull();
+ related['active-descendant'] = within(listbox).getByRole('option', {
+ ...hidden,
+ name: 'Apple',
+ });
+ }
+ return related;
+ },
+ cleanup,
+ });
+ });
+
+ it('keeps the bounded first-adopter state matrix explicit', () => {
+ expect(
+ SELECTOR_COMBOBOX_SCENARIOS.map(scenario => [
+ scenario.binding,
+ scenario.id,
+ ]),
+ ).toEqual([
+ ['Selector.trigger', 'closed'],
+ ['Selector.trigger', 'open'],
+ ['Selector.trigger', 'read-only'],
+ ['Selector.trigger', 'busy'],
+ ['Selector.trigger', 'sheet-open'],
+ ['Selector.search', 'search-active'],
+ ]);
+ expect(SELECTOR_COMBOBOX_EXCLUSIONS).toHaveLength(5);
+ });
+
+ it('pins every known failure to exactly one bound state', () => {
+ expect(SELECTOR_COMBOBOX_KNOWN_FAILURES).toHaveLength(1);
+ for (const record of SELECTOR_COMBOBOX_KNOWN_FAILURES) {
+ expect(
+ SELECTOR_COMBOBOX_SCENARIOS.filter(
+ scenario =>
+ scenario.binding === record.binding && scenario.id === record.state,
+ ),
+ ).toHaveLength(1);
+ }
+ });
+});