@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/ScrollableArea/modules/useScrollableArea.spec.md

@@ -10,7 +10,12 @@ approved_by: cixzhang
 approved_at: 2026-09-11
 owners: [cixzhang]
 review_triggers: [public-api, behavior, accessibility]
-verified_by: [packages/core/src/hooks/useScrollableArea.test.tsx]
+verified_by:
+  [
+    packages/core/src/hooks/useScrollableArea.test.tsx,
+    packages/core/src/hooks/scrollKeyboardDelegation.test.ts,
+    packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
+  ]
 parent_component: component:ScrollableArea
 references: [architecture:public-component-api, spec:AST-025/DEC-1]
 ---
@@ -47,24 +52,25 @@ and scroll chaining without inserting structure.
 
 ## Public API and concepts
 
-| Concept        | Closed values or states            | Meaning                               | Default                   | Owner                                     | Stability |
-| -------------- | ---------------------------------- | ------------------------------------- | ------------------------- | ----------------------------------------- | --------- |
-| axis           | `inline`, `block`, `both`          | requested logical scroll intent       | required                  | `spec:AST-025`                            | stable    |
-| keyboard owner | `content`, named `viewport`        | where keyboard scrolling is reached   | required                  | `spec:AST-025`                            | stable    |
-| overscroll     | `allow`, `contain`                 | edge propagation on effective axes    | `allow`                   | `spec:AST-025`                            | stable    |
-| axis state     | `isScrollable`, `atStart`, `atEnd` | effective ownership and logical edges | inactive, both edges true | `module:ScrollableArea/useScrollableArea` | stable    |
+| Concept        | Closed values or states                                | Meaning                                 | Default                   | Owner                                     | Stability |
+| -------------- | ------------------------------------------------------ | --------------------------------------- | ------------------------- | ----------------------------------------- | --------- |
+| axis           | `inline`, `block`, `both`                              | requested logical scroll intent         | required                  | `spec:AST-025`                            | stable    |
+| keyboard owner | `content`, named `viewport`, named `contentOrViewport` | fixed or automatic keyboard scroll path | required                  | `spec:AST-025`                            | stable    |
+| overscroll     | `allow`, `contain`                                     | edge propagation on effective axes      | `allow`                   | `spec:AST-025`                            | stable    |
+| axis state     | `isScrollable`, `atStart`, `atEnd`                     | effective ownership and logical edges   | inactive, both edges true | `module:ScrollableArea/useScrollableArea` | stable    |
 
 ## Behavioral contract
 
-| ID  | Invariant                                                                                                                                                                             | Basis                       | Acceptance and implementation state     |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------- |
-| FR1 | An axis MUST be effective only when requested, computed overflow is scroll-capable, and geometry exceeds 1px.                                                                         | `spec:AST-025` FR1–FR4      | implemented                             |
-| FR2 | Viewport and content geometry MUST be observed; invalidations MUST coalesce and preserve the last valid state while unmeasurable.                                                     | `spec:AST-025` FR5–FR9      | implemented                             |
-| FR3 | Logical edges and behavior-owned physical overflow MUST map through direction and horizontal, vertical, or sideways writing modes without requiring adopters to recreate the mapping. | `spec:AST-025` FR1, FR3–FR4 | implemented                             |
-| FR4 | The nearest registered effective owner MUST win independently by axis.                                                                                                                | `spec:AST-025` FR10, FR18   | implemented privately for future Sticky |
-| FR5 | Viewport keyboard props and overscroll containment MUST appear only while applicable requested axes are effective.                                                                    | `spec:AST-025` FR12–FR14    | implemented                             |
-| FR6 | Prop getters MUST compose refs and preserve caller handlers/classes/styles/ARIA while behavior-owned accessibility and non-cancellable behavior win conflicts.                        | `spec:AST-025` IR4          | implemented                             |
-| FR7 | The viewport prop getter MUST consume caller `xstyle` and internally compose geometry-driven `clip`/`auto`/`hidden` overflow plus explicit fitting Sticky containment.                | `spec:AST-025` FR21         | implemented                             |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                        | Basis                       | Acceptance and implementation state     |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------- |
+| FR1 | An axis MUST be effective only when requested, computed overflow is scroll-capable, and geometry exceeds 1px.                                                                                                                                                                                                                                                                    | `spec:AST-025` FR1–FR4      | implemented                             |
+| FR2 | Viewport and content geometry MUST be observed; invalidations MUST coalesce and preserve the last valid state while unmeasurable.                                                                                                                                                                                                                                                | `spec:AST-025` FR5–FR9      | implemented                             |
+| FR3 | Logical edges and behavior-owned physical overflow MUST map through direction and horizontal, vertical, or sideways writing modes without requiring adopters to recreate the mapping.                                                                                                                                                                                            | `spec:AST-025` FR1, FR3–FR4 | implemented                             |
+| FR4 | The nearest registered effective owner MUST win independently by axis.                                                                                                                                                                                                                                                                                                           | `spec:AST-025` FR10, FR18   | implemented privately for future Sticky |
+| FR5 | Viewport keyboard props and overscroll containment MUST appear only while applicable requested axes are effective.                                                                                                                                                                                                                                                               | `spec:AST-025` FR12–FR14    | implemented                             |
+| FR6 | Prop getters MUST compose refs and preserve caller handlers/classes/styles/ARIA while behavior-owned accessibility and non-cancellable behavior win conflicts.                                                                                                                                                                                                                   | `spec:AST-025` IR4          | implemented                             |
+| FR7 | The viewport prop getter MUST consume caller `xstyle` and internally compose geometry-driven `clip`/`auto`/`hidden` overflow plus explicit fitting Sticky containment.                                                                                                                                                                                                           | `spec:AST-025` FR21         | implemented                             |
+| FR8 | `contentOrViewport` MUST retain the named overflowing viewport, inspect the first sequential descendant on forward Tab entry, and delegate only to a native link/button outside navigation-key-owning surfaces. Reverse traversal from the delegated first child skips the viewport. Pointer/programmatic focus never delegates; eligibility is checked again on the next entry. | `spec:AST-025` FR12–FR13    | implemented                             |
 
 ### Transformation and precedence order
 
