rfc: Adopting Async React in React Aria Components

.storybook/preview.js

@@ -28,6 +28,12 @@ export const parameters = {
       ]
     }
   },
+  react: {
+    rootOptions: {
+      // Prevent errors caught in error boundaries from showing Parcel's error overlay.
+      onCaughtError() {}
+    }
+  },
   layout: 'fullscreen',
   // Stops infinite loop memory crash when saving CSF stories https://github.com/storybookjs/storybook/issues/12747#issuecomment-1151803506
   docs: {

jest.config.js

@@ -94,7 +94,8 @@ module.exports = {
     '^bundle-text:.*\\.svg$': '<rootDir>/__mocks__/fileMock.js',
     '\\.svg$': '<rootDir>/__mocks__/svg.js',
     '\\.(jpg|jpeg|png|gif|eot|otf|webp|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/__mocks__/fileMock.js',
-    '\\.(css|styl)$': 'identity-obj-proxy'
+    '\\.(css|styl)$': 'identity-obj-proxy',
+    'vanilla-starter/(.*)': '<rootDir>/starters/docs/src/$1'
   },
 
   // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader

packages/@adobe/react-spectrum/src/button/Button.tsx

@@ -90,7 +90,10 @@ export const Button = React.forwardRef(function Button<T extends ElementType = '
     ...otherProps
   } = props;
   let domRef = useFocusableRef(ref);
-  let {buttonProps, isPressed} = useButton(props, domRef);
+  let {buttonProps, isPressed} = useButton({
+    ...props,
+    isPending: false // handled differently than RAC
+  }, domRef);
   let {hoverProps, isHovered} = useHover({isDisabled});
   let [isFocused, onFocusChange] = useState(false);
   let {focusProps} = useFocus({onFocusChange, isDisabled});

packages/@adobe/react-spectrum/src/color/ColorField.tsx

@@ -75,6 +75,7 @@ function ColorChannelField(props: ColorChannelFieldProps) {
     value,          // eslint-disable-line @typescript-eslint/no-unused-vars
     defaultValue,   // eslint-disable-line @typescript-eslint/no-unused-vars
     onChange,       // eslint-disable-line @typescript-eslint/no-unused-vars
+    changeAction,   // eslint-disable-line @typescript-eslint/no-unused-vars
     validate,       // eslint-disable-line @typescript-eslint/no-unused-vars
     forwardedRef,
     ...otherProps
@@ -111,6 +112,7 @@ function HexColorField(props: HexColorFieldProps) {
     value,          // eslint-disable-line @typescript-eslint/no-unused-vars
     defaultValue,   // eslint-disable-line @typescript-eslint/no-unused-vars
     onChange,       // eslint-disable-line @typescript-eslint/no-unused-vars
+    changeAction,   // eslint-disable-line @typescript-eslint/no-unused-vars
     forwardedRef,
     ...otherProps
   } = props;

packages/@adobe/react-spectrum/test/numberfield/NumberField.test.js

@@ -1681,10 +1681,8 @@ describe('NumberField', function () {
       expect(label).toHaveAttribute('for', textField.id);
 
       expect(incrementButton).toHaveAttribute('aria-label', 'Increase Width');
-      expect(incrementButton).not.toHaveAttribute('id');
       expect(incrementButton).not.toHaveAttribute('aria-labelledby');
       expect(decrementButton).toHaveAttribute('aria-label', 'Decrease Width');
-      expect(decrementButton).not.toHaveAttribute('id');
       expect(decrementButton).not.toHaveAttribute('aria-labelledby');
     });
 
@@ -1697,10 +1695,8 @@ describe('NumberField', function () {
       expect(textField).toHaveAttribute('aria-label', 'Width');
 
       expect(incrementButton).toHaveAttribute('aria-label', 'Increase Width');
-      expect(incrementButton).not.toHaveAttribute('id');
       expect(incrementButton).not.toHaveAttribute('aria-labelledby');
       expect(decrementButton).toHaveAttribute('aria-label', 'Decrease Width');
-      expect(decrementButton).not.toHaveAttribute('id');
       expect(decrementButton).not.toHaveAttribute('aria-labelledby');
     });
 
@@ -1753,10 +1749,8 @@ describe('NumberField', function () {
       expect(textField).toHaveAttribute('aria-label', 'Width');
 
       expect(incrementButton).toHaveAttribute('aria-label', 'Increment');
-      expect(incrementButton).not.toHaveAttribute('id');
       expect(incrementButton).not.toHaveAttribute('aria-labelledby');
       expect(decrementButton).toHaveAttribute('aria-label', 'Decrease Width');
-      expect(decrementButton).not.toHaveAttribute('id');
       expect(decrementButton).not.toHaveAttribute('aria-labelledby');
     });
 
@@ -1770,10 +1764,8 @@ describe('NumberField', function () {
       expect(textField).toHaveAttribute('aria-label', 'Width');
 
       expect(incrementButton).toHaveAttribute('aria-label', 'Increase Width');
-      expect(incrementButton).not.toHaveAttribute('id');
       expect(incrementButton).not.toHaveAttribute('aria-labelledby');
       expect(decrementButton).toHaveAttribute('aria-label', 'Decrement');
-      expect(decrementButton).not.toHaveAttribute('id');
       expect(decrementButton).not.toHaveAttribute('aria-labelledby');
     });
 

packages/@react-spectrum/s2/src/Button.tsx

@@ -457,7 +457,8 @@ export const LinkButton = forwardRef(function LinkButton(props: LinkButtonProps,
         size,
         staticColor,
         isStaticColor: !!staticColor,
-        isPending: false
+        isPending: false,
+        actionError: null
       }, styles)}>
       {(renderProps) => (<>
         {variant === 'genai' || variant === 'premium'

packages/react-aria-components/exports/Alert.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// Mark as a client only package. This will cause a build time error if you try
+// to import it from a React Server Component in a framework like Next.js.
+import 'client-only';
+
+export {Alert, AlertContext} from '../src/Alert';
+export type {AlertProps, AlertRenderProps} from '../src/Alert';

packages/react-aria-components/exports/index.ts

@@ -14,6 +14,7 @@
 // to import it from a React Server Component in a framework like Next.js.
 import 'client-only';
 
+export {Alert, AlertContext} from '../src/Alert';
 export {Autocomplete, AutocompleteContext, AutocompleteStateContext, SelectableCollectionContext, FieldInputContext} from '../src/Autocomplete';
 export {Breadcrumbs, BreadcrumbsContext, Breadcrumb} from '../src/Breadcrumbs';
 export {Button, ButtonContext} from '../src/Button';
@@ -101,6 +102,7 @@ export type {CollectionProps} from 'react-aria/Collection';
 export type {Placement} from 'react-aria/useOverlayPosition';
 export type {VisuallyHiddenProps} from 'react-aria/VisuallyHidden';
 
+export type {AlertProps, AlertRenderProps} from '../src/Alert';
 export type {AutocompleteProps, SelectableCollectionContextValue} from '../src/Autocomplete';
 export type {BreadcrumbsProps, BreadcrumbProps, BreadcrumbRenderProps} from '../src/Breadcrumbs';
 export type {ButtonProps, ButtonRenderProps} from '../src/Button';

packages/react-aria-components/src/Alert.tsx

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {ContextValue, RenderProps, useContextProps, useRenderProps} from './utils';
+import {DOMProps} from '@react-types/shared';
+import {filterDOMProps} from 'react-aria/filterDOMProps';
+import React, {createContext, ForwardedRef, forwardRef, useEffect, useRef} from 'react';
+import {useFocusRing} from 'react-aria/useFocusRing';
+import {useObjectRef} from 'react-aria/useObjectRef';
+
+export interface AlertProps extends RenderProps<AlertRenderProps>, DOMProps {
+  /**
+   * Whether to automatically focus the alert when it first renders.
+   */
+  autoFocus?: boolean
+}
+
+export interface AlertRenderProps {
+  /**
+   * Whether the button is focused, either via a mouse or keyboard.
+   * @selector [data-focused]
+   */
+  isFocused: boolean,
+  /**
+   * Whether the button is keyboard focused.
+   * @selector [data-focus-visible]
+   */
+  isFocusVisible: boolean
+}
+
+export const AlertContext = createContext<ContextValue<AlertProps, HTMLDivElement>>(null);
+
+export const Alert = forwardRef(function Alert(props: AlertProps, ref: ForwardedRef<HTMLDivElement>) {
+  [props, ref] = useContextProps(props, ref, AlertContext);
+  let domProps = filterDOMProps(props, {global: true})!;
+  let {isFocused, isFocusVisible, focusProps} = useFocusRing({autoFocus: props.autoFocus});
+  let renderProps = useRenderProps({
+    ...props,
+    defaultClassName: 'react-aria-Alert',
+    values: {
+      isFocused,
+      isFocusVisible
+    }
+  });
+
+  let autoFocusRef = useRef(props.autoFocus);
+  let domRef = useObjectRef(ref);
+  useEffect(() => {
+    if (autoFocusRef.current && domRef.current) {
+      domRef.current.focus();
+    }
+    autoFocusRef.current = false;
+  }, [domRef]);
+
+  return (
+    <div
+      {...domProps}
+      {...focusProps}
+      {...renderProps}
+      ref={domRef}
+      role="alert"
+      tabIndex={props.autoFocus ? -1 : undefined} />
+  );
+});

packages/react-aria-components/src/Button.tsx

@@ -10,8 +10,6 @@
  * governing permissions and limitations under the License.
  */
 
-import {announce} from 'react-aria/private/live-announcer/LiveAnnouncer';
-
 import {AriaButtonProps, useButton} from 'react-aria/useButton';
 import {
   ClassNameOrFunction,
@@ -24,14 +22,14 @@ import {
 } from './utils';
 import {createHideableComponent} from 'react-aria/private/collections/Hidden';
 import {filterDOMProps} from 'react-aria/filterDOMProps';
+import {FormPendingContext} from './Form';
 import {GlobalDOMAttributes} from '@react-types/shared';
 import {HoverEvents} from '@react-types/shared';
 import {mergeProps} from 'react-aria/mergeProps';
 import {ProgressBarContext} from './ProgressBar';
-import React, {createContext, ForwardedRef, useEffect, useRef} from 'react';
+import React, {createContext, ForwardedRef, useContext} from 'react';
 import {useFocusRing} from 'react-aria/useFocusRing';
 import {useHover} from 'react-aria/useHover';
-import {useId} from 'react-aria/useId';
 
 export interface ButtonRenderProps {
   /**
@@ -60,23 +58,23 @@ export interface ButtonRenderProps {
    */
   isDisabled: boolean,
   /**
-   * Whether the button is currently in a pending state.
+   * Whether the button's action is pending.
    * @selector [data-pending]
    */
-  isPending: boolean
+  isPending: boolean,
+  /**
+   * The last error that occurred within the button's action.
+   * @selector [data-action-error]
+   */
+  actionError: unknown | null
 }
 
 export interface ButtonProps extends Omit<AriaButtonProps, 'children' | 'href' | 'target' | 'rel' | 'elementType'>, HoverEvents, SlotProps, RenderProps<ButtonRenderProps, 'button'>, Omit<GlobalDOMAttributes<HTMLButtonElement>, 'onClick'> {
   /**
    * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
    * @default 'react-aria-Button'
    */
-  className?: ClassNameOrFunction<ButtonRenderProps>,
-  /**
-   * Whether the button is in a pending state. This disables press and hover events
-   * while retaining focusability, and announces the pending state to screen readers.
-   */
-  isPending?: boolean
+  className?: ClassNameOrFunction<ButtonRenderProps>
 }
 
 interface ButtonContextValue extends ButtonProps {
@@ -91,9 +89,14 @@ export const ButtonContext = createContext<ContextValue<ButtonContextValue, HTML
 export const Button = /*#__PURE__*/ createHideableComponent(function Button(props: ButtonProps, ref: ForwardedRef<HTMLButtonElement>) {
   [props, ref] = useContextProps(props, ref, ButtonContext);
   let ctx = props as ButtonContextValue;
-  let {isPending} = ctx;
-  let {buttonProps, isPressed} = useButton(props, ref);
-  buttonProps = useDisableInteractions(buttonProps, isPending);
+
+  // Ideally we would use React's `useFormStatus` for this but it is buggy.
+  // https://github.com/facebook/react/issues/30368
+  let isFormPending = useContext(FormPendingContext);
+  let {buttonProps, progressBarProps, isPressed, isPending, actionError} = useButton({
+    ...props,
+    isPending: props.isPending || (props.type === 'submit' && isFormPending)
+  }, ref);
   let {focusProps, isFocused, isFocusVisible} = useFocusRing(props);
   let {hoverProps, isHovered} = useHover({
     ...props,
@@ -105,7 +108,8 @@ export const Button = /*#__PURE__*/ createHideableComponent(function Button(prop
     isFocused,
     isFocusVisible,
     isDisabled: props.isDisabled || false,
-    isPending: isPending ?? false
+    isPending,
+    actionError
   };
 
   let renderProps = useRenderProps({
@@ -114,70 +118,24 @@ export const Button = /*#__PURE__*/ createHideableComponent(function Button(prop
     defaultClassName: 'react-aria-Button'
   });
 
-  let buttonId = useId(buttonProps.id);
-  let progressId = useId();
-
-  let ariaLabelledby = buttonProps['aria-labelledby'];
-  if (isPending) {
-    // aria-labelledby wins over aria-label
-    // https://www.w3.org/TR/accname-1.2/#computation-steps
-    if (ariaLabelledby) {
-      ariaLabelledby = `${ariaLabelledby} ${progressId}`;
-    } else if (buttonProps['aria-label']) {
-      ariaLabelledby = `${buttonId} ${progressId}`;
-    }
-  }
-
-  let wasPending = useRef(isPending);
-  useEffect(() => {
-    let message = {'aria-labelledby': ariaLabelledby || buttonId};
-    if (!wasPending.current && isFocused && isPending) {
-      announce(message, 'assertive');
-    } else if (wasPending.current && isFocused && !isPending) {
-      announce(message, 'assertive');
-    }
-    wasPending.current = isPending;
-  }, [isPending, isFocused, ariaLabelledby, buttonId]);
-
   let DOMProps = filterDOMProps(props, {global: true});
   delete DOMProps.onClick;
 
   return (
     <dom.button
       {...mergeProps(DOMProps, renderProps, buttonProps, focusProps, hoverProps)}
-      // When the button is in a pending state, we want to stop implicit form submission (ie. when the user presses enter on a text input).
-      // We do this by changing the button's type to button.
-      type={buttonProps.type === 'submit' && isPending ? 'button' : buttonProps.type}
-      id={buttonId}
       ref={ref}
-      aria-labelledby={ariaLabelledby}
       slot={props.slot || undefined}
-      aria-disabled={isPending ? 'true' : buttonProps['aria-disabled']}
       data-disabled={props.isDisabled || undefined}
       data-pressed={renderValues.isPressed || undefined}
       data-hovered={isHovered || undefined}
       data-focused={isFocused || undefined}
       data-pending={isPending || undefined}
-      data-focus-visible={isFocusVisible || undefined}>
-      <ProgressBarContext.Provider value={{id: progressId}}>
+      data-focus-visible={isFocusVisible || undefined}
+      data-action-error={actionError || undefined}>
+      <ProgressBarContext.Provider value={progressBarProps}>
         {renderProps.children}
       </ProgressBarContext.Provider>
     </dom.button>
   );
 });
-
-// Events to preserve when isPending is true (for tooltips and other overlays)
-const PRESERVED_EVENT_PATTERN = /Focus|Blur|Hover|Pointer(Enter|Leave|Over|Out)|Mouse(Enter|Leave|Over|Out)/;
-
-function useDisableInteractions(props, isPending) {
-  if (isPending) {
-    for (const key in props) {
-      if (key.startsWith('on') && !PRESERVED_EVENT_PATTERN.test(key)) {
-        props[key] = undefined;
-      }
-    }
-    props.href = undefined;
-    props.target = undefined;
-  }
-  return props;
-}