[Due for payment 2026-07-16] Make modal-to-destination transitions gapless with usePreMountDestination

[mountiny]

Coming from here

Background

When the app dismisses an RHP modal to show a new fullscreen destination, the modal closes first, then the destination mounts - creating a visible gap (narrow layout) or flash of the previous page (wide layout).
For the Submit Expense flow, I solved this with two strategies: pre-inserting the destination behind the RHP on narrow layout, and swapping the fullscreen before dismissing on wide layout (see before/after videos). Both are shipped and work well, but they're manually orchestrated in SubmitExpenseOrchestrator.tsx with ~40 lines of flag management, cleanup paths, and layout-specific function calls that other flows can't easily reuse.

Problem

When a user dismisses a modal and the app navigates to a different destination than what's currently behind it, there is a visible gap (narrow layout) or flash of the previous page (wide layout) between the modal closing and the destination appearing - because the destination component tree hasn't mounted yet at the time of dismissal. This affects any modal-to-destination flow where the destination differs from what was previously behind the modal (e.g., workspace creation, which currently has this gap/flash).

Solution

A usePreMountDestination(route) hook that encapsulates the entire pre-mount lifecycle behind a one-line setup:

const {reveal} = usePreMountDestination(ROUTES.SEARCH_CENTRAL_PANE);

const handleSubmit = () => {
    reveal(() => {
        // expensive work runs after the user already sees the destination
        createExpense(params);
    });
};

The hook has two internal strategies based on layout:

Narrow layout (pre-insert on mount):

1. On mount, schedules preInsertFullscreenUnderRHP(route) after a 300ms delay (configurable via {delay: ms}). This gives the confirmation screen time to render before the background insert starts.
2. Emits SET_RHP_SLIDE_LEFT so the RHP dismiss animation slides forward (reveals the destination underneath) instead of the default slide-right.
3. On reveal(callback): clears the pre-insert flag and calls dismissModal({afterTransition: callback}).
4. On unmount without submit (user backed out): calls removePreInsertedFullscreenIfNeeded() and emits RESTORE_RHP_ANIMATION to reset the dismiss direction.

Wide layout (reveal at call time):

1. On mount: no-op (no pre-insertion needed  - web rendering is fast enough).
2. On reveal(callback): calls revealRouteBeforeDismissingModal(route, {afterTransition: callback}) which swaps the fullscreen in frame 1 and dismisses the modal in frame 2.
3. On unmount without reveal being called: no-op (nothing was pre-inserted).

What this changes from today

1. Encapsulation - The pre-insert lifecycle (flag management, cleanup, animation events) moves from consumer code into the hook. Consumers just call usePreMountDestination(route) and reveal().
2. Automatic back-out cleanup - Currently manual; the hook handles it via useEffect cleanup + an internal ref tracking whether reveal() was called.

Parameters

• route (type: Route) - required; The destination to pre-mount
• delay (type: number) - optional, default: CONST.PRE_INSERT_FULLSCREEN_DELAY (300ms); How long to wait before pre-inserting on narrow layout. Shorter for screens where the user spends less time, longer for heavier destinations.

Migration plan

1. Ship the hook.
2. Migrate Submit Expense flow (SubmitExpenseOrchestrator.tsx) to use the hook instead of manual orchestration  - this validates it works end-to-end.
3. Create a rule (ESLint or AI) that will enforce only using this hook in the narrow usecase it is designed for
4. First new adoption: workspace creation -> workspace overview (follow-up issue).

When NOT to use this hook

1. Destination isn't known in advance - route must be fixed at mount time.
2. No dwell time before dismiss (narrow layout only) - the user must spend at least 300ms on the screen before the RHP is dismissed, so the pre-insert timer can fire.
3. No modal to dismiss - this is for RHP/modal-to-destination flows only.
4. Transition is already fast enough - profile first, don't add complexity if there's no perceived gap.

Alternative solutions explored

