@react-navigation/core 6.0.1 → 6.1.1

package/src/UnhandledActionContext.tsx

@@ -1,9 +1,8 @@
 import type { NavigationAction } from '@react-navigation/routers';
 import * as React from 'react';
 
-const UnhandledActionContext =
-  React.createContext<((action: NavigationAction) => void) | undefined>(
-    undefined
-  );
+const UnhandledActionContext = React.createContext<
+  ((action: NavigationAction) => void) | undefined
+>(undefined);
 
 export default UnhandledActionContext;

package/src/createNavigationContainerRef.tsx

@@ -1,6 +1,10 @@
 import { CommonActions } from '@react-navigation/routers';
 
-import type { NavigationContainerRefWithCurrent } from './types';
+import type {
+  NavigationContainerEventMap,
+  NavigationContainerRef,
+  NavigationContainerRefWithCurrent,
+} from './types';
 
 export const NOT_INITIALIZED_ERROR =
   "The 'navigation' object hasn't been initialized yet. This might happen if you don't have a navigator mounted, or if the navigator hasn't finished mounting. See https://reactnavigation.org/docs/navigating-without-navigation-prop#handling-initialization for more details.";
@@ -14,6 +18,7 @@ export default function createNavigationContainerRef<
     'removeListener',
     'resetRoot',
     'dispatch',
+    'isFocused',
     'canGoBack',
     'getRootState',
     'getState',
@@ -22,26 +27,72 @@ export default function createNavigationContainerRef<
     'getCurrentOptions',
   ] as const;
 
