@astryxdesign/core 0.6.1 → 0.6.2-canary.0faf070

package/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts

@@ -0,0 +1,344 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetKeyboard.a11y.browser.spec.ts
+ * @input Built BottomSheet stories and real Chromium/WebKit keyboard input
+ * @output Browser evidence for shared focus delegation, traversal, and native scrolling
+ * @position Cross-browser proof for useScrollableArea's contentOrViewport policy
+ */
+
+import {expect, test, type Page, type Locator} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+// macOS WebKit defaults to text-field traversal. Option+Tab selects its native
+// all-controls traversal, equivalent to enabling Safari's keyboard preference.
+function tabKey(browserName: string, reverse = false): string {
+  return `${browserName === 'webkit' && process.platform === 'darwin' ? 'Alt+' : ''}${reverse ? 'Shift+' : ''}Tab`;
+}
+
+async function mount(page: Page, browserName: string, variant = 'button') {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-bottomsheet--keyboard-delegation&viewMode=story`,
+  );
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  await page.getByLabel('Content case').selectOption(variant);
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+  // WebKit includes the non-modal dialog host in sequential navigation;
+  // Chromium enters its descendants directly. Start immediately before the body.
+  const before =
+    browserName === 'webkit'
+      ? page.getByRole('dialog', {name: 'Keyboard reading', exact: true})
+      : page.getByRole('button', {name: 'Toggle modal', exact: true});
+  await before.focus();
+  return {viewport, before};
+}
+
+for (const variant of ['button', 'link']) {
+  test(`${variant}: forward entry delegates once and reverse traversal exits`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    const first = page.getByRole(variant === 'button' ? 'button' : 'link', {
+      name: variant === 'button' ? 'First action' : 'First link',
+      exact: true,
+    });
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await expect(first).toHaveAccessibleName(
+      variant === 'button' ? 'First action' : 'First link',
+    );
+    await page.keyboard.press(tabKey(browserName));
+    await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(first).toBeFocused();
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+    await expect(viewport).toHaveAttribute('tabindex', '0');
+    await page.keyboard.press(tabKey(browserName));
+    await expect(first).toBeFocused();
+  });
+}
+
+for (const variant of [
+  'text',
+  'input',
+  'disabled',
+  'nested',
+  'native-scroll',
+  'radiogroup',
+  'slider',
+  'combobox',
+  'listbox',
+  'menu',
+  'grid',
+  'tree',
+  'tablist',
+  'toolbar',
+]) {
+  test(`${variant}: retains a named viewport stop`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport, before} = await mount(page, browserName, variant);
+    await page.keyboard.press(tabKey(browserName));
+    await expect(viewport).toBeFocused();
+    await expect(viewport).toHaveAccessibleName('Keyboard reading');
+    await page.keyboard.press(tabKey(browserName, true));
+    await expect(before).toBeFocused();
+  });
+}
+
+async function scrollRange(viewport: Locator) {
+  return viewport.evaluate(element => ({
+    position: element.scrollTop,
+    max: element.scrollHeight - element.clientHeight,
+  }));
+}
+
+for (const key of ['PageDown', 'ArrowDown']) {
+  test(`${key}: reaches both scroll edges after delegation`, async ({
+    page,
+    browserName,
+  }) => {
+    const {viewport} = await mount(page, browserName);
+    await page.keyboard.press(tabKey(browserName));
+    const first = page.getByRole('button', {name: 'First action', exact: true});
+    await expect(first).toBeFocused();
+    for (let count = 0; count < 300; count++) {
+      const {position, max} = await scrollRange(viewport);
+      if (position >= max - 1) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: key === 'ArrowDown' ? 50 : 25});
+    }
+    await expect
+      .poll(async () => {
+        const {position, max} = await scrollRange(viewport);
+        // WebKit can overshoot a native edge while showing rubber-band feedback.
+        return max - position;
+      })
+      .toBeLessThanOrEqual(1);
+    for (let count = 0; count < 300; count++) {
+      if ((await scrollRange(viewport)).position <= 1) {
+        break;
+      }
+      await page.keyboard.press(key === 'PageDown' ? 'PageUp' : 'ArrowUp', {
+        delay: key === 'ArrowDown' ? 50 : 25,
+      });
+    }
+    await expect
+      .poll(async () => (await scrollRange(viewport)).position)
+      .toBeLessThanOrEqual(1);
+    await expect(first).toBeFocused();
+  });
+}
+
+test('pointer and programmatic focus stay on the viewport, including during keydown', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.focus();
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await viewport.click({position: {x: 4, y: 40}});
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await before.evaluate(element => {
+    element.addEventListener('keydown', event => {
+      if (event instanceof KeyboardEvent && event.key === 'Tab') {
+        event.preventDefault();
+        document
+          .querySelector<HTMLElement>(
+            '[role="group"][aria-label="Keyboard reading"]',
+          )
+          ?.focus();
+      }
+    });
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('dynamic eligibility is checked at the next entry without mutation observation', async ({
+  page,
+  browserName,
+}) => {
+  await page.addInitScript(() => {
+    const Original = window.MutationObserver;
+    const observers: MutationObserver[] = [];
+    window.MutationObserver = class extends Original {
+      constructor(callback: MutationCallback) {
+        super(callback);
+        observers.push(this);
+      }
+    };
+    Object.assign(window, {
+      stopMutationObservers: () =>
+        observers.forEach(observer => observer.disconnect()),
+    });
+  });
+  const {viewport, before} = await mount(page, browserName);
+  await page.evaluate(() => {
+    (
+      window as unknown as {stopMutationObservers: () => void}
+    ).stopMutationObservers();
+  });
+  await viewport.focus();
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await first.evaluate(element => element.setAttribute('disabled', ''));
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(page.getByRole('button', {name: 'Last action'})).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.removeAttribute('disabled'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    const input = document.createElement('input');
+    input.setAttribute('aria-label', 'Inserted input');
+    element.prepend(input);
+  });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+  await page.getByLabel('Inserted input').evaluate(element => element.remove());
+  await expect(viewport).toBeFocused();
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(first).toBeFocused();
+  await before.focus();
+  await first.evaluate(element => element.setAttribute('role', 'combobox'));
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});
+
+test('modal BottomSheet keeps native focus containment without cycling through the viewport', async ({
+  page,
+  browserName,
+}) => {
+  await mount(page, browserName);
+  await page.getByRole('button', {name: 'Toggle modal', exact: true}).click();
+  const dialog = page.getByRole('dialog', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect
+    .poll(async () => dialog.evaluate(element => element.matches(':modal')))
+    .toBe(true);
+  const viewport = page.getByRole('group', {
+    name: 'Keyboard reading',
+    exact: true,
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+  const panel = dialog.locator('.astryx-bottom-sheet');
+  await panel.focus();
+  await page.keyboard.press(tabKey(browserName));
+  const first = page.getByRole('button', {name: 'First action', exact: true});
+  await expect(first).toBeFocused();
+  await page.keyboard.press(tabKey(browserName, true));
+  await expect(viewport).not.toBeFocused();
+  await expect(first).not.toBeFocused();
+  // Native dialog traversal may wrap to another sheet target or browser chrome;
+  // it must never focus the inert background or create a viewport/child loop.
+  await expect(
+    page.getByRole('button', {name: 'Before sheet', includeHidden: true}),
+  ).not.toBeFocused();
+  await expect(viewport).toHaveAttribute('tabindex', '0');
+});
+
+test('fitting text removes the viewport stop while preserving current focus', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName, 'text');
+  await viewport.focus();
+  await viewport.locator('[data-scroll-content]').evaluate(element => {
+    element.textContent = 'Short reading content';
+  });
+  await expect(viewport).not.toHaveAttribute('data-scrollable-block', 'true');
+  await expect(viewport).toHaveAttribute('tabindex', '-1');
+  await expect(viewport).toBeFocused();
+});
+
+test('horizontal overflow remains keyboard scrollable after delegation', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport, before} = await mount(page, browserName);
+  await viewport.evaluate(element => {
+    const content = element.querySelector<HTMLElement>('[data-scroll-content]');
+    if (content != null) {
+      content.style.width = `${element.clientWidth + 320}px`;
+    }
+  });
+  await expect(viewport).toHaveAttribute('data-scrollable-inline', 'true');
+  await before.focus();
+  await page.keyboard.press(tabKey(browserName));
+  await expect(
+    page.getByRole('button', {name: 'First action', exact: true}),
+  ).toBeFocused();
+  for (const key of ['ArrowRight', 'ArrowLeft']) {
+    for (let count = 0; count < 100; count++) {
+      const atEdge = await viewport.evaluate(
+        (element, forward) =>
+          forward
+            ? element.scrollLeft >=
+              element.scrollWidth - element.clientWidth - 1
+            : element.scrollLeft <= 1,
+        key === 'ArrowRight',
+      );
+      if (atEdge) {
+        break;
+      }
+      await page.keyboard.press(key, {delay: 50});
+    }
+    await expect
+      .poll(async () =>
+        viewport.evaluate(
+          (element, forward) =>
+            forward
+              ? element.scrollWidth - element.clientWidth - element.scrollLeft
+              : element.scrollLeft,
+          key === 'ArrowRight',
+        ),
+      )
+      .toBeLessThanOrEqual(1);
+  }
+});
+
+test('does not skip an aria-hidden first tab stop to delegate to a later action', async ({
+  page,
+  browserName,
+}) => {
+  const {viewport} = await mount(page, browserName);
+  await page
+    .getByRole('button', {name: 'First action', exact: true})
+    .evaluate(element => {
+      element.setAttribute('aria-hidden', 'true');
+    });
+  await page.keyboard.press(tabKey(browserName));
+  await expect(viewport).toBeFocused();
+});

package/src/Button/__tests__/Button.a11y.chromium.spec.ts

@@ -21,7 +21,13 @@
  *   ./Button.a11y.known-failures.ts, both shared with the jsdom lane.
  */
 
-import {expect, test, type CDPSession, type Page} from '@playwright/test';
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
 import {
   BUTTON_PATTERN,
   blockingResults,
@@ -93,6 +99,14 @@ async function activationsOn(page: Page): Promise<number> {
   return Number(raw ?? '0');
 }
 
+function pointerTargetFor(
+  page: Page,
+  state: ButtonBindingRow,
+): Locator | undefined {
+  const selector = (state as ButtonBindingState).pointerTargetSelector;
+  return selector == null ? undefined : page.locator(selector).first();
+}
+
 async function runState(
   page: Page,
   cdp: CDPSession,
@@ -111,6 +125,7 @@ async function runState(
       return createChromiumHarness({
         page,
         subject: page.locator('#storybook-root').getByRole('button').first(),
+        pointerTarget: pointerTargetFor(page, state),
         cdp,
       });
     },
@@ -306,6 +321,7 @@ test('every expectation is exercised by at least one bound state', async ({
               .locator('#storybook-root')
               .getByRole('button')
               .first(),
+            pointerTarget: pointerTargetFor(page, state),
             cdp,
           });
         },

package/src/Button/__tests__/Button.a11y.known-failures.ts

@@ -83,33 +83,4 @@ export const BUTTON_KNOWN_FAILURES: ReadonlyArray<KnownFailure> = [
     userImpact: 'The same, from an icon button.',
     reason: 'Inherited from Button, as above.',
   },
-
-  // ---- ClickableCard's role-bearing element cannot be clicked -------------
-  {
-    expectation: 'button.action.survives-an-aborted-press',
-    binding: 'ClickableCard',
-    state: 'clickable-card',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'a pointer press cannot land on this control: something else is on top of it at its own centre, so there is no press here to abort',
-    standardsReference: 'WCAG 2.2 2.5.2 Pointer Cancellation (Level A)',
-    userImpact:
-      'The same defect seen from the other side: pointer cancellation cannot be demonstrated on a control no pointer press can land on. Recorded rather than reported green — a serene pass here would claim an outcome nobody observed.',
-    reason:
-      'Same cause as the record above. It is a second record rather than a wider one because a known failure names exactly one outcome, and these two would be fixed and verified separately.',
-  },
-  {
-    expectation: 'button.action.runs-on-pointer',
-    binding: 'ClickableCard',
-    state: 'clickable-card',
-    evidenceLayer: 'real-browser',
-    failureEquals:
-      'a pointer could not reach this control within 2000ms: the browser never found it visible, stable, and able to receive a pointer event. Something is covering it, or it is clipped to nothing.',
-    standardsReference:
-      'Current Astryx buttons family FR2 and WAI-ARIA APG Button operability requirement; supports WCAG 2.2 4.1.2 Name, Role, Value (Level A)',
-    userImpact:
-      "Anyone whose tooling acts on the accessible object rather than on pixels — a speech-input user saying the card's name, or assistive technology dispatching a click at the element it is told is the button — aims at a 1×1 control the card's own content paints over. A sighted mouse user is unaffected: they click the card surface, which handles it.",
-    reason:
-      'ClickableCard deliberately splits the surface that takes the click from the hidden button that carries the role and name. Reconciling the two is a design-system decision, not a change this contract should make.',
-  },
 ];

package/src/Button/__tests__/Button.a11y.renders.tsx

@@ -88,12 +88,19 @@ export const BUTTON_STATE_RENDERS: Record<ButtonStateId, StateRender> = {
   ),
 
   'clickable-card': activate => (
-    <ClickableCard label="Open billing settings" onClick={activate}>
+    <ClickableCard
+      data-a11y-pointer-target
+      label="Open billing settings"
+      onClick={activate}>
       <div>Billing</div>
     </ClickableCard>
   ),
   'clickable-card-disabled': activate => (
-    <ClickableCard label="Open billing settings" isDisabled onClick={activate}>
+    <ClickableCard
+      data-a11y-pointer-target
+      label="Open billing settings"
+      isDisabled
+      onClick={activate}>
       <div>Billing</div>
     </ClickableCard>
   ),

package/src/Button/__tests__/Button.a11y.states.ts

@@ -92,6 +92,13 @@ export interface ButtonBindingState {
    * typo here is reported as a stale inventory, not as a standards failure.
    */
   readonly visibleLabel: string | null;
+  /**
+   * The surface that receives pointer input when it is not the role-bearing
+   * element. ClickableCard keeps its button/link hidden for role, name, and
+   * keyboard focus, and takes the pointer on the card surface; a binding that
+   * aimed the pointer at the hidden control would be testing the wrong surface.
+   */
+  readonly pointerTargetSelector?: string;
   /** The checked-in Storybook story the Chromium lane drives. */
   readonly storyId: string;
   /**
@@ -220,6 +227,7 @@ export const BUTTON_BINDING_STATES = [
       "a card whose whole surface performs an action, through the hidden button that carries the card's role and name",
     facts: facts(),
     visibleLabel: null,
+    pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-button-pattern--clickable-card-default',
   },
   {
@@ -228,6 +236,7 @@ export const BUTTON_BINDING_STATES = [
     summary: 'a disabled action card',
     facts: facts({operable: false, focusable: false, unavailable: true}),
     visibleLabel: null,
+    pointerTargetSelector: '[data-a11y-pointer-target]',
     storyId: 'a11y-button-pattern--clickable-card-disabled',
   },
 

package/src/CheckboxInput/CheckboxInput.doc.mjs

@@ -137,6 +137,17 @@ export const docs = {
     ],
   },
   usage: {
+    accessibility: [
+      {
+        name: 'Checkbox box',
+        category: 'Color contrast',
+        criterion: '1.4.11 Non-text Contrast',
+        requirement: '3:1',
+        states: ['Rest', 'Hover', 'Pointer down', 'Checked'],
+        description:
+          'The box edge (unchecked) and fill (checked) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied.',
+      },
+    ],
     description: 'CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.',
     bestPractices: [
       { guidance: true, description: 'Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.' },

package/src/CheckboxInput/CheckboxInput.test.tsx

@@ -15,6 +15,7 @@
 import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {CheckboxInput} from './CheckboxInput';
 import {Theme} from '../theme/Theme';
 import {defineTheme} from '../theme/defineTheme';
@@ -763,3 +764,36 @@ describe('label theme target', () => {
     expect(label).toHaveClass('astryx-checkbox-label');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay over the indicator while the row is pressed', () => {
+    const {container} = render(
+      <CheckboxInput label="Accept terms" value={false} onChange={() => {}} />,
+    );
+    const box = container.querySelector('.astryx-checkbox-indicator');
+    const wrapper = box?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the checkbox has no indicator wrapper to press');
+    }
+    // The owner paints over the resolved indicator, so the treatment survives a
+    // theme replacement that does not forward style props.
+    expect(hasPressedArm(wrapper)).toBe(true);
+  });
+
+  it('does not expose a pressed arm on a disabled checkbox', () => {
+    const {container} = render(
+      <CheckboxInput
+        label="Unavailable"
+        value={false}
+        onChange={() => {}}
+        isDisabled
+      />,
+    );
+    const box = container.querySelector('.astryx-checkbox-indicator');
+    const wrapper = box?.parentElement?.parentElement;
+    if (wrapper == null) {
+      throw new Error('the checkbox has no indicator wrapper');
+    }
+    expect(hasPressedArm(wrapper)).toBe(false);
+  });
+});

package/src/CheckboxInput/CheckboxInput.tsx

@@ -70,6 +70,22 @@ const styles = stylex.create({
     flexShrink: 0,
     isolation: 'isolate',
   },
+  // The owner paints this layer over the resolved indicator, so a theme
+  // replacement cannot accidentally drop the component's pressed contract.
+  indicatorPressOverlay: {
+    '::after': {
+      content: '""',
+      position: 'absolute',
+      inset: 0,
+      borderRadius: radiusVars['--radius-inner'],
+      pointerEvents: 'none',
+      backgroundColor: {
+        default: 'transparent',
+        [stylex.when.ancestor(':active', indicatorScope)]:
+          colorVars['--color-overlay-pressed'],
+      },
+    },
+  },
   // Holds only the indicator, so the focus ring has one unambiguous target.
   // `display: contents` adds no box of its own — the indicator keeps whatever
   // layout relationship it already had with the wrapper.
@@ -399,7 +415,11 @@ export function CheckboxInput({
           !isDisabled && indicatorScope,
         )}>
         <div
-          {...stylex.props(styles.checkboxWrapper, wrapperSizeStyles[size])}
+          {...stylex.props(
+            styles.checkboxWrapper,
+            wrapperSizeStyles[size],
+            !isDisabled && styles.indicatorPressOverlay,
+          )}
           {...focusProps}>
           <input
             {...rest}