@astryxdesign/core 0.7.3 → 0.7.4-canary.3f6ea7d

package/src/ProgressBar/__tests__/ProgressBar.a11y.test.tsx

@@ -0,0 +1,107 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file ProgressBar.a11y.test.tsx
+ * @input PROGRESSBAR_PATTERN bound to ProgressBar's representative states
+ * @output jsdom-lane proof of the DOM expectations and an honest "unrun" report for the browser layers
+ * @position Binding test for the ProgressBar binding (the Chromium spec covers the rest)
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  PROGRESSBAR_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {PROGRESSBAR_KNOWN_FAILURES} from './ProgressBar.a11y.known-failures';
+import {renderProgressBarState} from './ProgressBar.a11y.renders';
+import {
+  PROGRESSBAR_BINDING_STATES,
+  PROGRESSBAR_EXCLUSIONS,
+  type ProgressBarBindingState,
+} from './ProgressBar.a11y.states';
+
+function progressbar(state: ProgressBarBindingState): HTMLElement {
+  return screen.getByRole('progressbar', {name: state.facts.name});
+}
+
+async function checkState(
+  state: ProgressBarBindingState,
+): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: PROGRESSBAR_PATTERN,
+    binding: 'ProgressBar',
+    state: state.id,
+    facts: state.facts,
+    knownFailures: PROGRESSBAR_KNOWN_FAILURES,
+    mount: async () => {
+      render(renderProgressBarState(state));
+      return createJsdomHarness({subject: progressbar(state), related: {}});
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('ProgressBar — progressbar pattern, jsdom lane', () => {
+  it.each(
+    PROGRESSBAR_BINDING_STATES.map(
+      state => [state.id, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectAccessibilitySpec({
+      spec: PROGRESSBAR_PATTERN,
+      binding: 'ProgressBar',
+      state: state.id,
+      facts: state.facts,
+      knownFailures: PROGRESSBAR_KNOWN_FAILURES,
+      render: () => {
+        render(renderProgressBarState(state));
+      },
+      subject: () => progressbar(state),
+      related: () => ({}),
+      cleanup,
+    });
+  });
+
+  it('runs the DOM layer and reports the browser-owned outcomes as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of PROGRESSBAR_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(PROGRESSBAR_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree']);
+    expect(report.counts.unexpectedPass).toBe(0);
+  });
+});
+
+describe('ProgressBar binding inventory', () => {
+  it('gives every representative state a distinct checked-in story', () => {
+    const stories = PROGRESSBAR_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(stories).size).toBe(stories.length);
+  });
+
+  it('keeps clamping and mark-trigger ownership explicit', () => {
+    expect(PROGRESSBAR_EXCLUSIONS.map(exclusion => exclusion.id)).toEqual([
+      'value-clamping',
+      'mark-trigger',
+    ]);
+    for (const exclusion of PROGRESSBAR_EXCLUSIONS) {
+      expect(exclusion.owner.length, exclusion.id).toBeGreaterThan(20);
+      expect(exclusion.reason.length, exclusion.id).toBeGreaterThan(80);
+    }
+  });
+
+  it('renders exactly one named progress bar for every state', () => {
+    for (const state of PROGRESSBAR_BINDING_STATES) {
+      render(renderProgressBarState(state));
+      expect(progressbar(state), state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});

package/src/Selector/Selector.test.tsx

@@ -253,6 +253,14 @@ function mockSelectorRects({
   };
 }
 
+/** A busy control's Spinner is decorative and silent (spec:AST-086 FR8). */
+function expectSilentBusySpinner() {
+  const spinner = document.querySelector('.astryx-spinner');
+  expect(spinner).not.toBeNull();
+  expect(spinner).toHaveAttribute('aria-hidden', 'true');
+  expect(screen.queryByRole('status', {name: 'Loading'})).toBeNull();
+}
+
 describe('Selector', () => {
   it('uses a bottom sheet and closes after a selection when requested', async () => {
     const user = userEvent.setup();
@@ -1388,7 +1396,7 @@ describe('Selector', () => {
         <Selector label="Fruit" options={[]} onChange={() => {}} isLoading />,
       );
       const trigger = screen.getByRole('combobox', {name: 'Fruit'});
-      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+      expectSilentBusySpinner();
 
       await user.click(trigger);
       expect(trigger).toHaveAttribute('aria-expanded', 'true');
@@ -1404,7 +1412,10 @@ describe('Selector', () => {
       // component cannot make; the trigger's spinner carries the state.
       const listbox = screen.getByRole('listbox', h);
       expect(within(listbox).queryByText('No options')).not.toBeInTheDocument();
-      expect(politeRegion()?.textContent ?? '').toBe('');
+      // Only the busy start is spoken (spec:AST-086 FR8), never an empty or
+      // no-results message the panel is suppressing.
+      // (The channel clears its text on a timer, so it may already be empty.)
+      expect(['', 'Loading']).toContain(politeRegion()?.textContent ?? '');
     });
 
     it('announces nothing while isLoading, matching the silent panel', async () => {
@@ -1437,7 +1448,10 @@ describe('Selector', () => {
       expect(
         within(listbox).queryByText('Nothing like that here'),
       ).not.toBeInTheDocument();
-      expect(politeRegion()?.textContent ?? '').toBe('');
+      // Only the busy start is spoken (spec:AST-086 FR8), never an empty or
+      // no-results message the panel is suppressing.
+      // (The channel clears its text on a timer, so it may already be empty.)
+      expect(['', 'Loading']).toContain(politeRegion()?.textContent ?? '');
     });
 
     it('announces the seeded query from type-to-open', async () => {
@@ -1490,7 +1504,10 @@ describe('Selector', () => {
         async () =>
           void (await new Promise(resolve => requestAnimationFrame(resolve))),
       );
-      expect(politeRegion()?.textContent ?? '').toBe('');
+      // Only the busy start is spoken (spec:AST-086 FR8), never an empty or
+      // no-results message the panel is suppressing.
+      // (The channel clears its text on a timer, so it may already be empty.)
+      expect(['', 'Loading']).toContain(politeRegion()?.textContent ?? '');
 
       // The fetch lands empty while the panel is open. The message appears, so
       // the region owes the same words — an open-only announcement misses this.
@@ -2896,7 +2913,7 @@ describe('Selector', () => {
 
       const trigger = screen.getByRole('combobox', {name: 'Fruit'});
       expect(trigger).toHaveAttribute('aria-busy', 'true');
-      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+      expectSilentBusySpinner();
 
       await user.click(trigger);
       expect(screen.queryByRole('listbox', h)).not.toBeInTheDocument();

package/src/Selector/Selector.tsx

@@ -87,6 +87,7 @@ import {
 } from '../Field/fieldParts';
 import {composeEventHandlers} from '../utils/composeEventHandlers';
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
@@ -1047,6 +1048,9 @@ export function Selector<T extends SelectorOptionType>(
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(normalizedValue);
   const isBusy = isLoading || optimisticValue !== normalizedValue;
+  // The busy Spinner is decorative; this control announces its busy start
+  // (spec:AST-086 FR8).
+  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
   const announce = useAnnounce();
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
@@ -2038,7 +2042,7 @@ export function Selector<T extends SelectorOptionType>(
         {htmlName != null && !isDisabled && (
           <input type="hidden" name={htmlName} value={value ?? ''} />
         )}
-        {isBusy && <Spinner size="sm" />}
+        {isBusy && <Spinner size="sm" aria-hidden="true" />}
         {hasClear && value != null && !isDisabled && !isEffectivelyReadOnly && (
           <InternalInputClearButton
             {...keepOpenProps}

package/src/TextArea/TextArea.test.tsx

@@ -55,6 +55,14 @@ beforeEach(() => {
 // accessibility tree. Use hidden: true to find it.
 const h = {hidden: true} as const;
 
+/** A busy control's Spinner is decorative and silent (spec:AST-086 FR8). */
+function expectSilentBusySpinner() {
+  const spinner = document.querySelector('.astryx-spinner');
+  expect(spinner).not.toBeNull();
+  expect(spinner).toHaveAttribute('aria-hidden', 'true');
+  expect(screen.queryByRole('status', {name: 'Loading'})).toBeNull();
+}
+
 describe('TextArea', () => {
   it('renders with label', () => {
     render(<TextArea label="Description" value="" onChange={() => {}} />);
@@ -348,7 +356,7 @@ describe('TextArea', () => {
       );
       // Matches the other inputs: spinner (role="status") and the status icon
       // render side by side in the end slot, not mutually exclusively.
-      expect(screen.getByRole('status')).toBeInTheDocument();
+      expectSilentBusySpinner();
       // Status icon svg is also present alongside the spinner.
       expect(container.querySelectorAll('svg').length).toBeGreaterThan(0);
     });

package/src/TextArea/TextArea.tsx

@@ -63,6 +63,7 @@ import {characterCount} from '../utils/characters';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
@@ -438,6 +439,9 @@ export function TextArea({
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
+  // The busy Spinner is decorative; this control announces its busy start
+  // (spec:AST-086 FR8).
+  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the textarea container (which already exists)
@@ -660,7 +664,7 @@ export function TextArea({
         />
         {(isBusy || statusIcon) && (
           <span {...stylex.props(styles.endSlot)}>
-            {isBusy && <Spinner size="sm" />}
+            {isBusy && <Spinner size="sm" aria-hidden="true" />}
             {statusIcon}
           </span>
         )}

package/src/TextInput/TextInput.tsx

@@ -118,6 +118,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 export type TextInputType = 'text' | 'password' | 'email';
 
 export interface TextInputProps extends Omit<
@@ -344,6 +345,9 @@ export function TextInput({
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
+  // The busy Spinner is decorative; this control announces its busy start
+  // (spec:AST-086 FR8).
+  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
   // tooltip listeners attach to the input container (which already exists) and
@@ -506,7 +510,7 @@ export function TextInput({
           onClick={handleClear}
         />
       )}
-      {isBusy && <Spinner size="sm" />}
+      {isBusy && <Spinner size="sm" aria-hidden="true" />}
       {statusIcon}
     </div>
   );

package/src/TimeInput/TimeInput.tsx

@@ -70,6 +70,7 @@ import {
 import type {SizeValue} from '../utils/types';
 import {useSize} from '../SizeContext/SizeContext';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -475,6 +476,9 @@ function TimeField({
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
+  // The busy Spinner is decorative; this control announces its busy start
+  // (spec:AST-086 FR8).
+  useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
 
   // In grouped mode the status message renders as a visually-hidden node that
   // exists only for aria-describedby. Announce it through the persistent
@@ -865,7 +869,7 @@ function TimeField({
           </VisuallyHidden>
         </>
       )}
-      {isBusy && <Spinner size="sm" />}
+      {isBusy && <Spinner size="sm" aria-hidden="true" />}
       {hasClear && optimisticValue && !isDisabled && (
         <InputClearButton
           label={t('@astryx.timeInput.clearLabel', {label})}

package/src/TimeInput/TouchTimeField.tsx

@@ -42,6 +42,7 @@ import {useFieldInputStyling} from '../Field/fieldParts';
 import {joinAriaIDs} from '../utils/inputAria';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {Icon} from '../Icon';
@@ -254,6 +255,15 @@ export function TouchTimeField({
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
+  const sheetBodyRef = useRef<HTMLDivElement | null>(null);
+  // The busy Spinner is decorative; this control announces its busy start
+  // (spec:AST-086 FR8). A change made in the open modal sheet starts it while
+  // the sheet is open, so it is announced from inside the sheet.
+  useBusyAnnouncement(
+    isBusy,
+    t('@astryx.spinner.loading'),
+    isSheetOpen ? sheetBodyRef : inputRef,
+  );
   const isEffectivelyDisabled = isDisabled || isLoading;
 
   const showsDisabledMessage = isDisabled && !!disabledMessage;
@@ -516,7 +526,7 @@ export function TouchTimeField({
         }
         {...stylex.props(styles.input)}
       />
-      {isBusy && <Spinner size="sm" />}
+      {isBusy && <Spinner size="sm" aria-hidden="true" />}
       {hasClear && optimisticValue && !isEffectivelyDisabled && (
         <InputClearButton
           label={t('@astryx.timeInput.clearLabel', {label})}
@@ -531,7 +541,7 @@ export function TouchTimeField({
         height="hug"
         // sheetBody owns the inset, including the band under the grab handle.
         padding={0}>
-        <div {...stylex.props(styles.sheetBody)}>
+        <div ref={sheetBodyRef} {...stylex.props(styles.sheetBody)}>
           <div {...stylex.props(styles.wheels)}>
             <Wheel
               label={t('@astryx.dateTimeInput.hourWheel')}

package/src/Tokenizer/Tokenizer.test.tsx

@@ -122,6 +122,17 @@ const userSource: SearchSource = {
   bootstrap: () => users.slice(0, 3),
 };
 
+/**
+ * The search Spinner: named but not live (family:input-fields FR7,
+ * spec:AST-086 FR8), so it is found as an image named "Loading".
+ */
+function queryBusySpinner(): Element | null {
+  return screen.queryByRole('img', {name: 'Loading'});
+}
+function getBusySpinner(): Element {
+  return screen.getByRole('img', {name: 'Loading'});
+}
+
 describe('Tokenizer minQueryLength', () => {
   it('forwards the threshold to the typeahead engine', async () => {
     const search = vi.fn((query: string) =>
@@ -1675,7 +1686,7 @@ describe('Tokenizer end-lane reserve', () => {
       fireEvent.change(screen.getByRole('combobox'), {target: {value: 'Al'}});
     });
 
-    expect(screen.getByRole('status')).toBeInTheDocument();
+    expect(getBusySpinner()).toBeInTheDocument();
     expect(reserveOf(container)).toBe(
       `calc(var(--spacing-2) + ${LANE_LOCAL_WIDTH}px)`,
     );
@@ -1774,7 +1785,7 @@ describe('Tokenizer end-lane reserve', () => {
     // The indicator is up, so the transition really did happen. Scoped by
     // name: the announcer for result counts is a role="status" live region
     // too, and it is not the indicator.
-    expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    expect(getBusySpinner()).toBeInTheDocument();
     // ...and it cost no token a render.
     expect(renderedTokens).toEqual([]);
 
@@ -1783,9 +1794,7 @@ describe('Tokenizer end-lane reserve', () => {
       await Promise.resolve();
     });
     await waitFor(() => {
-      expect(
-        screen.queryByRole('status', {name: 'Loading'}),
-      ).not.toBeInTheDocument();
+      expect(queryBusySpinner()).not.toBeInTheDocument();
     });
     expect(renderedTokens).toEqual([]);
   });
@@ -1823,24 +1832,20 @@ describe('Tokenizer end-lane reserve', () => {
 
     fireEvent.focus(input);
     await waitFor(() => {
-      expect(screen.getByRole('status', {name: 'Loading'})).toBeInTheDocument();
+      expect(getBusySpinner()).toBeInTheDocument();
     });
 
     fireEvent.click(screen.getByRole('button', {name: 'Add Token'}));
 
     await waitFor(() => {
-      expect(
-        screen.queryByRole('status', {name: 'Loading'}),
-      ).not.toBeInTheDocument();
+      expect(queryBusySpinner()).not.toBeInTheDocument();
     });
 
     await act(async () => {
       settle([]);
       await Promise.resolve();
     });
-    expect(
-      screen.queryByRole('status', {name: 'Loading'}),
-    ).not.toBeInTheDocument();
+    expect(queryBusySpinner()).not.toBeInTheDocument();
   });
 
   it('shares one observer across every field on the page', () => {

package/src/Tokenizer/Tokenizer.tsx

@@ -23,6 +23,7 @@ import React, {
   useRef,
   useState,
   type ReactNode,
+  type RefObject,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
@@ -37,6 +38,7 @@ import {
   useFieldInputStyling,
 } from '../Field/fieldParts';
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import type {SizeValue} from '../utils/types';
 import {BaseTypeahead} from '../Typeahead/BaseTypeahead';
 import {useSize} from '../SizeContext/SizeContext';
@@ -521,6 +523,7 @@ function EndLane({
   laneRef,
   laneXStyle,
   loadingLabel,
+  anchorRef,
   hasStaticContent,
   children,
 }: {
@@ -528,16 +531,21 @@ function EndLane({
   laneRef: (node: HTMLElement | null) => void;
   laneXStyle: stylex.StyleXStyles[];
   loadingLabel: string;
+  anchorRef: RefObject<Element | null>;
   hasStaticContent: boolean;
   children: ReactNode;
 }) {
   const isBusy = useIsBusy(lane);
+  // The search Spinner stays named (family:input-fields FR7) but is not a
+  // live region; the field announces each search's busy start instead
+  // (spec:AST-086 FR8).
+  useBusyAnnouncement(isBusy, loadingLabel, anchorRef);
   if (!isBusy && !hasStaticContent) {
     return null;
   }
   return (
     <div ref={laneRef} {...stylex.props(laneXStyle)}>
-      {isBusy && <Spinner size="sm" aria-label={loadingLabel} />}
+      {isBusy && <Spinner size="sm" aria-label={loadingLabel} role="img" />}
       {children}
     </div>
   );
@@ -1084,6 +1092,7 @@ export function Tokenizer<T extends SearchableItem>({
         laneRef={laneRef}
         laneXStyle={[styles.endSection, endSectionSizeStyles[size]]}
         loadingLabel={t('@astryx.typeahead.loading')}
+        anchorRef={wrapperRef}
         hasStaticContent={hasStaticEndLane}>
         {endContent}
         {hasClearButton && (

package/src/Typeahead/BaseTypeahead.tsx

@@ -62,6 +62,7 @@ import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
 import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
 import {clampInlineSize} from '../Layer/clampInlineSize';
 // =============================================================================
@@ -561,6 +562,14 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // A wrapper that owns the inline-end lane subscribes through context; see
   // busyIndicatorLane.tsx for why this is not a prop.
   const busyLane = useBusyIndicatorLane();
+  // Without a wrapper that took the indicator over, this input announces each
+  // search's busy start (spec:AST-086 FR8); its Spinner stays named but is not
+  // a live region (family:input-fields FR7).
+  useBusyAnnouncement(
+    isLoading && busyLane == null,
+    t('@astryx.typeahead.loading'),
+    inputRef,
+  );
   const onLoadingChangeRef = useRef(busyLane?.onBusyChange);
   useIsomorphicLayoutEffect(() => {
     onLoadingChangeRef.current = busyLane?.onBusyChange;
@@ -1218,7 +1227,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       />
       {isLoading && busyLane == null && (
         <span {...stylex.props(styles.loadingStatus)}>
-          <Spinner size="sm" aria-label={t('@astryx.typeahead.loading')} />
+          <Spinner
+            size="sm"
+            aria-label={t('@astryx.typeahead.loading')}
+            role="img"
+          />
         </span>
       )}
       {popover.render(