fix: The displayed error messages are not announced once they appear.

cspell.json

@@ -598,6 +598,7 @@
         "reactnativebackgroundtask",
         "reactnativehybridapp",
         "reactnativekeycommand",
+        "reannounce",
         "reauthentication",
         "Reauthenticator",
         "Rebooked",

src/components/Form/FormContext.tsx

@@ -7,12 +7,16 @@ type InputProps = Omit<InputComponentBaseProps, 'InputComponent' | 'inputID'>;
 type RegisterInput = (inputID: keyof Form, shouldSubmitForm: boolean, inputProps: InputProps) => InputProps;
 type FormContext = {
     registerInput: RegisterInput;
+    getErrorAnnouncementKey: () => number;
+    getFallbackAnnouncementMessage: () => string;
 };
 
 export default createContext<FormContext>({
     registerInput: () => {
         throw new Error('Registered input should be wrapped with FormWrapper');
     },
+    getErrorAnnouncementKey: () => 0,
+    getFallbackAnnouncementMessage: () => '',
 });
 
 export type {RegisterInput};

src/components/Form/FormProvider.tsx

@@ -7,11 +7,13 @@ import type {ValueOf} from 'type-fest';
 import {useInputBlurActions} from '@components/InputBlurContext';
 import type {LocalizedTranslate} from '@components/LocaleContextProvider';
 import {getIsRestoringKeyboardFocus} from '@components/TextInput';
+import useAccessibilityAnnouncement from '@hooks/useAccessibilityAnnouncement';
 import useDebounceNonReactive from '@hooks/useDebounceNonReactive';
 import useIsFocusedRef from '@hooks/useIsFocusedRef';
 import useLocalize from '@hooks/useLocalize';
 import useOnyx from '@hooks/useOnyx';
 import {isSafari} from '@libs/Browser';
+import {getLatestErrorMessage} from '@libs/ErrorUtils';
 import {prepareValues} from '@libs/ValidationUtils';
 import Visibility from '@libs/Visibility';
 import {clearErrorFields, clearErrors, setDraftValues, setErrors as setFormErrors} from '@userActions/FormActions';