• Pre-inserting on both layouts - unnecessary on wide (web renders fast enough); would risk browser-resize edge case for zero benefit.
• Platform-split (native/web) instead of layout-split (narrow/wide) - Tim's feedback: keep narrow/wide as the boundary, simpler and cross-platform.
• No hook, keep manual orchestration - leads to duplicated ~40-line patterns and leaked flags. The hook eliminates this class of bugs by design.

Flows that meet all requirements (RHP dismissed to reveal a fullscreen destination, destination known at mount, dwell time before dismiss):

• Workspace Creation → Workspace Overview - already partially uses the pattern manually (pushNewlyCreatedWorkspaceUnderActiveModal); first non-IOU adoption.
• Approval Workflow Create/Edit - dismisses modal + createApprovalWorkflow/updateApprovalWorkflow in afterTransition.
• Copy Policy Settings - confirmation screen + copyPolicySettings across multiple policies.
• Company Card Assignment - multi-step flow, confirmation step, assigns card via API write.
• Search Advanced Filters → Search Results - filter form dismissed, triggers full search list re-render.
• Workspace Invite → Members Page - multi-step invite, navigates to members list on confirm.

Full technical reference: CANVAS

Note to original participants
The afterTransition error isolation fix (wrapping the synchronous callback path in try/catch in TransitionTracker.ts) will be shipped as a separate small PR in parallel  - it's a one-line defensive fix that doesn't need its own proposal. The remaining items from the original thread (deferred write scheduling, progressive rendering hook renames) will be posted as separate proposals to allow independent discussion and progress on each.

Issue Owner

Current Issue Owner: @JakubKorytko

[Ayesha-Ashraf-Dev]

Contributor details

Your Expensify account email: ayeshaashraf0091@gmail.com
Upwork Profile Link: https://www.upwork.com/freelancers/ayeshaa337

Proposal
Problem Understanding
When dismissing an RHP modal to navigate to a new fullscreen destination, there's a visible gap (narrow) or flash of the previous page (wide) because the destination component tree hasn't mounted yet at dismissal time. The Submit Expense flow already solves this but with ~40 lines of manually orchestrated flag management in SubmitExpenseOrchestrator.tsx that can't be reused elsewhere.
Proposed Solution
Create a usePreMountDestination(route, options?) hook that encapsulates the entire pre-mount lifecycle.
Hook signature:

type UsePreMountDestinationOptions = {
delay?: number; // default: CONST.PRE_INSERT_FULLSCREEN_DELAY (300ms)
};

type UsePreMountDestinationResult = {
reveal: (callback?: () => void) => void;
};

function usePreMountDestination(
route: Route,
options?: UsePreMountDestinationOptions
): UsePreMountDestinationResult;

Narrow layout behavior (pre-insert on mount):
typescript// On mount:
const timer = setTimeout(() => {
preInsertFullscreenUnderRHP(route);
emitNavigationEvent(SET_RHP_SLIDE_LEFT);
hasPreInsertedRef.current = true;
}, options?.delay ?? CONST.PRE_INSERT_FULLSCREEN_DELAY);

// reveal():
clearTimeout(timer);
hasPreInsertedRef.current = false;
dismissModal({ afterTransition: callback });

// useEffect cleanup (back-out):
clearTimeout(timer);
if (hasPreInsertedRef.current) {
removePreInsertedFullscreenIfNeeded();
emitNavigationEvent(RESTORE_RHP_ANIMATION);
}
Wide layout behavior (reveal at call time):
typescript// On mount: no-op

// reveal():
revealRouteBeforeDismissingModal(route, { afterTransition: callback });

// useEffect cleanup: no-op
Consumer usage (replaces ~40 lines with 2):
typescriptconst { reveal } = usePreMountDestination(ROUTES.WORKSPACE_OVERVIEW);

const handleSubmit = () => {
reveal(() => {
createWorkspace(params); // runs after user sees destination
});
};
Implementation Steps

Create the hook at src/hooks/usePreMountDestination.ts

Import useWindowDimensions (or existing layout util) to branch on narrow/wide
Use useRef for hasPreInsertedRef and the timer ref
Use useEffect cleanup for back-out path
Export reveal as a stable callback (wrapped in useCallback)

