@react-navigation/core 8.0.0-alpha.30 → 8.0.0-alpha.32

package/src/BaseNavigationContainer.tsx

@@ -3,24 +3,31 @@ import {
   type InitialState,
   type NavigationAction,
   type NavigationState,
+  type ParamListBase,
   type PartialState,
   type Route,
 } from '@react-navigation/routers';
 import * as React from 'react';
 import useLatestCallback from 'use-latest-callback';
+import warnOnce from 'warn-once';
 
 import { checkDuplicateRouteNames } from './checkDuplicateRouteNames';
-import { checkSerializable } from './checkSerializable';
 import { ConsumedParamsContext } from './ConsumedParamsContext';
 import { NOT_INITIALIZED_ERROR } from './createNavigationContainerRef';
 import { EnsureSingleNavigator } from './EnsureSingleNavigator';
 import { findFocusedRoute } from './findFocusedRoute';
-import { NavigationBuilderContext } from './NavigationBuilderContext';
+import {
+  NavigationBuilderContext,
+  type WithStackTrace,
+} from './NavigationBuilderContext';
 import { NavigationContainerRefContext } from './NavigationContainerRefContext';
 import { NavigationIndependentTreeContext } from './NavigationIndependentTreeContext';
+import { NavigationRootContext } from './NavigationRootContext';
 import { NavigationStateContext } from './NavigationStateContext';
 import { ThemeProvider } from './theming/ThemeProvider';
 import type {
+  EventListenerCallback,
+  GenericNavigation,
   NavigationContainerEventMap,
   NavigationContainerProps,
   NavigationContainerRef,
@@ -37,9 +44,6 @@ import { useSyncState } from './useSyncState';
 
 type State = NavigationState | PartialState<NavigationState> | undefined;
 
-const serializableWarnings: string[] = [];
-const duplicateNameWarnings: string[] = [];
-
 type Props<ParamList extends {}> = NavigationContainerProps & {
   ref?: React.Ref<NavigationContainerRef<ParamList>>;
 };
@@ -104,7 +108,7 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
     );
   }
 
-  const { state, getState, setState, scheduleUpdate, flushUpdates } =
+  const { state, getState, setState, subscribe, scheduleUpdate, flushUpdates } =
     useSyncState<State>(() =>
       getPartialState(initialState == null ? undefined : initialState)
     );
@@ -125,6 +129,41 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
 
   const { keyedListeners, addKeyedListener } = useKeyedChildListeners();
 
+  const stackRef = React.useRef<string | undefined>(undefined);
+
+  const withStackTrace = React.useCallback<WithStackTrace>(
+    (entry, callback) => {
+      if (process.env.NODE_ENV === 'production' || stackRef.current != null) {
+        callback();
+        return;
+      }
+
+      const error = new Error();
+
+      if (Error.captureStackTrace) {
+        // Available on V8 and Hermes, omits the frames of `entry` and what it called
+        Error.captureStackTrace(error, entry);
+
+        stackRef.current = error.stack;
+      } else {
+        // Other engines always include them, so we drop the frames up to `entry` ourselves
+        const frames = error.stack?.split('\n') ?? [];
+        const index = frames.findIndex((frame) =>
+          frame.includes(`${entry.name}@`)
+        );
+
+        stackRef.current = frames.slice(index + 1).join('\n');
+      }
+
+      try {
+        callback();
+      } finally {
+        stackRef.current = undefined;
+      }
+    },
+    []
+  );
+
   const dispatch = useLatestCallback(
     (
       action: NavigationAction | ((state: NavigationState) => NavigationAction)
@@ -134,11 +173,13 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
       if (listener == null) {
         console.error(NOT_INITIALIZED_ERROR);
       } else {
-        listener((navigation) =>
-          React.startTransition(() => {
-            navigation.dispatch(action);
-          })
-        );
+        withStackTrace(dispatch, () => {
+          listener((navigation) =>
+            React.startTransition(() => {
+              navigation.dispatch(action);
+            })
+          );
+        });
       }
     }
   );
