@astryxdesign/core 0.6.0 → 0.6.1

package/src/FieldStatus/__tests__/StatusMessage.a11y.test.tsx

@@ -0,0 +1,155 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file StatusMessage.a11y.test.tsx
+ * @input Uses the shared status-message contract and current Core binding render map
+ * @output Component-facing jsdom evidence through expectAccessibilitySpec
+ * @position Fast migration lane; browser-owned outcomes remain explicitly unrun
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import {
+  STATUS_MESSAGE_PATTERN,
+  expectAccessibilitySpec,
+} from '@astryxdesign/a11y-spec';
+import {__resetLiveRegionsForTest} from '../../hooks/useAnnounce';
+import {CORE_STATUS_MESSAGE_KNOWN_FAILURES} from './StatusMessage.a11y.known-failures';
+import {
+  CORE_STATUS_MESSAGE_STATE_RENDERS,
+  transitionTestId,
+} from './StatusMessage.a11y.renders';
+import {
+  CORE_STATUS_MESSAGE_BINDING_STATES,
+  CORE_STATUS_MESSAGE_EXCLUSIONS,
+  type CoreStatusMessageBindingState,
+} from './StatusMessage.a11y.states';
+
+async function twoFrames(): Promise<void> {
+  await new Promise<void>(resolve => {
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+  });
+}
+
+async function renderState(
+  state: CoreStatusMessageBindingState,
+): Promise<void> {
+  render(CORE_STATUS_MESSAGE_STATE_RENDERS[state.id]());
+  await waitFor(() =>
+    expect(document.querySelector('[data-a11y-ready="true"]')).not.toBeNull(),
+  );
+}
+
+function subjectFor(state: CoreStatusMessageBindingState): Element {
+  const facts = state.facts;
+  const role = facts.kind === 'progressbar' ? 'progressbar' : facts.role;
+  if (role == null) {
+    throw new Error(
+      `${state.id}: this component binding declares no public role`,
+    );
+  }
+  const matches =
+    facts.kind === 'progressbar'
+      ? screen.getAllByRole(role, {hidden: true, name: facts.name})
+      : facts.messageSource === 'accessible-name'
+        ? screen.getAllByRole(role, {
+            hidden: true,
+            name: facts.initialMessage,
+          })
+        : screen
+            .getAllByRole(role, {hidden: true})
+            .filter(
+              element =>
+                (element.textContent ?? '').replace(/\s+/g, ' ').trim() ===
+                facts.initialMessage,
+            );
+  if (matches.length !== 1) {
+    throw new Error(
+      `${state.id}: expected one ${role} subject in initial state, found ${matches.length}`,
+    );
+  }
+  return matches[0];
+}
+
+async function transition(name: string): Promise<void> {
+  fireEvent.click(screen.getByTestId(transitionTestId(name)));
+  await act(twoFrames);
+}
+
+function reset(): void {
+  cleanup();
+  __resetLiveRegionsForTest();
+}
+
+afterEach(reset);
+
+describe('Core status-message bindings — jsdom lane', () => {
+  it.each(
+    CORE_STATUS_MESSAGE_BINDING_STATES.map(
+      state =>
+        [`${state.binding} [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: STATUS_MESSAGE_PATTERN,
+      binding: state.binding,
+      state: state.id,
+      facts: state.facts,
+      knownFailures: CORE_STATUS_MESSAGE_KNOWN_FAILURES,
+      render: async () => renderState(state),
+      subject: () => subjectFor(state),
+      transition,
+      cleanup: reset,
+    });
+  });
+});
+
+describe('Core status-message binding inventory', () => {
+  it('names a distinct checked-in story for every bound state', () => {
+    const stories = CORE_STATUS_MESSAGE_BINDING_STATES.map(
+      state => state.storyId,
+    );
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('binds every named Core status-message owner', () => {
+    expect(
+      [
+        ...new Set(
+          CORE_STATUS_MESSAGE_BINDING_STATES.map(state => state.binding),
+        ),
+      ].sort(),
+    ).toEqual([
+      'ChatSystemMessage',
+      'FieldStatus announcement channel',
+      'ProgressBar',
+      'Spinner',
+      'Toast announcement channel',
+      'Toast card',
+    ]);
+  });
+
+  it('records every adjacent non-status or separately owned surface explicitly', () => {
+    expect(CORE_STATUS_MESSAGE_EXCLUSIONS.map(entry => entry.part)).toEqual([
+      'visible validation text',
+      'aria-hidden decorative spinner',
+      'date or section separator',
+      'role=log transcript updates',
+      'composer errors and tool-run states',
+      'busy announcement',
+      'focusable target-mark triggers and labels',
+      'visual fill, track, animation, and status cadence',
+    ]);
+    expect(
+      CORE_STATUS_MESSAGE_EXCLUSIONS.every(entry => entry.reason.length > 0),
+    ).toBe(true);
+  });
+});

package/src/FileInput/FileInput.tsx

@@ -589,7 +589,16 @@ export function FileInput({
       onChange(null);
       if (inputRef.current) {
         inputRef.current.value = '';
-        inputRef.current.focus();
+        const targetInput = inputRef.current;
+        if (e.detail === 0) {
+          targetInput.focus();
+        } else {
+          // Defer focus restoration past the button's unmount task so iOS Safari
+          // and touch browsers don't jump the page scroll to 0 on tap.
+          requestAnimationFrame(() => {
+            targetInput.focus({preventScroll: true});
+          });
+        }
       }
     },
     [onChange],

package/src/FormLayout/__snapshots__/FormLayout.test.tsx.snap

@@ -2,7 +2,7 @@
 
 exports[`FormLayout > matches snapshot for horizontal direction 1`] = `
 <div
-  class="astryx-form-layout FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"
+  class="astryx-form-layout horizontal FormLayout__styles.base xdt5ytf x18g69wz FormLayout__styles.horizontal xrvj5dj x1mt1orb xu6a5m6"
   data-direction="horizontal"
   data-testid="layout"
 >
@@ -17,7 +17,7 @@ exports[`FormLayout > matches snapshot for horizontal direction 1`] = `
 
 exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `
 <div
-  class="astryx-form-layout FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
+  class="astryx-form-layout horizontal-labels FormLayout__styles.base xdt5ytf FormLayout__styles.horizontalLabels xrvj5dj x1pmbctz xlaq8a2 x7a106z xedohl4 x1rpgqan x1a1jff"
   data-direction="horizontal-labels"
   data-testid="layout"
 >
@@ -32,7 +32,7 @@ exports[`FormLayout > matches snapshot for horizontal-labels direction 1`] = `
 
 exports[`FormLayout > matches snapshot for vertical direction 1`] = `
 <div
-  class="astryx-form-layout FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
+  class="astryx-form-layout vertical FormLayout__styles.base x78zum5 xdt5ytf x18g69wz"
   data-direction="vertical"
   data-testid="layout"
 >

package/src/HoverCard/HoverCard.doc.mjs

@@ -17,8 +17,8 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-hover-card'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},
     ],
     vars: [
@@ -148,8 +148,8 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-hover-card'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {className: 'astryx-hovercard', deprecatedFor: 'hover-card'},
     ],
     vars: [

package/src/HoverCard/useHoverCard.tsx

@@ -609,8 +609,8 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
       const themeClassName = themeProps('hover-card', undefined, {
-        // `hovercard` ran the compound name together; themes styling it keep
-        // working until the next major.
+        // `hovercard` ran the compound name together; keep it emitted so
+        // existing themes continue to work.
         legacyNames: ['hovercard'],
       }).className;
       const renderProps = {

package/src/Indicator/CheckboxIndicator.tsx

@@ -206,8 +206,8 @@ export function CheckboxIndicator({
                 : null,
             disabled: isDisabled ? 'disabled' : null,
           },
-          // `checkbox` was the target before indicators existed; themes
-          // styling it keep working until the next major.
+          // `checkbox` was the target before indicators existed; keep it
+          // emitted so existing themes continue to work.
           {legacyNames: ['checkbox']},
         ),
         stylex.props(

package/src/Indicator/Indicator.doc.mjs

@@ -143,8 +143,8 @@ export const docs = {
         states: ['checked', 'disabled'],
       },
       {className: 'astryx-radio-indicator-dot', visualProps: ['size']},
-      // Still emitted beside the names above, so themes written against them
-      // keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {
         className: 'astryx-checkbox',
         visualProps: ['size'],

package/src/Indicator/Indicator.test.tsx

@@ -344,7 +344,7 @@ describe('useIndicator', () => {
  * A theme target is public API. Renaming one to follow the
  * `<component>-kebab` convention (`checkbox` → `checkbox-indicator`) would
  * silently break every theme styling the old name — the CSS still compiles, it
- * just stops matching. So both names are emitted for a deprecation window, and
+ * just stops matching. So both names remain emitted for compatibility, and
  * these tests pin that promise from both ends: the new name exists, and the
  * old one has not quietly disappeared.
  */

package/src/Indicator/RadioIndicator.tsx

@@ -170,8 +170,8 @@ export function RadioIndicator({
             checked: isChecked ? 'checked' : null,
             disabled: isDisabled ? 'disabled' : null,
           },
-          // `radio` was the target before indicators existed; themes styling
-          // it keep working until the next major.
+          // `radio` was the target before indicators existed; keep it emitted
+          // so existing themes continue to work.
           {legacyNames: ['radio']},
         ),
         stylex.props(

package/src/Layer/layerStack.ts

@@ -6,7 +6,8 @@
  * @file layerStack.ts
  * @input Uses the isImeKeyEvent predicate from utils/ime
  * @output Exports the shared layer dismissal stack: registration, top-most
- *   ordering, and the single document-level Escape listener
+ *   ordering, the document-level Escape listener, and its internal local-event
+ *   dispatcher
  * @position Internal to the Layer system; consumed by useLayerDismissal, which
  *   is what overlays actually call. Not exported from the package root.
  *
@@ -34,11 +35,12 @@
  * ## Bubble phase, not capture
  *
  * The listener is on the BUBBLE phase so content inside a layer can claim the
- * press first, either by `stopPropagation()` (the press never reaches us) or by
- * `preventDefault()` (we see it and stand down). Editors are the motivating
- * case: Monaco and the rich-text editor use Escape to close their own find
- * widget or autocomplete, and that must win over dismissing the Dialog they sit
- * in. A capture-phase listener would take the press away from them.
+ * press first, either by `stopPropagation()` (the press never reaches the
+ * document listener) or by `preventDefault()` (we see it and stand down).
+ * A host whose public event prop can stop propagation may route the still-
+ * unprevented event through `dispatchLayerEscapeKeyDown` at its own boundary;
+ * the same stack still chooses the owner. Editors are why `preventDefault()`
+ * remains the explicit cancellation signal: their own Escape action must win.
  *
  * ## The stack, not the browser, decides
  *
@@ -275,7 +277,16 @@ function dispatchEscape(): boolean {
   return true;
 }
 
-function handleKeyDown(event: KeyboardEvent): void {
+/**
+ * Resolve a keydown through the shared stack immediately.
+ *
+ * The document listener is the normal path. A host may call this at its own
+ * element boundary after a consumer handler when that handler can stop
+ * propagation before the event reaches `document`. The same stack still picks
+ * the owner, and `preventDefault()` records the decision so a bubbling event is
+ * not handled twice.
+ */
+export function dispatchLayerEscapeKeyDown(event: KeyboardEvent): void {
   if (event.key !== 'Escape') {
     return;
   }
@@ -309,7 +320,7 @@ function startListening(): void {
   if (isListening || typeof document === 'undefined') {
     return;
   }
-  document.addEventListener('keydown', handleKeyDown);
+  document.addEventListener('keydown', dispatchLayerEscapeKeyDown);
   document.addEventListener('compositionstart', handleCompositionStart, true);
   document.addEventListener('compositionend', handleCompositionEnd, true);
   document.addEventListener('blur', handleCompositionEnd, true);
@@ -320,7 +331,7 @@ function stopListening(): void {
   if (!isListening || typeof document === 'undefined') {
     return;
   }
-  document.removeEventListener('keydown', handleKeyDown);
+  document.removeEventListener('keydown', dispatchLayerEscapeKeyDown);
   document.removeEventListener(
     'compositionstart',
     handleCompositionStart,

package/src/Layer/useLayerDismissal.ts

@@ -97,9 +97,8 @@ export interface UseLayerDismissalReturn {
  * The layer does NOT attach a key listener — the stack owns one listener and
  * routes each Escape press to the top-most REGISTERED layer, so one press
  * dismisses exactly one of them. Dialog (and what is built on it), Popover and
- * the menus built on it, Tooltip, HoverCard, Lightbox and MobileNav register
- * today; `BottomSheetSwitcher` registers through its focus trap when modal and
- * still handles its own press when not.
+ * the menus built on it, Tooltip, HoverCard, Lightbox, MobileNav and
+ * BottomSheetSwitcher register today.
  *
  * `BottomSheet`, `CommandPalette`, `ContextMenu`, `DropdownMenuSubMenu`,
  * `PowerSearchEditPopover` and lab's `Drawer` still run their own Escape

package/src/MultiSelector/MultiSelector.test.tsx

@@ -2433,8 +2433,8 @@ describe('MultiSelector clear icon theme target', () => {
     // The canonical target lands on the icon element itself (not the button),
     // so a theme can restyle just this glyph (color, size, hover) via
     // `defineTheme` — a button-level target could not reach the icon's own
-    // color/size. The original per-component name rides along for a
-    // deprecation window.
+    // color/size. The original per-component name remains as a compatibility
+    // alias.
     const icon = getClearIcon();
     expect(icon).toHaveClass('astryx-input-clear-icon');
     expect(icon).toHaveClass('astryx-multi-selector-clear-icon');
@@ -2461,8 +2461,8 @@ describe('MultiSelector clear icon theme target', () => {
   it('routes the clear glyph through the shared clear button, keeping the legacy target', () => {
     // The clear affordance now composes the shared InputClearButton (a ghost
     // Button with a secondary/sm glyph), so the icon carries the canonical
-    // `astryx-input-clear-icon` target and — for a deprecation window — the
-    // original `astryx-multi-selector-clear-icon`. Aside from those target
+    // `astryx-input-clear-icon` target plus the supported compatibility alias
+    // `astryx-multi-selector-clear-icon`. Aside from those target
     // classes it matches the shared button's own `close`/`sm`/`secondary`
     // glyph exactly, so the default look is defined in one place.
     render(

package/src/NavIcon/NavIcon.doc.mjs

@@ -37,8 +37,8 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-nav-icon'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},
     ],
   },
@@ -70,8 +70,8 @@ export const docsZh = {
   theming: {
     targets: [
       {className: 'astryx-nav-icon'},
-      // Still emitted beside the names above, so themes written against
-      // them keep working. Drop in the next major.
+      // Retained beside the canonical names for backwards compatibility.
+      // New themes use the canonical targets above.
       {className: 'astryx-navicon', deprecatedFor: 'nav-icon'},
     ],
   },

package/src/NavIcon/NavIcon.tsx

@@ -80,8 +80,8 @@ export function NavIcon({
       ref={ref}
       {...mergeProps(
         themeProps('nav-icon', undefined, {
-          // `navicon` ran the compound name together; themes styling it keep
-          // working until the next major.
+          // `navicon` ran the compound name together; keep it emitted so
+          // existing themes continue to work.
           legacyNames: ['navicon'],
         }),
         stylex.props(styles.base, xstyle),

package/src/NumberInput/NumberInput.tsx

@@ -829,13 +829,24 @@ export function NumberInput({
   const canDecrement = getNextValue(-1) !== valueForStepping;
 
   // Handle clear button click
-  const handleClear = useCallback(() => {
-    if (hasClear) {
-      onChange(null);
-    }
-    setPendingInput(null);
-    inputRef.current?.focus();
-  }, [hasClear, onChange]);
+  const handleClear = useCallback(
+    (e?: React.MouseEvent<HTMLButtonElement>) => {
+      if (hasClear) {
+        onChange(null);
+      }
+      setPendingInput(null);
+      if (!e || e.detail === 0) {
+        inputRef.current?.focus();
+      } else {
+        // Defer focus restoration past the button's unmount task so iOS Safari
+        // and touch browsers don't jump the page scroll to 0 on tap.
+        requestAnimationFrame(() => {
+          inputRef.current?.focus({preventScroll: true});
+        });
+      }
+    },
+    [hasClear, onChange],
+  );
 
   // Focus input when clicking anywhere on the wrapper (icons, padding, etc.)
   const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =

package/src/Popover/Popover.doc.mjs

@@ -168,8 +168,8 @@ export const docs = {
     targets: [
       // Canonical broad target for the painted Popover surface.
       {className: 'astryx-popover'},
-      // Deprecated compatibility alias. Existing themes keep working during
-      // migration; new themes target `popover`.
+      // Deprecated compatibility alias. Existing themes remain supported;
+      // new themes target `popover`.
       {
         className: 'astryx-popover-surface',
         deprecatedFor: 'popover',
@@ -202,7 +202,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',
+          'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',
       },
       {
         guidance: false,
@@ -231,7 +231,7 @@ export const docs = {
         name: 'Popover surface',
         required: true,
         description:
-          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',
+          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',
       },
       {
         name: 'Popover content',
@@ -371,8 +371,8 @@ export const docsZh = {
     targets: [
       // Canonical broad target for the painted Popover surface.
       {className: 'astryx-popover'},
-      // Deprecated compatibility alias. Existing themes keep working during
-      // migration; new themes target `popover`.
+      // Deprecated compatibility alias. Existing themes remain supported;
+      // new themes target `popover`.
       {
         className: 'astryx-popover-surface',
         deprecatedFor: 'popover',
@@ -405,7 +405,7 @@ export const docsZh = {
       {
         guidance: true,
         description:
-          'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',
+          'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',
       },
       {
         guidance: false,
@@ -434,7 +434,7 @@ export const docsZh = {
         name: 'Popover surface',
         required: true,
         description:
-          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',
+          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',
       },
       {
         name: 'Popover content',
@@ -472,7 +472,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Theme the painted surface through popover. Existing popover-surface overrides remain supported during migration, but new themes should not depend on that deprecated alias.',
+          'Theme the painted surface through popover. Existing popover-surface overrides remain supported for compatibility, while new themes use the canonical target.',
       },
       {
         guidance: false,
@@ -501,7 +501,7 @@ export const docsDense = {
         name: 'Popover surface',
         required: true,
         description:
-          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains only as a deprecated compatibility alias during migration.',
+          'Painted surface owned by Popover. Theme it through the canonical popover target; popover-surface remains supported as a deprecated compatibility alias.',
       },
       {
         name: 'Popover content',