fix(accessibility): Field announce error message for focused field

packages/@react-aria/form/intl/en-US.json

@@ -0,0 +1,4 @@
+{
+  "invalidValue": "Invalid value.",
+  "reviewField": "Please review {accessibleName} field: {validationMessage}"
+}

packages/@react-aria/form/package.json

@@ -26,11 +26,14 @@
     "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
+    "@react-aria/i18n": "^3.12.10",
     "@react-aria/interactions": "^3.25.3",
+    "@react-aria/live-announcer": "^3.4.3",
     "@react-aria/utils": "^3.29.1",
     "@react-stately/form": "^3.1.5",
     "@react-types/shared": "^3.30.0",
-    "@swc/helpers": "^0.5.0"
+    "@swc/helpers": "^0.5.0",
+    "dom-accessibility-api": "^0.7.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1",

packages/@react-aria/form/src/useFormValidation.ts

@@ -10,25 +10,59 @@
  * governing permissions and limitations under the License.
  */
 
+import {announce} from '@react-aria/live-announcer';
+import {computeAccessibleName} from 'dom-accessibility-api';
 import {FormValidationState} from '@react-stately/form';
+import {getActiveElement, getOwnerDocument, useEffectEvent, useLayoutEffect} from '@react-aria/utils';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
 import {RefObject, Validation, ValidationResult} from '@react-types/shared';
 import {setInteractionModality} from '@react-aria/interactions';
-import {useEffect} from 'react';
-import {useEffectEvent, useLayoutEffect} from '@react-aria/utils';
+import {useEffect, useRef} from 'react';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
 
 type ValidatableElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
 
+function isValidatableElement(element: Element): boolean {
+  return element instanceof HTMLInputElement ||
+         element instanceof HTMLTextAreaElement ||
+         element instanceof HTMLSelectElement;
+}
+
 interface FormValidationProps<T> extends Validation<T> {
   focus?: () => void
 }
 