+  const listeners: Record<string, ((...args: any[]) => void)[]> = {};
+
+  const removeListener = (
+    event: string,
+    callback: (...args: any[]) => void
+  ) => {
+    if (listeners[event]) {
+      listeners[event] = listeners[event].filter((cb) => cb !== callback);
+    }
+  };
+
+  let current: NavigationContainerRef<ParamList> | null = null;
+
   const ref: NavigationContainerRefWithCurrent<ParamList> = {
+    get current() {
+      return current;
+    },
+    set current(value: NavigationContainerRef<ParamList> | null) {
+      current = value;
+
+      if (value != null) {
+        Object.entries(listeners).forEach(([event, callbacks]) => {
+          callbacks.forEach((callback) => {
+            value.addListener(
+              event as keyof NavigationContainerEventMap,
+              callback
+            );
+          });
+        });
+      }
+    },
+    isReady: () => {
+      if (current == null) {
+        return false;
+      }
+
+      return current.isReady();
+    },
     ...methods.reduce<any>((acc, name) => {
       acc[name] = (...args: any[]) => {
-        if (ref.current == null) {
-          console.error(NOT_INITIALIZED_ERROR);
+        if (current == null) {
+          switch (name) {
+            case 'addListener': {
+              const [event, callback] = args;
+
+              listeners[event] = listeners[event] || [];
+              listeners[event].push(callback);
+
+              return () => removeListener(event, callback);
+            }
+            case 'removeListener': {
+              const [event, callback] = args;
+
+              removeListener(event, callback);
+              break;
+            }
+            default:
+              console.error(NOT_INITIALIZED_ERROR);
+          }
         } else {
           // @ts-expect-error: this is ok
-          return ref.current[name](...args);
+          return current[name](...args);
         }
       };
       return acc;
     }, {}),
-    isReady: () => {
-      if (ref.current == null) {
-        return false;
-      }
-
-      return ref.current.isReady();
-    },
-    current: null,
   };
 
   return ref;

package/src/createNavigatorFactory.tsx

@@ -27,7 +27,7 @@ export default function createNavigatorFactory<
   > {
     if (arguments[0] !== undefined) {
       throw new Error(
-        "Creating a navigator doesn't take an argument. Maybe you are trying to use React Navigation 4 API with React Navigation 5? See https://reactnavigation.org/docs/upgrading-from-4.x for migration guide."
+        "Creating a navigator doesn't take an argument. Maybe you are trying to use React Navigation 4 API? See https://reactnavigation.org/docs/hello-react-navigation for the latest API and guides."
       );
     }
 

package/src/isArrayEqual.tsx

@@ -3,5 +3,13 @@
  * We need to make sure that both values and order match.
  */
 export default function isArrayEqual(a: any[], b: any[]) {
-  return a.length === b.length && a.every((it, index) => it === b[index]);
+  if (a === b) {
+    return true;
+  }
+
+  if (a.length !== b.length) {
+    return false;
+  }
+
+  return a.every((it, index) => it === b[index]);
 }

package/src/isRecordEqual.tsx

@@ -0,0 +1,20 @@
+/**
+ * Compare two records with primitive values as the content.
+ */
+export default function isRecordEqual(
+  a: Record<string, any>,
+  b: Record<string, any>
+) {
+  if (a === b) {
+    return true;
+  }
+
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+
+  return aKeys.every((key) => a[key] === b[key]);
+}

package/src/types.tsx

@@ -393,12 +393,12 @@ export type Descriptor<
 export type ScreenListeners<
   State extends NavigationState,
   EventMap extends EventMapBase
-> = Partial<
-  {
-    [EventName in keyof (EventMap &
-      EventMapCore<State>)]: EventListenerCallback<EventMap, EventName>;
-  }
->;
+> = Partial<{
+  [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
+    EventMap,
+    EventName
+  >;
+}>;
 
 export type RouteConfigComponent<
   ParamList extends ParamListBase,
@@ -439,6 +439,13 @@ export type RouteConfig<
   ScreenOptions extends {},
   EventMap extends EventMapBase
 > = {
+  /**
+   * Optional key for this screen. This doesn't need to be unique.
+   * If the key changes, existing screens with this name will be removed or reset.
+   * Useful when we have some common screens and have conditional rendering.
+   */
+  navigationKey?: string;
+
   /**
    * Route name of this screen.
    */
@@ -482,6 +489,12 @@ export type RouteGroupConfig<
   ParamList extends ParamListBase,
   ScreenOptions extends {}
 > = {
+  /**
+   * Optional key for the screens in this group.
+   * If the key changes, all existing screens in this group will be removed or reset.
+   */
+  navigationKey?: string;
+
   /**
    * Navigator options for this screen.
    */

package/src/useChildListeners.tsx

@@ -6,11 +6,9 @@ import type { ListenerMap } from './NavigationBuilderContext';
  * Hook which lets child navigators add action listeners.
  */
 export default function useChildListeners() {
-  const { current: listeners } = React.useRef<
-    {
-      [K in keyof ListenerMap]: ListenerMap[K][];
-    }
-  >({
+  const { current: listeners } = React.useRef<{
+    [K in keyof ListenerMap]: ListenerMap[K][];
+  }>({
     action: [],
     focus: [],
   });

package/src/useDescriptors.tsx

@@ -29,10 +29,11 @@ export type ScreenConfigWithParent<
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase
-> = [
-  (ScreenOptionsOrCallback<ScreenOptions> | undefined)[] | undefined,
-  RouteConfig<ParamListBase, string, State, ScreenOptions, EventMap>
-];
+> = {
+  keys: (string | undefined)[];
+  options: (ScreenOptionsOrCallback<ScreenOptions> | undefined)[] | undefined;
+  props: RouteConfig<ParamListBase, string, State, ScreenOptions, EventMap>;
+};
 
 type ScreenOptionsOrCallback<ScreenOptions extends {}> =
   | ScreenOptions
@@ -149,15 +150,15 @@ export default function useDescriptors<
     >
   >((acc, route, i) => {
     const config = screens[route.name];
-    const screen = config[1];
+    const screen = config.props;
     const navigation = navigations[route.key];
 
     const optionsList = [
       // The default `screenOptions` passed to the navigator
       screenOptions,
       // The `screenOptions` props passed to `Group` elements
-      ...((config[0]
-        ? config[0].filter(Boolean)
+      ...((config.options
+        ? config.options.filter(Boolean)
         : []) as ScreenOptionsOrCallback<ScreenOptions>[]),
       // The `options` prop passed to `Screen` elements,
       screen.options,

package/src/useKeyedChildListeners.tsx

@@ -6,14 +6,12 @@ import type { KeyedListenerMap } from './NavigationBuilderContext';
  * Hook which lets child navigators add getters to be called for obtaining rehydrated state.
  */
 export default function useKeyedChildListeners() {
-  const { current: keyedListeners } = React.useRef<
-    {
-      [K in keyof KeyedListenerMap]: Record<
-        string,
-        KeyedListenerMap[K] | undefined
-      >;
-    }
-  >({
+  const { current: keyedListeners } = React.useRef<{
+    [K in keyof KeyedListenerMap]: Record<
+      string,
+      KeyedListenerMap[K] | undefined
+    >;
+  }>({
     getState: {},
     beforeRemove: {},
   });

package/src/useNavigationBuilder.tsx

@@ -15,6 +15,7 @@ import { isValidElementType } from 'react-is';
 
 import Group from './Group';
 import isArrayEqual from './isArrayEqual';
+import isRecordEqual from './isRecordEqual';
 import NavigationHelpersContext from './NavigationHelpersContext';
 import NavigationRouteContext from './NavigationRouteContext';
 import NavigationStateContext from './NavigationStateContext';
@@ -51,6 +52,9 @@ type NavigatorRoute<State extends NavigationState> = {
   params?: NavigatorScreenParams<ParamListBase, State>;
 };
 
+const isValidKey = (key: unknown) =>
+  key === undefined || (typeof key === 'string' && key !== '');
+
 /**
  * Extract route config object from React children elements.
  *
@@ -62,7 +66,12 @@ const getRouteConfigsFromChildren = <
   EventMap extends EventMapBase
 >(
   children: React.ReactNode,
-  options?: ScreenConfigWithParent<State, ScreenOptions, EventMap>[0]
+  groupKey?: string,
+  groupOptions?: ScreenConfigWithParent<
+    State,
+    ScreenOptions,
+    EventMap
+  >['options']
 ) => {
   const configs = React.Children.toArray(children).reduce<
     ScreenConfigWithParent<State, ScreenOptions, EventMap>[]
@@ -71,29 +80,50 @@ const getRouteConfigsFromChildren = <
       if (child.type === Screen) {
         // We can only extract the config from `Screen` elements
         // If something else was rendered, it's probably a bug
-        acc.push([
-          options,
-          child.props as RouteConfig<
+
+        if (!isValidKey(child.props.navigationKey)) {
+          throw new Error(
+            `Got an invalid 'navigationKey' prop (${JSON.stringify(
+              child.props.navigationKey
+            )}) for the screen '${
+              child.props.name
+            }'. It must be a non-empty string or 'undefined'.`
+          );
+        }
+
+        acc.push({
+          keys: [groupKey, child.props.navigationKey],
+          options: groupOptions,
+          props: child.props as RouteConfig<
             ParamListBase,
             string,
             State,
             ScreenOptions,
             EventMap
           >,
-        ]);
+        });
         return acc;
       }
 
       if (child.type === React.Fragment || child.type === Group) {
+        if (!isValidKey(child.props.navigationKey)) {
+          throw new Error(
+            `Got an invalid 'navigationKey' prop (${JSON.stringify(
+              child.props.navigationKey
+            )}) for the group. It must be a non-empty string or 'undefined'.`
+          );
+        }
+
         // When we encounter a fragment or group, we need to dive into its children to extract the configs
         // This is handy to conditionally define a group of screens
         acc.push(
           ...getRouteConfigsFromChildren<State, ScreenOptions, EventMap>(
             child.props.children,
+            child.props.navigationKey,
             child.type !== Group
-              ? options
-              : options != null
-              ? [...options, child.props.screenOptions]
+              ? groupOptions
+              : groupOptions != null
+              ? [...groupOptions, child.props.screenOptions]
               : [child.props.screenOptions]
           )
         );
@@ -118,7 +148,7 @@ const getRouteConfigsFromChildren = <
 
   if (process.env.NODE_ENV !== 'production') {
     configs.forEach((config) => {
-      const { name, children, component, getComponent } = config[1];
+      const { name, children, component, getComponent } = config.props;
 
       if (typeof name !== 'string' || !name) {
         throw new Error(
@@ -169,13 +199,19 @@ const getRouteConfigsFromChildren = <
           );
         }
 
-        if (typeof component === 'function' && component.name === 'component') {
-          // Inline anonymous functions passed in the `component` prop will have the name of the prop
-          // It's relatively safe to assume that it's not a component since it should also have PascalCase name
-          // We won't catch all scenarios here, but this should catch a good chunk of incorrect use.
-          console.warn(
-            `Looks like you're passing an inline function for 'component' prop for the screen '${name}' (e.g. component={() => <SomeComponent />}). Passing an inline function will cause the component state to be lost on re-render and cause perf issues since it's re-created every render. You can pass the function as children to 'Screen' instead to achieve the desired behaviour.`
-          );
+        if (typeof component === 'function') {
+          if (component.name === 'component') {
+            // Inline anonymous functions passed in the `component` prop will have the name of the prop
+            // It's relatively safe to assume that it's not a component since it should also have PascalCase name
+            // We won't catch all scenarios here, but this should catch a good chunk of incorrect use.
+            console.warn(
+              `Looks like you're passing an inline function for 'component' prop for the screen '${name}' (e.g. component={() => <SomeComponent />}). Passing an inline function will cause the component state to be lost on re-render and cause perf issues since it's re-created every render. You can pass the function as children to 'Screen' instead to achieve the desired behaviour.`
+            );
+          } else if (/^[a-z]/.test(component.name)) {
+            console.warn(
+              `Got a component with the name '${component.name}' for the screen '${name}'. React Components must start with an uppercase letter. If you're passing a regular function and not a component, pass it as children to 'Screen' instead. Otherwise capitalize your component's name.`
+            );
+          }
         }
       } else {
         throw new Error(
@@ -230,26 +266,36 @@ export default function useNavigationBuilder<
     })
   );
 
-  const routeConfigs =
-    getRouteConfigsFromChildren<State, ScreenOptions, EventMap>(children);
+  const routeConfigs = getRouteConfigsFromChildren<
+    State,
+    ScreenOptions,
+    EventMap
+  >(children);
 
   const screens = routeConfigs.reduce<
     Record<string, ScreenConfigWithParent<State, ScreenOptions, EventMap>>
   >((acc, config) => {
-    if (config[1].name in acc) {
+    if (config.props.name in acc) {
       throw new Error(
-        `A navigator cannot contain multiple 'Screen' components with the same name (found duplicate screen named '${config[1].name}')`
+        `A navigator cannot contain multiple 'Screen' components with the same name (found duplicate screen named '${config.props.name}')`
       );
     }
 
-    acc[config[1].name] = config;
+    acc[config.props.name] = config;
     return acc;
   }, {});
 
-  const routeNames = routeConfigs.map((config) => config[1].name);
+  const routeNames = routeConfigs.map((config) => config.props.name);
+  const routeKeyList = routeNames.reduce<Record<string, React.Key | undefined>>(
+    (acc, curr) => {
+      acc[curr] = screens[curr].keys.map((key) => key ?? '').join(':');
+      return acc;
+    },
+    {}
+  );
   const routeParamList = routeNames.reduce<Record<string, object | undefined>>(
     (acc, curr) => {
-      const { initialParams } = screens[curr][1];
+      const { initialParams } = screens[curr].props;
       acc[curr] = initialParams;
       return acc;
     },
@@ -260,7 +306,7 @@ export default function useNavigationBuilder<
   >(
     (acc, curr) =>
       Object.assign(acc, {
-        [curr]: screens[curr][1].getId,
+        [curr]: screens[curr].props.getId,
       }),
     {}
   );
@@ -315,7 +361,7 @@ export default function useNavigationBuilder<
     const initialRouteParamList = routeNames.reduce<
       Record<string, object | undefined>
     >((acc, curr) => {
-      const { initialParams } = screens[curr][1];
+      const { initialParams } = screens[curr].props;
       const initialParamsFromParams =
         route?.params?.state == null &&
         route?.params?.initial !== false &&
@@ -371,6 +417,14 @@ export default function useNavigationBuilder<
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [currentState, router, isStateValid]);
 
+  const previousRouteKeyListRef = React.useRef(routeKeyList);
+
+  React.useEffect(() => {
+    previousRouteKeyListRef.current = routeKeyList;
+  });
+
+  const previousRouteKeyList = previousRouteKeyListRef.current;
+
   let state =
     // If the state isn't initialized, or stale, use the state we initialized instead
     // The state won't update until there's a change needed in the state we have initalized locally
@@ -381,12 +435,20 @@ export default function useNavigationBuilder<
 
   let nextState: State = state;
 
-  if (!isArrayEqual(state.routeNames, routeNames)) {
+  if (
+    !isArrayEqual(state.routeNames, routeNames) ||
+    !isRecordEqual(routeKeyList, previousRouteKeyList)
+  ) {
     // When the list of route names change, the router should handle it to remove invalid routes
     nextState = router.getStateForRouteNamesChange(state, {
       routeNames,
       routeParamList,
       routeGetIdList,
+      routeKeyChanges: Object.keys(routeKeyList).filter(
+        (name) =>
+          previousRouteKeyList.hasOwnProperty(name) &&
+          routeKeyList[name] !== previousRouteKeyList[name]
+      ),
     });
   }
 
@@ -522,7 +584,7 @@ export default function useNavigationBuilder<
         ...[
           screenListeners,
           ...routeNames.map((name) => {
-            const { listeners } = screens[name][1];
+            const { listeners } = screens[name].props;
             return listeners;
           }),
         ].map((listeners) => {

package/src/useRegisterNavigator.tsx

@@ -13,7 +13,7 @@ export default function useRegisterNavigator() {
 
   if (container === undefined) {
     throw new Error(
-      "Couldn't register the navigator. Have you wrapped your app with 'NavigationContainer'?"
+      "Couldn't register the navigator. Have you wrapped your app with 'NavigationContainer'?\n\nThis can also happen if there are multiple copies of '@react-navigation' packages installed."
     );
   }