@@ -161,7 +202,7 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
 
   const resetRoot = useLatestCallback(
     (state: PartialState<NavigationState> | NavigationState) => {
-      const target = state?.key ?? keyedListeners.getState.root?.().key;
+      const target = keyedListeners.getState.root?.().key;
       const listener = listeners.focus[0];
 
       if (target == null || listener == null) {
@@ -199,29 +240,28 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
 
   const { addOptionsGetter, getCurrentOptions } = useOptionsGetters({});
 
-  const navigation: NavigationContainerRef<ParamList> = React.useMemo(
+  const container: NavigationContainerRef<ParamList> = React.useMemo(
     () => ({
       ...Object.keys(CommonActions).reduce<any>((acc, name) => {
-        acc[name] = (...args: any[]) =>
-          // @ts-expect-error: this is ok
-          dispatch(CommonActions[name](...args));
+        const helper = (...args: any[]) =>
+          withStackTrace(helper, () =>
+            // @ts-expect-error: this is ok
+            dispatch(CommonActions[name](...args))
+          );
+
+        acc[name] = helper;
 
         return acc;
       }, {}),
       ...emitter.create('root'),
       dispatch,
       resetRoot,
-      isFocused: () => true,
       canGoBack,
-      getParent: () => undefined,
       getState,
       getRootState,
       getCurrentRoute,
       getCurrentOptions,
       isReady,
-      setOptions: () => {
-        throw new Error('Cannot call setOptions outside a screen');
-      },
     }),
     [
       canGoBack,
@@ -233,10 +273,112 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
       getState,
       isReady,
       resetRoot,
+      withStackTrace,
     ]
   );
 
-  React.useImperativeHandle(ref, () => navigation, [navigation]);
+  const navigation: GenericNavigation<ParamListBase> = React.useMemo(() => {
+    const events = emitter.create('root');
+
+    const dispatch = (
+      thunk: NavigationAction | ((state: NavigationState) => NavigationAction)
+    ) => {
+      const root = keyedListeners.getNavigation.root?.();
+
+      if (root == null) {
+        console.error(NOT_INITIALIZED_ERROR);
+        return;
+      }
+
+      withStackTrace(dispatch, () => {
+        React.startTransition(() => {
+          root.dispatch(thunk);
+        });
+      });
+    };
+
+    const helpers = Object.keys(CommonActions).reduce<any>((acc, name) => {
+      const helper = (...args: any) => {
+        if (
+          name === 'setParams' ||
+          name === 'replaceParams' ||
+          name === 'pushParams'
+        ) {
+          throw new Error(`Cannot call ${name} outside a screen`);
+        }
+
+        withStackTrace(helper, () =>
+          // @ts-expect-error name is a valid key, but TypeScript cannot infer it.
+          dispatch(CommonActions[name](...args))
+        );
+      };
+
+      acc[name] = helper;
+
+      return acc;
+    }, {});
+
+    const listeners = new WeakMap<
+      (...args: never[]) => void,
+      EventListenerCallback<NavigationContainerEventMap, 'state'>
+    >();
+
+    return {
+      ...helpers,
+      dispatch,
+      addListener: (type, callback) => {
+        if (type === 'state') {
+          let listener = listeners.get(callback);
+
+          if (listener === undefined) {
+            // Root's state change events can contain stale and undefined state
+            // But navigation objects should only receive non-stale state
+            // So we add a wrapper to filter out stale events
+            listener = (event) => {
+              if (event.data.state?.stale === false) {
+                // @ts-expect-error TypeScript doesn't narrow the generic event callback with its type.
+                callback(event);
+              }
+            };
+
+            listeners.set(callback, listener);
+          }
+
+          return events.addListener('state', listener);
+        }
+
+        return () => {};
+      },
+      removeListener: (type, callback) => {
+        if (type === 'state') {
+          const listener = listeners.get(callback);
+
+          if (listener) {
+            events.removeListener('state', listener);
+            listeners.delete(callback);
+          }
+        }
+      },
+      canGoBack: () =>
+        keyedListeners.getNavigation.root?.().canGoBack() ?? false,
+      getState: () => keyedListeners.getState.root?.(),
+      getParent: (routeName?: string) => {
+        if (routeName !== undefined) {
+          throw new Error(
+            `Couldn't find a navigation object for '${routeName}' because it's called outside a screen. Is your component inside a screen?`
+          );
+        }
+
+        return undefined;
+      },
+      setOptions: () => {
+        throw new Error('Cannot call setOptions outside a screen');
+      },
+      isFocused: () => true,
+    };
+  }, [emitter, keyedListeners, withStackTrace]);
+
+  React.useImperativeHandle(ref, () => container, [container]);
 
   const onDispatchAction = useLatestCallback(
     (action: NavigationAction, noop: boolean) => {
@@ -276,8 +418,6 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
     });
   });
 
-  const stackRef = React.useRef<string | undefined>(undefined);
-
   const lastEmittedStateRef = React.useRef<State>(undefined);
 
   const getIsStateEmitted = useLatestCallback(
@@ -294,7 +434,7 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
       getIsStateEmitted,
       scheduleUpdate,
       flushUpdates,
-      stackRef,
+      withStackTrace,
     }),
     [
       addListener,
@@ -305,6 +445,7 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
       getIsStateEmitted,
       scheduleUpdate,
       flushUpdates,
+      withStackTrace,
     ]
   );
 
