Add the ability to "retain" a dismissed screen, to support iOS Picture In Picture overlays.

packages/native-stack/src/index.tsx

@@ -8,6 +8,11 @@ export { default as createNativeStackNavigator } from './navigators/createNative
  */
 export { default as NativeStackView } from './views/NativeStackView';
 
+/**
+ * Contexts
+ */
+export { RetainContext } from './views/RetainContext';
+
 /**
  * Types
  */

packages/native-stack/src/views/NativeStackView.native.tsx

@@ -40,6 +40,7 @@
 import useInvalidPreventRemoveError from '../utils/useInvalidPreventRemoveError';
 import DebugContainer from './DebugContainer';
 import HeaderConfig from './HeaderConfig';
+import { RetainContext, useRetainContext } from './RetainContext';
 
 const isAndroid = Platform.OS === 'android';
 
@@ -120,6 +121,7 @@
   descriptor: NativeStackDescriptor;
   previousDescriptor?: NativeStackDescriptor;
   nextDescriptor?: NativeStackDescriptor;
+  hidden: boolean;
   onWillDisappear: () => void;
   onAppear: () => void;
   onDisappear: () => void;
@@ -134,6 +136,7 @@
   descriptor,
   previousDescriptor,
   nextDescriptor,
+  hidden,
   onWillDisappear,
   onAppear,
   onDisappear,
@@ -252,6 +255,7 @@
   return (
     <Screen
       key={route.key}
+      hidden={hidden}
       enabled
       style={StyleSheet.absoluteFill}
       customAnimationOnSwipe={customAnimationOnGesture}
@@ -397,74 +401,86 @@
 
   useInvalidPreventRemoveError(descriptors);
 
+  const { retainContext, hiddenRoutes, hiddenDescriptors, retainedKeys } =
+    useRetainContext(state, navigation, descriptors);
+  descriptors = { ...hiddenDescriptors, ...descriptors };
+
+  const routes = hiddenRoutes.concat(state.routes);
+
   return (
-    <ScreenStack style={styles.container}>
-      {state.routes.map((route, index) => {
-        const descriptor = descriptors[route.key];
-        const isFocused = state.index === index;
-        const previousKey = state.routes[index - 1]?.key;
-        const nextKey = state.routes[index + 1]?.key;
-        const previousDescriptor = previousKey
-          ? descriptors[previousKey]
-          : undefined;
-        const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
-
-        return (
-          <SceneView
-            key={route.key}
-            index={index}
-            focused={isFocused}
-            descriptor={descriptor}
-            previousDescriptor={previousDescriptor}
-            nextDescriptor={nextDescriptor}
-            onWillDisappear={() => {
-              navigation.emit({
-                type: 'transitionStart',
-                data: { closing: true },
-                target: route.key,
-              });
-            }}
-            onAppear={() => {
-              navigation.emit({
-                type: 'transitionEnd',
-                data: { closing: false },
-                target: route.key,
-              });
-            }}
-            onDisappear={() => {
-              navigation.emit({
-                type: 'transitionEnd',
-                data: { closing: true },
-                target: route.key,
-              });
-            }}
-            onDismissed={(event) => {
-              navigation.dispatch({
-                ...StackActions.pop(event.nativeEvent.dismissCount),
-                source: route.key,
-                target: state.key,
-              });
-
-              setNextDismissedKey(route.key);
-            }}
-            onHeaderBackButtonClicked={() => {
-              navigation.dispatch({
-                ...StackActions.pop(),
-                source: route.key,
-                target: state.key,
-              });
-            }}
-            onNativeDismissCancelled={(event) => {
-              navigation.dispatch({
-                ...StackActions.pop(event.nativeEvent.dismissCount),
-                source: route.key,
-                target: state.key,
-              });
-            }}
-          />
-        );
-      })}
-    </ScreenStack>
+    <RetainContext.Provider value={retainContext}>
+      <ScreenStack style={styles.container}>
+        {routes.map((route, offsetIndex) => {
+          const index = offsetIndex - hiddenRoutes.length;
+          const descriptor = descriptors[route.key];
+          const isFocused = state.index === index;
+          const previousKey = state.routes[index - 1]?.key;
+          const nextKey = state.routes[index + 1]?.key;
+          const previousDescriptor = previousKey
+            ? descriptors[previousKey]
+            : undefined;
+          const nextDescriptor = nextKey ? descriptors[nextKey] : undefined;
+
+          return (
+            <SceneView
+              key={route.key}
+              hidden={index < 0}
+              index={index}
+              focused={isFocused}
+              descriptor={descriptor}
+              previousDescriptor={previousDescriptor}
+              nextDescriptor={nextDescriptor}
+              onWillDisappear={() => {
+                navigation.emit({
+                  type: 'transitionStart',
+                  data: { closing: true },
+                  target: route.key,
+                });
+              }}
+              onAppear={() => {
+                navigation.emit({
+                  type: 'transitionEnd',
+                  data: { closing: false },
+                  target: route.key,
+                });
+              }}
+              onDisappear={() => {
+                navigation.emit({
+                  type: 'transitionEnd',
+                  data: { closing: true },
+                  target: route.key,
+                });
+              }}
+              onDismissed={(event) => {
+                navigation.dispatch({
+                  ...StackActions.pop(event.nativeEvent.dismissCount),
+                  source: route.key,
+                  target: state.key,
+                });
+
+                if (!retainedKeys.includes(route.key)) {
+                  setNextDismissedKey(route.key);
+                }
+              }}
+              onHeaderBackButtonClicked={() => {
+                navigation.dispatch({
+                  ...StackActions.pop(),
+                  source: route.key,
+                  target: state.key,
+                });
+              }}
+              onNativeDismissCancelled={(event) => {
+                navigation.dispatch({
+                  ...StackActions.pop(event.nativeEvent.dismissCount),
+                  source: route.key,
+                  target: state.key,
+                });
+              }}
+            />
+          );
+        })}
+      </ScreenStack>
+    </RetainContext.Provider>
   );
 }
 

