@astryxdesign/core 0.7.4 → 0.7.5-canary.031a639

package/src/NumberInput/NumberInput.test.tsx

@@ -13,6 +13,8 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {act, useState} from 'react';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {InternationalizationProvider} from '../i18n';
 import {registerIcons, resetIcons} from '../Icon';
@@ -22,6 +24,21 @@ import {defineTheme} from '../theme/defineTheme';
 import {generateThemeCSS} from '../theme/generateThemeRules';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+// jsdom cannot match `:focus-visible`: compare the ring's StyleX class hash.
+const RING = stylex
+  .props(
+    stylex.create({
+      ring: {
+        boxShadow: {
+          default: null,
+          ':has(> [aria-disabled="true"]:focus-visible)': `inset 0px 0px 0px 2px ${colorVars['--color-accent-muted']}`,
+        },
+      },
+    }).ring,
+  )
+  .className!.split(' ')
+  .pop()!;
+
 // FieldStatus announces status messages through the persistent useAnnounce
 // singletons; remove them between tests so role/aria-live queries in this
 // file never match a leftover region.
@@ -149,7 +166,7 @@ describe('NumberInput', () => {
     expect(screen.getByRole('spinbutton')).not.toHaveAttribute('aria-required');
   });
 
-  it('sets disabled attribute when isDisabled is true', () => {
+  it('exposes aria-disabled, not native disabled, when isDisabled is true (spec:AST-085)', () => {
     render(
       <NumberInput
         label="Quantity"
@@ -158,7 +175,76 @@ describe('NumberInput', () => {
         onChange={() => {}}
       />,
     );
-    expect(screen.getByRole('spinbutton')).toBeDisabled();
+    expect(screen.getByRole('spinbutton')).toHaveAttribute(
+      'aria-disabled',
+      'true',
+    );
+  });
+
+  it('keeps a disabled input in the tab order and rings it (spec:AST-085 FR1, FR6)', async () => {
+    const user = userEvent.setup();
+    render(
+      <>
+        <NumberInput label="First" value={1} onChange={() => {}} />
+        <NumberInput label="Second" value={2} onChange={() => {}} isDisabled />
+      </>,
+    );
+    await user.tab();
+    await user.tab();
+    const input = screen.getByRole('spinbutton', {name: 'Second'});
+    expect(input).toHaveFocus();
+    expect(input.parentElement).toHaveClass(RING);
+  });
+
+  it('runs no caller handler, steps nothing and submits no form while disabled (spec:AST-085 FR2)', async () => {
+    const user = userEvent.setup();
+    const handlers = {
+      onChange: vi.fn(),
+      onEnter: vi.fn(),
+      onKeyDown: vi.fn(),
+      onPaste: vi.fn(),
+    };
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    render(
+      <form onSubmit={onSubmit}>
+        <NumberInput
+          label="Quantity"
+          value={5}
+          isDisabled
+          hasNumberSteppers
+          {...handlers}
+        />
+      </form>,
+    );
+    await user.click(screen.getByRole('spinbutton'));
+    await user.keyboard('{ArrowUp}{ArrowDown}{Enter}');
+    await user.paste('9');
+    await user.click(screen.getByRole('button', {name: 'Increment Quantity'}));
+    for (const handler of [...Object.values(handlers), onSubmit]) {
+      expect(handler).not.toHaveBeenCalled();
+    }
+  });
+
+  it('commits nothing when a field disabled mid-entry loses focus (spec:AST-085 FR2)', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    const field = (isDisabled: boolean) => (
+      <NumberInput
+        label="Quantity"
+        value={5}
+        onChange={onChange}
+        isDisabled={isDisabled}
+      />
+    );
+    const {rerender} = render(field(false));
+    const input = screen.getByRole('spinbutton');
+    await user.clear(input);
+    await user.type(input, '8');
+    onChange.mockClear();
+    rerender(field(true));
+    await user.tab();
+    expect(onChange).not.toHaveBeenCalled();
+    expect(input).toHaveValue('5');
   });
 
   it('does not fire onChange when disabled', async () => {
@@ -994,6 +1080,49 @@ describe('NumberInput', () => {
       }
     });
 
+    it('names the input by its label and a caller aria-labelledby', () => {
+      render(
+        <>
+          <span id="shipping-heading">Shipping</span>
+          <NumberInput
+            label="Amount"
+            value={null}
+            onChange={() => {}}
+            aria-labelledby="shipping-heading"
+          />
+        </>,
+      );
+      const input = screen.getByRole('spinbutton', {name: 'Amount Shipping'});
+      expect(input.getAttribute('aria-labelledby')?.split(' ')).toContain(
+        'shipping-heading',
+      );
+    });
+
+    it('names a grouped input by the group, its label, and a caller aria-labelledby', () => {
+      render(
+        <>
+          <span id="shipping-heading">Shipping</span>
+          <InputGroup label="Price">
+            <NumberInput
+              label="Amount"
+              value={null}
+              onChange={() => {}}
+              aria-labelledby="shipping-heading"
+            />
+          </InputGroup>
+        </>,
+      );
+      expect(
+        screen.getByRole('spinbutton', {name: 'Price Amount Shipping'}),
+      ).toBeInTheDocument();
+    });
+
+    it('leaves a standalone input named by its label element without a caller aria-labelledby', () => {
+      render(<NumberInput label="Amount" value={null} onChange={() => {}} />);
+      const input = screen.getByRole('spinbutton', {name: 'Amount'});
+      expect(input).not.toHaveAttribute('aria-labelledby');
+    });
+
     it('does not render status message when not provided', () => {
       render(
         <NumberInput
@@ -1424,10 +1553,10 @@ describe('NumberInput', () => {
       const increment = screen.getByRole('button', {
         name: 'Increment Quantity',
       });
-      expect(increment).toBeDisabled();
+      expect(increment).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
 
       fireEvent.click(increment);
       expect(handleChange).not.toHaveBeenCalled();
@@ -1446,7 +1575,10 @@ describe('NumberInput', () => {
           />
         </form>,
       );
-      expect(screen.getByRole('spinbutton')).toBeDisabled();
+      expect(screen.getByRole('spinbutton')).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
       expect([
         ...new FormData(container.querySelector('form')!).keys(),
       ]).toEqual([]);
@@ -1480,6 +1612,24 @@ describe('NumberInput', () => {
       ).toBeInTheDocument();
     });
 
+    it('focuses the field inside the tap that clears it, without scrolling', () => {
+      // iOS Safari brings up its keyboard only for a focus made while
+      // handling the touch.
+      const onChange = vi.fn();
+      const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');
+      render(
+        <NumberInput label="Qty" value={5} onChange={onChange} hasClear />,
+      );
+      const input = screen.getByRole('spinbutton');
+      fireEvent.click(screen.getByRole('button', {name: 'Clear Qty'}), {
+        detail: 1,
+      });
+      expect(onChange).toHaveBeenCalledWith(null);
+      expect(document.activeElement).toBe(input);
+      expect(focusSpy).toHaveBeenLastCalledWith({preventScroll: true});
+      focusSpy.mockRestore();
+    });
+
     it('does not show clear button when value is null', () => {
       render(
         <NumberInput label="Qty" value={null} onChange={() => {}} hasClear />,
@@ -1693,7 +1843,7 @@ describe('NumberInput', () => {
       expect(onChange).not.toHaveBeenCalled();
     });
 
-    it('remains natively disabled when disabled without a reason', () => {
+    it('stays focusable when disabled without a reason', () => {
       render(
         <NumberInput
           label="Quantity"
@@ -1703,8 +1853,8 @@ describe('NumberInput', () => {
         />,
       );
       const input = screen.getByRole('spinbutton');
-      expect(input).toBeDisabled();
-      expect(input).not.toHaveAttribute('aria-disabled');
+      expect(input).not.toBeDisabled();
+      expect(input).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });
@@ -2006,14 +2156,14 @@ describe('NumberInput stepping', () => {
 
     const input = screen.getByRole('spinbutton');
     const increment = screen.getByRole('button', {name: 'Increment Amount'});
-    expect(increment).toBeEnabled();
+    expect(increment).not.toHaveAttribute('aria-disabled');
 
     fireEvent.click(increment);
 
     expect(input).toHaveValue('99.99');
     expect(input).toHaveAttribute('aria-valuenow', '99.99');
     expect(input).not.toHaveAttribute('aria-invalid');
-    expect(increment).toBeDisabled();
+    expect(increment).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('allows wheel stepping by default and consumes the focused gesture', () => {
@@ -2259,10 +2409,33 @@ describe('NumberInput stepping', () => {
       );
       expect(
         screen.getByRole('button', {name: 'Increment Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).not.toBeDisabled();
+      ).not.toHaveAttribute('aria-disabled');
+    });
+
+    it('commits nothing from a click on the stepper at the reached boundary (spec:AST-085 FR2)', async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <NumberInput
+          label="Quantity"
+          value={5}
+          onChange={onChange}
+          min={0}
+          max={10}
+          hasNumberSteppers
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      await user.clear(input);
+      await user.type(input, '10');
+      onChange.mockClear();
+      await user.click(
+        screen.getByRole('button', {name: 'Increment Quantity'}),
+      );
+      expect(onChange).not.toHaveBeenCalled();
     });
 
     it('disables both steppers with the input', () => {
@@ -2277,10 +2450,10 @@ describe('NumberInput stepping', () => {
       );
       expect(
         screen.getByRole('button', {name: 'Increment Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
       expect(
         screen.getByRole('button', {name: 'Decrement Quantity'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
     });
   });
 });

package/src/NumberInput/NumberInput.tsx

@@ -19,6 +19,7 @@
  */
 
 import {
+  use,
   useId,
   useState,
   useMemo,
@@ -51,13 +52,16 @@ import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 
 // Public padding tokens for the `number-input` theme target. A theme writes an
 // ordinary `padding` (in ANY spelling — the shorthand, `paddingBlock`, or a
@@ -203,7 +207,7 @@ const sizeStyles = stylex.create({
 
 export type NumberInputSize = keyof typeof sizeStyles;
 
-import {groupStyles} from '../InputGroup/groupStyles';
+import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 
 // Re-export shared types for convenience
 
@@ -261,7 +265,7 @@ interface NumberInputPropsBase extends Omit<
    * Whether the input is read-only.
    * The value is shown at full opacity and still submits with the form, but
    * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
-   * stays in the tab order — use it for a value the user should see and send
+   * keeps its form value — use it for a value the user should see and send
    * but not change. Stepping is off in every form while read-only: arrow keys,
    * the wheel, and the number steppers. `isDisabled` takes precedence when both
    * are set.
@@ -275,8 +279,8 @@ interface NumberInputPropsBase extends Omit<
    * keyboard and assistive technology. The field cannot be edited (it becomes
    * read-only) while disabled.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the reason
+   * is attached to the field itself.
    *
    * @example
    * ```
@@ -536,7 +540,7 @@ export function NumberInput({
   description,
   isOptional = false,
   isRequired = false,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   isReadOnly = false,
   disabledMessage,
   startIcon,
@@ -574,6 +578,7 @@ export function NumberInput({
   ref,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: NumberInputProps) {
   const {rest, container} = useFieldInputStyling('NumberInput', restProps, {
@@ -588,6 +593,7 @@ export function NumberInput({
   const size = useSize(sizeProp, 'md');
   const generatedID = useId();
   const id = idProp ?? generatedID;
+  const fieldLabelID = useId();
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
@@ -595,17 +601,27 @@ export function NumberInput({
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const inputGroup = useInputGroup();
+  const inputGroupState = use(InputGroupInternalContext);
+  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
 
   // Pending input while user is typing (null = show formatted value)
   const [pendingInput, setPendingInput] = useState<string | null>(null);
   const [isFocused, setIsFocused] = useState(false);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
+  // Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
   // the input stays perceivable via aria-disabled instead of the native
   // disabled attribute. The field is made read-only so it can't be typed into,
   // and value mutation is blocked by the isDisabled guard in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
+  // A disabled field keeps its tab stop but, like a natively disabled one,
+  // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
+  const fieldProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container div is not naturally focusable; focusin bubbles up from
@@ -638,6 +654,12 @@ export function NumberInput({
     ],
     inputGroup,
   );
+  // A caller aria-labelledby names the input together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const inputLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+      : ariaLabelledBy;
 
   const parseInput = useCallback(
     (text: string) => parseNumberInput(text, {min, max, isIntegerOnly, locale}),
@@ -699,6 +721,12 @@ export function NumberInput({
       if (pendingInput === null) {
         return;
       }
+      if (isDisabled) {
+        // A field disabled mid-entry commits nothing; its draft is dropped, as
+        // a natively disabled field's was (spec:AST-085 FR2).
+        setPendingInput(null);
+        return;
+      }
 
       const decision = resolveNumberInputCommit(pendingInput, {
         min,
@@ -722,7 +750,17 @@ export function NumberInput({
         onChange(decision.value);
       }
     },
-    [hasClear, isIntegerOnly, locale, max, min, onChange, pendingInput, value],
+    [
+      hasClear,
+      isDisabled,
+      isIntegerOnly,
+      locale,
+      max,
+      min,
+      onChange,
+      pendingInput,
+      value,
+    ],
   );
 
   // Blur ends the edit and displays the resulting committed value.
@@ -780,6 +818,13 @@ export function NumberInput({
   // Handle keyboard events
   const handleKeyDown = useCallback(
     (e: KeyboardEvent<HTMLInputElement>) => {
+      if (isDisabled) {
+        // A read-only field still submits its form on Enter.
+        if (e.key === 'Enter') {
+          e.preventDefault();
+        }
+        return;
+      }
       // The field is type="text" for formatted display, so an IME can compose
       // into it: Enter commits the candidate and the arrows walk the candidate
       // window. The composing keydown fires before compositionend, so without
@@ -804,7 +849,7 @@ export function NumberInput({
       }
       onKeyDown?.(e);
     },
-    [commitPendingInput, onEnter, onKeyDown, stepValue],
+    [commitPendingInput, isDisabled, onEnter, onKeyDown, stepValue],
   );
 
   // React's delegated wheel listener can be passive, so use a native,
@@ -860,11 +905,12 @@ export function NumberInput({
       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});
-        });
+        // Focus inside the tap: iOS Safari brings up its keyboard only for a
+        // focus made while handling the touch, so a field the tap reaches
+        // unfocused gets its keyboard, as UIKit's clear button makes the
+        // field first responder. `preventScroll` keeps a scrolled page where
+        // it is.
+        inputRef.current?.focus({preventScroll: true});
       }
     },
     [hasClear, onChange],
@@ -889,6 +935,7 @@ export function NumberInput({
       }}
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
+      {...(inputGroup ? inputGroupItemProps : undefined)}
       {...mergeProps(
         themeProps('number-input', {
           size,
@@ -902,6 +949,7 @@ export function NumberInput({
           hasNumberSteppers && styles.wrapperWithNumberSteppers,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && inputDisabledFocusStyles.ring,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -914,7 +962,7 @@ export function NumberInput({
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
-        {...rest}
+        {...fieldProps}
         ref={mergedInputRef}
         id={id}
         name={isDisabled || formatValue ? undefined : htmlName}
@@ -928,12 +976,11 @@ export function NumberInput({
         onBlur={handleBlur}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        // With a disabledMessage the input keeps focusability via aria-disabled
-        // so the reason is focus-discoverable; readOnly + the handler guards
-        // keep the value from changing.
-        disabled={isDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={isReadOnly || showsDisabledMessage || undefined}
+        // A disabled input keeps its place in the tab order (spec:AST-085):
+        // aria-disabled instead of the native attribute, with readOnly + the
+        // handler guards keeping the value from changing.
+        aria-disabled={isDisabled ? 'true' : undefined}
+        readOnly={isReadOnly || isDisabled || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-valuemin={min ?? undefined}
@@ -952,7 +999,7 @@ export function NumberInput({
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }
-        aria-labelledby={ariaLabelledBy}
+        aria-labelledby={inputLabelledBy}
         {...stylex.props(
           styles.input,
           isDisabled && styles.inputDisabled,
@@ -992,10 +1039,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canIncrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canIncrement || undefined
+            }
             aria-label={t('@astryx.numberInput.incrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canIncrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(1);
             }}
@@ -1016,10 +1070,17 @@ export function NumberInput({
             type="button"
             tabIndex={-1}
             {...pressable}
-            disabled={isDisabled || isReadOnly || !canDecrement}
+            aria-disabled={
+              isDisabled || isReadOnly || !canDecrement || undefined
+            }
             aria-label={t('@astryx.numberInput.decrementLabel', {label})}
             onPointerDown={event => event.preventDefault()}
             onClick={() => {
+              // An aria-disabled stepper does nothing, as a natively disabled
+              // one did (spec:AST-085 FR2).
+              if (isDisabled || isReadOnly || !canDecrement) {
+                return;
+              }
               inputRef.current?.focus();
               stepValue(-1);
             }}
@@ -1054,6 +1115,7 @@ export function NumberInput({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

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

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /** Real-browser and accessibility-tree binding evidence for NumberInput. */
 

package/src/Pagination/Pagination.test.tsx

@@ -965,7 +965,7 @@ describe('Pagination', () => {
         />,
       );
       const box = screen.getByRole('spinbutton', {name: 'Go to page'});
-      expect(box).toBeDisabled();
+      expect(box).toHaveAttribute('aria-disabled', 'true');
       // Disabled input never fires a change.
       await user.type(box, '5{Enter}');
       expect(onChange).not.toHaveBeenCalled();
@@ -999,7 +999,7 @@ describe('Pagination', () => {
       // editable box is inert rather than accepting entries it can't resolve.
       expect(
         screen.getByRole('spinbutton', {name: 'Go to page'}),
-      ).toBeDisabled();
+      ).toHaveAttribute('aria-disabled', 'true');
     });
 
     it('renders the localized "Page" label by default and a custom pageLabel', () => {