@@ -317,12 +458,22 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
       state,
       getState,
       setState,
+      subscribe,
       getKey,
       setKey,
       getIsInitial,
       addOptionsGetter,
     }),
-    [state, getState, setState, getKey, setKey, getIsInitial, addOptionsGetter]
+    [
+      state,
+      getState,
+      setState,
+      subscribe,
+      getKey,
+      setKey,
+      getIsInitial,
+      addOptionsGetter,
+    ]
   );
 
   const onReadyRef = React.useRef(onReady);
@@ -349,59 +500,6 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
 
     if (process.env.NODE_ENV !== 'production') {
       if (hydratedState !== undefined) {
-        const serializableResult = checkSerializable(hydratedState);
-
-        if (!serializableResult.serializable) {
-          const { location, reason } = serializableResult;
-
-          let path = '';
-          let pointer: Record<any, any> = hydratedState;
-          let params = false;
-
-          for (let i = 0; i < location.length; i++) {
-            const curr = location[i];
-            const prev = location[i - 1];
-
-            if (curr == null) {
-              continue;
-            }
-
-            pointer = pointer[curr];
-
-            if (!params && curr === 'state') {
-              continue;
-            } else if (!params && curr === 'routes') {
-              if (path) {
-                path += ' > ';
-              }
-            } else if (
-              !params &&
-              typeof curr === 'number' &&
-              prev === 'routes'
-            ) {
-              path += pointer?.name;
-            } else if (!params) {
-              path += ` > ${curr}`;
-              params = true;
-            } else {
-              if (typeof curr === 'number' || /^[0-9]+$/.test(curr)) {
-                path += `[${curr}]`;
-              } else if (/^[a-z$_]+$/i.test(curr)) {
-                path += `.${curr}`;
-              } else {
-                path += `[${JSON.stringify(curr)}]`;
-              }
-            }
-          }
-
-          const message = `Non-serializable values were found in the navigation state. Check:\n\n${path} (${reason})\n\nThis can break usage such as persisting and restoring state. This might happen if you passed non-serializable values such as function, class instances etc. in params. If you need to use components with callbacks in your options, you can use 'navigation.setOptions' instead. See https://reactnavigation.org/docs/troubleshooting#i-get-the-warning-non-serializable-values-were-found-in-the-navigation-state for more details.`;
-
-          if (!serializableWarnings.includes(message)) {
-            serializableWarnings.push(message);
-            console.warn(message);
-          }
-        }
-
         const duplicateRouteNamesResult =
           checkDuplicateRouteNames(hydratedState);
 
@@ -410,10 +508,7 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
             (locations) => `\n${locations.join(', ')}`
           )}\n\nThis can cause confusing behavior during navigation. Consider using unique names for each screen instead.`;
 
-          if (!duplicateNameWarnings.includes(message)) {
-            duplicateNameWarnings.push(message);
-            console.warn(message);
-          }
+          warnOnce(true, message);
         }
       }
     }
@@ -475,20 +570,22 @@ export function BaseNavigationContainer<ParamList extends {} = RootParamList>({
 
   return (
     <NavigationIndependentTreeContext.Provider value={false}>
-      <NavigationContainerRefContext.Provider value={navigation}>
-        <NavigationBuilderContext.Provider value={builderContext}>
-          <NavigationStateContext.Provider value={context}>
-            <ConsumedParamsContext.Provider value={consumedParams}>
-              <UnhandledActionContext.Provider
-                value={onUnhandledAction ?? defaultOnUnhandledAction}
-              >
-                <EnsureSingleNavigator>
-                  <ThemeProvider value={theme}>{children}</ThemeProvider>
-                </EnsureSingleNavigator>
-              </UnhandledActionContext.Provider>
-            </ConsumedParamsContext.Provider>
-          </NavigationStateContext.Provider>
-        </NavigationBuilderContext.Provider>
+      <NavigationContainerRefContext.Provider value={container}>
+        <NavigationRootContext.Provider value={navigation}>
+          <NavigationBuilderContext.Provider value={builderContext}>
+            <NavigationStateContext.Provider value={context}>
+              <ConsumedParamsContext.Provider value={consumedParams}>
+                <UnhandledActionContext.Provider
+                  value={onUnhandledAction ?? defaultOnUnhandledAction}
+                >
+                  <EnsureSingleNavigator>
+                    <ThemeProvider value={theme}>{children}</ThemeProvider>
+                  </EnsureSingleNavigator>
+                </UnhandledActionContext.Provider>
+              </ConsumedParamsContext.Provider>
+            </NavigationStateContext.Provider>
+          </NavigationBuilderContext.Provider>
+        </NavigationRootContext.Provider>
       </NavigationContainerRefContext.Provider>
     </NavigationIndependentTreeContext.Provider>
   );

package/src/DataLoading.tsx

@@ -134,7 +134,10 @@ export function getLoaderForStateChange(
   const nested =
     'config' in item
       ? item
-      : 'screen' in item && 'config' in item.screen
+      : 'screen' in item &&
+          // Nested navigators cannot be defined as a getter
+          Object.getOwnPropertyDescriptor(item, 'screen')?.get == null &&
+          'config' in item.screen
         ? item.screen
         : undefined;
 

package/src/NavigationBuilderContext.tsx

@@ -15,6 +15,7 @@ export type ListenerMap = {
 
 export type KeyedListenerMap = {
   getState: GetStateListener;
+  getNavigation: GetNavigationListener;
   beforeRemove: ChildBeforeRemoveListener;
 };
 
@@ -47,6 +48,13 @@ export type FocusedNavigationListener = <T>(
 
 export type GetStateListener = () => NavigationState;
 
+export type GetNavigationListener = () => NavigationHelpers<ParamListBase>;
+
+export type WithStackTrace = (
+  entry: (...args: never[]) => void,
+  callback: () => void
+) => void;
+
 export type ChildBeforeRemoveListener = (
   action: NavigationAction,
   nextState: NavigationState | PartialState<NavigationState> | undefined
@@ -73,7 +81,7 @@ export const NavigationBuilderContext = React.createContext<{
   getIsStateEmitted: () => boolean;
   scheduleUpdate: (callback: () => void) => void;
   flushUpdates: () => void;
-  stackRef?: React.RefObject<string | undefined> | undefined;
+  withStackTrace: WithStackTrace;
 }>({
   onDispatchAction: () => undefined,
   onEmitEvent: () => undefined,
@@ -85,4 +93,5 @@ export const NavigationBuilderContext = React.createContext<{
   flushUpdates: () => {
     throw new Error("Couldn't find a context for flushing updates.");
   },
+  withStackTrace: (_entry, callback) => callback(),
 });

package/src/NavigationIndependentTree.tsx

@@ -3,12 +3,17 @@ import * as React from 'react';
 import { NavigationFocusedRouteStateContext } from './NavigationFocusedRouteStateContext';
 import { NavigationIndependentTreeContext } from './NavigationIndependentTreeContext';
 import {
+  IsScreenContext,
   NamedRouteContextListContext,
   NavigationContext,
   NavigationRouteContext,
 } from './NavigationProvider';
+import { NavigationRootContext } from './NavigationRootContext';
 import { IsFocusedContext } from './useIsFocused';
-import { NamedNavigationStateListenerListContext } from './useNavigationState';
+import {
+  NamedNavigationStateListenerListContext,
+  NavigationStateListenerContext,
+} from './useNavigationState';
 
 /**
  * Component to make the child navigation container independent of parent containers.
@@ -20,20 +25,26 @@ export function NavigationIndependentTree({
 }) {
   return (
     // We need to clear any existing contexts for nested independent container to work correctly
-    <NamedNavigationStateListenerListContext.Provider value={undefined}>
-      <NamedRouteContextListContext.Provider value={undefined}>
-        <NavigationRouteContext.Provider value={undefined}>
-          <NavigationContext.Provider value={undefined}>
-            <NavigationFocusedRouteStateContext.Provider value={undefined}>
-              <IsFocusedContext.Provider value={undefined}>
-                <NavigationIndependentTreeContext.Provider value={true}>
-                  {children}
-                </NavigationIndependentTreeContext.Provider>
-              </IsFocusedContext.Provider>
-            </NavigationFocusedRouteStateContext.Provider>
-          </NavigationContext.Provider>
-        </NavigationRouteContext.Provider>
-      </NamedRouteContextListContext.Provider>
-    </NamedNavigationStateListenerListContext.Provider>
+    <NavigationStateListenerContext.Provider value={undefined}>
+      <NamedNavigationStateListenerListContext.Provider value={undefined}>
+        <NamedRouteContextListContext.Provider value={undefined}>
+          <NavigationRouteContext.Provider value={undefined}>
+            <NavigationContext.Provider value={undefined}>
+              <NavigationRootContext.Provider value={undefined}>
+                <NavigationFocusedRouteStateContext.Provider value={undefined}>
+                  <IsFocusedContext.Provider value={undefined}>
+                    <NavigationIndependentTreeContext.Provider value={true}>
+                      <IsScreenContext.Provider value={false}>
+                        {children}
+                      </IsScreenContext.Provider>
+                    </NavigationIndependentTreeContext.Provider>
+                  </IsFocusedContext.Provider>
+                </NavigationFocusedRouteStateContext.Provider>
+              </NavigationRootContext.Provider>
+            </NavigationContext.Provider>
+          </NavigationRouteContext.Provider>
+        </NamedRouteContextListContext.Provider>
+      </NamedNavigationStateListenerListContext.Provider>
+    </NavigationStateListenerContext.Provider>
   );
 }

package/src/NavigationProvider.tsx

@@ -20,11 +20,10 @@ export const NavigationContext = React.createContext<
   NavigationProp<ParamListBase> | undefined
 >(undefined);
 
-type Props = {
-  route: Route<string>;
-  navigation: NavigationProp<ParamListBase>;
-  children: React.ReactNode;
-};
+/**
+ * Context which indicates whether the component is inside a screen.
+ */
+export const IsScreenContext = React.createContext(false);
 
 /**
  * Component to provide the navigation and route contexts to its children.
@@ -33,6 +32,12 @@ export const NamedRouteContextListContext = React.createContext<
   Record<string, React.Context<Route<string>>> | undefined
 >(undefined);
 
+type Props = {
+  route: Route<string>;
+  navigation: NavigationProp<ParamListBase>;
+  children: React.ReactNode;
+};
+
 export function NavigationProvider({ route, navigation, children }: Props) {
   const NamedRouteContext = useLazyValue(() => React.createContext(route));
 
@@ -64,7 +69,9 @@ export function NavigationProvider({ route, navigation, children }: Props) {
           <NavigationRouteContext.Provider value={route}>
             <NavigationContext.Provider value={navigation}>
               <IsFocusedContext.Provider value={isFocused}>
-                {children}
+                <IsScreenContext.Provider value={true}>
+                  {children}
+                </IsScreenContext.Provider>
               </IsFocusedContext.Provider>
             </NavigationContext.Provider>
           </NavigationRouteContext.Provider>

package/src/NavigationRootContext.tsx

@@ -0,0 +1,11 @@
+import type { ParamListBase } from '@react-navigation/routers';
+import * as React from 'react';
+
+import type { GenericNavigation } from './types';
+
+/**
+ * Context which holds the navigation object for components outside a screen.
+ */
+export const NavigationRootContext = React.createContext<
+  GenericNavigation<ParamListBase> | undefined
+>(undefined);

package/src/NavigationStateContext.tsx

@@ -13,6 +13,7 @@ export const NavigationStateContext = React.createContext<{
   setState: (
     state: NavigationState | PartialState<NavigationState> | undefined
   ) => void;
+  subscribe: (callback: () => void) => () => void;
   getIsInitial: () => boolean;
   addOptionsGetter?:
     | ((key: string, getter: () => object | undefined | null) => void)
@@ -32,6 +33,9 @@ export const NavigationStateContext = React.createContext<{
   get setState(): any {
     throw new Error(MISSING_CONTEXT_ERROR);
   },
+  get subscribe(): any {
+    throw new Error(MISSING_CONTEXT_ERROR);
+  },
   get getIsInitial(): any {
     throw new Error(MISSING_CONTEXT_ERROR);
   },

package/src/SceneView.tsx

@@ -24,6 +24,7 @@ type Props<State extends NavigationState, ScreenOptions extends {}> = {
   routeState: NavigationState | PartialState<NavigationState> | undefined;
   getState: () => State;
   setState: (state: State) => void;
+  subscribe: (callback: () => void) => () => void;
   options: object;
   clearOptions: () => void;
 };
@@ -42,6 +43,7 @@ export function SceneView<
   routeState,
   getState,
   setState,
+  subscribe,
   options,
   clearOptions,
 }: Props<State, ScreenOptions>) {
@@ -152,6 +154,7 @@ export function SceneView<
       state: routeState,
       getState: getCurrentState,
       setState: setCurrentState,
+      subscribe,
       getKey,
       setKey,
       getIsInitial,
@@ -161,6 +164,7 @@ export function SceneView<
       routeState,
       getCurrentState,
       setCurrentState,
+      subscribe,
       getKey,
       setKey,
       getIsInitial,