packages/native-stack/src/views/RetainContext.tsx

@@ -0,0 +1,138 @@
+import type {
+  ParamListBase,
+  Route,
+  StackNavigationState,
+} from '@react-navigation/native';
+import * as React from 'react';
+
+import type {
+  NativeStackDescriptorMap,
+  NativeStackNavigationHelpers,
+} from '../types';
+
+type RetainContextT = {
+  retain(): string;
+  release(key: string): boolean;
+  restore(key: string): boolean;
+  supported: boolean;
+};
+
+/**
+ * This context allows you to retain screens in memory, even after
+ * they have been popped off the stack. This is important for
+ * supporting native iOS "Picture in Picture" mode, as the
+ * originating UIViewController must be retained in memory for the
+ * PiP overlay to continue running.
+ * Retained screens can also be "restored" to the top of the stack,
+ * for example when the user taps the button in the PiP overlay
+ * to return to the app.
+ */
+export const RetainContext = React.createContext<RetainContextT>({
+  retain() {
+    throw new Error(`Not in a native screen stack`);
+  },
+  release() {
+    throw new Error(`Not in a native screen stack`);
+  },
+  restore() {
+    throw new Error(`Not in a native screen stack`);
+  },
+  supported: false,
+});
+
+type RetainedScenes = {
+  [key: string]: {
+    route: Route<any>;
+    descriptor: NativeStackDescriptorMap['key'];
+  };
+};
+
+export function useRetainContext(
+  state: StackNavigationState<ParamListBase>,
+  navigation: NativeStackNavigationHelpers,
+  descriptors: NativeStackDescriptorMap
+) {
+  const [retainedScenes, setRetainedScenes] = React.useState<RetainedScenes>(
+    {}
+  );
+  const latestValues = React.useRef({ state, retainedScenes, descriptors });
+  React.useEffect(() => {
+    latestValues.current = { state, retainedScenes, descriptors };
+  });
+
+  const retainContext = React.useMemo<RetainContextT>(
+    () => ({
+      retain() {
+        const { state, descriptors } = latestValues.current;
+        const route = state.routes[state.routes.length - 1];
+        setRetainedScenes((screens) => ({
+          ...screens,
+          [route.key]: {
+            route,
+            descriptor: descriptors[route.key],
+          },
+        }));
+        return route.key;
+      },
+      release(key) {
+        setRetainedScenes((screens) => {
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          const { [key]: _, ...rest } = screens;
+          return rest;
+        });
+        return latestValues.current.retainedScenes[key] != null;
+      },
+      restore(key) {
+        const { retainedScenes, state } = latestValues.current;
+
+        const route = retainedScenes[key]?.route;
+        if (!route) {
+          return false;
+        }
+
+        // Remove from retained
+        setRetainedScenes((screens) => {
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          const { [key]: _, ...rest } = screens;
+          return rest;
+        });
+
+        const index = state.routes.findIndex((r) => r.key === key);
+        const routes =
+          index !== -1 ? state.routes.slice(0, index) : state.routes.slice();
+        routes.push(route);
+        navigation.dispatch({
+          type: 'RESET',
+          payload: { ...state, index: routes.length - 1, routes },
+        });
+
+        return true;
+      },
+      supported: true,
+    }),
+    [navigation]
+  );
+
+  const routeKeys = state.routes.reduce((map, route) => {
+    map[route.key] = true;
+    return map;
+  }, {} as { [key: string]: true });
+
+  // Routes that were marked as 'retain' and have been removed from the stack,
+  // for which we still want to keep the memory allocated.
+  const hiddenRoutes: Route<any>[] = [];
+  const hiddenDescriptors: NativeStackDescriptorMap = {};
+  Object.keys(retainedScenes).forEach((key) => {
+    if (!routeKeys[key]) {
+      hiddenRoutes.push(retainedScenes[key].route);
+      hiddenDescriptors[key] = retainedScenes[key].descriptor;
+    }
+  });
+
+  return {
+    retainContext,
+    hiddenRoutes,
+    hiddenDescriptors,
+    retainedKeys: Object.keys(retainedScenes),
+  };
+}