Refactor: flash list dom order improvement for simple lists

[sharabai]

Note

This PR depends on the FlashList natural-DOM-order patch PR (#91328) — that PR must be merged first.

Explanation of Change

What this fixes (user-visible). Continuous Tab navigation through long single-column selection lists (e.g. the currency picker reached via + → Create expense → tap the currency button) didn't work correctly together with the FlashList natural-DOM-order patch. Each Tab fired ListItemRenderer.onFocus → setFocusedIndex(N) (no scroll opt-out) → useArrowKeyFocusManager's onFocusedIndexChange effect → a programmatic scrollToIndex(N). From FlashList's perspective the resulting movement looked like keyboard-driven scrolling through useArrowKeyFocusManager, not Tab traversal — so the natural-DOM-order patch couldn't reliably treat the interaction as tabbing and DOM order drifted out of step with what Tab was doing. After this PR, ListItemRenderer.onFocus passes {shouldScroll: false}, so Tab no longer fires a programmatic scrollToIndex; FlashList sees the actual DOM Tab traversal and the natural-DOM-order patch behaves correctly across continuous tabbing.

Implementation note. Internally, the previous focus-management code suppressed unwanted scrolls via an imperative suppressNextFocusScrollRef flag that consumers had to flip at the right moment. This PR replaces that with an explicit setFocusedIndex(index, {shouldScroll}) option on useArrowKeyFocusManager, threaded through BaseSelectionList, BaseSelectionListWithSections, and useSearchFocusSync. ListItemRenderer.onFocus now passes {shouldScroll: false} so programmatic focus events never auto-scroll, and internal arrow-key handlers default to {shouldScroll: true}. The new declarative API should cover everything the suppress-ref pattern covered before — and may even be a touch more robust in corner cases where the imperative flag could fall out of sync with React state updates.

The primary target is CurrencySelectionList — a canonical single-column picker (no right-hand-side button, simple SingleSelectListItem rows). The same change benefits every similar single-column picker that uses SelectionListWithSections with a plain list item — currency picker, country picker, language picker, priority mode picker, tax picker, category/tag pickers, destination picker, debug constant picker, report-field initial-value picker, and the various workspace settings pickers (settlement frequency, statement close date, layout, etc.).

Fixed Issues

$ #86126
PROPOSAL:

Tests

Each test below exercises a specific code path that this PR rewrites. Test 1 is the user-visible fix; Tests 2–4 are regression checks on the other behaviors the old suppressNextFocusScrollRef flag was serving (their original test steps come from the merged PRs that introduced each behavior, linked inline).

Prerequisites: run these commands from project root before testing

rm -rf node_modules
npm i

1. Currency picker — continuous Tab navigation + arrow-key scroll into view (exercises ListItemRenderer.onFocus and useArrowKeyFocusManager's scroll gate — the actual fix).

   1. In the LHN, click the green "+" icon.
   2. Click "Create expense" (or "Track expense" — any flow that opens the expense form).
   3. In the expense form, click the button that shows the currency code (e.g. USD, EUR). The currency picker opens.
   4. Press Tab once to move focus from the search input onto the first currency row.
   5. Without touching the mouse, keep pressing Tab so focus walks down the list one row at a time. The row highlight should advance with focus exactly — no skipping, no flickering, no falling behind, no rows jumping under the cursor.
   6. Continue tabbing past the bottom of the visible area. The list should scroll the focused row into view smoothly and rows should stay in their visible top-to-bottom order as Tab keeps walking.
   7. Now press ArrowDown several times. The focused-row highlight should move down one row per press and the list should scroll to keep the focused row visible (i.e. the arrow-key scroll path is preserved).
   8. Press ArrowUp a few times — the focused row should walk back up and the list should scroll the other way to keep it visible.

2. Spend > Filters > Currency — typing in search scrolls to the top once, no double-bounce (exercises useSearchFocusSync + BaseSelectionListWithSections.onFocusedIndexChange, regression for #89498).

   1. Go to Spend > Expenses > Filters pill > Currency.
   2. Scroll well down the list and click any item.
   3. Verify the list does not jump/scroll unexpectedly on the click.
   4. Type a search query in the filter input.
   5. Verify the list scrolls to the top without a visible animated "bounce" (one scroll, not two).
   6. Clear the search input.
   7. Verify the list doesn't return to the previously selected item.
   8. Use ArrowUp/ArrowDown to navigate the list — the focused row should scroll into view.

3. Spend > Filters > Workspace — selecting items doesn't scroll or reorder (exercises BaseSelectionListWithSections.selectRow's {shouldScroll: false}, regression for #90121).

   Precondition: account with multiple workspaces.

   1. Go to Spend > Expenses > Filters pill > Workspace.
   2. Scroll down the list and click any workspace.
   3. Verify the selected item stays in place and the list does not scroll/jump to the top.
   4. Select additional items — verify no scroll jumping.
   5. Deselect an item — verify no scroll jumping and the item stays in its section.
   6. Save, close, and reopen the Workspace filter — verify the list scrolls to the first selected item on open.

4. Workspace > Categories — closing the category-detail RHP doesn't scroll the list (exercises BaseSelectionList.setFocusedIndexFromRowFocus + isFocusRestoreInProgress(), regression for #90869).

   1. Go to a workspace's Categories settings.
   2. Scroll down so the list is no longer at the top (any non-top scroll position is fine).
   3. Click any category in the list (the category-detail RHP opens).
   4. Click the RHP back button.
   5. Verify the categories list does not scroll on the way back, and focus returns to the row you clicked.

• Verify that no errors appear in the JS console

Offline tests

N/A — this is a focus-management refactor. No new API calls, Onyx writes, or offline-relevant code paths.

QA Steps

Same as Tests. macOS Chrome is the primary platform (keyboard-driven flows are where this refactor matters most); iOS Native, Android Native, and mWeb are regression-only — tap-to-focus rows should still highlight the tapped row without unexpected scrolling, and selection should still work.

• Verify that no errors appear in the JS console

PR Author Checklist

• I linked the correct issue in the ### Fixed Issues section above
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I added steps for the expected offline behavior in the Offline steps section
  • I added steps for Staging and/or Production testing in the QA steps section
  • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android: Native
  • Android: mWeb Chrome
  • iOS: Native
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I verified there are no new alerts related to the canBeMissing param for useOnyx
• I followed proper code patterns (see Reviewing the code)
  • I verified that any callback methods that were added or modified are named for what the method does and never what callback they handle (i.e. toggleReport and not onIconClick)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text shown in the product is localized by adding it to src/languages/* files and using the translation method
    • If any non-english text was added/modified, I used JaimeGPT to get English > Spanish translation. I then posted it in #expensify-open-source and it was approved by an internal Expensify engineer. Link to Slack message:
  • I verified all numbers, amounts, dates and phone numbers shown in the product are using the localization methods
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
  • I verified proper file naming conventions were followed for any new files or renamed files. All non-platform specific files are named after what they export and are not named "index.js". All platform-specific files are named for the platform the code supports as outlined in the README.
  • I verified the JSDocs style guidelines (in STYLE.md) were followed
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• I verified all code is DRY (the PR doesn't include any logic written more than once, with the exception of tests)
• I verified any variables that can be defined as constants (ie. in CONST.ts or at the top of the file that uses the constant) are defined as such
• I verified that if a function's arguments changed that all usages have also been updated correctly
• If any new file was added I verified that:
  • The file has a description of what it does and/or why is needed at the top of the file if the code is not self explanatory
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
• If new assets were added or existing ones were modified, I verified that:
  • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
  • The assets load correctly across all supported platforms.
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• If a new page is added, I verified it's using the ScrollView component to make it scrollable when more elements are added to the page.
• I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

ios.regression.tests.91605.mp4

iOS: mWeb Safari

ios.mWeb.regression.tests.91605.mp4

MacOS: Chrome / Safari

Working.Currency.List.mp4

[github-actions]

⚠️ This PR is possibly changing native code and/or updating libraries, it may cause problems with HybridApp. Please check if any patch updates are required in the HybridApp repo and run an AdHoc build to verify that HybridApp will not break. Ask Contributor Plus for help if you are not sure how to handle this. ⚠️

[codecov]

Codecov Report

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

Files with missing lines	Coverage Δ
src/components/SelectionList/BaseSelectionList.tsx	83.66% <100.00%> (+16.33%)	⬆️
...ListWithSections/BaseSelectionListWithSections.tsx	92.47% <100.00%> (+6.17%)	⬆️
...mponents/SelectionList/hooks/useSearchFocusSync.ts	100.00% <ø> (ø)
...ts/SelectionList/hooks/useSelectedItemFocusSync.ts	100.00% <ø> (ø)
...lectionList/hooks/useSelectionListKeyboardFocus.ts	94.73% <100.00%> (ø)
src/hooks/useArrowKeyFocusManager.ts	62.92% <100.00%> (+2.68%)	⬆️
... and 72 files with indirect coverage changes

[sharabai]

@TaduJR, could you take a look if I'd introduced any regression unknowingly to your changes from this PR? I've removed lots of the things you added in that PR. I've tried to check the things your PR aimed to fix for regressions and haven't found anything. Still, a second opinion is welcome.

[sharabai]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep it up!

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[melvin-bot]

@huult 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]

[huult]

@sharabai Do we need to create a new ticket for this PR? Is this refactor related to the ticket mentioned above?

[sharabai]

@huult
This PR is just another step towards solving the original issue. It's a follow-up to the PR that introduced the patch to the FlashList.
In other words, no need for a separate issue.

[trjExpensify]

PR doesn’t need product input as a refactor PR. Unassigning and unsubscribing myself.

[huult]

@MelvinBot Please help generate test steps for this ticket.

[MelvinBot]

Here are test steps for this PR, huult. Since this is a refactor (replacing the imperative suppressNextFocusScrollRef flag with the declarative setFocusedIndex(index, {shouldScroll}) API), the goal is to confirm the user-visible fix works and that the three behaviors the old flag was guarding have not regressed. Each test below names the code path it exercises so you can map a failure back to a specific change.

Primary platform: macOS Chrome — keyboard-driven flows are where this refactor matters. iOS/Android/mWeb are regression-only (tap a row → it highlights without unexpected scrolling; selection still works).

Tests

1. Currency picker — continuous Tab nav + arrow-key scroll (the fix)
Exercises ListItemRenderer.onFocus (now non-scrolling) + the onFocusedIndexChange scroll gate in BaseSelectionListWithSections.

1. LHN → green + → Create expense (or Track expense).
2. In the expense form, click the currency-code button (e.g. USD). The currency picker opens.
3. Press Tab once → focus moves from the search input to the first currency row.
4. Keep pressing Tab (no mouse). Verify the row highlight advances exactly one row per press — no skipping, flicker, falling behind, or rows jumping under the cursor.
5. Tab past the bottom of the visible area. Verify the focused row scrolls into view smoothly and rows stay in top-to-bottom order.
6. Press ArrowDown a few times → verify the highlight moves down one row per press and the list scrolls to keep the focused row visible.
7. Press ArrowUp a few times → verify the highlight walks back up and the list scrolls the other way.

2. Search sync — typing scrolls to top once, no double-bounce
Exercises useSearchFocusSync (suppress-ref params removed). Regression for #89498.

1. Go to Spend > Expenses > Filters pill > Currency.
2. Scroll well down and click any item. Verify the list does not jump on the click.
3. Type a query in the filter input. Verify the list scrolls to the top with a single scroll (no animated "bounce").
4. Clear the search input. Verify the list does not return to the previously selected item.
5. Use ArrowUp/ArrowDown → verify the focused row scrolls into view.

3. Multi-select — selecting items doesn't scroll or reorder
Exercises selectRow now calling plain setFocusedIndex (defaults to shouldScroll: false) in BaseSelectionListWithSections. Regression for #90121.
Precondition: account with multiple workspaces.

1. Go to Spend > Expenses > Filters pill > Workspace.
2. Scroll down and click any workspace. Verify the item stays in place and the list does not jump to the top.
3. Select more items → verify no scroll jumping.
4. Deselect an item → verify no scroll jumping and the item stays in its section.
5. Save, close, reopen the Workspace filter → verify the list scrolls to the first selected item on open.

4. Focus restore — closing the detail RHP doesn't scroll the list
Exercises the removal of setFocusedIndexFromRowFocus / isFocusRestoreInProgress() — row focus is now always non-scrolling in BaseSelectionList. Regression for #90869.

1. Go to a workspace's Categories settings.
2. Scroll down so the list is not at the top.
3. Click any category → the category-detail RHP opens.
4. Click the RHP back button.
5. Verify the categories list does not scroll on the way back, and focus returns to the row you clicked.

5. Console — throughout all flows, verify no errors appear in the JS console.

Offline

N/A — focus-management refactor only. No new API calls, Onyx writes, or offline-relevant paths.

Automated coverage (already in the PR — run before manual QA)

npx jest tests/unit/useArrowKeyFocusManagerTest.ts tests/unit/BaseSelectionListTest.tsx

These assert the new setFocusedIndex(index, shouldScroll) forwarding contract and that programmatic focus (Tab / pointer / focus-restore) no longer auto-scrolls.

---

⚠️ Reminder: this PR depends on the FlashList natural-DOM-order patch (#91328) being merged first, so test on a branch that includes it. Reply with @MelvinBot <feedback> to refine these steps.

[chuckdries]

Ah, I think I understand. Can we solve it simply here or will it require another patch?

[TaduJR]

I think it requires another patch from @sharabai comment earlier.

What @TaduJR pointed out totally makes sense and it could be easily fixed with a small patch.

[chuckdries]

Ah, since it's a separate patch, and doesn't really meet the description of the original issue linked from this PR, let's handle it as a separate issue. At the very least, I don't want to increase the chance we revert this improvement for web users. @sharabai feel free to file it and assign @TaduJR to review

[sharabai]

Also The Chat list non-interactive items are individually focusable only on this PR, instead of focusing as a whole on one message.

This seems like we should fix in this PR. @sharabai do you have a sense for why this happened?

@chuckdries I'm not fully sure what @TaduJR meant by it. I'll build main and compare it to this branch to see the difference.

[sharabai]

Also The Chat list non-interactive items are individually focusable only on this PR, instead of focusing as a whole on one message.

@TaduJR I'm having trouble finding that.
Here's a recording from main build:

91605.main.mp4

And here's one from the branch build:

91605.local.mp4

What am I missing?

[sharabai]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: cf231ecda7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chuckdries]

I did some testing of main versus this branch, and I concur I didn't notice a difference between what items are selectable with talkback. I was just tabbing through a concierge chat. @TaduJR can you clarify what use case or situation you found in this comment

Also The Chat list non-interactive items are individually focusable only on this PR, instead of focusing as a whole on one message.

[TaduJR]

@TaduJR I'm having trouble finding that.
Here's a recording from main build:

I did some testing of main versus this branch, and I concur I didn't notice a difference between what items are selectable with talkback. I was just tabbing through a concierge chat. @TaduJR can you clarify what use case or situation you found in this comment

@sharabai @chuckdries

I think it's another PR that was offending during that time. It was not like that previously. I am seeing same behaviour as you stated on the demo now.

Also The Chat list non-interactive items are individually focusable only on this PR, instead of focusing as a whole on one message.

We can leave this now.

Thanks!

[chuckdries]

Ok! Thanks for sticking with this everyone. I would always rather be extra cautious at review time than have to revert due to a deployblocker later!

[chuckdries]

@huult looks like we changed the checklist between when you filled it out and now. Would you kindly update your checklist to match the latest https://raw.githubusercontent.com/Expensify/App/main/contributingGuides/REVIEWER_CHECKLIST.md then we're finally good to merge!

[huult]

sure

[sharabai]

@TaduJR I'm with @chuckdries on this one, it's better to be safe than sorry.
You did great with the review and pointing out a sibling issue for Native devices.

[chuckdries]

Oh speaking of, did that sibling issue ever get filed or was I supposed to do it?

[TaduJR]

@TaduJR I'm with @chuckdries on this one, it's better to be safe than sorry.
You did great with the review and pointing out a sibling issue for Native devices.

Yea @sharabai, I am already fully in support of handling separately.

Oh speaking of, did that sibling issue ever get filed or was I supposed to do it?

@chuckdries

I think it's this one #94165

@sharabai feel free to file it and assign @TaduJR to review

Should I comment one the issue?

[sharabai]

@chuckdries @TaduJR

I think it's this one #94165

Yeah, that's the one. I left a comment explaining the origin, but I can't assign anyone directly.

[chuckdries]

@huult reviewer checklist is still failing https://github.com/Expensify/App/actions/runs/28180818828/job/83535773117

[huult]

LGTM.

[OSBotify]

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

[github-actions]

🚧 chuckdries has triggered a test Expensify/App build. You can view the workflow run here.

[github-actions]

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #91605.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-3ec299a7283-27a47d6-b587fbf32fd2c1e5accd93cce4b8ea02847f718c/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-3ec299a-27a47d6-5ceb06dcbc5cc7695b2d44f3858b463d28fff29c/index.html

Web 🕸️
https://91605.pr-testing.expensify.com

---

👀 View the workflow run that generated this build 👀

[OSBotify]

🚀 Deployed to staging by https://github.com/chuckdries in version: 9.4.21-2 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

[OSBotify]

🚀 Deployed to production by https://github.com/mountiny in version: 9.4.21-9 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

Bundle Size Analysis (Sentry):

• Android