Skip to content

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

TypeScript

test(a11y): add shared Spinbutton contract (#6638)

Cindy Zhange78c3ce46a5c
diff --git a/apps/storybook/stories/NumberInputA11y.stories.tsx b/apps/storybook/stories/NumberInputA11y.stories.tsx
new file mode 100644
index 0000000000..357a127474
--- /dev/null
+++ b/apps/storybook/stories/NumberInputA11y.stories.tsx
@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** One checked-in Storybook fixture for every NumberInput Spinbutton state. */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {NUMBER_INPUT_A11Y_RENDERS} from '../../../packages/core/src/NumberInput/__tests__/NumberInput.a11y.renders';
+import {NUMBER_INPUT_A11Y_STATES} from '../../../packages/core/src/NumberInput/__tests__/NumberInput.a11y.states';
+
+function storyFor(id: string): StoryObj {
+ const state = NUMBER_INPUT_A11Y_STATES.find(candidate => candidate.id === id);
+ if (state == null) {
+ throw new Error(`no binding state "${id}"`);
+ }
+ return {
+ name: `NumberInput — ${state.id}`,
+ render: () => NUMBER_INPUT_A11Y_RENDERS[state.id](),
+ };
+}
+
+const meta: Meta = {
+ title: 'a11y/Spinbutton pattern',
+ tags: ['no-visual'],
+ parameters: {
+ docs: {
+ description: {
+ component:
+ 'Binding states for the NumberInput Spinbutton accessibility contract.',
+ },
+ },
+ },
+};
+
+export default meta;
+export const DefaultValue = storyFor('default-value');
+export const BoundedValue = storyFor('bounded-value');
+export const FormattedValue = storyFor('formatted-value');
+export const EmptyValue = storyFor('empty-value');
+export const Invalid = storyFor('invalid');
+export const Disabled = storyFor('disabled');
+export const DisabledWithMessage = storyFor('disabled-with-message');
+export const ReadOnly = storyFor('read-only');
+export const ArrowStepping = storyFor('arrow-stepping');
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index f521cbf790..f03b46a840 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -48,22 +48,32 @@ src/
├── modal-dialog.* the native modal-dialog pattern, same four files
├── status-message.* live-region and progress status mechanics
├── tabs.* explicit horizontal ARIA Tabs semantics
- └── listbox.* listbox, group, and option semantics
+ ├── listbox.* listbox, group, and option semantics
+ └── spinbutton.* numeric role, value, bounds, state, and arrow stepping
```
## The patterns
-| Pattern | Adopted from | Bound by |
-| ---------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `radio-group` | [APG radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | RadioList, SegmentedControl; role/state portions of DropdownMenu radio items |
-| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
-| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
-| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
-| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
-| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
-| `status-message` | [WCAG 2.2 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Toast, FieldStatus, Spinner, ChatSystemMessage, ChatTypingIndicator, ProgressBar |
-| `tabs` | [APG Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Explicit `role="tablist"` TabList, Tab, and caller-authored tabpanels |
-| `listbox` | [WAI-ARIA 1.2 Listbox](https://www.w3.org/TR/wai-aria-1.2/#listbox) and WCAG 2.2 semantics | Selector and MultiSelector popup listbox, group, and option parts |
+| Pattern | Adopted from | Bound by |
+| ---------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `radio-group` | [APG radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | RadioList, SegmentedControl; role/state portions of DropdownMenu radio items |
+| `checkbox` | [APG checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | CheckboxInput, CheckboxListItem, DropdownMenuCheckboxItem, SelectableCard |
+| `switch` | [APG switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Switch |
+| `button` | [APG button](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | Button, IconButton, ClickableCard, SideNavCollapseButton, ChatSendButton |
+| `text-input` | Native HTML controls and [WAI-ARIA textbox](https://www.w3.org/TR/wai-aria-1.2/#textbox) | TextInput, TextArea |
+| `modal-dialog` | [APG dialog (modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Dialog |
+| `status-message` | [WCAG 2.2 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | Toast, FieldStatus, Spinner, ChatSystemMessage, ChatTypingIndicator, ProgressBar |
+| `tabs` | [APG Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Explicit `role="tablist"` TabList, Tab, and caller-authored tabpanels |
+| `listbox` | [WAI-ARIA 1.2 Listbox](https://www.w3.org/TR/wai-aria-1.2/#listbox) and WCAG 2.2 semantics | Selector and MultiSelector popup listbox, group, and option parts |
+| `spinbutton` | WCAG 2.2 semantics and [APG Spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) | NumberInput |
+
+The `spinbutton` contract owns NumberInput's required role, persistent name,
+committed numeric value, optional bounds and formatted value text, disabled and
+read-only exposure, and keyboard reachability. ArrowUp and ArrowDown stepping
+are recorded as advisory APG evidence because no current Astryx authority
+adopts those mechanics as a shared requirement. Typed draft parsing,
+formatting, commit/clamp policy, callbacks, optional buttons, and date/time
+segments keep their existing owners.
The `listbox` contract is a bounded semantic migration, not blanket APG
interaction adoption. Its first bindings cover 21 existing scenarios across
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index 185c9be2b8..c10b28db48 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -112,3 +112,8 @@ export {BUTTON_PATTERN, type ButtonStateFacts} from './patterns/button';
export {TABS_PATTERN, type TabsStateFacts} from './patterns/tabs';
export {LISTBOX_PATTERN, type ListboxStateFacts} from './patterns/listbox';
+
+export {
+ SPINBUTTON_PATTERN,
+ type SpinbuttonStateFacts,
+} from './patterns/spinbutton';
diff --git a/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts b/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts
new file mode 100644
index 0000000000..6ca4432840
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/spinbutton.chromium.spec.ts
@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Chromium positive and mutation proof for the shared Spinbutton contract. */
+
+import {expect, test, type Page} from '@playwright/test';
+import {checkAccessibilitySpec, requiredLayers} from '../index';
+import {CHROMIUM_OBSERVES, createChromiumHarness} from '../harness/chromium';
+import {SPINBUTTON_PATTERN} from './spinbutton';
+import {
+ CONFORMING_SPINBUTTON_FIXTURES,
+ SPINBUTTON_MUTATIONS,
+ SPINBUTTON_SUBJECT_SELECTOR,
+ spinbuttonFixture,
+} from './spinbutton.fixtures';
+
+async function run(page: Page, id: string, only?: readonly string[]) {
+ const fixture = spinbuttonFixture(id);
+ const cdp = await page.context().newCDPSession(page);
+ return checkAccessibilitySpec({
+ spec: SPINBUTTON_PATTERN,
+ binding: 'fixture',
+ state: id,
+ facts: fixture.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixture.html);
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: page.locator(SPINBUTTON_SUBJECT_SELECTOR),
+ });
+ },
+ });
+}
+
+for (const expectation of SPINBUTTON_PATTERN.expectations) {
+ test(`${expectation.id} has Chromium coverage`, async ({page}) => {
+ expect(
+ requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ ),
+ ).toBe(true);
+ const conforming = CONFORMING_SPINBUTTON_FIXTURES.find(id => {
+ const fixture = spinbuttonFixture(id);
+ return expectation.appliesWhen.test(fixture.facts);
+ });
+ if (conforming == null) {
+ throw new Error(`no conforming fixture exercises ${expectation.id}`);
+ }
+ const result = await run(page, conforming, [expectation.id]);
+ expect(result.results[0]?.status).toBe('pass');
+ });
+
+ for (const mutation of SPINBUTTON_MUTATIONS[expectation.id] ?? []) {
+ test(`${expectation.id} rejects ${mutation}`, async ({page}) => {
+ const result = await run(page, mutation, [expectation.id]);
+ expect(result.results[0]?.status).toBe('fail');
+ expect(result.results[0]?.description).toContain(expectation.id);
+ });
+ }
+}
diff --git a/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts b/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts
new file mode 100644
index 0000000000..8918bfbb54
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/spinbutton.fixtures.ts
@@ -0,0 +1,238 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Plain-HTML positive and mutation fixtures for the Spinbutton contract. */
+
+import type {SpinbuttonStateFacts} from './spinbutton';
+
+export const SPINBUTTON_SUBJECT_SELECTOR = '[data-a11y-subject]';
+
+export interface SpinbuttonFixture {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: SpinbuttonStateFacts;
+ readonly html: string;
+}
+
+function facts(
+ overrides: Partial<SpinbuttonStateFacts> = {},
+): SpinbuttonStateFacts {
+ return {
+ value: 5,
+ min: 1,
+ max: 9,
+ valueText: null,
+ disabled: false,
+ readOnly: false,
+ focusable: true,
+ stepUpValue: 6,
+ stepDownValue: 4,
+ ...overrides,
+ };
+}
+
+interface Options {
+ readonly role?: string;
+ readonly label?: boolean;
+ readonly value?: number | null;
+ readonly min?: number | null;
+ readonly max?: number | null;
+ readonly valueText?: string | null;
+ readonly disabled?: boolean;
+ readonly readOnly?: boolean;
+ readonly tabIndex?: number;
+ readonly trapTab?: boolean;
+ readonly brokenUp?: boolean;
+ readonly brokenDown?: boolean;
+}
+
+function html(options: Options = {}): string {
+ const value = options.value === undefined ? 5 : options.value;
+ const min = options.min === undefined ? 1 : options.min;
+ const max = options.max === undefined ? 9 : options.max;
+ const valueText = options.valueText === undefined ? null : options.valueText;
+ const role = options.role ?? 'spinbutton';
+ const label = options.label ?? true;
+ return `
+ <button type="button">Before</button>
+ ${label ? '<label for="amount">Quantity</label>' : ''}
+ <input data-a11y-subject id="amount" type="text" role="${role}"
+ ${value == null ? '' : `value="${value}" aria-valuenow="${value}"`}
+ ${min == null ? '' : `aria-valuemin="${min}"`}
+ ${max == null ? '' : `aria-valuemax="${max}"`}
+ ${valueText == null ? '' : `aria-valuetext="${valueText}"`}
+ ${options.disabled ? 'disabled' : ''}
+ ${options.readOnly ? 'readonly' : ''}
+ ${options.tabIndex == null ? '' : `tabindex="${options.tabIndex}"`}
+ onkeydown="
+ if (event.key === 'Tab' && ${options.trapTab ? 'true' : 'false'}) event.preventDefault();
+ if (event.key === 'ArrowUp' && ${options.brokenUp ? 'false' : 'true'}) { this.value = '6'; this.setAttribute('aria-valuenow', '6'); }
+ if (event.key === 'ArrowDown' && ${options.brokenDown ? 'false' : 'true'}) { this.value = '4'; this.setAttribute('aria-valuenow', '4'); }
+ " />
+ <button type="button">After</button>
+ `;
+}
+
+export const SPINBUTTON_FIXTURES: readonly SpinbuttonFixture[] = [
+ {
+ id: 'conforming-value',
+ summary: 'a labelled bounded spinbutton',
+ facts: facts(),
+ html: html(),
+ },
+ {
+ id: 'conforming-formatted',
+ summary: 'a formatted spinbutton value',
+ facts: facts({valueText: '5 GB', stepUpValue: null, stepDownValue: null}),
+ html: html({valueText: '5 GB'}),
+ },
+ {
+ id: 'conforming-empty',
+ summary: 'an empty spinbutton',
+ facts: facts({
+ value: null,
+ min: null,
+ max: null,
+ stepUpValue: null,
+ stepDownValue: null,
+ }),
+ html: html({value: null, min: null, max: null}),
+ },
+ {
+ id: 'conforming-disabled',
+ summary: 'a disabled spinbutton',
+ facts: facts({
+ disabled: true,
+ focusable: false,
+ stepUpValue: null,
+ stepDownValue: null,
+ }),
+ html: html({disabled: true}),
+ },
+ {
+ id: 'conforming-readonly',
+ summary: 'a read-only spinbutton',
+ facts: facts({readOnly: true, stepUpValue: null, stepDownValue: null}),
+ html: html({readOnly: true}),
+ },
+ {
+ id: 'violating-role',
+ summary: 'a textbox instead of a spinbutton',
+ facts: facts(),
+ html: html({role: 'textbox'}),
+ },
+ {
+ id: 'violating-name',
+ summary: 'an unnamed spinbutton',
+ facts: facts(),
+ html: html({label: false}),
+ },
+ {
+ id: 'violating-label',
+ summary: 'a spinbutton without a persistent label',
+ facts: facts(),
+ html: html({label: false}),
+ },
+ {
+ id: 'violating-value',
+ summary: 'a stale exposed value',
+ facts: facts(),
+ html: html({value: 4}),
+ },
+ {
+ id: 'violating-empty-value',
+ summary: 'an empty binding with stale aria-valuenow',
+ facts: facts({
+ value: null,
+ min: null,
+ max: null,
+ stepUpValue: null,
+ stepDownValue: null,
+ }),
+ html: html({value: 5, min: null, max: null}),
+ },
+ {
+ id: 'violating-bounds',
+ summary: 'incorrect exposed bounds',
+ facts: facts(),
+ html: html({min: 0, max: 10}),
+ },
+ {
+ id: 'violating-value-text',
+ summary: 'incorrect formatted value text',
+ facts: facts({valueText: '5 GB', stepUpValue: null, stepDownValue: null}),
+ html: html({valueText: 'five'}),
+ },
+ {
+ id: 'violating-disabled',
+ summary: 'an available control declared disabled',
+ facts: facts({disabled: true, stepUpValue: null, stepDownValue: null}),
+ html: html(),
+ },
+ {
+ id: 'violating-false-disabled',
+ summary: 'a disabled control declared available',
+ facts: facts({stepUpValue: null, stepDownValue: null}),
+ html: html({disabled: true}),
+ },
+ {
+ id: 'violating-readonly',
+ summary: 'an editable control declared read-only',
+ facts: facts({readOnly: true, stepUpValue: null, stepDownValue: null}),
+ html: html(),
+ },
+ {
+ id: 'violating-unreachable',
+ summary: 'a spinbutton outside the tab sequence',
+ facts: facts(),
+ html: html({tabIndex: -1}),
+ },
+ {
+ id: 'violating-trap',
+ summary: 'a spinbutton that traps Tab',
+ facts: facts(),
+ html: html({trapTab: true}),
+ },
+ {
+ id: 'violating-arrow-up',
+ summary: 'a spinbutton that ignores Up Arrow',
+ facts: facts(),
+ html: html({brokenUp: true}),
+ },
+ {
+ id: 'violating-arrow-down',
+ summary: 'a spinbutton that ignores Down Arrow',
+ facts: facts(),
+ html: html({brokenDown: true}),
+ },
+];
+
+export const CONFORMING_SPINBUTTON_FIXTURES = SPINBUTTON_FIXTURES.filter(
+ fixture => fixture.id.startsWith('conforming-'),
+).map(fixture => fixture.id);
+
+export const SPINBUTTON_MUTATIONS: Readonly<Record<string, readonly string[]>> =
+ {
+ 'spinbutton.identity.exposed': ['violating-role', 'violating-name'],
+ 'spinbutton.label.persistently-associated': ['violating-label'],
+ 'spinbutton.value.exposed': ['violating-value'],
+ 'spinbutton.value.empty': ['violating-empty-value'],
+ 'spinbutton.bounds.exposed': ['violating-bounds'],
+ 'spinbutton.value-text.exposed': ['violating-value-text'],
+ 'spinbutton.disabled.exposed': ['violating-disabled'],
+ 'spinbutton.available.not-disabled': ['violating-false-disabled'],
+ 'spinbutton.readonly.exposed': ['violating-readonly'],
+ 'spinbutton.keyboard.reachable-and-escapable': [
+ 'violating-unreachable',
+ 'violating-trap',
+ ],
+ 'spinbutton.keyboard.arrow-up': ['violating-arrow-up'],
+ 'spinbutton.keyboard.arrow-down': ['violating-arrow-down'],
+ };
+
+export function spinbuttonFixture(id: string): SpinbuttonFixture {
+ const fixture = SPINBUTTON_FIXTURES.find(candidate => candidate.id === id);
+ if (fixture == null) {
+ throw new Error(`unknown Spinbutton fixture "${id}"`);
+ }
+ return fixture;
+}
diff --git a/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts b/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts
new file mode 100644
index 0000000000..75ca677137
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/spinbutton.jsdom.test.ts
@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Contract completeness, evidence-boundary, and DOM mutation proof. */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {checkAccessibilitySpec} from '../check';
+import {requiredLayers, unansweredDimensions} from '../contract';
+import {createJsdomHarness, JSDOM_OBSERVES} from '../harness/jsdom';
+import {SPINBUTTON_PATTERN} from './spinbutton';
+import {
+ CONFORMING_SPINBUTTON_FIXTURES,
+ SPINBUTTON_MUTATIONS,
+ SPINBUTTON_SUBJECT_SELECTOR,
+ spinbuttonFixture,
+} from './spinbutton.fixtures';
+
+afterEach(() => document.body.replaceChildren());
+
+async function run(id: string) {
+ const fixture = spinbuttonFixture(id);
+ return checkAccessibilitySpec({
+ spec: SPINBUTTON_PATTERN,
+ binding: 'fixture',
+ state: id,
+ facts: fixture.facts,
+ mount: async () => {
+ document.body.innerHTML = fixture.html;
+ const subject = document.querySelector(SPINBUTTON_SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${id}" marks no subject`);
+ }
+ return createJsdomHarness({subject});
+ },
+ unmount: () => document.body.replaceChildren(),
+ });
+}
+
+const observableHere = SPINBUTTON_PATTERN.expectations.filter(expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+describe('Spinbutton contract — completeness', () => {
+ it('answers every checklist dimension', () => {
+ expect(unansweredDimensions(SPINBUTTON_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation a deliberately violating fixture', () => {
+ expect(
+ SPINBUTTON_PATTERN.expectations
+ .filter(
+ expectation =>
+ (SPINBUTTON_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id),
+ ).toEqual([]);
+ });
+
+ it('has an expectation for every mutation entry', () => {
+ const ids = new Set(
+ SPINBUTTON_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(
+ Object.keys(SPINBUTTON_MUTATIONS).filter(id => !ids.has(id)),
+ ).toEqual([]);
+ });
+});
+
+describe('Spinbutton contract — jsdom evidence boundary', () => {
+ it('runs DOM expectations and reports browser-owned layers as unrun', async () => {
+ const result = await run('conforming-empty');
+ expect(result.results.some(row => row.status === 'pass')).toBe(true);
+ expect(result.results.some(row => row.status === 'unrun')).toBe(true);
+ expect(result.results.filter(row => row.status === 'fail')).toEqual([]);
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ it.each(CONFORMING_SPINBUTTON_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply)',
+ async name => {
+ const result = (await run(name)).results.find(
+ row => row.expectation === id,
+ );
+ expect(['pass', 'not-applicable']).toContain(result?.status);
+ },
+ );
+
+ it.each((SPINBUTTON_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = (await run(name)).results.find(
+ row => row.expectation === id,
+ );
+ expect(result?.status).toBe('fail');
+ expect(result?.description).toContain(id);
+ },
+ );
+ },
+);
diff --git a/internal/a11y-spec/src/patterns/spinbutton.ts b/internal/a11y-spec/src/patterns/spinbutton.ts
new file mode 100644
index 0000000000..0aa7486e77
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/spinbutton.ts
@@ -0,0 +1,515 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file spinbutton.ts
+ * @input Uses the shared accessibility contract vocabulary
+ * @output SPINBUTTON_PATTERN and SpinbuttonStateFacts
+ * @position Reusable semantic and keyboard contract for numeric spinbuttons.
+ *
+ * The required slice covers role, name, committed value, bounds, availability,
+ * read-only exposure, and keyboard entry/exit. Arrow stepping is exercised as
+ * advisory APG behavior until a current Astryx component record adopts it.
+ */
+
+import {
+ definePattern,
+ type ApgRequirement,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/';
+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_2_1_1 = wcag('2.1.1', 'Keyboard', 'A', 'keyboard');
+const WCAG_2_1_2 = wcag('2.1.2', 'No Keyboard Trap', 'A', 'no-keyboard-trap');
+const WCAG_2_4_6 = wcag(
+ '2.4.6',
+ 'Headings and Labels',
+ 'AA',
+ 'headings-and-labels',
+);
+const WCAG_4_1_2 = wcag('4.1.2', 'Name, Role, Value', 'A', 'name-role-value');
+
+function apg(requirement: string): ApgRequirement {
+ return {standard: 'apg', pattern: 'spinbutton', requirement, url: APG_URL};
+}
+
+const APG_ARROW_UP = apg('Up Arrow increases the value.');
+const APG_ARROW_DOWN = apg('Down Arrow decreases the value.');
+const APG_NOT_FORMALLY_ADOPTED =
+ 'NumberInput currently implements this APG mechanic, but no current component record adopts it as a reusable required gate.';
+const TAB_BUDGET = 10;
+
+export interface SpinbuttonStateFacts {
+ readonly value: number | null;
+ readonly min: number | null;
+ readonly max: number | null;
+ readonly valueText: string | null;
+ readonly disabled: boolean;
+ readonly readOnly: boolean;
+ readonly focusable: boolean;
+ readonly stepUpValue: number | null;
+ readonly stepDownValue: number | null;
+}
+
+const ALWAYS = {
+ condition: 'the binding renders a numeric spinbutton',
+ test: () => true,
+};
+
+export const SPINBUTTON_PATTERN: PatternContract<SpinbuttonStateFacts> =
+ definePattern<SpinbuttonStateFacts>({
+ pattern: 'spinbutton',
+ url: APG_URL,
+ scope:
+ 'One labelled numeric spinbutton and its committed value, optional bounds, availability, read-only state, keyboard reachability, and currently implemented arrow stepping.',
+ expectations: [
+ {
+ id: 'spinbutton.identity.exposed',
+ outcome:
+ 'The browser exposes a named spinbutton so the user knows what numeric value it edits.',
+ sources: [WCAG_4_1_2, WCAG_2_4_6],
+ covers: ['4.1.2-name-role-value', '2.4.6-headings-and-labels'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role, name} = await subject.computed();
+ if (role !== 'spinbutton') {
+ throw new Error(
+ `the browser exposes ${role == null ? 'no role' : `"${role}"`} instead of spinbutton`,
+ );
+ }
+ if (name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this spinbutton',
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.label.persistently-associated',
+ outcome:
+ 'The spinbutton keeps a persistent programmatic label rather than relying on placeholder text.',
+ sources: [WCAG_1_3_1, WCAG_2_4_6],
+ covers: ['1.3.1-info-and-relationships', '2.4.6-headings-and-labels'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const label = await subject.labelText();
+ if (label == null || label.trim() === '') {
+ throw new Error(
+ 'the spinbutton has no persistent label relationship',
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.value.exposed',
+ outcome:
+ 'The browser exposes the committed numeric value, not an uncommitted edit.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding has a committed value',
+ test: facts => facts.value != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {rangeValue} = await subject.computed();
+ if (rangeValue !== facts.value) {
+ throw new Error(
+ `the binding commits ${facts.value}, but the browser exposes ${rangeValue ?? 'no numeric value'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.value.empty',
+ outcome:
+ 'An empty spinbutton does not advertise a stale committed numeric value.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding has no committed value',
+ test: facts => facts.value == null,
+ },
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const value = await subject.attribute('aria-valuenow');
+ if (value != null) {
+ throw new Error(
+ `the empty spinbutton advertises stale aria-valuenow="${value}"`,
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.bounds.exposed',
+ outcome:
+ 'The browser exposes each numeric bound supplied by the binding.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding supplies a minimum or maximum',
+ test: facts => facts.min != null || facts.max != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {rangeMin, rangeMax} = await subject.computed();
+ if (rangeMin !== facts.min || rangeMax !== facts.max) {
+ throw new Error(
+ `the binding declares bounds ${facts.min ?? 'none'}..${facts.max ?? 'none'}, but the browser exposes ${rangeMin ?? 'none'}..${rangeMax ?? 'none'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.value-text.exposed',
+ outcome:
+ 'A formatted committed value remains available as the spinbutton value text.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding supplies formatted value text',
+ test: facts => facts.valueText != null,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const {valueText} = await subject.computed();
+ if (valueText !== facts.valueText) {
+ throw new Error(
+ `the binding formats the value as "${facts.valueText}", but the browser exposes ${valueText == null ? 'no value text' : `"${valueText}"`}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.disabled.exposed',
+ outcome:
+ 'A spinbutton the binding marks unavailable is exposed as disabled.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding declares this state unavailable',
+ test: facts => facts.disabled,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {disabled} = await subject.computed();
+ if (!disabled) {
+ throw new Error(
+ 'the binding declares this spinbutton disabled, but the browser exposes it as available',
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.available.not-disabled',
+ outcome:
+ 'An available spinbutton does not expose a false disabled state.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding declares this state available',
+ test: facts => !facts.disabled,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {disabled} = await subject.computed();
+ if (disabled) {
+ throw new Error(
+ 'this spinbutton is available, but the browser exposes it as disabled',
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.readonly.exposed',
+ outcome: 'A read-only spinbutton is exposed as read-only.',
+ sources: [WCAG_4_1_2],
+ covers: ['4.1.2-name-role-value'],
+ appliesWhen: {
+ condition: 'the binding declares this state read-only',
+ test: facts => facts.readOnly,
+ },
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {readOnly} = await subject.computed();
+ if (readOnly !== true) {
+ throw new Error(
+ 'the binding declares this spinbutton read-only, but the browser does not expose read-only state',
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.keyboard.reachable-and-escapable',
+ outcome:
+ 'Keyboard focus can reach the spinbutton and leave it without a trap.',
+ sources: [WCAG_2_1_1, WCAG_2_1_2],
+ covers: ['2.1.1-keyboard', '2.1.2-no-keyboard-trap'],
+ appliesWhen: {
+ condition: 'the binding declares the spinbutton focusable',
+ test: facts => facts.focusable,
+ },
+ evidenceLayer: 'real-browser',
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ await harness.resetFocus();
+ for (
+ let index = 0;
+ index < TAB_BUDGET && !(await subject.isFocused());
+ index += 1
+ ) {
+ await harness.press('Tab');
+ }
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ `${TAB_BUDGET} presses of Tab never reached the spinbutton`,
+ );
+ }
+ await harness.press('Tab');
+ if (await subject.isFocused()) {
+ throw new Error('Tab did not leave the spinbutton');
+ }
+ },
+ },
+ {
+ id: 'spinbutton.keyboard.arrow-up',
+ outcome:
+ 'Up Arrow increases the committed value when stepping is available.',
+ sources: [APG_ARROW_UP],
+ wcagOutcome:
+ 'Supports WCAG 2.2 2.1.1 by keeping the currently implemented stepping function keyboard-operable.',
+ covers: ['apg-interaction'],
+ appliesWhen: {
+ condition: 'the binding supplies an enabled upward step',
+ test: facts => facts.stepUpValue != null,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'advisory',
+ advisoryBecause: APG_NOT_FORMALLY_ADOPTED,
+ run: async ({harness, subject, facts}) => {
+ await subject.focus();
+ await harness.press('ArrowUp');
+ const {rangeValue} = await subject.computed();
+ if (rangeValue !== facts.stepUpValue) {
+ throw new Error(
+ `Up Arrow should expose ${facts.stepUpValue}, but the browser exposes ${rangeValue ?? 'no numeric value'}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'spinbutton.keyboard.arrow-down',
+ outcome:
+ 'Down Arrow decreases the committed value when stepping is available.',
+ sources: [APG_ARROW_DOWN],
+ wcagOutcome:
+ 'Supports WCAG 2.2 2.1.1 by keeping the currently implemented stepping function keyboard-operable.',
+ covers: ['apg-interaction'],
+ appliesWhen: {
+ condition: 'the binding supplies an enabled downward step',
+ test: facts => facts.stepDownValue != null,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['accessibility-tree'],
+ enforcement: 'advisory',
+ advisoryBecause: APG_NOT_FORMALLY_ADOPTED,
+ run: async ({harness, subject, facts}) => {
+ await subject.focus();
+ await harness.press('ArrowDown');
+ const {rangeValue} = await subject.computed();
+ if (rangeValue !== facts.stepDownValue) {
+ throw new Error(
+ `Down Arrow should expose ${facts.stepDownValue}, but the browser exposes ${rangeValue ?? 'no numeric value'}`,
+ );
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'NumberInput icon and caller content',
+ verifiedBy: 'Component axe and content review',
+ reason:
+ 'The spinbutton semantic contract does not own decorative or informative graphics.',
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'Field and InputGroup composition',
+ verifiedBy: 'Component relationship tests and axe',
+ reason:
+ 'This contract checks the persistent label; descriptions and group composition remain local.',
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'Field composition and caller layout',
+ verifiedBy: 'Component DOM order and browser review',
+ reason:
+ 'One role-bearing control does not establish the surrounding reading sequence.',
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'Caller form purpose',
+ verifiedBy: 'Autocomplete and form review',
+ reason:
+ 'A numeric widget cannot infer whether it collects a listed personal-information purpose.',
+ },
+ '1.4.1-use-of-color': {
+ owner: 'Field status and theme',
+ verifiedBy: 'Component status tests and visual review',
+ reason:
+ 'Programmatic value state does not prove non-color visual cues.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'NumberInput themes',
+ verifiedBy: 'Contrast audit',
+ reason: 'Contrast requires rendered pixels.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'NumberInput themes and focus styling',
+ verifiedBy: 'Contrast and visual audit',
+ reason: 'Semantic state does not prove painted control contrast.',
+ },
+ '2.4.2-page-titled': {
+ owner: 'Page shell',
+ verifiedBy: 'Page-level review',
+ reason: 'A spinbutton does not own the document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'Field composition and caller layout',
+ verifiedBy: 'Real-browser form-flow review',
+ reason:
+ 'Reachability and escape do not determine the surrounding task order.',
+ },
+ '2.4.4-link-purpose': {
+ owner: 'Link and caller content',
+ verifiedBy: 'Navigation review',
+ reason: 'A spinbutton edits a value and is not a link.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'Caller label wording',
+ verifiedBy: 'Content review',
+ reason:
+ 'The contract proves a label exists, not that its wording is descriptive.',
+ coversRemainderOnly: true,
+ },
+ '2.4.7-focus-visible': {
+ owner: 'NumberInput theme and interaction-modality system',
+ verifiedBy: 'Rendered keyboard-focus review',
+ reason: 'Focus-ring paint requires visual evidence.',
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'Caller layout',
+ verifiedBy: 'Constrained-viewport browser review',
+ reason: 'Occlusion depends on surrounding content.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'NumberInput stepper and Field controls',
+ verifiedBy: 'Component pointer suites',
+ reason:
+ 'The subject is a text-editing control; adjacent buttons retain their own pointer contract.',
+ },
+ '2.5.3-label-in-name': {
+ owner: 'Field rendering and caller label',
+ verifiedBy: 'Visible-label versus computed-name browser review',
+ reason:
+ 'This first slice proves persistent naming without making a visible-label pixel claim.',
+ },
+ '2.5.8-target-size': {
+ owner: 'NumberInput theme and composed buttons',
+ verifiedBy: 'Browser geometry audit',
+ reason: 'Target size requires rendered geometry.',
+ },
+ '3.1.1-language-of-page': {
+ owner: 'Page shell and localization provider',
+ verifiedBy: 'Document-language checks',
+ reason: 'The spinbutton does not own the document language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'NumberInput commit policy and caller response',
+ verifiedBy: 'Component commit tests and task review',
+ reason:
+ 'The shared pattern does not decide application context changes.',
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'Design system and caller content',
+ verifiedBy: 'Cross-control review',
+ reason:
+ 'One fixture cannot establish consistency across an application.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'NumberInput validation and status-message owners',
+ verifiedBy:
+ 'Existing invalid-draft and status tests; AST-009 for announcements',
+ reason:
+ 'Parsing, error text, and announcement behavior remain component-local.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'Field and caller instructions',
+ verifiedBy: 'Field-label and form-content review',
+ reason:
+ 'A persistent label does not establish every instruction needed by the task.',
+ },
+ '4.1.3-status-messages': {
+ owner: 'Status-message contract and NumberInput invalid feedback',
+ verifiedBy: 'Component status tests; AST-009 for speech and timing',
+ reason: 'Static spinbutton semantics do not own announcement timing.',
+ },
+ 'apg-interaction': {
+ owner: 'Current NumberInput interaction authority',
+ verifiedBy: 'Advisory arrow-key contract and component stepping tests',
+ reason:
+ 'Arrow stepping is observed, while PageUp, PageDown, Home, and End remain optional APG mechanics not adopted by current Astryx authority.',
+ coversRemainderOnly: true,
+ },
+ 'forced-colors': {
+ owner: 'NumberInput themes',
+ verifiedBy: 'Real-browser forced-color review',
+ reason: 'Semantic state does not prove painted control visibility.',
+ },
+ 'reduced-motion': {
+ owner: 'NumberInput and adjacent overlay owners',
+ verifiedBy: 'Component motion review',
+ reason: 'This semantic and keyboard slice owns no animation.',
+ },
+ 'at-facing-strings': {
+ owner: 'NumberInput localization and caller labels',
+ verifiedBy:
+ 'Catalog checks and localized component tests; AST-009 for speech claims',
+ reason:
+ 'The binding uses deterministic labels without claiming spoken output.',
+ },
+ },
+ });
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..0307486cb5
--- /dev/null
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.chromium.spec.ts
@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** Real-browser and accessibility-tree binding evidence for NumberInput. */
+
+import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {
+ SPINBUTTON_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ neverExercised,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {
+ NUMBER_INPUT_A11Y_STATES,
+ type NumberInputA11yRow,
+} from './NumberInput.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-spinbutton-subject]';
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => storybook?.close());
+
+function storyUrl(id: string): string {
+ return `${storybook.origin}/iframe.html?id=${id}&viewMode=story`;
+}
+
+async function mount(page: Page, state: NumberInputA11yRow): Promise<void> {
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ await holdMotionStill(page);
+ await page.locator(SUBJECT_SELECTOR).waitFor({state: 'attached'});
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: NumberInputA11yRow,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: SPINBUTTON_PATTERN,
+ binding: 'NumberInput',
+ state: state.id,
+ facts: state.facts,
+ mount: async () => {
+ await mount(page, state);
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: page.locator(SUBJECT_SELECTOR),
+ });
+ },
+ });
+}
+
+test('every expectation is exercised by at least one NumberInput state', async ({
+ page,
+}) => {
+ test.setTimeout(4 * 60 * 1000);
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of NUMBER_INPUT_A11Y_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ expect(neverExercised(results)).toEqual([]);
+});
+
+for (const state of NUMBER_INPUT_A11Y_STATES) {
+ test(`NumberInput [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(SPINBUTTON_PATTERN, [result]);
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ });
+}
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.renders.tsx b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.renders.tsx
new file mode 100644
index 0000000000..4131ff1ce3
--- /dev/null
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.renders.tsx
@@ -0,0 +1,77 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/** Stable NumberInput renders shared by jsdom, Storybook, and Chromium bindings. */
+
+import {useState, type ReactElement} from 'react';
+import {NumberInput} from '../NumberInput';
+import type {NumberInputA11yRow} from './NumberInput.a11y.states';
+
+function StatefulNumberInput({
+ min,
+ max,
+ formatValue,
+ isDisabled,
+ isReadOnly,
+ disabledMessage,
+}: {
+ min?: number;
+ max?: number;
+ formatValue?: (value: number) => string;
+ isDisabled?: boolean;
+ isReadOnly?: boolean;
+ disabledMessage?: string;
+}) {
+ const [value, setValue] = useState(5);
+ return (
+ <NumberInput
+ data-a11y-spinbutton-subject
+ label="Quantity"
+ value={value}
+ onChange={setValue}
+ min={min}
+ max={max}
+ formatValue={formatValue}
+ isDisabled={isDisabled}
+ isReadOnly={isReadOnly}
+ disabledMessage={disabledMessage}
+ />
+ );
+}
+
+export const NUMBER_INPUT_A11Y_RENDERS: Readonly<
+ Record<NumberInputA11yRow['id'], () => ReactElement>
+> = {
+ 'default-value': () => <StatefulNumberInput />,
+ 'bounded-value': () => <StatefulNumberInput min={1} max={9} />,
+ 'formatted-value': () => (
+ <StatefulNumberInput formatValue={value => `${value} GB`} />
+ ),
+ 'empty-value': () => (
+ <NumberInput
+ data-a11y-spinbutton-subject
+ label="Quantity"
+ value={null}
+ onChange={() => {}}
+ />
+ ),
+ invalid: () => (
+ <NumberInput
+ data-a11y-spinbutton-subject
+ label="Quantity"
+ value={5}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Quantity is invalid'}}
+ />
+ ),
+ disabled: () => <StatefulNumberInput isDisabled />,
+ 'disabled-with-message': () => (
+ <StatefulNumberInput
+ isDisabled
+ disabledMessage="Quantity is fixed by policy"
+ />
+ ),
+ 'read-only': () => <StatefulNumberInput isReadOnly />,
+ 'arrow-stepping': () => <StatefulNumberInput />,
+};
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts
new file mode 100644
index 0000000000..2bb8b5bed8
--- /dev/null
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.states.ts
@@ -0,0 +1,117 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** AST-021 state inventory for the NumberInput spinbutton binding. */
+
+import type {SpinbuttonStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface NumberInputA11yState {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: SpinbuttonStateFacts;
+ readonly storyId: string;
+}
+
+export type NumberInputA11yRow = (typeof NUMBER_INPUT_A11Y_STATES)[number];
+
+const facts = (
+ overrides: Partial<SpinbuttonStateFacts> = {},
+): SpinbuttonStateFacts => ({
+ value: 5,
+ min: null,
+ max: null,
+ valueText: null,
+ disabled: false,
+ readOnly: false,
+ focusable: true,
+ stepUpValue: null,
+ stepDownValue: null,
+ ...overrides,
+});
+
+const story = (id: string) => `a11y-spinbutton-pattern--${id}`;
+
+export const NUMBER_INPUT_A11Y_STATES = [
+ {
+ id: 'default-value',
+ summary: 'a labelled editable value',
+ facts: facts(),
+ storyId: story('default-value'),
+ },
+ {
+ id: 'bounded-value',
+ summary: 'a value with minimum and maximum bounds',
+ facts: facts({min: 1, max: 9}),
+ storyId: story('bounded-value'),
+ },
+ {
+ id: 'formatted-value',
+ summary: 'a committed value with formatted value text',
+ facts: facts({valueText: '5 GB'}),
+ storyId: story('formatted-value'),
+ },
+ {
+ id: 'empty-value',
+ summary: 'an empty spinbutton with no committed numeric value',
+ facts: facts({value: null}),
+ storyId: story('empty-value'),
+ },
+ {
+ id: 'invalid',
+ summary: 'an invalid spinbutton that preserves its shared semantics',
+ facts: facts(),
+ storyId: story('invalid'),
+ },
+ {
+ id: 'disabled',
+ summary: 'a natively disabled spinbutton outside the tab sequence',
+ facts: facts({disabled: true, focusable: false}),
+ storyId: story('disabled'),
+ },
+ {
+ id: 'disabled-with-message',
+ summary:
+ 'an unavailable read-only spinbutton kept focusable for its reason',
+ facts: facts({disabled: true, readOnly: true}),
+ storyId: story('disabled-with-message'),
+ },
+ {
+ id: 'read-only',
+ summary: 'a read-only spinbutton that stays focusable',
+ facts: facts({readOnly: true}),
+ storyId: story('read-only'),
+ },
+ {
+ id: 'arrow-stepping',
+ summary: 'an editable spinbutton with one-step arrow movement',
+ facts: facts({stepUpValue: 6, stepDownValue: 4}),
+ storyId: story('arrow-stepping'),
+ },
+] as const satisfies ReadonlyArray<NumberInputA11yState>;
+
+export const NUMBER_INPUT_A11Y_EXCLUSIONS = [
+ {
+ owner: 'NumberInput commit policy',
+ reason:
+ 'Typed draft parsing, formatting, blur/Enter commit, clamping, callbacks, wheel input, and form submission remain component-specific.',
+ },
+ {
+ owner: 'Button pattern',
+ reason:
+ 'Optional increment, decrement, clear, and status controls are separate role-bearing button parts.',
+ },
+ {
+ owner: 'Date and time inputs',
+ reason:
+ 'Segmented date/time fields are not included until a part is shown to expose the same spinbutton semantics.',
+ },
+ {
+ owner: 'APG optional keys',
+ reason:
+ 'PageUp, PageDown, Home, and End are not adopted by current Astryx authority and are not inferred from the APG example.',
+ },
+ {
+ owner: 'AST-009',
+ reason:
+ 'This binding claims computed browser exposure and keyboard behavior, not speech, braille, announcement timing, or virtual-cursor behavior.',
+ },
+] as const;
diff --git a/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx
new file mode 100644
index 0000000000..2bb3bc7073
--- /dev/null
+++ b/packages/core/src/NumberInput/__tests__/NumberInput.a11y.test.tsx
@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/** Fast DOM binding for NumberInput against the shared Spinbutton contract. */
+
+import {cleanup, render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+ SPINBUTTON_PATTERN,
+ checkAccessibilitySpec,
+ createJsdomHarness,
+ expectAccessibilitySpec,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {NUMBER_INPUT_A11Y_RENDERS} from './NumberInput.a11y.renders';
+import {
+ NUMBER_INPUT_A11Y_EXCLUSIONS,
+ NUMBER_INPUT_A11Y_STATES,
+ type NumberInputA11yRow,
+} from './NumberInput.a11y.states';
+
+const SUBJECT_SELECTOR = '[data-a11y-spinbutton-subject]';
+
+function subjectFor(): HTMLInputElement {
+ const subject = document.querySelector(SUBJECT_SELECTOR);
+ if (!(subject instanceof HTMLInputElement)) {
+ throw new Error('binding did not render one native spinbutton subject');
+ }
+ return subject;
+}
+
+async function checkState(state: NumberInputA11yRow): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: SPINBUTTON_PATTERN,
+ binding: 'NumberInput',
+ state: state.id,
+ facts: state.facts,
+ mount: async () => {
+ render(NUMBER_INPUT_A11Y_RENDERS[state.id]());
+ return createJsdomHarness({subject: subjectFor()});
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('the shared Spinbutton pattern, jsdom lane', () => {
+ it.each(
+ NUMBER_INPUT_A11Y_STATES.map(
+ state => [`NumberInput [${state.id}]`, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectAccessibilitySpec({
+ spec: SPINBUTTON_PATTERN,
+ binding: 'NumberInput',
+ state: state.id,
+ facts: state.facts,
+ render: () => {
+ render(NUMBER_INPUT_A11Y_RENDERS[state.id]());
+ },
+ subject: subjectFor,
+ cleanup,
+ });
+ });
+
+ it('runs DOM expectations and reports browser-owned layers as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of NUMBER_INPUT_A11Y_STATES) {
+ results.push(await checkState(state));
+ }
+ const report = summarize(SPINBUTTON_PATTERN, results);
+ expect(report.counts.pass).toBeGreaterThan(0);
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+});
+
+describe('the NumberInput Spinbutton binding inventory', () => {
+ it('names a distinct checked-in story for every state', () => {
+ const ids = NUMBER_INPUT_A11Y_STATES.map(state => state.storyId);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+
+ it('records every adjacent exclusion with an owner and reason', () => {
+ expect(
+ NUMBER_INPUT_A11Y_EXCLUSIONS.every(row => row.owner && row.reason),
+ ).toBe(true);
+ });
+
+ it('renders exactly one subject for every state', () => {
+ for (const state of NUMBER_INPUT_A11Y_STATES) {
+ render(NUMBER_INPUT_A11Y_RENDERS[state.id]());
+ expect(subjectFor(), state.id).toBeTruthy();
+ expect(document.querySelectorAll(SUBJECT_SELECTOR)).toHaveLength(1);
+ cleanup();
+ }
+ });
+});