@@ -128,6 +130,7 @@ function FormProvider({
     shouldRenderFooterAboveSubmit = false,
     shouldUseStrictHtmlTagValidation = false,
     shouldPreventDefaultFocusOnPressSubmit = false,
+    shouldHideFixErrorsAlert = false,
     keyboardSubmitBehavior = CONST.KEYBOARD_SUBMIT_BEHAVIOR.DISMISS_THEN_SUBMIT,
     ref,
     ...rest
@@ -149,9 +152,26 @@ function FormProvider({
     }
 
     const [errors, setErrors] = useState<GenericFormInputErrors>({});
+    const [errorAnnouncementKey, setErrorAnnouncementKey] = useState(0);
     const hasServerError = useMemo(() => !!formState && !isEmptyObject(formState?.errors), [formState]);
     const {setIsBlurred} = useInputBlurActions();
 
+    const errorMessage = formState ? getLatestErrorMessage(formState) : undefined;
+    const isGeneralAlertVisible = ((!isEmptyObject(errors) || !isEmptyObject(formState?.errorFields)) && !shouldHideFixErrorsAlert) || !!errorMessage;
+    const firstFieldErrorMessage = useMemo(() => {
+        for (const errorMsg of Object.values(errors)) {
+            if (errorMsg) {
+                return errorMsg;
+            }
+        }
+        return '';
+    }, [errors]);
+
+    useAccessibilityAnnouncement(firstFieldErrorMessage, !isGeneralAlertVisible && !!firstFieldErrorMessage && errorAnnouncementKey > 1, {
+        shouldAnnounceOnNative: true,
+        announcementKey: errorAnnouncementKey,
+    });
+
     const onValidate = useCallback(
         (values: FormOnyxValues, shouldClearServerError = true) => {
             const trimmedStringValues = shouldTrimValues ? prepareValues(values) : values;
@@ -264,6 +284,7 @@ function FormProvider({
 
             // Validate form and return early if any errors are found
             if (!isEmptyObject(onValidate(trimmedStringValues))) {
+                setErrorAnnouncementKey((prev) => prev + 1);
                 return;
             }
 
@@ -481,19 +502,30 @@ function FormProvider({
             isFocusedRef,
         ],
     );
-    const value = useMemo(() => ({registerInput}), [registerInput]);
+    const fallbackAnnouncementMessage = !isGeneralAlertVisible ? firstFieldErrorMessage : '';
+    const getErrorAnnouncementKey = useCallback(() => errorAnnouncementKey, [errorAnnouncementKey]);
+    const getFallbackAnnouncementMessage = useCallback(() => fallbackAnnouncementMessage, [fallbackAnnouncementMessage]);
+    const value = useMemo(() => ({registerInput, getErrorAnnouncementKey, getFallbackAnnouncementMessage}), [registerInput, getErrorAnnouncementKey, getFallbackAnnouncementMessage]);
+
+    const submitAndAnnounce = useCallback(() => {
+        if (hasServerError) {
+            setErrorAnnouncementKey((prev) => prev + 1);
+        }
+        submit();
+    }, [hasServerError, submit]);
 
     return (
         <FormContext.Provider value={value}>
             {/* eslint-disable react/jsx-props-no-spreading */}
             <FormWrapper
                 {...rest}
                 formID={formID}
-                onSubmit={submit}
+                onSubmit={submitAndAnnounce}
                 inputRefs={inputRefs}
                 errors={errors}
                 isLoading={isLoading}
                 enabledWhenOffline={enabledWhenOffline}
+                shouldHideFixErrorsAlert={shouldHideFixErrorsAlert}
                 shouldRenderFooterAboveSubmit={shouldRenderFooterAboveSubmit}
                 shouldPreventDefaultFocusOnPressSubmit={shouldPreventDefaultFocusOnPressSubmit}
                 ref={formWrapperRef}

src/components/Form/FormWrapper.tsx

@@ -1,4 +1,4 @@
-import React, {useImperativeHandle, useRef} from 'react';
+import React, {useContext, useImperativeHandle, useRef} from 'react';
 import type {ForwardedRef, RefObject} from 'react';
 // eslint-disable-next-line no-restricted-imports
 import type {ScrollView as RNScrollView, StyleProp, ViewStyle} from 'react-native';
@@ -7,17 +7,20 @@ import FormAlertWithSubmitButton from '@components/FormAlertWithSubmitButton';
 import FormElement from '@components/FormElement';
 import ScrollView from '@components/ScrollView';
 import ScrollViewWithContext from '@components/ScrollViewWithContext';
+import Text from '@components/Text';
 import useBottomSafeSafeAreaPaddingStyle from '@hooks/useBottomSafeSafeAreaPaddingStyle';
 import useOnyx from '@hooks/useOnyx';
 import useSafeAreaPaddings from '@hooks/useSafeAreaPaddings';
 import useThemeStyles from '@hooks/useThemeStyles';
 import Accessibility from '@libs/Accessibility';
 import {getLatestErrorMessage} from '@libs/ErrorUtils';
+import getPlatform from '@libs/getPlatform';
 import CONST from '@src/CONST';
 import type {OnyxFormKey} from '@src/ONYXKEYS';
 import type {Form} from '@src/types/form';
 import type ChildrenProps from '@src/types/utils/ChildrenProps';
 import {isEmptyObject} from '@src/types/utils/EmptyObject';
+import FormContext from './FormContext';
 import type {FormInputErrors, FormProps, FormWrapperRef, InputRefs} from './types';
 
 type FormWrapperProps = ChildrenProps &
@@ -106,6 +109,10 @@ function FormWrapper({
     const styles = useThemeStyles();
     const formRef = useRef<RNScrollView>(null);
     const formContentRef = useRef<View>(null);
+    const {getErrorAnnouncementKey, getFallbackAnnouncementMessage} = useContext(FormContext);
+    const errorAnnouncementKey = getErrorAnnouncementKey();
+    const fallbackAnnouncementMessage = getFallbackAnnouncementMessage();
+    const isWeb = getPlatform() === CONST.PLATFORM.WEB;
 
     const [formState] = useOnyx<OnyxFormKey, Form>(`${formID}`);
 
@@ -224,6 +231,15 @@ function FormWrapper({
             }}
         >
             {children}
+            {isWeb && !!fallbackAnnouncementMessage && errorAnnouncementKey > 1 && (
+                <Text
+                    key={`fallback-announce-${errorAnnouncementKey}`}
+                    style={styles.hiddenElementOutsideOfWindow}
+                    role={CONST.ROLE.ALERT}
+                >
+                    {fallbackAnnouncementMessage}
+                </Text>
+            )}
             {!shouldSubmitButtonStickToBottom && SubmitButton}
         </FormElement>
     );

src/components/FormAlertWrapper.tsx

@@ -50,6 +50,9 @@ function FormAlertWrapper({
     const {translate} = useLocalize();
     const {isOffline} = useNetwork();
 
+    const defaultFixErrorsMessage = `${translate('common.please')} ${translate('common.fixTheErrors')} ${translate('common.inTheFormBeforeContinuing')}.`;
+    const announcementMessage = message?.length ? message : defaultFixErrorsMessage;
+
     let content;
     if (!message?.length) {
         content = (
@@ -72,8 +75,10 @@ function FormAlertWrapper({
         <View style={containerStyles}>
             {isAlertVisible && (
                 <FormHelpMessage
-                    message={message}
+                    message={announcementMessage}
+                    shouldRenderMessageAsHTML={isMessageHtml}
                     style={[styles.mb3, errorMessageStyle]}
+                    shouldReannounceOnSubmit
                 >
                     {content}
                 </FormHelpMessage>

src/components/FormHelpMessage.tsx

@@ -1,5 +1,5 @@
 import isEmpty from 'lodash/isEmpty';
-import React, {useMemo} from 'react';
+import React, {useContext, useMemo} from 'react';
 import type {StyleProp, ViewStyle} from 'react-native';
 import {View} from 'react-native';
 import useAccessibilityAnnouncement from '@hooks/useAccessibilityAnnouncement';
@@ -9,6 +9,7 @@ import useThemeStyles from '@hooks/useThemeStyles';
 import getPlatform from '@libs/getPlatform';
 import Parser from '@libs/Parser';
 import CONST from '@src/CONST';
+import FormContext from './Form/FormContext';
 import Icon from './Icon';
 import RenderHTML from './RenderHTML';
 import Text from './Text';
@@ -37,6 +38,11 @@ type FormHelpMessageProps = {
 
     /** Native ID for accessibility association (aria-describedby) */
     nativeID?: string;
+
+    /** Whether this message should be re-announced on repeated form submissions.
+     *  All error messages announce on first appearance. This prop controls whether
+     *  the message also re-announces when the form is re-submitted with the same errors. */
+    shouldReannounceOnSubmit?: boolean;
 };
 
 function FormHelpMessage({
@@ -48,16 +54,41 @@ function FormHelpMessage({
     shouldRenderMessageAsHTML = false,
     isInfo = false,
     nativeID,
+    shouldReannounceOnSubmit = false,
 }: FormHelpMessageProps) {
     const theme = useTheme();
     const styles = useThemeStyles();
     const icons = useMemoizedLazyExpensifyIcons(['DotIndicator', 'Exclamation']);
+    const {getErrorAnnouncementKey} = useContext(FormContext);
+    const errorAnnouncementKey = getErrorAnnouncementKey();
+
     const isWeb = getPlatform() === CONST.PLATFORM.WEB;
     const shouldAnnounceError = isError && typeof message === 'string' && !!message && !shouldRenderMessageAsHTML && children == null;
     const shouldUseSeparateWebLiveAnnouncement = isWeb && !!nativeID && shouldAnnounceError;
     const visibleMessageRole = shouldUseSeparateWebLiveAnnouncement || !shouldAnnounceError ? undefined : CONST.ROLE.ALERT;
     const visibleMessageLiveRegion = shouldUseSeparateWebLiveAnnouncement || !shouldAnnounceError ? undefined : 'assertive';
 
+    const errorAnnouncementText = useMemo(() => {
+        if (!isError || typeof message !== 'string') {
+            return '';
+        }
+        const trimmedMessage = message.trim();
+        if (!trimmedMessage) {
+            return '';
+        }
+        return shouldRenderMessageAsHTML ? Parser.htmlToText(trimmedMessage) : trimmedMessage;
+    }, [isError, message, shouldRenderMessageAsHTML]);
+
+    const hasError = errorAnnouncementText.length > 0;
+
+    useAccessibilityAnnouncement(message, shouldAnnounceError);
+
+    // Re-announce on native via AccessibilityInfo when form is re-submitted
+    useAccessibilityAnnouncement(errorAnnouncementText, hasError && shouldReannounceOnSubmit && errorAnnouncementKey > 0, {
+        shouldAnnounceOnNative: true,
+        announcementKey: errorAnnouncementKey,
+    });
+
     const HTMLMessage = useMemo(() => {
         if (typeof message !== 'string' || !shouldRenderMessageAsHTML) {
             return '';
@@ -72,8 +103,6 @@ function FormHelpMessage({
         return `<muted-text-label>${replacedText}</muted-text-label>`;
     }, [isError, message, shouldRenderMessageAsHTML]);
 
-    useAccessibilityAnnouncement(message, shouldAnnounceError);
-
     const errorIconLabel = isError && shouldShowRedDotIndicator ? CONST.ACCESSIBILITY_LABELS.ERROR : undefined;
 
     if (isEmpty(message) && isEmpty(children)) {
@@ -111,17 +140,13 @@ function FormHelpMessage({
                             style={[isError ? styles.formError : styles.formHelp, styles.mb0]}
                             nativeID={nativeID}
                             role={visibleMessageRole}
-                            // TalkBack on some Android versions skips role-only alert announcements,
-                            // so keep native accessibilityRole/live-region as a platform fallback.
                             accessibilityRole={!isWeb && shouldAnnounceError ? CONST.ROLE.ALERT : undefined}
                             accessibilityLiveRegion={visibleMessageLiveRegion}
                         >
                             {message}
                         </Text>
                     ))}
                 {shouldUseSeparateWebLiveAnnouncement && (
-                    // Keep a separate live region for immediate web announcements without
-                    // changing the visible described text Safari relies on when refocusing inputs.
                     <Text
                         style={styles.hiddenElementOutsideOfWindow}
                         role={CONST.ROLE.ALERT}
@@ -130,6 +155,15 @@ function FormHelpMessage({
                         {message}
                     </Text>
                 )}
+                {isWeb && shouldReannounceOnSubmit && hasError && errorAnnouncementKey > 0 && (
+                    <Text
+                        key={`reannounce-${errorAnnouncementKey}`}
+                        style={styles.hiddenElementOutsideOfWindow}
+                        role={CONST.ROLE.ALERT}
+                    >
+                        {errorAnnouncementText}
+                    </Text>
+                )}
             </View>
         </View>
     );

src/hooks/useAccessibilityAnnouncement/index.ios.ts

@@ -8,14 +8,18 @@ const DELAY_FOR_ACCESSIBILITY_TREE_SYNC = 100;
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 function useAccessibilityAnnouncement(message: string | ReactNode, shouldAnnounceMessage: boolean, _options?: UseAccessibilityAnnouncementOptions) {
     const previousAnnouncedMessageRef = useRef('');
+    const previousKeyRef = useRef(_options?.announcementKey);
 
     useEffect(() => {
         if (!shouldAnnounceMessage || typeof message !== 'string' || !message.trim()) {
             previousAnnouncedMessageRef.current = '';
             return;
         }
 
-        if (previousAnnouncedMessageRef.current === message) {
+        const keyChanged = _options?.announcementKey !== undefined && _options.announcementKey !== previousKeyRef.current;
+        previousKeyRef.current = _options?.announcementKey;
+
+        if (!keyChanged && previousAnnouncedMessageRef.current === message) {
             return;
         }
 
@@ -26,8 +30,9 @@ function useAccessibilityAnnouncement(message: string | ReactNode, shouldAnnounc
             AccessibilityInfo.announceForAccessibility(message);
         }, DELAY_FOR_ACCESSIBILITY_TREE_SYNC);
 
+        // eslint-disable-next-line consistent-return
         return () => clearTimeout(timeout);
-    }, [message, shouldAnnounceMessage]);
+    }, [message, shouldAnnounceMessage, _options?.announcementKey]);
 }
 
 export default useAccessibilityAnnouncement;

src/hooks/useAccessibilityAnnouncement/index.native.ts

@@ -5,6 +5,7 @@ import type UseAccessibilityAnnouncementOptions from './types';
 
 function useAccessibilityAnnouncement(message: string | ReactNode, shouldAnnounceMessage: boolean, options?: UseAccessibilityAnnouncementOptions) {
     const previousAnnouncedMessageRef = useRef('');
+    const previousKeyRef = useRef(options?.announcementKey);
     const shouldAnnounceOnNative = options?.shouldAnnounceOnNative ?? false;
 
     useEffect(() => {
@@ -13,13 +14,16 @@ function useAccessibilityAnnouncement(message: string | ReactNode, shouldAnnounc
             return;
         }
 
-        if (previousAnnouncedMessageRef.current === message) {
+        const keyChanged = options?.announcementKey !== undefined && options.announcementKey !== previousKeyRef.current;
+        previousKeyRef.current = options?.announcementKey;
+
+        if (!keyChanged && previousAnnouncedMessageRef.current === message) {
             return;
         }
 
         previousAnnouncedMessageRef.current = message;
         AccessibilityInfo.announceForAccessibility(message);
-    }, [message, shouldAnnounceMessage, shouldAnnounceOnNative]);
+    }, [message, shouldAnnounceMessage, shouldAnnounceOnNative, options?.announcementKey]);
 }
 
 export default useAccessibilityAnnouncement;

src/hooks/useAccessibilityAnnouncement/types.ts

@@ -1,6 +1,7 @@
 type UseAccessibilityAnnouncementOptions = {
     shouldAnnounceOnNative?: boolean;
     shouldAnnounceOnWeb?: boolean;
+    announcementKey?: number;
 };
 
 export default UseAccessibilityAnnouncementOptions;