@@ -82,9 +88,20 @@ and scroll chaining without inserting structure.
 
 ## Accessibility contract
 
-- **AR1 — Named viewport owner.** Viewport-owned access requires a label and adds
-  the viewport to the tab order only while an applicable axis is effective.
-- **AR2 — Focus continuity.** State changes never move or blur focus.
+- **AR1 — Named viewport owner.** Fixed viewport and automatic access require a
+  label and retain `tabIndex=0` while effectively scrollable. Automatic access
+  delegates only on forward keyboard entry; the descendant retains its own name
+  inside the named viewport group/region.
+- **AR2 — Focus continuity.** Content, eligibility, and geometry changes never
+  move or blur focus. A viewport losing overflow while focused remains
+  programmatically focusable. Reverse traversal from the delegated first child
+  skips the viewport, including after visiting later descendants.
+- **AR3 — Conservative eligibility.** Inspect the first sequential target; do not
+  search past an excluded one for a link/button. Composite roles, editable
+  surfaces, native or registered nested scroll owners, positive tab ordering,
+  popup triggers, and unproven interactive roles retain the viewport path.
+- **AR4 — Native scrolling.** Delegation MUST preserve Arrow/Page access to both
+  scroll edges without implementing JavaScript scrolling.
 
 ## Design relationships
 
@@ -97,9 +114,9 @@ No visual representation is owned by this hook.
 
 ## Verification map
 
-| Contract         | Verification                                                   | Representative states                                                                 | Mutation or failure expectation                                                                                |
-| ---------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| FR1–FR6, AR1–AR2 | `useScrollableArea.test.tsx` plus real-browser Storybook probe | horizontal/vertical/sideways, LTR/RTL, fit/overflow/edge, nested owners, focused loss | style-only or geometry-only ownership, physical-edge leakage, stale state, ref loss, or dead containment fails |
+| Contract         | Verification                                                                                                     | Representative states                                                                                                                                  | Mutation or failure expectation                                                                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR8, AR1–AR4 | `useScrollableArea.test.tsx`, `scrollKeyboardDelegation.test.ts`, and `BottomSheetKeyboard.a11y.browser.spec.ts` | horizontal/vertical/sideways, LTR/RTL, fit/overflow/edge, fixed/automatic keyboard owners, dynamic descendant eligibility, nested owners, focused loss | style-only or geometry-only ownership, physical-edge leakage, duplicate/missing keyboard path, stale state, ref loss, or dead containment fails |
 
 ## Decision log
 
@@ -111,6 +128,17 @@ No visual representation is owned by this hook.
 One returned prop object per owned element keeps refs, accessibility, handlers,
 and behavior together without making consumer spread order part of correctness.
 
