fix: Screen Reader: Global: Focus is lost when returning to the previous screen by TaduJR · Pull Request #91752 · Expensify/App

TaduJR · 2026-05-26T19:12:31Z

Explanation of Change

When a screen-reader user navigates back, focus now returns to the row they tapped to go forward (WCAG 2.4.3). Also fixes WCAG 2.4.7 (Focus Visible) on touch initial-focus and modal close.

Approach. On press, we record the element + its identifier against the screen the user is leaving. On back navigation, after the transition settles, we re-fire accessibility focus on that element. If react-native-screens detached the original view, a per-screen registry resolves the live re-mounted one by identifier. Bounded retry budget covers slow re-attach. Sighted users pay nothing the pipeline short-circuits when the screen reader is known-off.

Native rescue (new) capture on press, restore after transition, registry fallback for detached views, retry budget for slow re-attach.
Web rescue (refactor) migrated off the deprecated InteractionManager onto TransitionTracker. Also fixes a latent ~1s back-nav stall.
Focus priority all focus claimers go through one arbiter so the next screen's autofocus can't trample the restore.
Stable row identity 6 pages re-keyed off value-derived React keys so the captured row doesn't remount on every edit.
Save-and-close submit-driven goBack skips restore so a re-focused row can't hijack the destination form's Save button.

Fixed Issues

$ #77411
PROPOSAL:

Tests

1. Going back returns focus to the item you opened

Turn the screen reader ON.
Go to Account (Settings) → Profile → Display name.
On the Display name screen, activate the Back button.
Expected: focus goes back to the Display name row and the screen reader reads it out. Focus is not lost or silent.
Repeat from a few other screens (e.g. Profile → Contact methods, then back) and confirm focus always returns to the row or button you opened.

2. Same behavior inside Workspace settings

Screen reader ON.
Go to Settings → Workspaces → [a workspace] and open any settings sub-page (e.g. More features, Members, Categories).
Open a row from there, then activate Back.
Expected: focus returns to the exact row you opened — not the Back button and not the top of the screen.

3. Opening a screen announces it

On Android Chrome or iOS Safari, screen reader ON.
Navigate into a settings screen (e.g. Account → Profile → Display name).
Expected: once the screen finishes opening, the screen reader automatically announces the screen (focus lands on the Back button). Before, nothing was announced on open.
Confirm the page does not jump or scroll when the screen opens.

Verify that no errors appear in the JS console

Offline tests

Same as tests

QA Steps

// TODO: These must be filled out, or the issue title must include "[No QA]."
Same as tests

Verify that no errors appear in the JS console

PR Author Checklist

Screenshots/Videos

Android: Native

Android-Native-1.mp4

Android: mWeb Chrome

Android-mWeb-2.mp4

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

Mac-Chrome.mp4

…ous screen

melvin-bot · 2026-05-26T19:12:40Z

@marufsharifi Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

TaduJR · 2026-05-26T19:13:14Z

cc @mkhutornyi

codecov · 2026-05-26T19:21:34Z

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines	Coverage Δ
...mponents/FocusTrap/FocusTrapForModal/index.web.tsx	`100.00% <100.00%> (+27.77%)`	⬆️
...ponents/FocusTrap/FocusTrapForScreen/index.web.tsx	`0.00% <ø> (ø)`
src/components/HeaderWithBackButton/index.tsx	`89.21% <100.00%> (+0.10%)`	⬆️
...oneyRequestConfirmationList/sections/TaxFields.tsx	`81.81% <100.00%> (+0.33%)`	⬆️
...cPressable/implementation/BaseGenericPressable.tsx	`80.99% <100.00%> (+1.71%)`	⬆️
...rc/components/Search/SearchRouter/SearchButton.tsx	`100.00% <ø> (ø)`
...dRules/configuration/SpendRuleMerchantEditBase.tsx	`100.00% <ø> (+100.00%)`	⬆️
src/components/SubStepForms/ConfirmationStep.tsx	`95.45% <100.00%> (+95.45%)`	⬆️
src/components/Table/TableRow.tsx	`75.32% <100.00%> (+0.32%)`	⬆️
src/hooks/useActiveElementRole/index.ts	`100.00% <ø> (ø)`
... and 39 more
... and 12 files with indirect coverage changes

