feat: add retaining of the screen to the stack navigator (#11765)

The changes are pretty straightforward and should be expressive enough
to understand by reading the codebase. This PR:
- Adds the new retaining feature including changes in the router and
minor changes in the card stack (as temporarily scene can include both
the preloaded route and the one getting detached )
- Moves around some leftovers from the previous PR (#11758 )
- Adds tests 

To test, try the example.

example/src/Screens/StackPreloadFlow.tsx

@@ -45,6 +45,9 @@ const DetailsScreen = ({
       >
         Go to Profile
       </Button>
+      <Button onPress={navigation.retain} style={styles.button}>
+        Retain
+      </Button>
     </View>
   );
 };
@@ -65,7 +68,7 @@ const ProfileScreen = ({
 const HomeScreen = ({
   navigation,
 }: StackScreenProps<PreloadStackParams, 'Home'>) => {
-  const { navigate, preload, removePreload } = navigation;
+  const { navigate, preload, remove } = navigation;
 
   return (
     <View style={styles.content}>
@@ -78,7 +81,7 @@ const HomeScreen = ({
       <Button onPress={() => navigate('Details')} style={styles.button}>
         Navigate Details
       </Button>
-      <Button onPress={() => removePreload('Details')} style={styles.button}>
+      <Button onPress={() => remove('Details')} style={styles.button}>
         Remove Details preload
       </Button>
     </View>

packages/routers/src/CommonActions.tsx

@@ -54,15 +54,6 @@ export type Action =
       };
       source?: string;
       target?: string;
-    }
-  | {
-      type: 'REMOVE_PRELOAD';
-      payload: {
-        name: string;
-        params?: object;
-      };
-      source?: string;
-      target?: string;
     };
 
 export function goBack(): Action {

packages/routers/src/StackRouter.tsx

@@ -1,7 +1,6 @@
 import { nanoid } from 'nanoid/non-secure';
 
 import { BaseRouter } from './BaseRouter';
-import type { Action } from './CommonActions';
 import type {
   CommonNavigationAction,
   DefaultRouterOptions,
@@ -45,6 +44,20 @@ export type StackActionType =
       };
       source?: string;
       target?: string;
+    }
+  | {
+      type: 'REMOVE';
+      payload: {
+        name: string;
+        params?: object;
+      };
+      source?: string;
+      target?: string;
+    }
+  | {
+      type: 'RETAIN';
+      source?: string;
+      target?: string;
     };
 
 export type StackRouterOptions = DefaultRouterOptions;
@@ -126,7 +139,7 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
    * @param name Name of the route to remove preload.
    * @param [params] Params object for the route.
    */
-  removePreload<RouteName extends keyof ParamList>(
+  remove<RouteName extends keyof ParamList>(
     ...args: RouteName extends unknown
       ? undefined extends ParamList[RouteName]
         ?
@@ -135,6 +148,13 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
         : [screen: RouteName, params: ParamList[RouteName]]
       : never
   ): void;
+
+  /**
+   * Removes a screen from the active routes, at the same time
+   * retaining the screen in the preloaded screens list,
+   * so it is not getting detached.
+   */
+  retain(): void;
 };
 
 export const StackActions = {
@@ -153,8 +173,11 @@ export const StackActions = {
   popTo(name: string, params?: object, merge?: boolean): StackActionType {
     return { type: 'POP_TO', payload: { name, params, merge } };
   },
-  removePreload(name: string, params?: object): Action {
-    return { type: 'REMOVE_PRELOAD', payload: { name, params } };
+  remove(name: string, params?: object): StackActionType {
+    return { type: 'REMOVE', payload: { name, params } };
+  },
+  retain(): StackActionType {
+    return { type: 'RETAIN' };
   },
 };
 
@@ -724,7 +747,22 @@ export function StackRouter(options: StackRouterOptions) {
             };
           }
         }
-        case 'REMOVE_PRELOAD': {
+        case 'RETAIN': {
+          const index =
+            action.target === state.key && action.source
+              ? state.routes.findIndex((r) => r.key === action.source)
+              : state.index;
+          const route = state.routes[index];
+
+          return {
+            ...state,
+            index: state.index - 1,
+            routes: state.routes.filter((r) => r !== route),
+            preloadedRoutes: state.preloadedRoutes.concat(route),
+          };
+        }
+
+        case 'REMOVE': {
           const getId = options.routeGetIdList[action.payload.name];
           const id = getId?.({ params: action.payload.params });
 

packages/routers/src/TabRouter.tsx

@@ -449,23 +449,6 @@ export function TabRouter({
           };
         }
 
-        case 'REMOVE_PRELOAD': {
-          const routeIndex = state.routes.findIndex(
-            (route) => route.name === action.payload.name
-          );
-          if (routeIndex === -1) {
-            return null;
-          }
-          const route = state.routes[routeIndex];
-
-          return {
-            ...state,
-            preloadedRouteKeys: state.preloadedRouteKeys.filter(
-              (key) => key !== route.key
-            ),
-          };
-        }
-
         default:
           return BaseRouter.getStateForAction(state, action);
       }

packages/routers/src/__tests__/StackRouter.test.tsx

@@ -2159,7 +2159,7 @@ it('handles screen preloading', () => {
         ],
       },
 
-      StackActions.removePreload('bar', { answer: 43 }),
+      StackActions.remove('bar', { answer: 43 }),
       options
     )
   ).toEqual({
@@ -2405,7 +2405,7 @@ it('handles screen preloading', () => {
         ],
       },
 
-      StackActions.removePreload('bar', { answer: 42 }),
+      StackActions.remove('bar', { answer: 42 }),
       options
     )
   ).toEqual({
@@ -2417,4 +2417,43 @@ it('handles screen preloading', () => {
     routeNames: ['baz', 'bar', 'qux'],
     routes: [{ key: 'qux-test', name: 'qux' }],
   });
+
+  expect(
+    router.getStateForAction(
+      {
+        stale: false,
+        type: 'stack',
+        key: 'root',
+        index: 1,
+        preloadedRoutes: [],
+        routeNames: ['baz', 'bar', 'qux'],
+        routes: [
+          {
+            key: 'baz-test',
+            name: 'baz',
+          },
+          {
+            key: 'qux-test',
+            name: 'qux',
+          },
+        ],
+      },
+
+      StackActions.retain(),
+      options
+    )
+  ).toEqual({
+    stale: false,
+    type: 'stack',
+    key: 'root',
+    index: 0,
+    preloadedRoutes: [{ key: 'qux-test', name: 'qux' }],
+    routeNames: ['baz', 'bar', 'qux'],
+    routes: [
+      {
+        key: 'baz-test',
+        name: 'baz',
+      },
+    ],
+  });
 });

packages/stack/src/__tests__/index.test.tsx

@@ -135,7 +135,7 @@ it('handles screens preloading', async () => {
   expect(
     queryByText('Screen B', { includeHiddenElements: true })
   ).not.toBeNull();
-  act(() => navigation.dispatch(StackActions.removePreload('B')));
+  act(() => navigation.dispatch(StackActions.remove('B')));
   expect(queryByText('Screen B', { includeHiddenElements: true })).toBeNull();
 });
 
@@ -172,7 +172,7 @@ it('runs focus effect on focus change on preloaded route', () => {
   expect(focusEffectCleanup).not.toHaveBeenCalled();
 
   act(() => navigation.preload('A'));
-  act(() => navigation.dispatch(StackActions.removePreload('B')));
+  act(() => navigation.dispatch(StackActions.remove('B')));
   act(() => navigation.preload('B'));
 
   expect(focusEffect).not.toHaveBeenCalled();

packages/stack/src/views/Stack/CardStack.tsx

@@ -617,7 +617,19 @@ export class CardStack extends React.Component<Props, State> {
             const focused = focusedRoute.key === route.key;
             const gesture = gestures[route.key];
             const scene = scenes[index];
-            const isPreloaded = state.preloadedRoutes.includes(route);
+            // It is possible that for a short period the route appears in both arrays.
+            // Particularly, if the screen is removed with `retain`, then it needs a moment to execute the animation.
+            // However, due to the router action, it immediately populates the `preloadedRoutes` array.
+            // Practically, the logic below takes care that it is rendered only once.
+            const isPreloaded =
+              state.preloadedRoutes.includes(route) && !routes.includes(route);
+            if (
+              state.preloadedRoutes.includes(route) &&
+              routes.includes(route) &&
+              index >= routes.length
+            ) {
+              return null;
+            }
 
             // For the screens that shouldn't be active, the value is 0
             // For those that should be active, but are not the top screen, the value is 1