Migration navigation from InteractionManager to TransitionTracker

contributingGuides/INTERACTION_MANAGER.md

@@ -0,0 +1,67 @@
+# InteractionManager Migration
+
+## Why
+
+`InteractionManager` is being removed from React Native. We currently maintain a patch to keep it working, but that's a temporary measure and upstream libraries will also drop support over time.
+
+Rather than keep patching, we're replacing `InteractionManager.runAfterInteractions` with purpose-built alternatives that are more precise.
+
+## Current state
+
+`runAfterInteractions` is used across the codebase for a wide range of reasons: waiting for navigation transitions, deferring work after modals close, managing input focus, delaying scroll operations, and many other cases that are hard to classify.
+
+## The problem
+
+`runAfterInteractions` is a global queue with no granularity. This made it a convenient catch-all, but the intent behind each call is often unclear. Many usages exist simply because it "just worked" as a timing workaround, not because it was the right tool for the job.
+
+This makes the migration non-trivial: you have to understand *what each call is actually waiting for* before you can pick the right replacement.
+
+## The approach
+
+**TransitionTracker** is the backbone. It tracks navigation transitions explicitly, so other APIs can hook into transition lifecycle without relying on a global queue.
+
+On top of TransitionTracker, existing APIs gain transition-aware callbacks:
+
+- Navigation methods accept `afterTransition` — a callback that runs after the triggered navigation transition completes
+- Navigation methods accept `waitForTransition` — the call waits for all ongoing transitions to finish before navigating
+- Keyboard methods accept `afterTransition` — a callback that runs after the keyboard transition completes
+- `useConfirmModal` hook's `showConfirmModal` returns a Promise that resolves **after the modal close transition completes**, so any work awaited after it naturally runs post-transition — no explicit `afterTransition` callback needed
+
+This makes the code self-descriptive: instead of a generic `runAfterInteractions`, each call site says exactly what it's waiting for and why.
+
+> **Note:** `TransitionTracker.runAfterTransitions` is an internal primitive. Application code should use the higher-level APIs (`Navigation`, `useConfirmModal`, etc.) rather than importing TransitionTracker directly.
+
+## How
+The migration is split into 9 issues. Current status of the migration can be found in the parent Github issue [here](https://github.com/Expensify/App/issues/71913). 
+
+## Primitives comparison
+
+For reference, here's how the available timing primitives compare:
+
+### `requestAnimationFrame` (rAF)
+
+- Fires **before the next paint** (~16ms at 60fps)
+- Guaranteed to run every frame if the thread isn't blocked
+- Use for: UI updates that need to happen on the next frame (scroll, layout measurement, enabling a button after a state flush)
+
+### `requestIdleCallback`
+
+- Fires when the runtime has **idle time** — no pending frames, no urgent work
+- May be delayed indefinitely if the main thread stays busy
+- Accepts a `timeout` option to force execution after a deadline
+- Use for: Non-urgent background work (Pusher subscriptions, search API calls, contact imports)
+
+### `InteractionManager.runAfterInteractions` (legacy — do not use)
+
+- React Native-specific. Fires after all **ongoing interactions** (animations, touches) complete
+- Tracks interactions via `createInteractionHandle()` — anything that calls `handle.done()` unblocks the queue
+- In practice, this means "run after the current navigation transition finishes"
+- Problem: it's a global queue with no granularity — you can't say "after _this specific_ transition"
+
+### Summary
+
+|                        | Timing                    | Granularity               | Platform              |
+| ---------------------- | ------------------------- | ------------------------- | --------------------- |
+| `rAF`                  | Next frame (~16ms)        | None — just "next paint"  | Web + RN              |
+| `requestIdleCallback`  | When idle (unpredictable) | None — "whenever free"    | Web + RN (polyfilled) |
+| `runAfterInteractions` | After animations finish   | Global — all interactions | RN only               |

src/CONST/index.ts

@@ -229,6 +229,7 @@ const CONST = {
     ANIMATED_PROGRESS_BAR_DURATION: 750,
     ANIMATION_IN_TIMING: 100,
     COMPOSER_FOCUS_DELAY: 150,
+    MAX_TRANSITION_DURATION_MS: 1000,
     ANIMATION_DIRECTION: {
         IN: 'in',
         OUT: 'out',
@@ -8253,10 +8254,6 @@ const CONST = {
         ADD_EXPENSE_APPROVALS: 'addExpenseApprovals',
     },
 
-    MODAL_EVENTS: {
-        CLOSED: 'modalClosed',
-    },
-
     LIST_BEHAVIOR: {
         REGULAR: 'regular',
         INVERTED: 'inverted',

src/components/EmojiPicker/EmojiPicker.tsx

@@ -116,7 +116,7 @@ function EmojiPicker({viewportOffsetTop, ref}: EmojiPickerProps) {
 
         // It's possible that the anchor is inside an active modal (e.g., add emoji reaction in report context menu).
         // So, we need to get the anchor position first before closing the active modal which will also destroy the anchor.
-        KeyboardUtils.dismiss(true).then(() =>
+        KeyboardUtils.dismiss({shouldSkipSafari: true}).then(() =>
             calculateAnchorPosition(emojiPopoverAnchor?.current, anchorOriginValue).then((value) => {
                 close(() => {
                     onWillShow?.();

src/components/Modal/BaseModal.tsx

@@ -2,7 +2,7 @@ import React, {useCallback, useContext, useEffect, useMemo, useRef, useState} fr
 import type {LayoutChangeEvent} from 'react-native';
 // Animated required for side panel navigation
 // eslint-disable-next-line no-restricted-imports
-import {Animated, DeviceEventEmitter, View} from 'react-native';
+import {Animated, View} from 'react-native';
 import ColorSchemeWrapper from '@components/ColorSchemeWrapper';
 import NavigationBar from '@components/NavigationBar';
 import ScreenWrapperOfflineIndicatorContext from '@components/ScreenWrapper/ScreenWrapperOfflineIndicatorContext';
@@ -167,8 +167,6 @@ function BaseModal({
         [],
     );
 
-    useEffect(() => () => DeviceEventEmitter.emit(CONST.MODAL_EVENTS.CLOSED), []);
-
     const handleShowModal = useCallback(() => {
         if (shouldSetModalVisibility) {
             setModalVisibility(true, type);

src/components/Modal/ReanimatedModal/index.tsx

@@ -9,6 +9,7 @@ import useThemeStyles from '@hooks/useThemeStyles';
 import useWindowDimensions from '@hooks/useWindowDimensions';
 import blurActiveElement from '@libs/Accessibility/blurActiveElement';
 import getPlatform from '@libs/getPlatform';
+import TransitionTracker from '@libs/Navigation/TransitionTracker';
 import variables from '@styles/variables';
 import CONST from '@src/CONST';
 import Backdrop from './Backdrop';
@@ -102,6 +103,7 @@ function ReanimatedModal({
                 // eslint-disable-next-line @typescript-eslint/no-deprecated
                 InteractionManager.clearInteractionHandle(handleRef.current);
             }
+            TransitionTracker.endTransition();
 
             setIsVisibleState(false);
             setIsContainerOpen(false);
@@ -114,13 +116,15 @@ function ReanimatedModal({
         if (isVisible && !isContainerOpen && !isTransitioning) {
             // eslint-disable-next-line @typescript-eslint/no-deprecated
             handleRef.current = InteractionManager.createInteractionHandle();
+            TransitionTracker.startTransition();
             onModalWillShow();
 
             setIsVisibleState(true);
             setIsTransitioning(true);
         } else if (!isVisible && isContainerOpen && !isTransitioning) {
             // eslint-disable-next-line @typescript-eslint/no-deprecated
             handleRef.current = InteractionManager.createInteractionHandle();
+            TransitionTracker.startTransition();
             onModalWillHide();
 
             blurActiveElement();
@@ -141,6 +145,7 @@ function ReanimatedModal({
             // eslint-disable-next-line @typescript-eslint/no-deprecated
             InteractionManager.clearInteractionHandle(handleRef.current);
         }
+        TransitionTracker.endTransition();
         onModalShow();
     }, [onModalShow]);
 
@@ -151,6 +156,7 @@ function ReanimatedModal({
             // eslint-disable-next-line @typescript-eslint/no-deprecated
             InteractionManager.clearInteractionHandle(handleRef.current);
         }
+        TransitionTracker.endTransition();
 
         // Because on Android, the Modal's onDismiss callback does not work reliably. There's a reported issue at:
         // https://stackoverflow.com/questions/58937956/react-native-modal-ondismiss-not-invoked

src/libs/Navigation/AppNavigator/Navigators/RightModalNavigator.tsx

@@ -1,8 +1,8 @@
 import type {NavigatorScreenParams} from '@react-navigation/native';
 import {useFocusEffect} from '@react-navigation/native';
-import React, {useCallback, useEffect, useMemo, useRef} from 'react';
+import React, {useCallback, useMemo, useRef} from 'react';
 // eslint-disable-next-line no-restricted-imports
-import {Animated, DeviceEventEmitter, InteractionManager} from 'react-native';
+import {Animated, InteractionManager} from 'react-native';
 import NoDropZone from '@components/DragAndDrop/NoDropZone';
 import {MultifactorAuthenticationContextProviders} from '@components/MultifactorAuthentication/Context';
 import {
@@ -169,8 +169,6 @@ function RightModalNavigator({navigation, route}: RightModalNavigatorProps) {
         }, [syncRHPKeys, clearWideRHPKeysAfterTabChanged]),
     );
 
-    useEffect(() => () => DeviceEventEmitter.emit(CONST.MODAL_EVENTS.CLOSED), []);
-
     return (
         <NarrowPaneContextProvider>
             <MultifactorAuthenticationContextProviders>