+### DEC-2 — Automatic ownership is shared behavior
+
+**Reference:** `module:ScrollableArea/useScrollableArea/DEC-2`
+**Decider:** cixzhang, 2026-09-13
+
+`contentOrViewport` retains the named overflowing viewport and delegates only on
+forward Tab entry to a safe first sequential native link/button. This replaces
+continuous keyboard-eligibility observation. Geometry observation is unchanged;
+keyboard eligibility adds no subtree or ancestor observers and is inspected anew
+at each entry. BottomSheet is a proving composition of this shared behavior.
+
 ## Open questions
 
 None.

package/src/SegmentedControl/SegmentedControl.doc.mjs

@@ -129,9 +129,9 @@ export const docs = {
         category: 'Color contrast',
         criterion: '1.4.3 Contrast (Minimum)',
         requirement: '4.5:1',
-        states: ['Rest', 'Hover', 'Selected'],
+        states: ['Rest', 'Hover', 'Pointer down', 'Selected'],
         description:
-          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, and selected colors as they appear on screen.',
+          'Each label must have at least 4.5:1 contrast with its segment background. Check unselected, Hover, Pointer down, and selected colors as they appear on screen. For Hover and Pointer down, measure the final background after the overlay is applied.',
       },
       {
         name: 'Essential icon',

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -15,6 +15,7 @@
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {SegmentedControl} from './SegmentedControl';
 import {SegmentedControlItem} from './SegmentedControlItem';
 import {
@@ -672,3 +673,33 @@ describe('forced colors (WCAG 1.4.11)', () => {
     expect(getAllInjectedCss()).toContain('forced-color-adjust: none;');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay on a segment while it is pressed', () => {
+    render(
+      <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" />
+      </SegmentedControl>,
+    );
+    // The unselected segment is the one a press can change; it carries the
+    // system's hover and pressed overlay.
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'List'}))).toBe(true);
+    // The selected segment keeps its raised surface as it is.
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'Grid'}))).toBe(
+      false,
+    );
+  });
+
+  it('does not press a disabled segment', () => {
+    render(
+      <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+        <SegmentedControlItem value="grid" label="Grid" />
+        <SegmentedControlItem value="list" label="List" isDisabled />
+      </SegmentedControl>,
+    );
+    expect(hasPressedArm(screen.getByRole('radio', {name: 'List'}))).toBe(
+      false,
+    );
+  });
+});

package/src/SegmentedControl/SegmentedControlItem.tsx

