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.ymlindex 7eca9425b4..66cff2406a 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -2011,6 +2011,60 @@ jobs:retention-days: 30if-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. Everydiff --git a/apps/storybook/stories/ComboboxA11y.stories.tsx b/apps/storybook/stories/ComboboxA11y.stories.tsxnew file mode 100644index 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.mdindex 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 staywith their own patterns; the APG Breadcrumb page remains context because nocurrent 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 thebinding declares, the label it declares, and the content the region bounds. Itreports the APG unique-label principle for same-role peers as advisory becausediff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdindex 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 logdiff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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);+ }+ });+});