fix: Screen Reader: Global: Focus is lost when returning to the previous screen

knip.json

@@ -52,6 +52,7 @@
     },
     "ignoreDependencies": [
         "@expensify/react-native-hybrid-app",
+        "focus-trap",
         "group-ib-fp",
         "react-native-image-size",
         "react-native-picker-select",

src/components/DialogLabelContext.tsx

@@ -1,5 +1,6 @@
-import React, {createContext, useContext, useRef} from 'react';
+import React, {createContext, useContext, useEffect, useLayoutEffect, useRef} from 'react';
 import type {View} from 'react-native';
+import isHTMLElement from '@libs/isHTMLElement';
 
 type LabelEntry = {id: number; text: string};
 
@@ -27,18 +28,34 @@ const DialogLabelActionsContext = createContext<DialogLabelActions>({
 
 type DialogLabelProviderProps = {
     children: React.ReactNode;
-    containerRef: React.RefObject<View | null>;
+    /** Pass via `useState`/callback-ref so the provider observes node identity changes; a `RefObject` would pin the MutationObserver to the original node across Animated.View remounts. */
+    containerNode: View | HTMLElement | null;
 };
 
-function DialogLabelProvider({children, containerRef}: DialogLabelProviderProps) {
+// Title-stack and initial-focus claim are co-located: each pushLabel re-arms the focus claim so a sub-screen re-receives initial focus.
+function DialogLabelProvider({children, containerNode}: DialogLabelProviderProps) {
     const nextIdRef = useRef(0);
     const labelStackRef = useRef<LabelEntry[]>([]);
     const initialFocusClaimedRef = useRef(false);
+    // Stable RefObject for `.current` consumers (e.g. useDialogContainerFocus reads inside a rAF after node swaps).
+    const containerRef = useRef<View | null>(null);
+    useLayoutEffect(() => {
+        containerRef.current = (containerNode as View | null) ?? null;
+    }, [containerNode]);
 
     const updateContainerLabel = () => {
+        if (typeof document === 'undefined') {
+            return;
+        }
         const top = labelStackRef.current.at(-1);
-        const node = containerRef.current as unknown as HTMLElement | null;
-        if (!node || typeof node.setAttribute !== 'function') {
+        const node = containerRef.current;
+        if (!isHTMLElement(node)) {
+            return;
+        }
+        // aria-label on a container without dialog semantics is ignored; skip the set on mobile where the RHP has no dialog role.
+        const hasDialogSemantics = node.getAttribute('role') === 'dialog' || node.getAttribute('aria-modal') === 'true';
+        if (!hasDialogSemantics) {
+            node.removeAttribute('aria-label');
             return;
         }
         if (top?.text) {
@@ -61,6 +78,19 @@ function DialogLabelProvider({children, containerRef}: DialogLabelProviderProps)
         updateContainerLabel();
     };
 
+    // Observe `role`/`aria-modal` so a viewport-resize flip re-applies the label; the initial call back-fills labels pushed by child effects before this parent effect ran.
+    useEffect(() => {
+        if (typeof MutationObserver === 'undefined' || !isHTMLElement(containerNode)) {
+            return;
+        }
+        const observer = new MutationObserver(updateContainerLabel);
+        observer.observe(containerNode, {attributes: true, attributeFilter: ['role', 'aria-modal']});
+        updateContainerLabel();
+        return () => {
+            observer.disconnect();
+        };
+    }, [containerNode, updateContainerLabel]);
+
     const claimInitialFocus = (): boolean => {
         if (initialFocusClaimedRef.current) {
             return false;

src/components/FocusTrap/FocusTrapForModal/index.web.tsx

@@ -1,9 +1,10 @@
 import {FocusTrap} from 'focus-trap-react';
 import React, {useRef} from 'react';
-import sharedTrapStack from '@components/FocusTrap/sharedTrapStack';
 import blurActiveElement from '@libs/Accessibility/blurActiveElement';
-import {scheduleClearActivePopoverLauncher, setActivePopoverLauncher} from '@libs/LauncherStack';
+import {markActivePopoverLauncherDeactivated, setActivePopoverLauncher} from '@libs/LauncherStack';
 import ReportActionComposeFocusManager from '@libs/ReportActionComposeFocusManager';
+import restoreFocusWithModality from '@libs/restoreFocusWithModality';
+import sharedTrapStack from '@libs/sharedTrapStack';
 import type FocusTrapForModalProps from './FocusTrapForModalProps';
 
 function FocusTrapForModal({children, active, initialFocus = false, shouldPreventScroll = false, shouldReturnFocus = true}: FocusTrapForModalProps) {
@@ -28,24 +29,19 @@ function FocusTrapForModal({children, active, initialFocus = false, shouldPreven
                     if (!launcher) {
                         return;
                     }
-                    // Deferred so popover paths that navigate after modal-hide can still consume.
-                    scheduleClearActivePopoverLauncher(launcher);
+                    // Mark first so a throw in restoreFocusWithModality can't leak the LauncherStack entry; the deferred clear keeps the post-hide capture window.
+                    markActivePopoverLauncherDeactivated(launcher);
+                    if (shouldReturnFocus && !ReportActionComposeFocusManager.isFocused() && document.contains(launcher)) {
+                        restoreFocusWithModality(launcher, {preventScroll: shouldPreventScroll});
+                    }
                 },
                 preventScroll: shouldPreventScroll,
                 trapStack: sharedTrapStack,
                 clickOutsideDeactivates: true,
                 initialFocus,
                 // Lazy so document.body isn't evaluated at render time (SSR-safe).
                 fallbackFocus: () => document.body,
-                setReturnFocus: (element) => {
-                    if (ReportActionComposeFocusManager.isFocused()) {
-                        return false;
-                    }
-                    if (shouldReturnFocus) {
-                        return element;
-                    }
-                    return false;
-                },
+                setReturnFocus: false,
             }}
         >
             {children}

src/components/FocusTrap/FocusTrapForScreen/index.web.tsx

@@ -1,12 +1,12 @@
 import {useIsFocused, useRoute} from '@react-navigation/native';
 import {FocusTrap} from 'focus-trap-react';
 import React, {useMemo} from 'react';
-import sharedTrapStack from '@components/FocusTrap/sharedTrapStack';
 import TOP_TAB_SCREENS from '@components/FocusTrap/TOP_TAB_SCREENS';
 import WIDE_LAYOUT_INACTIVE_SCREENS from '@components/FocusTrap/WIDE_LAYOUT_INACTIVE_SCREENS';
 import useResponsiveLayout from '@hooks/useResponsiveLayout';
 import {isCancellingDndKeyboardDrag} from '@libs/cancelDndKeyboardDrag';
 import {isSidebarScreenName} from '@libs/Navigation/helpers/isNavigatorName';
+import sharedTrapStack from '@libs/sharedTrapStack';
 import CONST from '@src/CONST';
 import type FocusTrapProps from './FocusTrapProps';
 

src/components/HeaderWithBackButton/index.tsx

@@ -13,6 +13,7 @@ import SidePanelButton from '@components/SidePanel/SidePanelButton';
 import ThreeDotsMenu from '@components/ThreeDotsMenu';
 import Tooltip from '@components/Tooltip';
 import useDialogLabelRegistration from '@hooks/useDialogLabelRegistration';
+import useInitialFocusRef from '@hooks/useInitialFocusRef';
 import useIsInLandscapeMode from '@hooks/useIsInLandscapeMode';
 import {useMemoizedLazyExpensifyIcons} from '@hooks/useLazyAsset';
 import useLocalize from '@hooks/useLocalize';
@@ -90,6 +91,7 @@ function HeaderWithBackButton({
     const [isDownloadButtonActive, temporarilyDisableDownloadButton] = useThrottledButtonState();
     const {translate} = useLocalize();
     const isInLandscapeMode = useIsInLandscapeMode();
+    const setBackButtonRef = useInitialFocusRef({shouldSkip: shouldSkipFocusAfterTransition});
 
     const downloadReasonAttributes = useMemo<SkeletonSpanReasonAttributes>(
         () => ({
@@ -244,6 +246,7 @@ function HeaderWithBackButton({
                 {shouldShowBackButton && (
                     <Tooltip text={translate('common.back')}>
                         <PressableWithoutFeedback
+                            ref={setBackButtonRef}
                             onPress={() => {
                                 if (Keyboard.isVisible()) {
                                     Keyboard.dismiss();

src/components/MoneyRequestConfirmationList/sections/TaxFields.tsx

@@ -121,7 +121,8 @@ function TaxFields({policy, policyForMovingExpenses, iouCurrencyCode, canModifyT
     return (
         <>
             <MenuItemWithTopDescription
-                key={`${taxRates?.name}${taxRateTitle}`}
+                key={`${taxRates?.name}_rate`}
+                pressableTestID={`${taxRates?.name}_rate`}
                 shouldShowRightIcon={canModifyTaxFields}
                 title={taxRateTitle}
                 description={taxRates?.name}
@@ -160,7 +161,8 @@ function TaxFields({policy, policyForMovingExpenses, iouCurrencyCode, canModifyT
                 </View>
             ) : (
                 <MenuItemWithTopDescription
-                    key={`${taxRates?.name}${formattedTaxAmount}`}
+                    key={`${taxRates?.name}_amount`}
+                    pressableTestID={`${taxRates?.name}_amount`}
                     shouldShowRightIcon={canModifyTaxFields}
                     title={formattedTaxAmount}
                     description={translate('iou.taxAmount')}

src/components/Pressable/GenericPressable/implementation/BaseGenericPressable.tsx

@@ -1,16 +1,18 @@
-import type {ForwardedRef} from 'react';
-import React, {useCallback, useMemo, useState} from 'react';
+import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react';
 import type {GestureResponderEvent, View} from 'react-native';
 // eslint-disable-next-line no-restricted-imports
 import {Pressable} from 'react-native';
 import type {ValueOf} from 'type-fest';
 import type PressableProps from '@components/Pressable/GenericPressable/types';
 import useKeyboardShortcut from '@hooks/useKeyboardShortcut';
+import useRouteKey from '@hooks/useRouteKey';
 import useSingleExecution from '@hooks/useSingleExecution';
 import useStyleUtils from '@hooks/useStyleUtils';
 import useThemeStyles from '@hooks/useThemeStyles';
 import Accessibility from '@libs/Accessibility';
 import HapticFeedback from '@libs/HapticFeedback';
+import mergeRefs from '@libs/mergeRefs';
+import {notifyPressedTrigger, registerPressable} from '@libs/NavigationFocusReturn';
 import CONST from '@src/CONST';
 
 function GenericPressable({
@@ -47,9 +49,23 @@ function GenericPressable({
     const StyleUtils = useStyleUtils();
     const {isExecuting, singleExecution} = useSingleExecution();
     const isScreenReaderActive = Accessibility.useScreenReaderStatus();
+    const screenReaderState = Accessibility.useScreenReaderState();
     const [hitSlop, onLayout] = Accessibility.useAutoHitSlop();
     const [isHovered, setIsHovered] = useState(false);
     const isRoleButton = [rest.accessibilityRole, rest.role].includes(CONST.ROLE.BUTTON);
+    const internalRef = useRef<View | null>(null);
+    const composedRef = useMemo(() => mergeRefs(ref, internalRef), [ref]);
+    const routeKey = useRouteKey();
+    // `||` so empty strings skip — never key off an empty prop.
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+    const focusIdentifier = rest.id || rest.nativeID || rest.testID || undefined;
+
+    useEffect(() => {
+        if (screenReaderState === 'disabled' || !routeKey || !focusIdentifier) {
+            return;
+        }
+        return registerPressable(routeKey, focusIdentifier, internalRef);
+    }, [screenReaderState, routeKey, focusIdentifier]);
 
     const isDisabled = useMemo(() => {
         let shouldBeDisabledByScreenReader = false;
@@ -123,9 +139,10 @@ function GenericPressable({
                 ref.current?.blur();
                 Accessibility.moveAccessibilityFocus(nextFocusRef);
             }
+            notifyPressedTrigger(internalRef, focusIdentifier);
             return onPress(event);
         },
-        [shouldUseHapticsOnPress, onPress, nextFocusRef, ref, isDisabled, interactive],
+        [shouldUseHapticsOnPress, onPress, nextFocusRef, ref, isDisabled, interactive, focusIdentifier],
     );
 
     const voidOnPressHandler = useCallback(
@@ -176,7 +193,7 @@ function GenericPressable({
         <Pressable
             hitSlop={shouldUseAutoHitSlop ? hitSlop : undefined}
             onLayout={shouldUseAutoHitSlop ? onLayout : undefined}
-            ref={ref as ForwardedRef<View>}
+            ref={composedRef}
             disabled={fullDisabled || undefined}
             onPress={!isDisabled ? singleExecution(onPressHandler) : undefined}
             onLongPress={!isDisabled && onLongPress ? onLongPressHandler : undefined}

src/components/Search/SearchRouter/SearchButton.tsx

@@ -1,5 +1,5 @@
-import React, {useRef} from 'react';
-import type {StyleProp, View, ViewStyle} from 'react-native';
+import React from 'react';
+import type {StyleProp, ViewStyle} from 'react-native';
 import Icon from '@components/Icon';
 import {PressableWithoutFeedback} from '@components/Pressable';
 import Tooltip from '@components/Tooltip';
@@ -24,13 +24,10 @@ function SearchButton({style, shouldUseAutoHitSlop = false}: SearchButtonProps)
     const theme = useTheme();
     const {translate} = useLocalize();
     const {openSearchRouter} = useSearchRouterActions();
-    const pressableRef = useRef<View>(null);
     const expensifyIcons = useMemoizedLazyExpensifyIcons(['MagnifyingGlass']);
 
     const onPress = () => {
         callFunctionIfActionIsAllowed(() => {
-            pressableRef.current?.blur();
-
             startSpan(CONST.TELEMETRY.SPAN_OPEN_SEARCH_ROUTER, {
                 name: CONST.TELEMETRY.SPAN_OPEN_SEARCH_ROUTER,
                 op: CONST.TELEMETRY.SPAN_OPEN_SEARCH_ROUTER,
@@ -48,7 +45,6 @@ function SearchButton({style, shouldUseAutoHitSlop = false}: SearchButtonProps)
     return (
         <Tooltip text={translate('common.search')}>
             <PressableWithoutFeedback
-                ref={pressableRef}
                 testID="searchButton"
                 accessibilityLabel={translate('common.search')}
                 role={CONST.ROLE.BUTTON}

src/components/SpendRules/configuration/SpendRuleMerchantEditBase.tsx

@@ -15,6 +15,7 @@ import useAutoFocusInput from '@hooks/useAutoFocusInput';
 import useCanWriteCardSpendRules from '@hooks/useCanWriteCardSpendRules';
 import useLocalize from '@hooks/useLocalize';
 import useThemeStyles from '@hooks/useThemeStyles';
+import {skipNextFocusRestore} from '@libs/NavigationFocusReturn';
 import AccessOrNotFoundWrapper from '@pages/workspace/AccessOrNotFoundWrapper';
 import CONST from '@src/CONST';
 import ONYXKEYS from '@src/ONYXKEYS';
@@ -76,6 +77,8 @@ function SpendRuleMerchantEditBase({policyID, merchantIndex, merchantMatchTypes,
                 const updatedMerchantMatchTypes = merchantMatchTypes.filter((_, merchantArrayIndex) => merchantArrayIndex !== index);
                 onMerchantDataChange(updatedMerchantNames, updatedMerchantMatchTypes);
             }
+            // Skip on every submit-driven goBack — the parent list has its own Save button, and a re-focused row would hijack the next Enter.
+            skipNextFocusRestore();
             goBack();
             return;
         }
@@ -89,6 +92,7 @@ function SpendRuleMerchantEditBase({policyID, merchantIndex, merchantMatchTypes,
             : merchantMatchTypes.map((type, merchantArrayIndex) => (merchantArrayIndex === index ? matchType : type));
 
         onMerchantDataChange(updatedMerchantNames, updatedMerchantMatchTypes);
+        skipNextFocusRestore();
         goBack();
     };
 

src/components/SpendRules/configuration/SpendRuleMerchantsBase.tsx

@@ -17,15 +17,19 @@ import CONST from '@src/CONST';
 import type {Route} from '@src/ROUTES';
 import ROUTES from '@src/ROUTES';
 
+type SpendRuleMerchant = {
+    name: string;
+    matchType: ValueOf<typeof CONST.SEARCH.SYNTAX_OPERATORS> | undefined;
+};
+
 type SpendRuleMerchantsBaseProps = {
     policyID: string;
     action: string;
-    merchantNames: string[];
-    merchantMatchTypes: Array<ValueOf<typeof CONST.SEARCH.SYNTAX_OPERATORS>>;
+    merchants: SpendRuleMerchant[];
     getEditMerchantRoute: (merchantIndex: string) => Route;
 };
 
-function SpendRuleMerchantsBase({policyID, action, merchantMatchTypes, merchantNames, getEditMerchantRoute}: SpendRuleMerchantsBaseProps) {
+function SpendRuleMerchantsBase({policyID, action, merchants, getEditMerchantRoute}: SpendRuleMerchantsBaseProps) {
     const styles = useThemeStyles();
     const {translate} = useLocalize();
     const expensifyIcons = useMemoizedLazyExpensifyIcons(['Plus']);
@@ -76,23 +80,27 @@ function SpendRuleMerchantsBase({policyID, action, merchantMatchTypes, merchantN
                         titleStyle={styles.textStrong}
                         onPress={addMerchant}
                     />
-                    {merchantNames.length > 0 ? (
-                        merchantNames.map((merchantName, index) => (
-                            <MenuItemWithTopDescription
-                                // eslint-disable-next-line react/no-array-index-key
-                                key={`${merchantName}-${merchantMatchTypes.at(index) ?? ''}-${index}`}
-                                description={
-                                    merchantMatchTypes.at(index) === CONST.SEARCH.SYNTAX_OPERATORS.EQUAL_TO
-                                        ? translate('workspace.rules.spendRules.merchantExactlyMatches')
-                                        : translate('workspace.rules.spendRules.merchantContains')
-                                }
-                                onPress={() => navigateToMerchantEdit(String(index))}
-                                shouldShowRightIcon
-                                title={merchantName}
-                                titleStyle={styles.flex1}
-                                sentryLabel={CONST.SENTRY_LABEL.WORKSPACE.RULES.MERCHANT_RULE_SECTION_ITEM}
-                            />
-                        ))
+                    {merchants.length > 0 ? (
+                        merchants.map(({name, matchType}, index) => {
+                            // `name`/`matchType` are edited on the detail screen — keying by content would remount the row on save and lose the captured focus-return target. No per-merchant backend ID.
+                            const rowId = `merchant-${index}`;
+                            return (
+                                <MenuItemWithTopDescription
+                                    key={rowId}
+                                    pressableTestID={rowId}
+                                    description={
+                                        matchType === CONST.SEARCH.SYNTAX_OPERATORS.EQUAL_TO
+                                            ? translate('workspace.rules.spendRules.merchantExactlyMatches')
+                                            : translate('workspace.rules.spendRules.merchantContains')
+                                    }
+                                    onPress={() => navigateToMerchantEdit(String(index))}
+                                    shouldShowRightIcon
+                                    title={name}
+                                    titleStyle={styles.flex1}
+                                    sentryLabel={CONST.SENTRY_LABEL.WORKSPACE.RULES.MERCHANT_RULE_SECTION_ITEM}
+                                />
+                            );
+                        })
                     ) : (
                         <BlockingView
                             icon={illustrations.FoodTruck}