+const TIMEOUT_DURATION = 325;
+
 export function useFormValidation<T>(props: FormValidationProps<T>, state: FormValidationState, ref: RefObject<ValidatableElement | null> | undefined): void {
   let {validationBehavior, focus} = props;
 
+  let justBlurredRef = useRef(false);
+  let timeoutIdRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  function announceErrorMessage(errorMessage: string = ''): void {
+    if (timeoutIdRef.current != null) {
+      clearTimeout(timeoutIdRef.current);
+      timeoutIdRef.current = null;
+    }
+    if (ref && ref.current && errorMessage !== '' && (
+        ref.current.contains(getActiveElement(getOwnerDocument(ref.current))) ||
+        justBlurredRef.current
+      )
+    ) {
+      timeoutIdRef.current = setTimeout(() => announce(errorMessage, 'polite'), TIMEOUT_DURATION);
+    }
+  }
+
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/form');
+
   // This is a useLayoutEffect so that it runs before the useEffect in useFormValidationState, which commits the validation change.
   useLayoutEffect(() => {
     if (validationBehavior === 'native' && ref?.current && !ref.current.disabled) {
-      let errorMessage = state.realtimeValidation.isInvalid ? state.realtimeValidation.validationErrors.join(' ') || 'Invalid value.' : '';
+      let errorMessage =
+        state.realtimeValidation.isInvalid ?
+        (state.realtimeValidation.validationErrors?.join(' ') || stringFormatter.format('invalidValue') || '') :
+        '';
       ref.current.setCustomValidity(errorMessage);
 
       // Prevent default tooltip for validation message.
@@ -56,11 +90,17 @@ export function useFormValidation<T>(props: FormValidationProps<T>, state: FormV
 
     // Auto focus the first invalid input in a form, unless the error already had its default prevented.
     let form = ref?.current?.form;
-    if (!e.defaultPrevented && ref && form && getFirstInvalidInput(form) === ref.current) {
-      if (focus) {
-        focus();
-      } else {
-        ref.current?.focus();
+    if (!e.defaultPrevented && ref && form) {
+
+      // Announce the current error message
+      announceErrorMessage(ref?.current?.validationMessage || '');
+
+      if (getFirstInvalidInput(form) === ref.current) {
+        if (focus) {
+          focus();
+        } else {
+          ref.current?.focus();
+        }
       }
 
       // Always show focus ring.
@@ -75,25 +115,64 @@ export function useFormValidation<T>(props: FormValidationProps<T>, state: FormV
     state.commitValidation();
   });
 
+  let onBlur = useEffectEvent((event: Event) => {
+    const input = ref?.current;
+    const relatedTarget = (event as FocusEvent).relatedTarget as Element | null;
+    if (
+      (!input || !input.validationMessage) ||
+      (relatedTarget && isValidatableElement(relatedTarget) && (relatedTarget as ValidatableElement).validationMessage)
+    ) {
+      // If the input has no validation message,
+      // or the relatedTarget has a validation message, don't announce the error message.
+      // This prevents announcing the error message when the user is navigating
+      // between inputs that may already have an error message.
+      return;
+    }
+    justBlurredRef.current = true;
+    const isRadioOrCheckbox = input.type === 'radio' || input.type === 'checkbox';
+    const groupElement = isRadioOrCheckbox ? input.closest('[role="group"][aria-labelledby], [role=\'group\'][aria-label], fieldset') : undefined;
+    // Announce the current error message
+    const accessibleName = computeAccessibleName(groupElement || input);
+    const validationMessage = input.validationMessage;
+    announceErrorMessage(
+      accessibleName && validationMessage ?
+      stringFormatter.format(
+        'reviewField',
+        {
+          accessibleName,
+          validationMessage
+        }) :
+      validationMessage
+    );
+    justBlurredRef.current = false;
+  });
+
   useEffect(() => {
     let input = ref?.current;
     if (!input) {
       return;
     }
 
     let form = input.form;
+    input.addEventListener('blur', onBlur);
     input.addEventListener('invalid', onInvalid);
     input.addEventListener('change', onChange);
     form?.addEventListener('reset', onReset);
     return () => {
+      if (timeoutIdRef.current != null) {
+        clearTimeout(timeoutIdRef.current);
+        timeoutIdRef.current = null;
+      }
+      justBlurredRef.current = false;
+      input!.removeEventListener('blur', onBlur);
       input!.removeEventListener('invalid', onInvalid);
       input!.removeEventListener('change', onChange);
       form?.removeEventListener('reset', onReset);
     };
-  }, [ref, onInvalid, onChange, onReset, validationBehavior]);
+  }, [onBlur, onChange, onInvalid, onReset, ref, validationBehavior]);
 }
 
-function getValidity(input: ValidatableElement) {
+function getValidity(input: ValidatableElement): ValidityState {
   // The native ValidityState object is live, meaning each property is a getter that returns the current state.
   // We need to create a snapshot of the validity state at the time this function is called to avoid unpredictable React renders.
   let validity = input.validity;

packages/@react-spectrum/autocomplete/intl/en-US.json

@@ -2,5 +2,6 @@
   "loading": "Loading...",
   "noResults": "No results",
   "clear": "Clear",
-  "invalid": "(invalid)"
+  "invalid": "(invalid)",
+  "valid": "(valid)"
 }

packages/@react-spectrum/autocomplete/src/MobileSearchAutocomplete.tsx

@@ -207,9 +207,10 @@ const SearchAutocompleteButton = React.forwardRef(function SearchAutocompleteBut
   let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/autocomplete');
   let valueId = useId();
   let invalidId = useId();
+  let validId = useId();
   let validationIcon = validationState === 'invalid'
     ? <AlertMedium id={invalidId} aria-label={stringFormatter.format('invalid')} />
-    : <CheckmarkMedium />;
+    : <CheckmarkMedium id={validId} aria-label={stringFormatter.format('valid')} />;
 
   if (icon) {
     icon = React.cloneElement(icon, {
@@ -262,7 +263,8 @@ const SearchAutocompleteButton = React.forwardRef(function SearchAutocompleteBut
       props['aria-labelledby'],
       props['aria-label'] && !props['aria-labelledby'] ? props.id : null,
       valueId,
-      validationState === 'invalid' ? invalidId : null
+      validationState === 'invalid' ? invalidId : null,
+      validationState === 'valid' ? validId : null
     ].filter(Boolean).join(' '),
     elementType: 'div'
   }, ref);

packages/@react-spectrum/combobox/intl/en-US.json

@@ -2,5 +2,6 @@
   "loading": "Loading...",
   "noResults": "No results",
   "clear": "Clear",
-  "invalid": "(invalid)"
+  "invalid": "(invalid)",
+  "valid": "(valid)"
 }

packages/@react-spectrum/combobox/src/MobileComboBox.tsx

@@ -179,9 +179,10 @@ export const ComboBoxButton = React.forwardRef(function ComboBoxButton(props: Co
   let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/combobox');
   let valueId = useId();
   let invalidId = useId();
+  let validId = useId();
   let validationIcon = validationState === 'invalid'
     ? <AlertMedium id={invalidId} aria-label={stringFormatter.format('invalid')} />
-    : <CheckmarkMedium />;
+    : <CheckmarkMedium id={validId} aria-label={stringFormatter.format('valid')} />;
 
   let validation = React.cloneElement(validationIcon, {
     UNSAFE_className: classNames(
@@ -202,7 +203,8 @@ export const ComboBoxButton = React.forwardRef(function ComboBoxButton(props: Co
       props['aria-labelledby'],
       props['aria-label'] && !props['aria-labelledby'] ? props.id : null,
       valueId,
-      validationState === 'invalid' ? invalidId : null
+      validationState === 'invalid' ? invalidId : null,
+      validationState === 'valid' ? validId : null
     ].filter(Boolean).join(' '),
     elementType: 'div'
   }, objRef);

packages/@react-spectrum/datepicker/intl/en-US.json

@@ -1,5 +1,6 @@
 {
   "time": "Time",
   "startTime": "Start time",
-  "endTime": "End time"
+  "endTime": "End time",
+  "valid": "(valid)"
 }

packages/@react-spectrum/datepicker/src/DateField.tsx

@@ -17,12 +17,13 @@ import datepickerStyles from './styles.css';
 import {DateValue, SpectrumDateFieldProps} from '@react-types/datepicker';
 import {Field} from '@react-spectrum/label';
 import {FocusableRef} from '@react-types/shared';
-import {Input} from './Input';
+import {Input, VALID_ICON_POSTFIX} from './Input';
 import React, {ReactElement, useRef} from 'react';
 import {useDateField} from '@react-aria/datepicker';
 import {useDateFieldState} from '@react-stately/datepicker';
 import {useFocusManagerRef, useFormatHelpText, useFormattedDateWidth} from './utils';
 import {useFormProps} from '@react-spectrum/form';
+import {useId} from '@react-aria/utils';
 import {useLocale} from '@react-aria/i18n';
 import {useProviderProps} from '@react-spectrum/provider';
 
@@ -67,6 +68,9 @@ export const DateField = React.forwardRef(function DateField<T extends DateValue
 
   let approximateWidth = useFormattedDateWidth(state) + 'ch';
 
+  let dateFieldInputId = useId();
+  let validIconId = validationState === 'valid' ? dateFieldInputId + VALID_ICON_POSTFIX : undefined;
+
   return (
     <Field
       {...props}
@@ -82,6 +86,7 @@ export const DateField = React.forwardRef(function DateField<T extends DateValue
       validationDetails={validationDetails}
       wrapperClassName={classNames(datepickerStyles, 'react-spectrum-Datepicker-fieldWrapper')}>
       <Input
+        id={dateFieldInputId}
         ref={fieldRef}
         fieldProps={fieldProps}
         isDisabled={isDisabled}
@@ -92,6 +97,7 @@ export const DateField = React.forwardRef(function DateField<T extends DateValue
         className={classNames(datepickerStyles, 'react-spectrum-DateField')}>
         {state.segments.map((segment, i) =>
           (<DatePickerSegment
+            aria-describedby={i === 0 ? validIconId : undefined}
             key={i}
             segment={segment}
             state={state}

packages/@react-spectrum/datepicker/src/DatePicker.tsx

@@ -24,7 +24,7 @@ import {FocusableRef} from '@react-types/shared';
 import {Input} from './Input';
 // @ts-ignore
 import intlMessages from '../intl/*.json';
-import {mergeProps} from '@react-aria/utils';
+import {mergeProps, useId} from '@react-aria/utils';
 import React, {ReactElement, useRef} from 'react';
 import '@adobe/spectrum-css-temp/components/textfield/vars.css'; // HACK: must be included BEFORE inputgroup
 import styles from '@adobe/spectrum-css-temp/components/inputgroup/vars.css';
@@ -118,6 +118,8 @@ export const DatePicker = React.forwardRef(function DatePicker<T extends DateVal
 
   let approximateWidth = useFormattedDateWidth(state) + 'ch';
 
+  let datePickerInputId = useId();
+
   return (
     <Field
       {...props}
@@ -137,6 +139,7 @@ export const DatePicker = React.forwardRef(function DatePicker<T extends DateVal
         className={className}
         ref={targetRef}>
         <Input
+          id={datePickerInputId}
           isDisabled={isDisabled}
           isQuiet={isQuiet}
           validationState={validationState}
@@ -147,6 +150,7 @@ export const DatePicker = React.forwardRef(function DatePicker<T extends DateVal
           <DatePickerField
             {...fieldProps}
             data-testid="date-field"
+            id={validationState === 'valid' ? datePickerInputId : undefined}
             isQuiet={isQuiet} />
         </Input>
         <DialogTrigger

packages/@react-spectrum/datepicker/src/DatePickerField.tsx

@@ -19,6 +19,7 @@ import React, {JSX, useRef} from 'react';
 import {useDateField} from '@react-aria/datepicker';
 import {useDateFieldState} from '@react-stately/datepicker';
 import {useLocale} from '@react-aria/i18n';
+import {VALID_ICON_POSTFIX} from './Input';
 
 interface DatePickerFieldProps<T extends DateValue> extends SpectrumDatePickerProps<T> {
   inputClassName?: string,
@@ -28,11 +29,13 @@ interface DatePickerFieldProps<T extends DateValue> extends SpectrumDatePickerPr
 
 export function DatePickerField<T extends DateValue>(props: DatePickerFieldProps<T>): JSX.Element {
   let {
+    id: datePickerInputId,
     isDisabled,
     isReadOnly,
     isRequired,
     inputClassName
   } = props;
+
   let ref = useRef<HTMLDivElement | null>(null);
   let {locale} = useLocale();
   let state = useDateFieldState({
@@ -44,10 +47,16 @@ export function DatePickerField<T extends DateValue>(props: DatePickerFieldProps
   let inputRef = useRef<HTMLInputElement | null>(null);
   let {fieldProps, inputProps} = useDateField({...props, inputRef}, state, ref);
 
+  let validIconId = datePickerInputId ? datePickerInputId + VALID_ICON_POSTFIX : undefined;
+
+  // field props is container element that does not need an id
+  fieldProps.id = undefined;
+
   return (
     <span {...fieldProps} data-testid={props['data-testid']} className={classNames(datepickerStyles, 'react-spectrum-Datepicker-segments', inputClassName)} ref={ref}>
       {state.segments.map((segment, i) =>
         (<DatePickerSegment
+          aria-describedby={i === 0 ? validIconId : undefined}
           key={i}
           segment={segment}
           state={state}

packages/@react-spectrum/datepicker/src/DatePickerSegment.tsx

@@ -49,9 +49,15 @@ function LiteralSegment({segment}: LiteralSegmentProps) {
   );
 }
 
-function EditableSegment({segment, state}: DatePickerSegmentProps) {
+function EditableSegment({segment, state, ...otherProps}: DatePickerSegmentProps & {'aria-describedby'?: string}) {
   let ref = useRef<HTMLDivElement | null>(null);
   let {segmentProps} = useDateSegment(segment, state, ref);
+  let {'aria-describedby': ariaDescribedByProp} = otherProps;
+
+  if (ariaDescribedByProp) {
+    // Merge aria-describedby from segmentProps and otherProps
+    segmentProps['aria-describedby'] = segmentProps['aria-describedby'] ? `${segmentProps['aria-describedby']} ${ariaDescribedByProp}` : ariaDescribedByProp;
+  }
 
   return (
     <span