Skip to content

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

TypeScript

test(a11y): Window Splitter contract and ResizeHandle binding (#7485)

Cindy Zhang664eae9b35bb
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fcbe49bddf..7eca9425b4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1913,6 +1913,55 @@ jobs:
retention-days: 30
if-no-files-found: warn
+ # The window-splitter contract's separator role and name, its pane
+ # relationship, and its arrow, Enter, Home and End results are
+ # accessibility-tree and real-browser facts that jsdom cannot observe.
+ # Run the contract's own fixture proof and the ResizeHandle binding
+ # whenever Resizable, the harness, the binding's stories, or the contract
+ # changes. Its own --output directory; the JSON report is the
+ # head-bound record, uploaded next.
+ - name: Run Window Splitter accessibility contract
+ id: window-splitter-contract
+ if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+ env:
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ PLAYWRIGHT_JSON_OUTPUT_FILE: window-splitter-contract/report.json
+ run: |
+ should_run=false
+ # 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/window-splitter|internal/a11y-spec/src/harness|packages/core/src/Resizable/|apps/storybook/stories/WindowSplitterA11y)' || scope=$?
+ fi
+ if [ "$scope" != 1 ]; then
+ should_run=true
+ fi
+ echo "should_run=${should_run}" >> "$GITHUB_OUTPUT"
+ if [ "$should_run" != true ]; then
+ echo "Resizable and the window-splitter contract are not in PR scope; skipping window-splitter evidence."
+ exit 0
+ fi
+ pnpm exec playwright test \
+ internal/a11y-spec/src/patterns/window-splitter.chromium.spec.ts \
+ packages/core/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts \
+ --project chromium \
+ --reporter list,json \
+ --output window-splitter-contract-output
+
+ - name: Upload Window Splitter accessibility contract evidence
+ if: ${{ !cancelled() && steps.window-splitter-contract.outputs.should_run == 'true' }}
+ uses: actions/upload-artifact@v7
+ with:
+ name: window-splitter-contract-evidence-${{ needs.build-storybook.outputs.short_hash }}
+ path: window-splitter-contract/
+ retention-days: 30
+ if-no-files-found: warn
+
# The link contract's role, name, Tab, Enter, and pointer-release outcomes
# are accessibility-tree and real-browser facts that jsdom cannot observe.
# Run the contract's own fixture proof and the Link binding whenever Link
diff --git a/apps/storybook/stories/WindowSplitterA11y.stories.tsx b/apps/storybook/stories/WindowSplitterA11y.stories.tsx
new file mode 100644
index 0000000000..24de40978d
--- /dev/null
+++ b/apps/storybook/stories/WindowSplitterA11y.stories.tsx
@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file WindowSplitterA11y.stories.tsx
+ * @input The ResizeHandle binding states, rendered through the binding's own renderer so the jsdom and Chromium lanes see the same tree
+ * @output One checked-in story per state for the Chromium accessibility lane; excluded from the visual matrix
+ * @position Browser fixtures for component:Resizable AR1 (WINDOW_SPLITTER_PATTERN)
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {renderResizeHandleState} from '../../../packages/core/src/Resizable/__tests__/ResizeHandle.a11y.renders';
+import {RESIZE_HANDLE_BINDING_STATES} from '../../../packages/core/src/Resizable/__tests__/ResizeHandle.a11y.states';
+
+const meta = {
+ title: 'A11y/WindowSplitter',
+ tags: ['no-visual'],
+ parameters: {layout: 'padded'},
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function storyFor(
+ id: (typeof RESIZE_HANDLE_BINDING_STATES)[number]['id'],
+): Story {
+ const state = RESIZE_HANDLE_BINDING_STATES.find(
+ candidate => candidate.id === id,
+ );
+ if (state == null) {
+ throw new Error(`no ResizeHandle binding state "${id}"`);
+ }
+ return {render: () => renderResizeHandleState(state)};
+}
+
+export const BareHorizontal = storyFor('bare-horizontal');
+export const BareVertical = storyFor('bare-vertical');
+export const BareReversed = storyFor('bare-reversed');
+export const BareRtl = storyFor('bare-rtl');
+export const BareCollapsible = storyFor('bare-collapsible');
+export const BareSmallMin = storyFor('bare-small-min');
+export const BareStartCollapsed = storyFor('bare-start-collapsed');
+export const BareUnbounded = storyFor('bare-unbounded');
+export const BareUnboundedInContainer = storyFor('bare-unbounded-in-container');
+export const BareSnapped = storyFor('bare-snapped');
+export const BareDocumentedUsage = storyFor('bare-documented-usage');
+export const BareDisabled = storyFor('bare-disabled');
diff --git a/internal/a11y-spec/README.md b/internal/a11y-spec/README.md
index 240678d6b9..c0dc1de4ff 100644
--- a/internal/a11y-spec/README.md
+++ b/internal/a11y-spec/README.md
@@ -51,6 +51,7 @@ src/
├── listbox.* listbox, group, and option semantics
├── spinbutton.* numeric role, value, bounds, state, and arrow stepping
├── disclosure.* standalone disclosure state/content semantics
+ ├── window-splitter.* a focusable resize separator's role, name, position/bounds, pane relationship, and arrow/Enter keys (Home/End advisory)
├── grid.* a composite grid's role, name, row/cell structure, single Tab stop, selection, and arrow/Home/End/Enter keys
├── alert-dialog.* a confirmation surface's alertdialog role, title/message references, modality, initial focus, Escape and click-beside dismissal
├── carousel.* non-rotating collection, slide, off-screen, and focus semantics
@@ -64,29 +65,30 @@ src/
## 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 |
-| `toggle-button` | Toggle-button semantics in the [APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | ToggleButton, including standalone and grouped states |
-| `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 |
-| `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 |
-| `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 |
-| `carousel` | [APG Carousel](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) and WCAG 2.2 semantics | Carousel container, slides, scroll area, and stable navigation-control focus |
-| `alertdialog` | [APG Alert Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) role, references, modality, focus, dismissal | AlertDialog: alertdialog role and name, aria-describedby to the message, modal, Cancel first (advisory), Escape closes, click beside inert (advisory); modal mechanics stay with the modal-dialog contract through Dialog |
-| `grid` | [APG Grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) role, structure, name, selection and data-grid keys | Calendar month grids: grid role/name, row and gridcell/columnheader structure, one Tab stop, aria-selected/aria-multiselectable, arrows in reading order, Home/End, Enter selects (advisory) |
-| `link` | WCAG 2.2 semantics; [APG Link](https://www.w3.org/WAI/ARIA/apg/patterns/link/) role and Enter mechanics | Link, including LinkProvider and `as` router components |
+| 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 |
+| `toggle-button` | Toggle-button semantics in the [APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/) | ToggleButton, including standalone and grouped states |
+| `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 |
+| `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 |
+| `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 |
+| `carousel` | [APG Carousel](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) and WCAG 2.2 semantics | Carousel container, slides, scroll area, and stable navigation-control focus |
+| `alertdialog` | [APG Alert Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) role, references, modality, focus, dismissal | AlertDialog: alertdialog role and name, aria-describedby to the message, modal, Cancel first (advisory), Escape closes, click beside inert (advisory); modal mechanics stay with the modal-dialog contract through Dialog |
+| `grid` | [APG Grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) role, structure, name, selection and data-grid keys | Calendar month grids: grid role/name, row and gridcell/columnheader structure, one Tab stop, aria-selected/aria-multiselectable, arrows in reading order, Home/End, Enter selects (advisory) |
+| `windowsplitter` | [APG Window Splitter](https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/) role, values, name, relationship and keys | ResizeHandle: separator role/name, now/min/max, orientation, aria-controls to the pane, arrows, Enter collapse/restore, Home/End, disabled keeps position |
+| `link` | WCAG 2.2 semantics; [APG Link](https://www.w3.org/WAI/ARIA/apg/patterns/link/) role and Enter mechanics | Link, including LinkProvider and `as` router components |
The toggle-button contract owns the persistent-action extension of button
semantics: the pressed state must be exposed, reversible by pointer, Enter, and
diff --git a/internal/a11y-spec/src/index.ts b/internal/a11y-spec/src/index.ts
index b82539a2c3..52200dfcfb 100644
--- a/internal/a11y-spec/src/index.ts
+++ b/internal/a11y-spec/src/index.ts
@@ -152,6 +152,10 @@ export {
ALERT_DIALOG_PATTERN,
type AlertDialogStateFacts,
} from './patterns/alert-dialog';
+export {
+ WINDOW_SPLITTER_PATTERN,
+ type WindowSplitterStateFacts,
+} from './patterns/window-splitter';
export {
LINK_PATTERN,
type LinkCurrentToken,
diff --git a/internal/a11y-spec/src/patterns/window-splitter.chromium.spec.ts b/internal/a11y-spec/src/patterns/window-splitter.chromium.spec.ts
new file mode 100644
index 0000000000..2269739905
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/window-splitter.chromium.spec.ts
@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file window-splitter.chromium.spec.ts
+ * @input WINDOW_SPLITTER_PATTERN and its fixtures in real Chromium (the fixture script implements the APG keyboard model)
+ * @output Proof that every expectation passes conforming fixtures and fails its mutation at the layers only a browser observes
+ * @position Contract self-test, Chromium lane
+ */
+
+import {expect, test, type CDPSession, 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 {WINDOW_SPLITTER_PATTERN} from './window-splitter';
+import {
+ WINDOW_SPLITTER_MUTATIONS,
+ CONFORMING_FIXTURES,
+ RELATION_SELECTORS,
+ SUBJECT_SELECTOR,
+ fixture,
+ type WindowSplitterFixture,
+} from './window-splitter.fixtures';
+
+function fixturePage(html: string): string {
+ return `<!doctype html><html lang="en"><body>${html}</body></html>`;
+}
+
+async function results(
+ page: Page,
+ cdp: CDPSession,
+ target: WindowSplitterFixture,
+ only?: readonly string[],
+): Promise<readonly ExpectationResult[]> {
+ const run = await checkAccessibilitySpec({
+ spec: WINDOW_SPLITTER_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ only,
+ mount: async () => {
+ await page.setContent(fixturePage(target.html));
+ await holdMotionStill(page);
+ return createChromiumHarness({
+ page,
+ cdp,
+ subject: page.locator(SUBJECT_SELECTOR),
+ related: Object.fromEntries(
+ Object.entries(RELATION_SELECTORS).map(([name, selector]) => [
+ name,
+ page.locator(selector),
+ ]),
+ ),
+ });
+ },
+ });
+ return run.results;
+}
+
+test.describe('window-splitter contract — conforming fixtures', () => {
+ for (const id of CONFORMING_FIXTURES) {
+ test(`${id}: every applicable expectation passes`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const observed = await results(page, cdp, fixture(id));
+ expect(
+ observed
+ .filter(
+ result =>
+ result.status !== 'pass' && result.status !== 'not-applicable',
+ )
+ .map(result => `${result.expectation}: ${result.detail ?? ''}`),
+ ).toEqual([]);
+ });
+ }
+});
+
+test.describe('window-splitter contract — deliberately violating fixtures', () => {
+ for (const expectation of WINDOW_SPLITTER_PATTERN.expectations) {
+ if (
+ !requiredLayers(expectation).every(layer =>
+ CHROMIUM_OBSERVES.includes(layer),
+ )
+ ) {
+ continue;
+ }
+ for (const fixtureId of WINDOW_SPLITTER_MUTATIONS[expectation.id] ?? []) {
+ test(`${describeExpectation(expectation)} — fails against ${fixtureId}`, async ({
+ page,
+ }) => {
+ const cdp = await page.context().newCDPSession(page);
+ const [result] = await results(page, cdp, fixture(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/window-splitter.fixtures.ts b/internal/a11y-spec/src/patterns/window-splitter.fixtures.ts
new file mode 100644
index 0000000000..85b6ac58bb
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/window-splitter.fixtures.ts
@@ -0,0 +1,263 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file window-splitter.fixtures.ts
+ * @input Plain HTML splitters between two panes (one script implements the APG keyboard model; the DOM lane never runs it), conforming and deliberately violating
+ * @output WINDOW_SPLITTER_FIXTURES, the subject and pane selectors, and the expectation → violating-fixture map
+ * @position Contract self-test data for window-splitter.jsdom.test.ts and window-splitter.chromium.spec.ts
+ */
+
+import type {WindowSplitterStateFacts} from './window-splitter';
+
+const SUBJECT_ATTRIBUTE = 'data-a11y-subject';
+export const SUBJECT_SELECTOR = `[${SUBJECT_ATTRIBUTE}]`;
+export const RELATION_SELECTORS = {pane: '#primary-pane'} as const;
+
+export interface WindowSplitterFixture {
+ readonly id: string;
+ readonly summary: string;
+ readonly facts: WindowSplitterStateFacts;
+ readonly html: string;
+}
+
+const SCRIPT = `<script>
+(() => {
+ const bar = document.querySelector('[${SUBJECT_ATTRIBUTE}]');
+ const num = name => Number(bar.getAttribute(name));
+ let previous = num('aria-valuenow');
+ const set = raw => {
+ const min = num('aria-valuemin');
+ const max = bar.hasAttribute('aria-valuemax') ? num('aria-valuemax') : Infinity;
+ bar.setAttribute('aria-valuenow', String(Math.min(max, Math.max(min, raw))));
+ };
+ bar.addEventListener('keydown', e => {
+ if (bar.getAttribute('aria-disabled') === 'true' && !window.__splitterDisabledMoves) return;
+ const now = num('aria-valuenow');
+ const step = Number(bar.dataset.step || 10);
+ const grow = bar.dataset.increaseKey || 'ArrowRight';
+ const shrink = {ArrowRight: 'ArrowLeft', ArrowLeft: 'ArrowRight', ArrowUp: 'ArrowDown', ArrowDown: 'ArrowUp'}[grow];
+ if (e.key === grow) { e.preventDefault(); set(now + step * (window.__splitterDoubleStep ? 2 : 1)); return; }
+ if (e.key === shrink) { e.preventDefault(); set(now - step); return; }
+ if (e.key === 'Home') { e.preventDefault(); set(num('aria-valuemin')); return; }
+ if (e.key === 'End') { e.preventDefault(); if (bar.hasAttribute('aria-valuemax')) set(window.__splitterEndShort ? num('aria-valuemax') - step : num('aria-valuemax')); return; }
+ if (e.key === 'Enter' && bar.dataset.collapsible === 'true') {
+ e.preventDefault();
+ if (bar.hasAttribute('aria-valuetext')) {
+ bar.removeAttribute('aria-valuetext');
+ set(window.__splitterRestoresMinimum ? num('aria-valuemin') : previous);
+ } else {
+ previous = now;
+ bar.setAttribute('aria-valuetext', 'Collapsed');
+ set(num('aria-valuemin'));
+ }
+ }
+ });
+})();
+</script>`;
+
+function splitter({
+ now = 200,
+ min = 100,
+ max = 400 as number | null,
+ orientationAttr = 'vertical' as string | null,
+ increaseKey = 'ArrowRight',
+ step = 10,
+ disabled = false,
+ collapsible = false,
+ role = 'separator',
+ label = 'Resize sidebar' as string | null,
+ controls = 'primary-pane' as string | null,
+ omitNow = false,
+ omitMin = false,
+}: {
+ now?: number;
+ min?: number;
+ max?: number | null;
+ orientationAttr?: string | null;
+ increaseKey?: string;
+ step?: number;
+ disabled?: boolean;
+ collapsible?: boolean;
+ role?: string;
+ label?: string | null;
+ controls?: string | null;
+ omitNow?: boolean;
+ omitMin?: boolean;
+} = {}): string {
+ return `<div style="display:flex;width:600px;height:200px"><div id="primary-pane" style="width:${now}px;background:#eee">Primary</div><div ${SUBJECT_ATTRIBUTE} role="${role}" tabindex="${disabled ? -1 : 0}" data-step="${step}" data-increase-key="${increaseKey}" data-collapsible="${collapsible}"${omitNow ? '' : ` aria-valuenow="${now}"`} ${omitMin ? '' : ` aria-valuemin="${min}"`}${max == null ? '' : ` aria-valuemax="${max}"`}${orientationAttr == null ? '' : ` aria-orientation="${orientationAttr}"`}${label == null ? '' : ` aria-label="${label}"`}${controls == null ? '' : ` aria-controls="${controls}"`}${disabled ? ' aria-disabled="true"' : ''} style="width:8px;background:#888"></div><div style="flex:1">Secondary</div></div>${SCRIPT}`;
+}
+
+const facts = (
+ overrides: Partial<WindowSplitterStateFacts> = {},
+): WindowSplitterStateFacts => ({
+ valueNow: 200,
+ valueMin: 100,
+ valueMax: 400,
+ orientation: 'vertical',
+ increaseKey: 'ArrowRight',
+ step: 10,
+ operable: true,
+ collapsible: false,
+ ...overrides,
+});
+
+const flag = (name: string, html: string) =>
+ html.replace('<script>', `<script>window.${name} = true;</script><script>`);
+
+export const WINDOW_SPLITTER_FIXTURES: readonly WindowSplitterFixture[] = [
+ {
+ id: 'conforming-vertical-bar',
+ summary: 'a vertical bar between left and right panes at 200 of 100–400',
+ facts: facts(),
+ html: splitter(),
+ },
+ {
+ id: 'conforming-horizontal-bar',
+ summary:
+ 'a horizontal bar between top and bottom panes: ArrowDown grows the top pane',
+ facts: facts({orientation: 'horizontal', increaseKey: 'ArrowDown'}),
+ html: splitter({orientationAttr: 'horizontal', increaseKey: 'ArrowDown'}),
+ },
+ {
+ id: 'conforming-reversed',
+ summary: 'a vertical bar on the start side of its pane: ArrowLeft grows it',
+ facts: facts({increaseKey: 'ArrowLeft'}),
+ html: splitter({increaseKey: 'ArrowLeft'}),
+ },
+ {
+ id: 'conforming-collapsible',
+ summary:
+ 'a collapsible pane: Enter collapses, Enter restores the previous position',
+ facts: facts({collapsible: true}),
+ html: splitter({collapsible: true}),
+ },
+ {
+ id: 'conforming-disabled',
+ summary: 'an unavailable splitter that keeps its position',
+ facts: facts({operable: false}),
+ html: splitter({disabled: true}),
+ },
+ {
+ id: 'violating-role',
+ summary: 'a splitter exposed as a generic div',
+ facts: facts(),
+ html: splitter({role: 'presentation'}),
+ },
+ {
+ id: 'violating-name',
+ summary: 'a splitter with no accessible name',
+ facts: facts(),
+ html: splitter({label: null}),
+ },
+ {
+ id: 'violating-no-valuenow',
+ summary: 'a splitter with no aria-valuenow',
+ facts: facts(),
+ html: splitter({omitNow: true}),
+ },
+ {
+ id: 'violating-no-valuemin',
+ summary: 'a splitter with no aria-valuemin',
+ facts: facts(),
+ html: splitter({omitMin: true}),
+ },
+ {
+ id: 'violating-now-above-max',
+ summary: 'a splitter announcing 200 of 100–150',
+ facts: facts(),
+ html: splitter({max: 150}),
+ },
+ {
+ id: 'violating-no-valuemax',
+ summary: 'a splitter with no aria-valuemax',
+ facts: facts(),
+ html: splitter({max: null}),
+ },
+ {
+ id: 'violating-orientation',
+ summary: 'a left/right bar that claims the default horizontal orientation',
+ facts: facts(),
+ html: splitter({orientationAttr: null}),
+ },
+ {
+ id: 'violating-no-controls',
+ summary: 'a splitter that names no pane',
+ facts: facts(),
+ html: splitter({controls: null}),
+ },
+ {
+ id: 'violating-controls-dangling',
+ summary:
+ 'a splitter whose aria-controls names an element that is not the pane',
+ facts: facts(),
+ html: splitter({controls: 'nowhere'}),
+ },
+ {
+ id: 'violating-double-step',
+ summary: 'a splitter whose grow arrow moves two steps',
+ facts: facts(),
+ html: flag('__splitterDoubleStep', splitter()),
+ },
+ {
+ id: 'violating-restores-minimum',
+ summary:
+ 'a collapsible pane whose second Enter reopens at the minimum, not the previous position',
+ facts: facts({collapsible: true}),
+ html: flag('__splitterRestoresMinimum', splitter({collapsible: true})),
+ },
+ {
+ id: 'violating-end-short',
+ summary: 'a splitter whose End stops short of the maximum',
+ facts: facts(),
+ html: flag('__splitterEndShort', splitter()),
+ },
+ {
+ id: 'violating-disabled-moves',
+ summary: 'an unavailable splitter that still moves on the arrow keys',
+ facts: facts({operable: false}),
+ html: flag('__splitterDisabledMoves', splitter({disabled: true})),
+ },
+];
+
+export function fixture(id: string): WindowSplitterFixture {
+ const found = WINDOW_SPLITTER_FIXTURES.find(candidate => candidate.id === id);
+ if (found == null) {
+ throw new Error(`unknown window-splitter fixture "${id}"`);
+ }
+ return found;
+}
+
+export const CONFORMING_FIXTURES: readonly string[] =
+ WINDOW_SPLITTER_FIXTURES.filter(candidate =>
+ candidate.id.startsWith('conforming-'),
+ ).map(candidate => candidate.id);
+
+export const WINDOW_SPLITTER_MUTATIONS: Readonly<
+ Record<string, readonly string[]>
+> = {
+ 'windowsplitter.separator.role-and-name': [
+ 'violating-role',
+ 'violating-name',
+ ],
+ 'windowsplitter.separator.position-and-minimum': [
+ 'violating-no-valuenow',
+ 'violating-no-valuemin',
+ ],
+ 'windowsplitter.separator.maximum': [
+ 'violating-no-valuemax',
+ 'violating-now-above-max',
+ ],
+ 'windowsplitter.separator.orientation': ['violating-orientation'],
+ 'windowsplitter.separator.controls-pane': [
+ 'violating-no-controls',
+ 'violating-controls-dangling',
+ ],
+ 'windowsplitter.keys.arrows-move': ['violating-double-step'],
+ 'windowsplitter.keys.enter-collapses-and-restores': [
+ 'violating-restores-minimum',
+ ],
+ 'windowsplitter.keys.home-end': ['violating-end-short'],
+ 'windowsplitter.separator.unavailable-keeps-position': [
+ 'violating-disabled-moves',
+ ],
+};
diff --git a/internal/a11y-spec/src/patterns/window-splitter.jsdom.test.ts b/internal/a11y-spec/src/patterns/window-splitter.jsdom.test.ts
new file mode 100644
index 0000000000..d612180abf
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/window-splitter.jsdom.test.ts
@@ -0,0 +1,164 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file window-splitter.jsdom.test.ts
+ * @input WINDOW_SPLITTER_PATTERN and its conforming and violating fixtures
+ * @output Proof that the contract is complete, that every DOM-layer expectation passes conforming fixtures and fails its mutation, and that jsdom reports browser layers as unrun
+ * @position Contract self-test, jsdom lane
+ */
+
+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 {WINDOW_SPLITTER_PATTERN} from './window-splitter';
+import {
+ WINDOW_SPLITTER_MUTATIONS,
+ CONFORMING_FIXTURES,
+ RELATION_SELECTORS,
+ SUBJECT_SELECTOR,
+ fixture,
+ type WindowSplitterFixture,
+} from './window-splitter.fixtures';
+
+const observableHere = WINDOW_SPLITTER_PATTERN.expectations.filter(
+ expectation =>
+ requiredLayers(expectation).every(layer => JSDOM_OBSERVES.includes(layer)),
+);
+
+afterEach(() => document.body.replaceChildren());
+
+async function resultsFor(target: WindowSplitterFixture) {
+ const container = document.createElement('div');
+ document.body.append(container);
+ const result = await checkAccessibilitySpec({
+ spec: WINDOW_SPLITTER_PATTERN,
+ binding: 'fixture',
+ state: target.id,
+ facts: target.facts,
+ mount: async () => {
+ container.innerHTML = target.html;
+ const subject = container.querySelector(SUBJECT_SELECTOR);
+ if (subject == null) {
+ throw new Error(`fixture "${target.id}" is missing its subject`);
+ }
+ const related: Record<string, Element> = {};
+ for (const [name, selector] of Object.entries(RELATION_SELECTORS)) {
+ const element = container.querySelector(selector);
+ if (element != null) {
+ related[name] = element;
+ }
+ }
+ return createJsdomHarness({subject, related});
+ },
+ unmount: () => {
+ container.innerHTML = '';
+ },
+ });
+ return result.results;
+}
+
+function resultFor(
+ results: readonly ExpectationResult[],
+ id: string,
+): ExpectationResult {
+ const found = results.find(result => result.expectation === id);
+ if (found == null) {
+ throw new Error(`no result for ${id}`);
+ }
+ return found;
+}
+
+describe('window-splitter contract — completeness', () => {
+ it('answers every completeness dimension', () => {
+ expect(unansweredDimensions(WINDOW_SPLITTER_PATTERN)).toEqual([]);
+ });
+
+ it('gives every expectation at least one deliberately violating fixture', () => {
+ const missing = WINDOW_SPLITTER_PATTERN.expectations
+ .filter(
+ expectation =>
+ (WINDOW_SPLITTER_MUTATIONS[expectation.id] ?? []).length === 0,
+ )
+ .map(expectation => expectation.id);
+ expect(missing).toEqual([]);
+ });
+
+ it('has an expectation for every mutation it records', () => {
+ const ids = new Set(
+ WINDOW_SPLITTER_PATTERN.expectations.map(expectation => expectation.id),
+ );
+ expect(
+ Object.keys(WINDOW_SPLITTER_MUTATIONS).filter(id => !ids.has(id)),
+ ).toEqual([]);
+ });
+
+ it('names every fixture it records a mutation against', () => {
+ for (const fixtures of Object.values(WINDOW_SPLITTER_MUTATIONS)) {
+ for (const id of fixtures) {
+ expect(() => fixture(id)).not.toThrow();
+ }
+ }
+ });
+});
+
+describe('window-splitter contract — the jsdom harness stays within its evidence boundary', () => {
+ it('runs DOM expectations and reports browser expectations as unrun', async () => {
+ const results = await resultsFor(fixture('conforming-vertical-bar'));
+ expect(results.some(result => result.status === 'pass')).toBe(true);
+ const above = results.filter(result => result.status === 'unrun');
+ expect(above.length).toBeGreaterThan(0);
+ for (const result of above) {
+ expect(
+ (result.missingLayers ?? []).some(
+ layer => layer === 'real-browser' || layer === 'accessibility-tree',
+ ),
+ ).toBe(true);
+ }
+ });
+});
+
+describe.each(observableHere.map(expectation => [expectation.id] as const))(
+ '%s',
+ id => {
+ const expectation = WINDOW_SPLITTER_PATTERN.expectations.find(
+ candidate => candidate.id === id,
+ )!;
+
+ it.each(CONFORMING_FIXTURES.map(name => [name] as const))(
+ 'passes against %s (or does not apply to it)',
+ async name => {
+ const result = resultFor(await resultsFor(fixture(name)), id);
+ expect(
+ ['pass', 'not-applicable'],
+ `${id} against ${name}: ${result.detail ?? ''}`,
+ ).toContain(result.status);
+ },
+ );
+
+ it.each((WINDOW_SPLITTER_MUTATIONS[id] ?? []).map(name => [name] as const))(
+ 'fails against %s, which removes its outcome',
+ async name => {
+ const result = resultFor(await resultsFor(fixture(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 = fixture(
+ WINDOW_SPLITTER_MUTATIONS[id]?.[0] ?? CONFORMING_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/window-splitter.ts b/internal/a11y-spec/src/patterns/window-splitter.ts
new file mode 100644
index 0000000000..326a55935f
--- /dev/null
+++ b/internal/a11y-spec/src/patterns/window-splitter.ts
@@ -0,0 +1,620 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file window-splitter.ts
+ * @input WCAG 2.2 A/AA success criteria and the APG Window Splitter pattern's role, value, name, relationship, and keyboard requirements
+ * @output WINDOW_SPLITTER_PATTERN — the reusable contract a focusable resize separator binds to when it adopts the pattern (ResizeHandle under component:Resizable AR1, `spec:AST-020/FR15`)
+ * @position Pattern contract; bound by ResizeHandle and the components that render it
+ */
+
+import {
+ definePattern,
+ type ApgRequirement,
+ type PatternContract,
+ type WcagCriterion,
+} from '../contract';
+import type {Key, Subject} from '../harness';
+
+const APG_URL = 'https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/';
+const UNDERSTANDING = 'https://www.w3.org/WAI/WCAG22/Understanding';
+
+const WCAG_1_3_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '1.3.1',
+ name: 'Info and Relationships',
+ level: 'A',
+ url: `${UNDERSTANDING}/info-and-relationships.html`,
+};
+const WCAG_2_1_1: WcagCriterion = {
+ standard: 'wcag',
+ id: '2.1.1',
+ name: 'Keyboard',
+ level: 'A',
+ url: `${UNDERSTANDING}/keyboard.html`,
+};
+const WCAG_4_1_2: WcagCriterion = {
+ standard: 'wcag',
+ id: '4.1.2',
+ name: 'Name, Role, Value',
+ level: 'A',
+ url: `${UNDERSTANDING}/name-role-value.html`,
+};
+
+const apgReq = (requirement: string, anchor: string): ApgRequirement => ({
+ standard: 'apg',
+ pattern: 'windowsplitter',
+ requirement,
+ url: `${APG_URL}#${anchor}`,
+});
+const A = 'wai-ariaroles,states,andproperties';
+const K = 'keyboardinteraction';
+const APG_ROLE = apgReq(
+ 'The element that serves as the focusable splitter has role separator.',
+ A,
+);
+const APG_VALUES = apgReq(
+ 'The separator element has the aria-valuenow property set to a decimal value representing the current position of the separator; aria-valuemin set to the position where the primary pane has its minimum size; aria-valuemax set to the position where the primary pane has its maximum size.',
+ A,
+);
+const APG_NAME = apgReq(
+ 'If the primary pane has a visible label, it is referenced by aria-labelledby on the separator element. Otherwise, the separator element has a label provided by aria-label.',
+ A,
+);
+const APG_CONTROLS = apgReq(
+ 'The separator element has aria-controls referring to the primary pane.',
+ A,
+);
+const APG_ARROWS = apgReq(
+ 'Left Arrow: Moves a vertical splitter to the left. Right Arrow: Moves a vertical splitter to the right. Up Arrow: Moves a horizontal splitter up. Down Arrow: Moves a horizontal splitter down.',
+ K,
+);
+const APG_ENTER = apgReq(
+ 'Enter: If the primary pane is not collapsed, collapses the pane. If the pane is collapsed, restores the splitter to its previous position.',
+ K,
+);
+const APG_HOME_END = apgReq(
+ 'Home (Optional): Moves splitter to the position that gives the primary pane its smallest allowed size. End (Optional): Moves splitter to the position that gives the primary pane its largest allowed size.',
+ K,
+);
+
+/**
+ * What a binding knows about one focusable splitter (the subject). Positions
+ * are the pixel sizes the separator exposes; `increaseKey` is the arrow that
+ * grows `aria-valuenow` in this binding's layout (direction, reversal, and
+ * reading direction decide it); `step` is that key's pixel step.
+ */
+export interface WindowSplitterStateFacts {
+ readonly valueNow: number;
+ readonly valueMin: number;
+ /** The maximum the separator exposes, or null when the binding sets none (a recorded gap). */
+ readonly valueMax: number | null;
+ /** The axis the separator LIES along: a left/right pane handle is `vertical`. */
+ readonly orientation: 'horizontal' | 'vertical';
+ readonly increaseKey: 'ArrowRight' | 'ArrowLeft' | 'ArrowUp' | 'ArrowDown';
+ readonly step: number;
+ /** Whether the user is meant to be able to move the separator. */
+ readonly operable: boolean;
+ /** Whether Enter collapses and restores the primary pane. */
+ readonly collapsible: boolean;
+ /**
+ * Whether the pane starts collapsed. The collapse-and-restore row assumes
+ * an open pane, so it does not run here; the arrow row still does, since a
+ * collapsed pane must still answer the keyboard.
+ */
+ readonly startsCollapsed?: boolean;
+}
+
+const ALWAYS = {
+ condition: 'the binding designates a focusable splitter',
+ test: () => true,
+};
+
+const OPPOSITE: Record<WindowSplitterStateFacts['increaseKey'], Key> = {
+ ArrowRight: 'ArrowLeft',
+ ArrowLeft: 'ArrowRight',
+ ArrowUp: 'ArrowDown',
+ ArrowDown: 'ArrowUp',
+};
+
+async function numericAttribute(
+ subject: Subject,
+ name: string,
+): Promise<number> {
+ const raw = await subject.attribute(name);
+ const parsed = raw == null ? Number.NaN : Number(raw);
+ if (!Number.isFinite(parsed)) {
+ throw new Error(`${name} is ${raw ?? 'absent'}, not a number`);
+ }
+ return parsed;
+}
+
+async function valueNow(subject: Subject): Promise<number> {
+ return numericAttribute(subject, 'aria-valuenow');
+}
+
+async function focusOrFail(subject: Subject, forWhat: string): Promise<void> {
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ throw new Error(
+ `the splitter did not take focus, so ${forWhat} never reaches it`,
+ );
+ }
+}
+
+async function expectValue(
+ subject: Subject,
+ expected: number,
+ after: string,
+): Promise<void> {
+ const now = await valueNow(subject);
+ if (Math.abs(now - expected) > 0.5) {
+ throw new Error(`${after} left aria-valuenow at ${now}, not ${expected}`);
+ }
+}
+
+function clampTo(facts: WindowSplitterStateFacts, target: number): number {
+ const upper = facts.valueMax ?? Number.POSITIVE_INFINITY;
+ return Math.min(upper, Math.max(facts.valueMin, target));
+}
+
+export const WINDOW_SPLITTER_PATTERN: PatternContract<WindowSplitterStateFacts> =
+ definePattern<WindowSplitterStateFacts>({
+ pattern: 'windowsplitter',
+ url: APG_URL,
+ scope:
+ "A focusable splitter's role and name, its position and bounds, the pane it controls, its orientation, and the arrow, Enter, Home and End keys.",
+ expectations: [
+ {
+ id: 'windowsplitter.separator.role-and-name',
+ outcome:
+ 'The browser exposes the splitter as a named separator, so a user hears which pane they are resizing.',
+ sources: [WCAG_4_1_2, APG_ROLE, APG_NAME],
+ covers: [
+ '4.1.2-name-role-value',
+ '2.4.6-headings-and-labels',
+ 'apg-interaction',
+ ],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'accessibility-tree',
+ enforcement: 'required',
+ run: async ({subject}) => {
+ const {role, name} = await subject.computed();
+ if (role !== 'separator' && role !== 'splitter') {
+ throw new Error(
+ `the browser exposes this splitter as ${role == null ? 'no role' : `"${role}"`}, not as a separator`,
+ );
+ }
+ if (!name || name.trim() === '') {
+ throw new Error(
+ 'the browser computes no accessible name for this splitter',
+ );
+ }
+ },
+ },
+ {
+ id: 'windowsplitter.separator.position-and-minimum',
+ outcome:
+ 'The splitter states where it is and the smallest size the pane can take, so a user hears their position in the range.',
+ sources: [WCAG_4_1_2, APG_VALUES],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const now = await valueNow(subject);
+ const min = await numericAttribute(subject, 'aria-valuemin');
+ if (now !== facts.valueNow || min !== facts.valueMin) {
+ throw new Error(
+ `the splitter exposes now/min ${now}/${min}, not ${facts.valueNow}/${facts.valueMin}`,
+ );
+ }
+ if (now < min) {
+ throw new Error('aria-valuenow lies below aria-valuemin');
+ }
+ },
+ },
+ {
+ id: 'windowsplitter.separator.maximum',
+ outcome:
+ 'The splitter states the largest size the pane can take, so a user hears where the range ends.',
+ sources: [WCAG_4_1_2, APG_VALUES],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const raw = await subject.attribute('aria-valuemax');
+ if (raw == null) {
+ throw new Error('the splitter exposes no aria-valuemax');
+ }
+ const max = Number(raw);
+ if (!Number.isFinite(max)) {
+ throw new Error(`aria-valuemax is "${raw}", not a number`);
+ }
+ if (facts.valueMax != null && max !== facts.valueMax) {
+ throw new Error(`aria-valuemax is ${max}, not ${facts.valueMax}`);
+ }
+ if (max < facts.valueMin) {
+ throw new Error('aria-valuemax lies below aria-valuemin');
+ }
+ const now = await valueNow(subject);
+ if (now > max) {
+ throw new Error('aria-valuenow lies above aria-valuemax');
+ }
+ },
+ },
+ {
+ id: 'windowsplitter.separator.orientation',
+ outcome:
+ 'The splitter says which axis it lies along, so a user knows which arrows move it.',
+ sources: [WCAG_4_1_2, APG_ARROWS],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({subject, facts}) => {
+ const orientation = await subject.attribute('aria-orientation');
+ // A separator's default is horizontal; the bar that divides
+ // left/right panes must say vertical.
+ const actual = orientation ?? 'horizontal';
+ if (actual !== facts.orientation) {
+ throw new Error(
+ `aria-orientation is ${orientation ?? 'absent (horizontal)'}, not ${facts.orientation}`,
+ );
+ }
+ },
+ },
+ {
+ id: 'windowsplitter.separator.controls-pane',
+ outcome:
+ 'The splitter names the pane it resizes, so assistive technology can relate the control to its target.',
+ sources: [WCAG_1_3_1, APG_CONTROLS],
+ covers: ['1.3.1-info-and-relationships', 'apg-interaction'],
+ appliesWhen: ALWAYS,
+ evidenceLayer: 'dom',
+ enforcement: 'required',
+ run: async ({harness, subject}) => {
+ const controls = await subject.attribute('aria-controls');
+ if (controls == null || controls.trim() === '') {
+ throw new Error('the splitter carries no aria-controls');
+ }
+ const pane = await harness.related('pane');
+ if (!(await harness.references(subject, 'aria-controls', pane))) {
+ throw new Error(
+ `aria-controls points at "${controls}", not at the pane the binding designates`,
+ );
+ }
+ },
+ },
+ {
+ id: 'windowsplitter.keys.arrows-move',
+ outcome:
+ 'One arrow moves the splitter so the pane grows by a step and the opposite arrow moves it back.',
+ sources: [WCAG_2_1_1, APG_ARROWS],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition: 'the splitter can be moved',
+ test: facts => facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['dom'],
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ await focusOrFail(subject, 'the arrow keys');
+ await harness.press(facts.increaseKey);
+ await expectValue(
+ subject,
+ clampTo(facts, facts.valueNow + facts.step),
+ `${facts.increaseKey} (grow)`,
+ );
+ await harness.press(OPPOSITE[facts.increaseKey]);
+ await expectValue(
+ subject,
+ facts.valueNow,
+ `${OPPOSITE[facts.increaseKey]} (shrink)`,
+ );
+ },
+ },
+ {
+ id: 'windowsplitter.keys.enter-collapses-and-restores',
+ outcome:
+ 'Enter collapses the pane and announces it; Enter again restores the splitter to where it was.',
+ sources: [WCAG_2_1_1, APG_ENTER],
+ covers: ['2.1.1-keyboard', '4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: {
+ condition:
+ 'the pane is collapsible, starts open, and the splitter can be moved',
+ test: facts =>
+ facts.collapsible && facts.operable && !facts.startsCollapsed,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['dom'],
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ await focusOrFail(subject, 'Enter');
+ await harness.press('Enter');
+ const text = await subject.attribute('aria-valuetext');
+ if (text == null || text.trim() === '') {
+ throw new Error(
+ 'Enter did not collapse the pane (no aria-valuetext announces the collapsed state)',
+ );
+ }
+ await harness.press('Enter');
+ const after = await subject.attribute('aria-valuetext');
+ if (after != null) {
+ throw new Error(
+ 'a second Enter did not restore the pane (aria-valuetext still announces it collapsed)',
+ );
+ }
+ await expectValue(subject, facts.valueNow, 'Enter (restore)');
+ },
+ },
+ {
+ id: 'windowsplitter.keys.home-end',
+ outcome:
+ 'Home gives the pane its smallest allowed size and End its largest.',
+ sources: [WCAG_2_1_1, APG_HOME_END],
+ covers: ['2.1.1-keyboard', 'apg-interaction'],
+ appliesWhen: {
+ condition: 'the splitter can be moved',
+ test: facts => facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['dom'],
+ enforcement: 'advisory',
+ advisoryBecause:
+ "Home and End are optional in the APG pattern; this becomes required once the binding's component record adopts them as current (AST-020 FR9).",
+ run: async ({harness, subject, facts}) => {
+ await focusOrFail(subject, 'Home and End');
+ await harness.press('Home');
+ await expectValue(subject, facts.valueMin, 'Home');
+ await harness.press('End');
+ // End should reach the maximum the separator exposes. Without a
+ // configured maximum that is the reported stand-in (or, when none is
+ // exposed, there is nowhere for End to go: it stays at the minimum
+ // Home just reached). The row reports what End does rather than
+ // skipping the state.
+ const exposedMax = await subject.attribute('aria-valuemax');
+ const endTarget =
+ facts.valueMax ??
+ (exposedMax != null && Number.isFinite(Number(exposedMax))
+ ? Number(exposedMax)
+ : facts.valueMin);
+ await expectValue(subject, endTarget, 'End');
+ },
+ },
+ {
+ id: 'windowsplitter.separator.unavailable-keeps-position',
+ outcome:
+ 'An unavailable splitter says so and keeps its position on every key, so a locked layout never moves under the keyboard.',
+ sources: [WCAG_4_1_2, APG_ARROWS],
+ covers: ['4.1.2-name-role-value', 'apg-interaction'],
+ appliesWhen: {
+ condition: 'the splitter cannot be moved',
+ test: facts => !facts.operable,
+ },
+ evidenceLayer: 'real-browser',
+ alsoNeeds: ['dom'],
+ enforcement: 'required',
+ run: async ({harness, subject, facts}) => {
+ if ((await subject.attribute('aria-disabled')) !== 'true') {
+ throw new Error(
+ 'an unavailable splitter does not carry aria-disabled="true"',
+ );
+ }
+ await subject.focus();
+ if (!(await subject.isFocused())) {
+ // Out of the Tab order: nothing can reach it, so nothing moves.
+ return;
+ }
+ for (const key of [facts.increaseKey, 'Home', 'Enter'] as const) {
+ await harness.press(key);
+ await expectValue(
+ subject,
+ facts.valueNow,
+ `${key} on an unavailable splitter`,
+ );
+ }
+ },
+ },
+ ],
+ exemptions: {
+ '1.1.1-non-text-content': {
+ owner: 'the binding component',
+ verifiedBy:
+ "the component's decorative-icon tests and the repository axe audit, `pnpm a11y:audit`",
+ reason:
+ "This contract owns the splitter's semantics and keys. The grip pill and divider line the binding paints are decorative composition.",
+ },
+ '1.3.1-info-and-relationships': {
+ owner: 'the binding component and composing page',
+ verifiedBy:
+ "the component's pane structure tests and page-level relationship review",
+ reason:
+ "This contract proves the splitter names the pane it controls. The panes themselves and their landmarks are the binding's and the page's.",
+ coversRemainderOnly: true,
+ },
+ '1.3.2-meaningful-sequence': {
+ owner: 'the binding component and composing page',
+ verifiedBy:
+ "the component's DOM-order tests and page-level reading-order review",
+ reason:
+ "Where the splitter sits between its panes, and the panes' reading order, is composition.",
+ },
+ '1.3.5-identify-input-purpose': {
+ owner: 'the binding component',
+ verifiedBy:
+ "this contract's role row (the separator carries role, name and value properties and no input purpose) and the component's render tests",
+ reason:
+ "A splitter collects a layout position, not information about the user that autofill could supply; the binding's separator is the only control it renders.",
+ },
+ '1.4.1-use-of-color': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ "the component's hover, focus and disabled state tests plus rendered review",
+ reason:
+ 'Hover, drag and disabled cues on the handle are paint results owned by the binding and theme; this contract proves the programmatic position and state.',
+ },
+ '1.4.3-contrast-minimum': {
+ owner: 'the binding component and theme',
+ verifiedBy: 'the repository axe audit plus rendered contrast review',
+ reason:
+ 'A splitter paints no text; the collapsed announcement is programmatic.',
+ },
+ '1.4.11-non-text-contrast': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ 'the repository axe audit plus rendered review of the divider, grip and focus indicator',
+ reason:
+ 'Divider, grip and focus indicator contrast are paint outcomes owned by the binding and theme.',
+ },
+ '2.1.1-keyboard': {
+ owner: 'the composing page',
+ verifiedBy: 'page-level keyboard review',
+ reason:
+ "This contract encodes the splitter's arrow, Enter, Home and End keys. Reaching the splitter, F6 pane cycling, and other page keyboard paths remain with the composition.",
+ coversRemainderOnly: true,
+ },
+ '2.1.2-no-keyboard-trap': {
+ owner: 'the binding component and composing page',
+ verifiedBy: "the component's Tab tests and page-level keyboard review",
+ reason:
+ 'A splitter adds no focus trap; Tab entry and exit are generic focus behavior.',
+ },
+ '2.4.2-page-titled': {
+ owner: 'the page',
+ verifiedBy: 'page-level review',
+ reason: 'A splitter rendered in isolation owns no document title.',
+ },
+ '2.4.3-focus-order': {
+ owner: 'the composing page',
+ verifiedBy: 'page-level focus-order review',
+ reason:
+ "The splitter's place among surrounding controls depends on composition.",
+ },
+ '2.4.4-link-purpose': {
+ owner: 'the binding component',
+ verifiedBy:
+ "this contract's role row and the component's render tests (the handle renders a separator and a grab zone, no anchor)",
+ reason:
+ 'A splitter renders no link; the composing page owns any link placed around it.',
+ },
+ '2.4.6-headings-and-labels': {
+ owner: 'the binding component and caller content',
+ verifiedBy: "the component's name tests and caller content review",
+ reason:
+ 'This contract proves the splitter has a name; whether that label is descriptive is caller content.',
+ coversRemainderOnly: true,
+ },
+ '2.4.7-focus-visible': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ "the component's focus-outline tests and rendered focus review",
+ reason:
+ "The focused splitter's indicator is a paint result owned by the binding and theme.",
+ },
+ '2.4.11-focus-not-obscured': {
+ owner: 'the composing page',
+ verifiedBy: 'page-level layout review',
+ reason:
+ 'Whether another surface covers the focused splitter depends on composition.',
+ },
+ '2.5.2-pointer-cancellation': {
+ owner: 'the binding component',
+ verifiedBy:
+ "the component's pointer suites: capture on the grab zone, moves from a pointer that does not own the drag are ignored, a drag that ends normally reports no cancel, pointercancel and lost capture end the gesture, and double-click collapse/restore",
+ reason:
+ "A splitter moves through the drag itself (the down event starts a reversible gesture; releasing ends it), so the pointer model is the binding's and outside this keyboard contract. The handle has no Escape cancel; the browser's pointercancel and lost capture are what end an interrupted drag.",
+ },
+ '2.5.3-label-in-name': {
+ owner: 'the binding component',
+ verifiedBy: "the component's accessible-name tests",
+ reason:
+ 'A splitter has no visible text label; its name is authored by the binding.',
+ },
+ '2.5.8-target-size': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ "the repository axe audit's target-size rule over the grab zone",
+ reason:
+ "The grab zone's hit area is geometry owned by the binding and theme.",
+ },
+ '3.1.1-language-of-page': {
+ owner: 'the page',
+ verifiedBy: 'page-level review',
+ reason: 'A splitter owns no document language.',
+ },
+ '3.2.2-on-input': {
+ owner: 'the caller and composing page',
+ verifiedBy:
+ 'integration review of what a caller does with onSizeChange and onCollapseChange',
+ reason:
+ "Resizing or collapsing a pane is the splitter's own purpose; any further context change a caller makes is the caller's action.",
+ },
+ '3.2.4-consistent-identification': {
+ owner: 'the composing page',
+ verifiedBy:
+ 'this shared contract across bindings plus content review of repeated splitter labels',
+ reason:
+ 'Consistency is a property of the full set of repeated functions, not one isolated splitter.',
+ },
+ '3.3.1-error-identification': {
+ owner: 'the binding component and composing page',
+ verifiedBy:
+ "this contract's value rows (aria-valuenow stays within aria-valuemin/aria-valuemax, so no entry can be in error) and the composing page's form checks",
+ reason:
+ 'A splitter has no free entry to validate: its value is clamped to its bounds as it changes; a form around it reports its own errors.',
+ },
+ '3.3.2-labels-or-instructions': {
+ owner: 'the binding component and composing page',
+ verifiedBy:
+ "this contract's name row (every separator is labelled) and the composing page's review of any instructions around it",
+ reason:
+ "The separator is named by its label; a splitter needs no entry instructions, and any guidance about the layout is the composing page's.",
+ },
+ '4.1.2-name-role-value': {
+ owner: 'the binding component',
+ verifiedBy: "the component's collapsed-state and disabled tests",
+ reason:
+ "This contract encodes the splitter's role, name, position, bounds, orientation, collapsed text and disabled state. The panes' own roles are the binding's and the page's.",
+ coversRemainderOnly: true,
+ },
+ '4.1.3-status-messages': {
+ owner:
+ 'the caller and the assistive-technology verification record, spec:AST-009',
+ verifiedBy:
+ 'the status-message pattern and real-AT evidence under AST-009 when a change claims spoken or braille output',
+ reason:
+ 'A size change is not a status-message contract; the collapsed state is exposed through aria-valuetext, not a live region.',
+ },
+ 'apg-interaction': {
+ owner: "the binding component's record",
+ verifiedBy:
+ 'component:Resizable AR1 and its decision entry, which adopt the pattern as one composite control and name the gaps',
+ reason:
+ "This contract encodes the splitter role, position, bounds, name, relationship and keys. F6 pane cycling is not adopted; the pointer drag model is the binding's.",
+ coversRemainderOnly: true,
+ },
+ 'forced-colors': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ "the component's forced-colors tests plus rendered Windows High Contrast review",
+ reason:
+ 'Forced-colors output is a paint result owned by the binding and theme.',
+ },
+ 'reduced-motion': {
+ owner: 'the binding component and theme',
+ verifiedBy:
+ "the component's reduced-motion source tests and rendered motion review",
+ reason:
+ 'Pane and handle motion is binding-specific paint over time and is not part of splitter semantics.',
+ },
+ 'at-facing-strings': {
+ owner: 'the binding component and caller content',
+ verifiedBy:
+ 'the repository i18n catalog check and source review of authored labels',
+ reason:
+ "The splitter contract introduces no string; the label and the collapsed text come from the binding's catalog.",
+ },
+ },
+ });
diff --git a/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..96d2374294
--- /dev/null
+++ b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.chromium.spec.ts
@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ResizeHandle.a11y.chromium.spec.ts
+ * @input Built ResizeHandle stories and WINDOW_SPLITTER_PATTERN in real Chromium
+ * @output Browser evidence for every window-splitter expectation across the binding's states, reconciled against the exact known failures
+ * @position Chromium lane of the ResizeHandle binding (component:Resizable AR1)
+ */
+
+import {
+ expect,
+ test,
+ type CDPSession,
+ type Locator,
+ type Page,
+} from '@playwright/test';
+import {
+ WINDOW_SPLITTER_PATTERN,
+ blockingResults,
+ checkAccessibilitySpec,
+ formatFailures,
+ neverExercised,
+ summarize,
+ unmatchedKnownFailures,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+ createChromiumHarness,
+ holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {RESIZE_HANDLE_KNOWN_FAILURES} from './ResizeHandle.a11y.known-failures';
+import {
+ RESIZE_HANDLE_BINDING_STATES,
+ type ResizeHandleBindingState,
+} from './ResizeHandle.a11y.states';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+function storyUrl(storyId: string): string {
+ return `${storybook.origin}/iframe.html?id=${storyId}&viewMode=story`;
+}
+
+async function mountState(
+ page: Page,
+ state: ResizeHandleBindingState,
+): Promise<{subject: Locator; related: Record<string, Locator>}> {
+ await page.goto(storyUrl(state.storyId), {waitUntil: 'load'});
+ await holdMotionStill(page);
+ const root = page.locator('#storybook-root');
+ const subject = root.getByRole('separator', {name: state.label});
+ await subject.waitFor({state: 'attached'});
+ const pane = root.locator('#a11y-splitter-pane');
+ return {subject, related: {pane}};
+}
+
+async function runState(
+ page: Page,
+ cdp: CDPSession,
+ state: ResizeHandleBindingState,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: WINDOW_SPLITTER_PATTERN,
+ binding: 'ResizeHandle',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RESIZE_HANDLE_KNOWN_FAILURES,
+ mount: async () => {
+ const {subject, related} = await mountState(page, state);
+ return createChromiumHarness({page, cdp, subject, related});
+ },
+ });
+}
+
+test('every window-splitter expectation is exercised by a ResizeHandle state', async ({
+ page,
+}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const results: BindingResult[] = [];
+ for (const state of RESIZE_HANDLE_BINDING_STATES) {
+ results.push(await runState(page, cdp, state));
+ }
+ expect(neverExercised(results)).toEqual([]);
+ expect(unmatchedKnownFailures(RESIZE_HANDLE_KNOWN_FAILURES, results)).toEqual(
+ [],
+ );
+});
+
+for (const state of RESIZE_HANDLE_BINDING_STATES) {
+ test(`ResizeHandle [${state.id}] — ${state.summary}`, async ({page}) => {
+ const cdp = await page.context().newCDPSession(page);
+ const result = await runState(page, cdp, state);
+ const report = summarize(WINDOW_SPLITTER_PATTERN, [result]);
+ // Required rows block (AST-020 FR9); advisory rows and exact known
+ // failures report.
+ expect(formatFailures(blockingResults([result]))).toBe('');
+ expect(report.unrunLayers).toEqual([]);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+}
diff --git a/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.known-failures.ts b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.known-failures.ts
new file mode 100644
index 0000000000..d3c55d9ff2
--- /dev/null
+++ b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.known-failures.ts
@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ResizeHandle.a11y.known-failures.ts
+ * @input The exact window-splitter failures the shipped ResizeHandle produces today
+ * @output RESIZE_HANDLE_KNOWN_FAILURES — records both lanes reconcile against, so a fix shows up as an unexpected pass and any other failure stays a failure
+ * @position Known-failure ledger for the ResizeHandle binding
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const RESIZE_HANDLE_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+ {
+ expectation: 'windowsplitter.separator.maximum',
+ binding: 'ResizeHandle',
+ state: 'bare-unbounded-in-container',
+ evidenceLayer: 'dom',
+ failureEquals: 'the splitter exposes no aria-valuemax',
+ standardsReference:
+ 'WAI-ARIA separator (focusable): aria-valuemax; APG Window Splitter states and properties; Astryx component:Resizable AR1 (an unbounded Handle in a container that no percentage bound observes carries no aria-valuemax, because measuring that container would add an observer to a region whose bounds are all in pixels).',
+ userImpact:
+ 'A screen-reader user on a handle whose pixel-only region sits in a container and sets no maximum hears a value and a minimum but no maximum.',
+ reason:
+ 'A recorded gap with a reason the record owns (Performance and resources: atomic pixel paths add no observer); it closes only with a record decision, not a fix.',
+ },
+ {
+ expectation: 'windowsplitter.keys.arrows-move',
+ binding: 'ResizeHandle',
+ state: 'bare-snapped',
+ evidenceLayer: 'real-browser',
+ failureEquals: 'ArrowRight (grow) left aria-valuenow at 200, not 210',
+ standardsReference:
+ 'APG Window Splitter keyboard interaction — the arrow keys move the splitter; Astryx component:Resizable AR1.',
+ userImpact:
+ 'A keyboard user on a region with snap points presses an arrow and nothing happens: a 10px step snaps back to the point it started on, so only a pointer drag reaches the next point.',
+ reason:
+ 'This test-only binding records the gap; moving to the adjacent snap point on an arrow is a component decision for its own spec-backed patch.',
+ },
+ {
+ expectation: 'windowsplitter.separator.controls-pane',
+ binding: 'ResizeHandle',
+ state: 'bare-documented-usage',
+ evidenceLayer: 'dom',
+ failureEquals: 'the splitter carries no aria-controls',
+ standardsReference:
+ 'APG Window Splitter states and properties: the separator has aria-controls set to the id of the primary pane; Astryx component:Resizable AR1 (the Handle names the pane it resizes with aria-controls only when its caller passes one).',
+ userImpact:
+ 'A screen-reader user on a handle rendered the documented minimal way hears a separator with no named pane; the relationship exists only when the caller wires it (SideNav does).',
+ reason:
+ 'A recorded gap the record owns: whether the Handle should derive the pane relationship itself is a component decision for its own spec-backed patch.',
+ },
+];
diff --git a/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.renders.tsx b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.renders.tsx
new file mode 100644
index 0000000000..78b8f2edc7
--- /dev/null
+++ b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.renders.tsx
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ResizeHandle.a11y.renders.tsx
+ * @input One ResizeHandle binding state
+ * @output The React tree every lane renders for that state (the jsdom test directly, the story through Storybook)
+ * @position Shared fixture for the ResizeHandle binding
+ */
+
+import {useRef, type ReactElement} from 'react';
+import {ResizeHandle} from '../ResizeHandle';
+import {useResizable} from '../useResizable';
+import type {ResizeHandleBindingState} from './ResizeHandle.a11y.states';
+
+/** The id the binding gives the pane the bare handle controls. */
+export const BARE_PANE_ID = 'a11y-splitter-pane';
+
+function BareSplitter({state}: {state: ResizeHandleBindingState}) {
+ const direction = state.direction ?? 'horizontal';
+ const containerRef = useRef<HTMLDivElement>(null);
+ const region = useResizable({
+ containerRef: state.inContainer ? containerRef : undefined,
+ defaultSize: state.facts.valueNow,
+ minSize: state.facts.valueMin,
+ maxSize: state.maxSize === null ? undefined : (state.facts.valueMax ?? 400),
+ direction,
+ collapsible: state.facts.collapsible,
+ collapsedSize: state.collapsedSize,
+ defaultIsCollapsed: state.startsCollapsed,
+ snaps: state.snaps ? [...state.snaps] : undefined,
+ });
+ const isHorizontal = direction === 'horizontal';
+ const pane = (
+ <div
+ id={BARE_PANE_ID}
+ style={{
+ ...(isHorizontal ? {width: region.size} : {height: region.size}),
+ background: 'var(--astryx-bg-surface, #f2f2f2)',
+ padding: 12,
+ }}>
+ Details
+ </div>
+ );
+ const handle = (
+ <ResizeHandle
+ resizable={region.props}
+ label={state.label}
+ direction={direction}
+ isReversed={state.isReversed}
+ isDisabled={state.disabled}
+ aria-controls={state.withoutControls ? undefined : BARE_PANE_ID}
+ />
+ );
+ return (
+ <div
+ ref={containerRef}
+ style={{
+ display: 'flex',
+ flexDirection: isHorizontal ? 'row' : 'column',
+ width: 600,
+ height: 320,
+ }}>
+ {state.isReversed ? handle : pane}
+ {state.isReversed ? pane : handle}
+ <div style={{flex: 1, padding: 12}}>Main content</div>
+ </div>
+ );
+}
+
+export function renderResizeHandleState(
+ state: ResizeHandleBindingState,
+): ReactElement {
+ return (
+ <div dir={state.rtl ? 'rtl' : 'ltr'} style={{padding: 16}}>
+ <BareSplitter state={state} />
+ </div>
+ );
+}
diff --git a/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.states.ts b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.states.ts
new file mode 100644
index 0000000000..1164e875f5
--- /dev/null
+++ b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.states.ts
@@ -0,0 +1,196 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ResizeHandle.a11y.states.ts
+ * @input ResizeHandle's representative splitter states and the facts WINDOW_SPLITTER_PATTERN reads
+ * @output RESIZE_HANDLE_BINDING_STATES and the explicit ownership exclusions for this binding
+ * @position Binding inventory shared by the jsdom test, the Chromium spec, and the story (component:Resizable AR1)
+ */
+
+import type {WindowSplitterStateFacts} from '@astryxdesign/a11y-spec';
+
+export interface ResizeHandleBindingState {
+ readonly id: string;
+ readonly summary: string;
+ readonly storyId: string;
+ /** Which composition renders the handle; SideNav's binding follows separately. */
+ readonly component: 'ResizeHandle';
+ /** The separator's accessible name. */
+ readonly label: string;
+ readonly facts: WindowSplitterStateFacts;
+ /** Bare-handle configuration. */
+ readonly direction?: 'horizontal' | 'vertical';
+ readonly isReversed?: boolean;
+ readonly rtl?: boolean;
+ readonly maxSize?: number | null;
+ /** The hook's collapse threshold, when the state sets one. */
+ readonly collapsedSize?: number;
+ /** Start the pane collapsed (`defaultIsCollapsed`). */
+ readonly startsCollapsed?: boolean;
+ /** Pass a `containerRef` (a pixel-only region inside a container). */
+ readonly inContainer?: boolean;
+ /** Snap points for the region (`snaps`). */
+ readonly snaps?: ReadonlyArray<number>;
+ /** Render the documented minimal usage: no `aria-controls` passed. */
+ readonly withoutControls?: boolean;
+ readonly disabled?: boolean;
+}
+
+function facts(
+ overrides: Partial<WindowSplitterStateFacts> = {},
+): WindowSplitterStateFacts {
+ return {
+ valueNow: 200,
+ valueMin: 100,
+ valueMax: 400,
+ orientation: 'vertical',
+ increaseKey: 'ArrowRight',
+ step: 10,
+ operable: true,
+ collapsible: false,
+ ...overrides,
+ };
+}
+
+const story = (id: string) => `a11y-windowsplitter--${id}`;
+
+export const RESIZE_HANDLE_BINDING_STATES = [
+ {
+ id: 'bare-horizontal',
+ summary: 'a bare ResizeHandle on the end side of a 200px pane (100–400)',
+ storyId: story('bare-horizontal'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts(),
+ },
+ {
+ id: 'bare-vertical',
+ summary: 'a bare ResizeHandle below a 200px pane: ArrowDown grows it',
+ storyId: story('bare-vertical'),
+ component: 'ResizeHandle',
+ label: 'Resize log pane',
+ facts: facts({orientation: 'horizontal', increaseKey: 'ArrowDown'}),
+ direction: 'vertical',
+ },
+ {
+ id: 'bare-reversed',
+ summary:
+ 'a bare ResizeHandle on the start side of its pane: ArrowLeft grows it',
+ storyId: story('bare-reversed'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({increaseKey: 'ArrowLeft'}),
+ isReversed: true,
+ },
+ {
+ id: 'bare-rtl',
+ summary:
+ 'a bare ResizeHandle on a right-to-left page: the inline arrows follow the reading direction',
+ storyId: story('bare-rtl'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({increaseKey: 'ArrowLeft'}),
+ rtl: true,
+ },
+ {
+ id: 'bare-collapsible',
+ summary:
+ 'a bare ResizeHandle on a collapsible pane: Enter collapses and restores',
+ storyId: story('bare-collapsible'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({collapsible: true}),
+ },
+ {
+ id: 'bare-small-min',
+ summary:
+ 'a bare ResizeHandle on a collapsible pane whose minimum sits below the collapse threshold',
+ storyId: story('bare-small-min'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({collapsible: true, valueMin: 20}),
+ collapsedSize: 50,
+ },
+ {
+ id: 'bare-start-collapsed',
+ summary:
+ 'a bare ResizeHandle on a pane that starts collapsed: it announces the minimum as its value',
+ storyId: story('bare-start-collapsed'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ // Collapsed, the handle announces the minimum (100) as its value.
+ facts: facts({collapsible: true, startsCollapsed: true, valueNow: 100}),
+ startsCollapsed: true,
+ },
+ {
+ id: 'bare-unbounded',
+ summary: 'a bare ResizeHandle whose region sets no maximum',
+ storyId: story('bare-unbounded'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({valueMax: null}),
+ maxSize: null,
+ },
+ {
+ id: 'bare-unbounded-in-container',
+ summary:
+ 'a bare ResizeHandle whose pixel-only region sets no maximum and passes a containerRef: the first useResizable example',
+ storyId: story('bare-unbounded-in-container'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({valueMax: null}),
+ maxSize: null,
+ inContainer: true,
+ },
+ {
+ id: 'bare-snapped',
+ summary:
+ 'a bare ResizeHandle whose region sets snap points [100, 200, 300, 400]: it can rest only on a snap point',
+ storyId: story('bare-snapped'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts(),
+ snaps: [100, 200, 300, 400],
+ },
+ {
+ id: 'bare-documented-usage',
+ summary:
+ 'the documented minimal usage — <ResizeHandle direction resizable={region.props} /> with no aria-controls passed',
+ storyId: story('bare-documented-usage'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts(),
+ withoutControls: true,
+ },
+ {
+ id: 'bare-disabled',
+ summary: 'a disabled ResizeHandle: out of the Tab order and unmoving',
+ storyId: story('bare-disabled'),
+ component: 'ResizeHandle',
+ label: 'Resize details pane',
+ facts: facts({operable: false}),
+ disabled: true,
+ },
+] as const satisfies ReadonlyArray<ResizeHandleBindingState>;
+
+export const RESIZE_HANDLE_EXCLUSIONS = [
+ {
+ id: 'sidenav-binding',
+ owner:
+ 'SideNav.test.tsx until SideNav binds this contract in its own change',
+ reason:
+ 'SideNav renders ResizeHandle in overlay position with its own collapse coupling and translated label, and hides the handle entirely while the nav is collapsed, so the collapse-and-restore row cannot run against it as written; SideNav binds separately with states shaped for that.',
+ },
+ {
+ id: 'pointer-drag-model',
+ owner: 'ResizeHandle.test.tsx pointer suites',
+ reason:
+ "Dragging (pointer capture on the grab zone, ignoring a pointer that does not own the drag, ending on pointercancel or lost capture), double-click collapse and restore, and the grab-zone geometry are pointer behavior outside the keyboard-and-semantics pattern; the component's own jsdom pointer suites prove them. ResizeHandle has no Escape cancel and no Chromium pointer suite.",
+ },
+ {
+ id: 'pane-cycling',
+ owner: 'component:Resizable AR1 (not adopted) and the composing page',
+ reason:
+ "F6 pane cycling is an optional part of the APG pattern that the record does not adopt; which panes exist and how focus cycles among them is the composing page's decision.",
+ },
+] as const;
diff --git a/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.test.tsx b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.test.tsx
new file mode 100644
index 0000000000..efaca05ad5
--- /dev/null
+++ b/packages/core/src/Resizable/__tests__/ResizeHandle.a11y.test.tsx
@@ -0,0 +1,123 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file ResizeHandle.a11y.test.tsx
+ * @input WINDOW_SPLITTER_PATTERN bound to ResizeHandle's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for component:Resizable AR1 (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+ WINDOW_SPLITTER_PATTERN,
+ checkAccessibilitySpec,
+ createJsdomHarness,
+ expectAccessibilitySpec,
+ summarize,
+ type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {RESIZE_HANDLE_KNOWN_FAILURES} from './ResizeHandle.a11y.known-failures';
+import {
+ BARE_PANE_ID,
+ renderResizeHandleState,
+} from './ResizeHandle.a11y.renders';
+import {
+ RESIZE_HANDLE_BINDING_STATES,
+ RESIZE_HANDLE_EXCLUSIONS,
+ type ResizeHandleBindingState,
+} from './ResizeHandle.a11y.states';
+
+function separator(state: ResizeHandleBindingState): HTMLElement {
+ return screen.getByRole('separator', {name: state.label});
+}
+
+function pane(): HTMLElement {
+ const element = document.getElementById(BARE_PANE_ID);
+ if (element == null) {
+ throw new Error('the bare pane is not rendered');
+ }
+ return element;
+}
+
+async function checkState(
+ state: ResizeHandleBindingState,
+): Promise<BindingResult> {
+ return checkAccessibilitySpec({
+ spec: WINDOW_SPLITTER_PATTERN,
+ binding: 'ResizeHandle',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RESIZE_HANDLE_KNOWN_FAILURES,
+ mount: async () => {
+ render(renderResizeHandleState(state));
+ return createJsdomHarness({
+ subject: separator(state),
+ related: {pane: pane()},
+ });
+ },
+ unmount: cleanup,
+ });
+}
+
+describe('ResizeHandle — window splitter pattern, jsdom lane', () => {
+ it.each(
+ RESIZE_HANDLE_BINDING_STATES.map(
+ state => [state.id, state.summary, state] as const,
+ ),
+ )('%s — %s', async (_id, _summary, state) => {
+ await expectAccessibilitySpec({
+ spec: WINDOW_SPLITTER_PATTERN,
+ binding: 'ResizeHandle',
+ state: state.id,
+ facts: state.facts,
+ knownFailures: RESIZE_HANDLE_KNOWN_FAILURES,
+ render: () => {
+ render(renderResizeHandleState(state));
+ },
+ subject: () => separator(state),
+ related: () => ({pane: pane()}),
+ cleanup,
+ });
+ });
+
+ it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+ const results: BindingResult[] = [];
+ for (const state of RESIZE_HANDLE_BINDING_STATES) {
+ results.push(await checkState(state));
+ }
+ const report = summarize(WINDOW_SPLITTER_PATTERN, results);
+ expect(report.counts.pass).toBeGreaterThan(0);
+ expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+ expect(report.counts.unexpectedPass).toBe(0);
+ });
+});
+
+describe('ResizeHandle binding inventory', () => {
+ it('gives every representative state a distinct checked-in story', () => {
+ const stories = RESIZE_HANDLE_BINDING_STATES.map(state => state.storyId);
+ expect(new Set(stories).size).toBe(stories.length);
+ });
+
+ it('keeps pointer and pane-cycling ownership explicit', () => {
+ expect(RESIZE_HANDLE_EXCLUSIONS.map(exclusion => exclusion.id)).toEqual([
+ 'sidenav-binding',
+ 'pointer-drag-model',
+ 'pane-cycling',
+ ]);
+ for (const exclusion of RESIZE_HANDLE_EXCLUSIONS) {
+ expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+ expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+ }
+ });
+
+ it('renders exactly one named separator and its pane for every state', () => {
+ for (const state of RESIZE_HANDLE_BINDING_STATES) {
+ render(renderResizeHandleState(state));
+ expect(separator(state), state.id).toBeTruthy();
+ expect(pane(), state.id).toBeTruthy();
+ cleanup();
+ }
+ });
+});