[$250] Refactor Search highlight logic from timer-based to readiness-based

[JakubKorytko]

On the native platforms (specifically observed on Android), scrolling to and highlighting a newly added expense is inconsistent. This race condition exists on main but has become more apparent following recent performance-focused changes.

Current Behavior

The search highlight flow is currently timer-based.

1. After submitting an expense outside of the Inbox, the new transaction is marked for highlight on the Search route.
2. This highlight state is cleared after a fixed timeout.
3. The actual scroll/highlight action triggers only after the Search list has mounted, data is grouped/sorted, and the list layout callback runs.

Problem

If Search rendering is delayed - due to navigation timing, loading skeletons, or heavy list processing - the highlight state often expires before the row is reachable. This results in the expense neither being scrolled into view nor highlighted.

Proposed solution

We need to move away from a timeout-based lifecycle and implement a readiness-based approach.

• Persist state: Maintain the manual highlight state/flag until the target transaction is confirmed to be present in the rendered Search data.
• Trigger on readiness: Only execute the scroll and highlight once the list is layout-ready and the specific item exists in the DOM/list index.
• Explicit cleanup: Clear the highlight flag only after the scroll/highlight animation has successfully initiated.

Impact

• Consistency: Ensures the "Add Expense" flow always provides visual confirmation of the new entry, regardless of device performance or network latency.
• UX: Eliminates the "vanishing highlight" bug where the UI state resets before the user even sees the Search page.

Note

This was identified during a performance PR where the timing window became easier to hit, but the root cause is an architectural race condition in the Search highlight logic.

Observed here: #84910 (comment)

Issue Owner

Current Issue Owner: @borys3kk

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022034273899120343057
• Upwork Job ID: 2034273899120343057
• Last Price Increase: 2026-03-18

[JakubKorytko]

cc @mountiny

[mountiny]

@staszekscp is this something someone from your team would like to handle?

[melvin-bot]

⚠️ Looks like this issue was linked to a Deploy Blocker here

If you are the assigned CME please investigate whether the linked PR caused a regression and leave a comment with the results.

If a regression has occurred and you are the assigned CM follow the instructions here.

If this regression could have been avoided please consider also proposing a recommendation to the PR checklist so that we can avoid it in the future.

[MelvinBot]

Proposal

Please re-state the problem that we are trying to solve in this issue.

After submitting an expense outside the Inbox (via the global create flow), the app should scroll to and highlight the new transaction on the Search page. On native platforms, this highlight/scroll frequently fails because the highlight state expires (via a 300ms timer) before the Search list has finished rendering and laying out.

What is the root cause of that problem?

The highlight/scroll lifecycle in useSearchHighlightAndScroll is governed by two independent 300ms setTimeout timers that clear state unconditionally, regardless of whether the Search list has actually rendered the target row.

Timer 1 (src/hooks/useSearchHighlightAndScroll.ts:249-251): Clears the Onyx TRANSACTION_IDS_HIGHLIGHT_ON_SEARCH_ROUTE flag back to false after 300ms via mergeTransactionIdsHighlightOnSearchRoute.

Timer 2 (src/hooks/useSearchHighlightAndScroll.ts:273-275): Sets local state newSearchResultKeys to null after 300ms.

The scroll action can only fire inside the FlashList onLayout callback (src/components/Search/index.tsx:1302-1313), which calls handleSelectionListScroll. That function early-returns if newSearchResultKeys is null (src/hooks/useSearchHighlightAndScroll.ts:287).

On native, the time between expense submission and onLayout firing includes: async navigation readiness (Navigation.isNavigationReady().then(...) at src/libs/actions/IOU/index.ts:1194-1200), screen transition animations, InteractionManager.runAfterInteractions deferral of the search API call (src/hooks/useSearchHighlightAndScroll.ts:136-138), skeleton loading state (src/components/Search/index.tsx:1365-1379), and the deferHeavySearchWork mechanism that delays list mounting by 1-2 requestAnimationFrame calls (src/components/Search/index.tsx:387-421). This pipeline routinely exceeds 300ms on native, so both timers fire before onLayout, causing neither scroll nor highlight.

The 300ms value (ANIMATED_HIGHLIGHT_START_DURATION at src/CONST/index.ts:221) was designed for the visual highlight animation phase, not for list layout readiness -- these are fundamentally different timescales.

What changes do you think we should make in order to solve the problem?

Replace the timer-based cleanup with a readiness-based approach in src/hooks/useSearchHighlightAndScroll.ts:

1. Remove the two 300ms setTimeout timers (lines 249-251 and 273-275) that unconditionally clear transactionIDsToHighlight and newSearchResultKeys.

2. Clear state only after successful scroll/highlight initiation: Move the cleanup logic into handleSelectionListScroll (line 283+), executing it only after ref.scrollToIndex() succeeds (line 321). At that point, clear newSearchResultKeys and the Onyx highlight flag. This ensures state persists until the list is confirmed ready and the scroll has been triggered.

3. Add a safety timeout as a fallback: To prevent the highlight state from persisting indefinitely if something goes wrong (e.g., the item never appears in search results), add a generous fallback timeout (e.g., 10-15 seconds) that clears state. This acts as a safety net, not the primary mechanism.

4. Clear the Onyx highlight flag in the same callback: After scrollToIndex fires, call mergeTransactionIdsHighlightOnSearchRoute(type, {[transactionID]: false}) to explicitly clean up, rather than relying on a timer.

The key principle: the newSearchResultKeys state and the transactionIDsToHighlight Onyx flag should remain active until either (a) the scroll/highlight succeeds, or (b) a generous safety timeout expires.

What alternative solutions did you explore? (Optional)

• Increasing the timer duration: Simple but fragile -- any fixed timeout can still be exceeded on slow devices. Doesn't solve the architectural issue.
• Retry loop in onLayout: Could re-check state on each layout pass, but adds complexity and still depends on state not being cleared.
• Using onViewableItemsChanged callback: FlashList supports this callback which fires when items become visible -- could be used as the "readiness" signal instead of onLayout, but onLayout is already in place and sufficient since the real problem is the premature state cleanup, not the trigger mechanism.

---

Next Steps for Contributor+ team: Reply with @MelvinBot implement this to create a draft PR, @MelvinBot <your feedback> to refine this analysis, or explain why you are rejecting Melvin's proposal.

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @abdulrahuman5196 (External)