… dedup native teardown

… SR listener

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

…LITY_FOCUS

…efocus

… native)

…le probe

…ndle leak, focusKey prop

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

MelvinBot · 2026-06-25T05:11:46Z

Code Review (re-review @ `96a6a0c`)

I re-reviewed the full focus architecture (web + native) at the latest commit with three parallel reviewers reading the post-PR files in full. No blockers. Every item from my earlier passes is resolved, and the newest commit's native retry-loop changes check out:

✅ Native crash-guard — fireFocusEvent now wraps sendAccessibilityEvent in try/catch + Log.warn, and scheduleRefocus routes through it (fireFocusEvent/index.native.ts:8-13).
✅ restoreFocusWithModality trap balance — now records wasAlreadyPaused and only unpauses the captured trap when it actually paused it (restoreFocusWithModality.ts:9-23).
✅ Native back-nav churn for sighted users — scheduleRestore early-returns on isScreenReaderKnownOff() before any transition wait / rAF / Log.warn (index.native.ts:156-159).
✅ Newest commit's retry loop — MAX_RESTORE_FRAMES budget is exactly 5 (no off-by-one), every rAF/transition handle is cancelled by the single arm-time pendingRestore.cancel closure, the rawRouteKey split is correctly hoisted out of the loop, and FIFO cap + per-removed-key pruning prevent map growth.

One thing worth a quick look before merge (Low)

useInitialFocusRef returns a non-memoized ref callback. useInitialFocusRef/index.ts:7-14 allocates a fresh arrow each render, so at the source level React detaches (null) then re-attaches the ref every commit, re-running the useScreenInitialFocus effect and restarting its rAF claim loop before the first claim lands. React Compiler memoizes this in the shipped build (the only dep, setNode, is stable), so there's no production impact — but the code reads as buggy and correctness silently depends on the compiler. Wrapping the returned callback in useCallback([]) (the functional setNode updater needs no deps) makes it robust regardless. Used on HeaderWithBackButton and HeaderView.

Cosmetic nits (non-blocking) + areas confirmed clean

Cosmetic

restoreFocusWithModality.ts:18 — the comment still says the unpause is "Unconditional", but the code is now guarded by !wasAlreadyPaused. Update the comment to avoid future confusion.
ConfirmationStep key fallback ${description}-${index} can't collide (index always disambiguates within one array); the only effect of the documented index-shift caveat is a harmless remount of a static display row when a conditional toggles — no captured input/focus state is lost. Informational only.

Confirmed clean (read in full, not just the patch)

Web core (NavigationFocusReturn/index.ts, ScreenFocusArbiter, claimInitialFocus, programmaticFocus, LauncherStack, FocusTrapForModal, navigationStateDiff): listener/timer lifecycle is balanced (every addEventListener/setTimeout/rAF has a matching teardown), arbiter priority logic (AUTO > INITIAL, lazy cycle expiry) is internally consistent, LauncherStack's in-loop splice iterates descending (safe), and SSR/typeof document guards are present on every DOM entry point.
Enter-to-submit safety on IOU forms: the back-button INITIAL claim can't hijack the auto-focused input — claimInitialFocus bails when activeElement !== body, and AUTO preempts INITIAL in the arbiter. The shouldSkipFocusRestore: !isEditing flip on Merchant/Description is correct for create/edit/split (isEditing derives from the immutable action route param and is snapshotted at arm time).
Native registries: triggerMap FIFO-capped at 64 with compound-prefix pruning per removed route key; pressableRegistry correctly keyed only by raw route keys (no compound pruning needed) and bounded by per-pressable unmount unsubscribe. No unbounded growth.
key / pressableTestID stabilizations (TaxFields, SpendRuleMerchantsBase, ConfirmationStep): no collisions, no incorrect remounts.
SearchButton dropping its self-blur is deliberate and correct — the trigger must retain focus for captureTriggerForRoute to restore it on close.

Next Steps: Reply with @MelvinBot <your feedback> to dig into any of these.

TaduJR · 2026-06-25T05:13:09Z