@@ -33,6 +33,7 @@ import {mergeProps, composeEventHandlers} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 
 export interface SegmentedControlItemProps extends BaseProps<HTMLButtonElement> {
   ref?: React.Ref<HTMLButtonElement>;
@@ -91,14 +92,6 @@ const styles = stylex.create({
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
-  hover: {
-    backgroundColor: {
-      default: null,
-      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
-        '@media (hover: hover)': colorVars['--color-overlay-hover'],
-      },
-    },
-  },
   selected: {
     // Forced colors (Windows High Contrast) strips the painted surface fill
     // and box shadow, which would leave the selected segment with no state
@@ -248,7 +241,11 @@ export function SegmentedControlItem({
           sizeStyles[size],
           isFill && styles.fill,
           isSelected && styles.selected,
-          !isSelected && !isItemDisabled && styles.hover,
+          // The shared hover and pressed overlay, on the segments a press can
+          // change: the selected segment keeps its raised surface as it is.
+          !isSelected &&
+            !isItemDisabled &&
+            interactionOverlayStyles.backgroundColor,
           isItemDisabled && styles.disabled,
           xstyle,
         ),

package/src/Selector/Selector.spec.md

@@ -14,6 +14,8 @@ verified_by:
   [
     packages/core/src/Selector/Selector.test.tsx,
     packages/core/src/Selector/Selector.source-build.test.mjs,
+    packages/core/src/Selector/__tests__/Selector.listbox.a11y.test.tsx,
+    packages/core/src/Selector/__tests__/Listbox.a11y.chromium.spec.ts,
   ]
 modules: []
 families: [family:input-fields]
@@ -274,15 +276,16 @@ in `spec:AST-004` as current runtime behavior.
 
 ## Verification map
 
-| Contract              | Verification                                                                               | Representative states                                             | Mutation or failure expectation                                                                                | Audit section                    |
-| --------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1, AR2, AR3         | `Selector.test.tsx` selection, focus, and keyboard suites                                  | closed/open, search/non-search, disabled option                   | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests              | `audit:Selector/behavior`        |
-| FR2                   | placement and selected-item geometry tests                                                 | default, explicit, RTL, transformed entry                         | Using the wrong positioning model fails the expected position-area or margin                                   | `audit:Selector/behavior`        |
-| FR3, AV1              | `itemMarkColumn` source inspection plus indicator-position and replacement-indicator tests | start/end, selected/unselected, check/radio                       | Removing the wrapper fails row-structure tests; changing its reserved width requires source/layout review      | `audit:Selector/design-rendered` |
-| FR4, AR1, AR2         | presentation tests plus `aria-haspopup` source review                                      | pointer, compact coarse pointer, search/non-search                | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility`   |
-| FR5                   | loading, empty-state, and live-region tests                                                | empty options, unmatched search, loading                          | Empty/no-results output appears or is announced while loading                                                  | `audit:Selector/behavior`        |
-| FR6, AR4              | read-only interaction, form, ARIA, and theme-state tests                                   | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent    | `audit:Selector/accessibility`   |
-| source-build contract | `Selector.source-build.test.mjs`                                                           | package source compiled by consumer Babel                         | Moving evaluated StyleX values outside the supported source form fails compilation                             | `audit:Selector/code-health`     |
+| Contract              | Verification                                                                                             | Representative states                                                                   | Mutation or failure expectation                                                                                                         | Audit section                    |
+| --------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, AR2, AR3         | `Selector.test.tsx` selection, focus, and keyboard suites                                                | closed/open, search/non-search, disabled option                                         | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests                                       | `audit:Selector/behavior`        |
+| FR2                   | placement and selected-item geometry tests                                                               | default, explicit, RTL, transformed entry                                               | Using the wrong positioning model fails the expected position-area or margin                                                            | `audit:Selector/behavior`        |
+| FR3, AV1              | `itemMarkColumn` source inspection plus indicator-position and replacement-indicator tests               | start/end, selected/unselected, check/radio                                             | Removing the wrapper fails row-structure tests; changing its reserved width requires source/layout review                               | `audit:Selector/design-rendered` |
+| FR4, AR1, AR2         | presentation tests plus `aria-haspopup` source review                                                    | pointer, compact coarse pointer, search/non-search                                      | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review                          | `audit:Selector/accessibility`   |
+| AR1, AV2              | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates; the exact unnamed no-search sheet state remains known debt | `audit:Selector/accessibility`   |
+| FR5                   | loading, empty-state, and live-region tests                                                              | empty options, unmatched search, loading                                                | Empty/no-results output appears or is announced while loading                                                                           | `audit:Selector/behavior`        |
+| FR6, AR4              | read-only interaction, form, ARIA, and theme-state tests                                                 | search/non-search, clearable, open→read-only, disabled precedence                       | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent                             | `audit:Selector/accessibility`   |
+| source-build contract | `Selector.source-build.test.mjs`                                                                         | package source compiled by consumer Babel                                               | Moving evaluated StyleX values outside the supported source form fails compilation                                                      | `audit:Selector/code-health`     |
 
 ## Decision log
 

package/src/Selector/Selector.tsx

@@ -102,9 +102,14 @@ const styles = stylex.create({
     paddingBlock: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-3'],
     fontFamily: typographyVars['--font-family-body'],
+    // The 16px floor is iOS-only: iOS Safari zooms the page when a focused
+    // control sits under 16px, and only iOS WebKit implements
+    // -webkit-touch-callout to key the coarse-pointer floor to it.
     fontSize: {
       default: typeScaleVars['--text-label-size'],
-      '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      '@media (pointer: coarse)': {
+        '@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+      },
     },
     // A FIXED line box, not the ratio: the trigger's padding is derived from
     // one line being `--spacing-5` tall, and a ratio makes the line box track

package/src/Selector/__tests__/Listbox.a11y.chromium.spec.ts

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.chromium.spec.ts
+ * @input Uses the Listbox contract, browser harness, state inventory, and checked-in stories
+ * @output DOM/accessibility-tree evidence for each real Listbox binding part
+ * @position Browser binding; keyboard policy, pixels, and real AT remain separate owners.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  LISTBOX_PATTERN,
+  checkAccessibilitySpec,
+  blockingResults,
+  formatFailures,
+  formatReport,
+  summarize,
+  neverExercised,
+  unmatchedKnownFailures,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {
+  createChromiumHarness,
+  holdMotionStill,
+} from '@astryxdesign/a11y-spec/chromium';
+import {
+  serveStorybook,
+  DEFAULT_STORYBOOK_DIR,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+import {LISTBOX_KNOWN_FAILURES} from './Listbox.a11y.known-failures';
+import {LISTBOX_SCENARIOS, listboxParts} from './Listbox.a11y.states';
+
+let storybook: StaticServer;
+const observedResults: BindingResult[] = [];
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+  expect(
+    unmatchedKnownFailures(LISTBOX_KNOWN_FAILURES, observedResults),
+  ).toEqual([]);
+});
+
+for (const scenario of LISTBOX_SCENARIOS) {
+  test(`${scenario.component} — ${scenario.id}`, async ({page}) => {
+    test.setTimeout(2 * 60 * 1000);
+    const cdp = await page.context().newCDPSession(page);
+    const results: BindingResult[] = [];
+    const mount = async () => {
+      await page.goto(
+        `${storybook.origin}/iframe.html?id=a11y-listbox-pattern--${scenario.id}&viewMode=story&globals=direction:${scenario.direction ?? 'ltr'}`,
+        {waitUntil: 'load'},
+      );
+      await holdMotionStill(page);
+      await expect(
+        page.locator(`[data-listbox-scenario="${scenario.id}"]`),
+      ).toBeAttached();
+      await page.getByRole('listbox').waitFor({state: 'visible'});
+      if (scenario.query != null) {
+        await page.getByRole('combobox').fill(scenario.query);
+      }
+      await expect(page.getByRole('listbox').getByRole('option')).toHaveCount(
+        scenario.expectedOptions.length,
+      );
+    };
+
+    for (const part of listboxParts(scenario)) {
+      results.push(
+        await checkAccessibilitySpec({
+          spec: LISTBOX_PATTERN,
+          binding: `${scenario.component}.${part.role}`,
+          state: part.state,
+          facts: part.facts,
+          knownFailures: LISTBOX_KNOWN_FAILURES,
+          mount: async () => {
+            await mount();
+            const listbox = page.getByRole('listbox');
+            const subject =
+              part.role === 'listbox'
+                ? listbox
+                : part.role === 'group'
+                  ? listbox
+                      .getByRole('group')
+                      .nth(scenario.groups.indexOf(part.name ?? ''))
+                  : listbox.getByRole('option', {
+                      name: part.name,
+                      exact: true,
+                    });
+            return createChromiumHarness({
+              page,
+              cdp,
+              subject,
+              related: {
+                listbox,
+                ...Object.fromEntries(
+                  scenario.expectedOptions.map(option => [
+                    `option:${option.value}`,
+                    listbox.getByRole('option', {
+                      name: option.name,
+                      exact: true,
+                    }),
+                  ]),
+                ),
+                ...Object.fromEntries(
+                  scenario.groups.map((name, index) => [
+                    `group:${name}`,
+                    listbox.getByRole('group').nth(index),
+                  ]),
+                ),
+              },
+            });
+          },
+        }),
+      );
+    }
+
+    observedResults.push(...results);
+    const report = summarize(LISTBOX_PATTERN, results);
+    console.log(formatReport(report));
+    expect(formatFailures(blockingResults(results))).toBe('');
+    expect(report.counts.unrun).toBe(0);
+    if (scenario.component === 'Selector' && scenario.groups.length > 0) {
+      expect(neverExercised(results)).toEqual([]);
+    }
+  });
+}

package/src/Selector/__tests__/Listbox.a11y.dom.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.dom.ts
+ * @input Uses Vitest lifecycle hooks and the DOM Dialog prototype
+ * @output Scoped stubs for Dialog methods missing from jsdom
+ * @position DOM-only binding setup; these stubs prove no native modal behavior.
+ */
+
+import {afterAll, beforeAll} from 'vitest';
+
+export function installListboxDialogStubs(): void {
+  const originals = new Map<string, PropertyDescriptor | undefined>();
+  beforeAll(() => {
+    for (const name of ['show', 'showModal', 'close']) {
+      originals.set(
+        name,
+        Object.getOwnPropertyDescriptor(HTMLDialogElement.prototype, name),
+      );
+      Object.defineProperty(HTMLDialogElement.prototype, name, {
+        configurable: true,
+        writable: true,
+        value: function (this: HTMLDialogElement) {
+          this.open = name !== 'close';
+        },
+      });
+    }
+  });
+  afterAll(() => {
+    for (const [name, descriptor] of originals) {
+      if (descriptor == null) {
+        Reflect.deleteProperty(HTMLDialogElement.prototype, name);
+      } else {
+        Object.defineProperty(HTMLDialogElement.prototype, name, descriptor);
+      }
+    }
+  });
+}

package/src/Selector/__tests__/Listbox.a11y.inventory.test.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.inventory.test.ts
+ * @input Uses the locked Listbox migration matrix and checklist
+ * @output Coverage-boundary and part-inventory regression checks
+ * @position Binding metadata proof, separate from runtime conformance results.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {LISTBOX_PATTERN, unansweredDimensions} from '@astryxdesign/a11y-spec';
+import {LISTBOX_KNOWN_FAILURES} from './Listbox.a11y.known-failures';
+import {
+  LISTBOX_SCENARIOS,
+  LISTBOX_EXCLUSIONS,
+  listboxParts,
+} from './Listbox.a11y.states';
+
+describe('Listbox migration inventory', () => {
+  it('accounts for every checklist dimension without claiming other evidence layers', () => {
+    expect(unansweredDimensions(LISTBOX_PATTERN)).toEqual([]);
+    expect(LISTBOX_EXCLUSIONS).toHaveLength(5);
+  });
+
+  it('binds 21 scenarios and all six real semantic parts', () => {
+    expect(LISTBOX_SCENARIOS).toHaveLength(21);
+    const parts = LISTBOX_SCENARIOS.flatMap(scenario =>
+      listboxParts(scenario).map(part => ({
+        binding: `${scenario.component}.${part.role}`,
+        state: part.state,
+      })),
+    );
+    expect(parts).toHaveLength(89);
+    expect(new Set(parts.map(part => part.state)).size).toBe(89);
+    expect([...new Set(parts.map(part => part.binding))].sort()).toEqual([
+      'MultiSelector.group',
+      'MultiSelector.listbox',
+      'MultiSelector.option',
+      'Selector.group',
+      'Selector.listbox',
+      'Selector.option',
+    ]);
+  });
+
+  it('pins each known failure to one exact inventory part', () => {
+    const parts = LISTBOX_SCENARIOS.flatMap(scenario =>
+      listboxParts(scenario).map(part => ({
+        binding: `${scenario.component}.${part.role}`,
+        state: part.state,
+      })),
+    );
+
+    expect(LISTBOX_KNOWN_FAILURES).toHaveLength(2);
+    for (const record of LISTBOX_KNOWN_FAILURES) {
+      expect(
+        parts.filter(
+          part =>
+            part.binding === record.binding && part.state === record.state,
+        ),
+      ).toHaveLength(1);
+    }
+  });
+});

package/src/Selector/__tests__/Listbox.a11y.known-failures.ts

@@ -0,0 +1,37 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Listbox.a11y.known-failures.ts
+ * @input Uses KnownFailure from @astryxdesign/a11y-spec
+ * @output Exact public-safe Selector and MultiSelector listbox migration failures
+ * @position AST-021 debt records; operational ownership remains outside public source.
+ */
+
+import type {KnownFailure} from '@astryxdesign/a11y-spec';
+
+export const LISTBOX_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
+  {
+    expectation: 'listbox.exposure.identity',
+    binding: 'Selector.listbox',
+    state: 'single-sheet:listbox',
+    evidenceLayer: 'accessibility-tree',
+    failureEquals: 'the browser exposes the listbox without an accessible name',
+    standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+    userImpact:
+      'An accessibility consumer encounters an unnamed listbox in the bottom-sheet presentation and cannot identify what set of choices it contains.',
+    reason:
+      'The no-search bottom-sheet presentation renders a visible sheet heading without assigning that heading, or another label, as the listbox accessible name. This migration records the existing behavior without changing the component.',
+  },
+  {
+    expectation: 'listbox.exposure.identity',
+    binding: 'MultiSelector.listbox',
+    state: 'multiple-sheet:listbox',
+    evidenceLayer: 'accessibility-tree',
+    failureEquals: 'the browser exposes the listbox without an accessible name',
+    standardsReference: 'WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
+    userImpact:
+      'An accessibility consumer encounters an unnamed multi-select listbox in the bottom-sheet presentation and cannot identify what set of choices it contains.',
+    reason:
+      'The no-search bottom-sheet presentation renders a visible sheet heading without assigning that heading, or another label, as the listbox accessible name. This migration records the existing behavior without changing the component.',
+  },
+];