Migrate SubmitExpenseOrchestrator.tsx to use the hook — removes existing manual flag orchestration, validates the hook end-to-end
Add ESLint rule (or document AI rule) to enforce:

usePreMountDestination is only used in RHP-to-fullscreen flows
route argument must be a static ROUTES.* constant (not dynamic)

Follow-up (separate issue): Migrate Workspace Creation → Workspace Overview as first new adoption

Files Likely Touched

src/hooks/usePreMountDestination.ts ← new file
src/pages/iou/SubmitExpenseOrchestrator.tsx ← migrate existing manual logic
src/libs/Navigation/TransitionTracker.ts ← confirm afterTransition error isolation is in place (or defer to parallel PR)
.eslintrc.js or eslint/ rules folder ← new lint rule

What This Does NOT Change

No behavior changes to any existing flows beyond Submit Expense in this PR
The afterTransition try/catch fix ships separately as noted in the issue
Wide layout pre-insertion remains excluded (as per Tim's feedback)

Why This Approach Wins

Zero duplicated logic — the hook owns the entire lifecycle; consumers can't leak flags by forgetting cleanup
Back-out safety is automatic — useEffect cleanup fires whether the user backs out, unmounts, or navigates away
Configurable delay — flows where users spend less time can pass a shorter delay
Consistent narrow/wide boundary — follows existing codebase convention rather than platform split

[melvin-bot]

📣 @Ayesha-Ashraf-Dev! 📣
Hey, it seems we don’t have your contributor details yet! You'll only have to do this once, and this is how we'll hire you on Upwork.
Please follow these steps:

1. Make sure you've read and understood the contributing guidelines.
2. Get the email address used to login to your Expensify account. If you don't already have an Expensify account, create one here. If you have multiple accounts (e.g. one for testing), please use your main account email.
3. Get the link to your Upwork profile. It's necessary because we only pay via Upwork. You can access it by logging in, and then clicking on your name. It'll look like this. If you don't already have an account, sign up for one here.
4. Copy the format below and paste it in a comment on this issue. Replace the placeholder text with your actual details.
   
   Format:

Contributor details
Your Expensify account email: <REPLACE EMAIL HERE>
Upwork Profile Link: <REPLACE LINK HERE>

[pvaghasiya087-has]

Proposal: Introduce "usePreMountDestination" for Seamless Modal Transitions

Problem

When an RHP modal is dismissed and the app navigates to a different fullscreen destination, the destination is mounted after the modal starts closing. This causes:

• Narrow layout: a visible blank gap before the destination appears.
• Wide layout: a brief flash of the previous page before the new destination loads.

The Submit Expense flow already solves this with custom logic, but the implementation is specific to that flow and duplicates complex state management, cleanup, and animation handling.

Proposed Solution

Introduce a reusable "usePreMountDestination(route)" hook that prepares the destination before dismissing the modal and exposes a simple API:

const {reveal} = usePreMountDestination(ROUTES.SEARCH_CENTRAL_PANE);

reveal(() => {
createExpense(params);
});

Internally the hook:

• Narrow layout: Pre-mounts the destination behind the modal and cleans it up automatically if the flow is cancelled.
• Wide layout: Reveals the destination before dismissing the modal, avoiding the flash of the previous screen.

Consumers only provide the destination route and call "reveal()".

Benefits

• Eliminates gap/flash during modal-to-destination transitions.
• Removes duplicated transition orchestration from individual flows.
• Centralizes cleanup and animation handling.
• Provides a consistent, reusable solution for future flows.

Alternatives Considered

• Keep manual orchestration: Works, but duplicates complex logic across features.
• Pre-mount on all layouts: Adds unnecessary complexity where it's not needed.
• Platform-based implementation: Layout-based behavior better matches the rendering differences.

Recommendation

Implement "usePreMountDestination" as the shared solution for modal-to-destination transitions where the destination is known in advance and a visible gap or flash exists.

[melvin-bot]

@JakubKorytko Whoops! This issue is 2 days overdue. Let's get this updated quick!

[JakubKorytko]

Will work on this really soon pinky promise