One thing worth a quick look before merge (Low)
useInitialFocusRef returns a non-memoized ref callback. useInitialFocusRef/index.ts:7-14 allocates a fresh arrow each render, so at the source level React detaches (null) then re-attaches the ref every commit, re-running the useScreenInitialFocus effect and restarting its rAF claim loop before the first claim lands. React Compiler memoizes this in the shipped build (the only dep, setNode, is stable), so there's no production impact — but the code reads as buggy and correctness silently depends on the compiler. Wrapping the returned callback in useCallback([]) (the functional setNode updater needs no deps) makes it robust regardless. Used on HeaderWithBackButton and HeaderView.

Same as Codex. Invalid

TaduJR · 2026-06-25T12:55:45Z

@roryabraham

1. What problem are we solving?

When a screen-reader user (TalkBack / VoiceOver) navigates forward by tapping a row, then navigates back, focus should land on the row they tapped so the screen reader can announce it again. Today it doesn't; focus collapses to the screen root / <body>, the screen reader has nothing to announce, and the user loses their place. Issue #77411 fails WCAG 2.4.3 (Focus Order).

2. What's the simplest naive solution, and why doesn't it work?

Naive solution A "just call .focus() after going back."
React Native has no JS event for accessibility focus, and react-native-screens can detach the prior screen's host views, nulling the JS ref of the element we want to refocus. So we can't just hold the ref and call .focus() later.

Naive solution B "use the right navigation library; @react-navigation/native-stack handles this."
This was Rushat's suggestion.

Apple's own View Controller Programming Guide Supporting Accessibility states: "When pushing a new view controller onto a navigation controller's stack, the VoiceOver cursor falls on the Back button of the navigation bar." The documented remedy is for the app to post UIAccessibilityScreenChangedNotification. UIKit's UINavigationController does not auto-restore prior focus. AOSP FragmentManager is the same.
We already use @react-navigation/native-stack on native (createPlatformStackNavigatorComponent.native.tsx wraps <NativeStackView>). It's a thin wrapper over react-native-screens, which mounts real UINavigationController / Fragment instances so we already inherit the system controller, and the bug still occurs.
Open community confirmations: react-navigation #11189 (the exact bug), #7056, #10468, #12724; react-native-screens #3147.

There is no library configuration that obviates the rescue. The contract has to live in the app.

3. What's the proposed solution?

A small, two-step rescue:

Capture. When a screen-reader user presses a row, we record {ref, identifier} against the screen they're navigating away from. The identifier is the row's existing id/nativeID/testID no new prop, no behavior change for sighted users.
Restore. When the user navigates back, we look up that capture and fire AccessibilityInfo.sendAccessibilityEvent(view, 'focus') once the navigation transition settles.

Web is the sibling that already shipped (PR #87852); this PR extends the same idea to native + closes a handful of mobile-web edges discovered along the way.

4. Can the PR be broken up?

I'd recommend keeping it as one PR. The diff looks large (82 files, +4486) but 76% of net additions are tests. Production code is 49 files / +945 net lines. We already achieved the core issue ~20th commit, but there were many edge cases to handle in review like flicking, slow navigation re-attach, form submit. We tried to covered every-possible cases.

cc @rushatgabhane

TaduJR · 2026-06-25T13:16:35Z

@mkhutornyi

PR is ready for re-review. I tried to test all possible cases again after refactor. I didn't find any issues.

All yours! LMK if there is from your side.

Both Codex and Melvin doesn't have any concerns to address.

Thanks so much for staying and supporting on this journey!

rushatgabhane · 2026-06-25T13:28:15Z

If it helps simplify the solution, we can solve this for native first and web later. what do you think? @TaduJR

TaduJR · 2026-06-25T13:30:58Z

If it helps simplify the solution, we can solve this for native first and web later. what do you think? @TaduJR

@rushatgabhane

Web is already implemented in this PR #87852 previously if you recalled.

Web is the sibling that already shipped (PR #87852); this PR extends the same idea to native + closes a handful of mobile-web edges discovered along the way.

rushatgabhane · 2026-06-25T13:38:02Z

ah cool

rushatgabhane · 2026-06-25T20:07:01Z

+ * Subscribers `.then()` it to catch the boot-race — the platform listener only fires on toggles, never on the initial state.
+ * `refresh()` invalidates the memo and re-warms; used on AppState resume to recover from toggles that fire while no JS listener was active.
+ */
+function makeWarmCache<T>(


Why do we need this function?
Should we use onyx instead of Set as our data structure

AccessibilityInfo.isScreenReaderEnabled() is async, but capture/restore in NavigationFocusReturn.native.ts runs synchronously inside onPress and the navigation reducer can't await. The platform screenReaderChanged listener only fires on toggles, never the initial state. makeWarmCache bridges this: eager warm at module load, sync accessor, AppState refresh, generation token to discard superseded fetches. Same shape applies to reduce-motion, so it's one helper instead of two.

Set and Onyx: The Set<() => void> holds useSyncExternalStore subscriber callbacks non-serializable React-renderer functions. Onyx can't store functions; Onyx itself uses Map/Set for its own subscriber registry. Persisting the cached boolean across launches would also be wrong OS-level SR state can change while the app is killed, and Onyx reads are async (defeats the sync cache). Established convention in this codebase: AgentZeroReasoningStore, NetworkState, RevealedCardSecretsStore all use the same Set + useSyncExternalStore pattern.

Onyx can't store functions

Why are we storing functions? Can we store the params to call those functions instead?

I thought we are storing the ID of a view, and focusing on it as per the simplified solution posted above

Two stores being conflated here. The Set in Accessibility/index.ts (screenReaderSubscribers) is NOT the view registry it's the useSyncExternalStore subscriber callback registry for the useScreenReaderStatus / useScreenReaderState hooks. When a component calls those hooks, React itself passes an opaque internal callback into our subscribe function; we keep it in the Set so we can notify React to re-read getSnapshot on AppState resume + warm-cache refresh. The callback takes zero arguments Set<() => void> there are no params to factor out the function IS React's notification protocol. Reimplementing it with IDs would mean rewriting useSyncExternalStore itself imo.

I see

A small, two-step rescue:

Capture. When a screen-reader user presses a row, we record {ref, identifier} against the screen they're navigating away from. The identifier is the row's existing id/nativeID/testID no new prop, no behavior change for sighted users.

Restore. When the user navigates back, we look up that capture and fire AccessibilityInfo.sendAccessibilityEvent(view, 'focus') once the navigation transition settles.

How does that fit in this?

That's the design already implemented in this PR

Should I continue explaining on how?

yes please, im trying to understand what the code does, and why are we doing things in the current way

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen # Conflicts: # src/pages/workspace/expensifyCard/WorkspaceExpensifyCardListPage.tsx

fix: Screen Reader: Global: Focus is lost when returning to the previ…

6c7e04d

…ous screen

TaduJR requested review from a team as code owners May 26, 2026 19:12

melvin-bot Bot assigned TaduJR May 26, 2026

melvin-bot Bot requested review from JmillsExpensify and marufsharifi and removed request for a team and marufsharifi May 26, 2026 19:12

TaduJR marked this pull request as draft May 26, 2026 19:13

github-actions Bot reviewed May 26, 2026

View reviewed changes

Comment thread src/libs/Accessibility/index.ts Outdated

github-actions Bot reviewed May 26, 2026

View reviewed changes

Comment thread src/libs/NavigationFocusReturn/index.native.ts

This comment was marked as resolved.

Sign in to view

TaduJR added 2 commits May 27, 2026 09:29

fix: cap stale press triggers; log Accessibility cache-warm failures;…

2d66e4e

… dedup native teardown

fix: Android forward auto-focus for mid-session TalkBack; consolidate…

6562712

… SR listener

This comment was marked as resolved.

Sign in to view

TaduJR added 4 commits May 27, 2026 12:01

fix: capture/restore focus on native PUSH_PARAMS via compound key

e4f3f8e

Merge branch 'main' of https://github.com/TaduJR/App into fix-Screen-…

068e3c7

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

fix: deterministic Android backward focus via native ACTION_ACCESSIBI…

394f13f

…LITY_FOCUS

fix: revert Android focus to sendAccessibilityEvent + idle-callback r…

75b0a42

…efocus

This comment was marked as resolved.

Sign in to view

chore: remove unused eslint-disable directives

e383907

This comment was marked as resolved.

Sign in to view

fix: clear trigger entry when skipNextFocusRestore is honoured (web +…

5645674

… native)

This comment was marked as resolved.

Sign in to view

This comment was marked as outdated.

Sign in to view

TaduJR added 8 commits June 24, 2026 11:16

fix: fall through to registry rescue when stale native handle throws

43c08c2

fix: fire fast + registry-rescue in parallel; drop boolean stale-hand…

02bde58

…le probe

fix: fall through to registry rescue when stale native handle throws

8d40270

fix: harden focus-return dialog viewport observer, save-arm count, ha…

5c22fbd

…ndle leak, focusKey prop

refactor: harden focus-return rescue, list keys, and transition handles

0a68193

fix: revert list keys; back-fill dialog label; re-arm save-nav

01ea0b9

fix: clear stale arm + skip-before-setter

91de9ca

fix: symmetric arm-time snapshot; hoist split out of retry loop

96a6a0c

This comment was marked as resolved.

Sign in to view

Merge branch 'main' of https://github.com/TaduJR/App into fix-Screen-…

c86f986

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

This comment was marked as resolved.

Sign in to view

TaduJR added 2 commits June 25, 2026 15:28

chore: add comments and some tests

9da0fc2

chore: knip

4fd277c

roryabraham requested changes Jun 25, 2026

View reviewed changes

Comment thread src/hooks/useInitialFocusRef.ts

Comment thread src/hooks/useScreenInitialFocus/types.ts Outdated

Comment thread src/hooks/useScreenInitialFocus/types.ts Outdated

Comment thread src/libs/Accessibility/index.ts Outdated

Comment thread src/libs/isEffectivelyVisible.ts

rushatgabhane suggested changes Jun 25, 2026

View reviewed changes

TaduJR added 4 commits June 26, 2026 18:37

Merge branch 'main' of https://github.com/TaduJR/App into fix-Screen-…

67592ac

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen

fix: defensive focus-return during screen-reader warm-up window

e7adc29

chore: drop unused ScreenReaderState type export

5d1d227

Merge branch 'main' of https://github.com/TaduJR/App into fix-Screen-…

8471c93

…Reader-Global-Focus-is-lost-when-returning-to-the-previous-screen # Conflicts: # src/pages/workspace/expensifyCard/WorkspaceExpensifyCardListPage.tsx

Uh oh!

Conversation

TaduJR commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Explanation of Change

Fixed Issues

Tests

Offline tests

QA Steps

PR Author Checklist

Screenshots/Videos

Uh oh!

melvin-bot Bot commented May 26, 2026

Uh oh!

TaduJR commented May 26, 2026

Uh oh!

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

codecov Bot commented May 26, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

This comment was marked as outdated.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

MelvinBot commented Jun 25, 2026

Code Review (re-review @ 96a6a0c)

One thing worth a quick look before merge (Low)

Uh oh!

TaduJR commented Jun 25, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

TaduJR commented Jun 25, 2026 • edited by roryabraham Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. What problem are we solving?

2. What's the simplest naive solution, and why doesn't it work?

3. What's the proposed solution?

4. Can the PR be broken up?

Uh oh!

TaduJR commented Jun 25, 2026

Uh oh!

rushatgabhane commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

TaduJR commented Jun 25, 2026

Uh oh!

rushatgabhane commented Jun 25, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rushatgabhane Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

TaduJR Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

rushatgabhane Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

TaduJR Jun 26, 2026

Choose a reason for hiding this comment

Uh oh!

rushatgabhane Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

TaduJR commented May 26, 2026 •

edited

Loading

codecov Bot commented May 26, 2026 •

edited by github-actions Bot

Loading

Code Review (re-review @ `96a6a0c`)

TaduJR commented Jun 25, 2026 •

edited by roryabraham

Loading

rushatgabhane commented Jun 25, 2026 •

edited

Loading

rushatgabhane Jun 26, 2026 •

edited

Loading