@react-navigation/core 6.0.3 → 6.2.0

package/src/NavigationContainerRefContext.tsx

@@ -6,9 +6,8 @@ import type { NavigationContainerRef } from './types';
 /**
  * Context which holds the route prop for a screen.
  */
-const NavigationContainerRefContext =
-  React.createContext<NavigationContainerRef<ParamListBase> | undefined>(
-    undefined
-  );
+const NavigationContainerRefContext = React.createContext<
+  NavigationContainerRef<ParamListBase> | undefined
+>(undefined);
 
 export default NavigationContainerRefContext;

package/src/NavigationContext.tsx

@@ -6,7 +6,8 @@ import type { NavigationProp } from './types';
 /**
  * Context which holds the navigation prop for a screen.
  */
-const NavigationContext =
-  React.createContext<NavigationProp<ParamListBase> | undefined>(undefined);
+const NavigationContext = React.createContext<
+  NavigationProp<ParamListBase> | undefined
+>(undefined);
 
 export default NavigationContext;

package/src/NavigationHelpersContext.tsx

@@ -7,7 +7,8 @@ import type { NavigationHelpers } from './types';
  * Context which holds the navigation helpers of the parent navigator.
  * Navigators should use this context in their view component.
  */
-const NavigationHelpersContext =
-  React.createContext<NavigationHelpers<ParamListBase> | undefined>(undefined);
+const NavigationHelpersContext = React.createContext<
+  NavigationHelpers<ParamListBase> | undefined
+>(undefined);
 
 export default NavigationHelpersContext;

package/src/NavigationRouteContext.tsx

@@ -4,7 +4,8 @@ import * as React from 'react';
 /**
  * Context which holds the route prop for a screen.
  */
-const NavigationRouteContext =
-  React.createContext<Route<string> | undefined>(undefined);
+const NavigationRouteContext = React.createContext<Route<string> | undefined>(
+  undefined
+);
 
 export default NavigationRouteContext;

package/src/SceneView.tsx

@@ -14,7 +14,13 @@ import useOptionsGetters from './useOptionsGetters';
 
 type Props<State extends NavigationState, ScreenOptions extends {}> = {
   screen: RouteConfigComponent<ParamListBase, string> & { name: string };
-  navigation: NavigationProp<ParamListBase, string, State, ScreenOptions>;
+  navigation: NavigationProp<
+    ParamListBase,
+    string,
+    string | undefined,
+    State,
+    ScreenOptions
+  >;
   route: Route<string>;
   routeState: NavigationState | PartialState<NavigationState> | undefined;
   getState: () => State;

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

@@ -33,7 +33,9 @@ export default function createNavigationContainerRef<
     event: string,
     callback: (...args: any[]) => void
   ) => {
-    listeners[event] = listeners[event]?.filter((cb) => cb !== callback);
+    if (listeners[event]) {
+      listeners[event] = listeners[event].filter((cb) => cb !== callback);
+    }
   };
 
   let current: NavigationContainerRef<ParamList> | null = null;

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

@@ -25,6 +25,10 @@ export type DefaultNavigatorOptions<
   ScreenOptions extends {},
   EventMap extends EventMapBase
 > = DefaultRouterOptions<Keyof<ParamList>> & {
+  /**
+   * Optional ID for the navigator. Can be used with `navigation.getParent(id)` to refer to a parent.
+   */
+  id?: string;
   /**
    * Children React Elements to extract the route configuration from.
    * Only `Screen`, `Group` and `React.Fragment` are supported as children.
@@ -153,7 +157,7 @@ export type EventEmitter<EventMap extends EventMapBase> = {
   >;
 };
 
-export class PrivateValueStore<A, B, C> {
+export class PrivateValueStore<T extends [any, any, any]> {
   /**
    * UGLY HACK! DO NOT USE THE TYPE!!!
    *
@@ -164,7 +168,7 @@ export class PrivateValueStore<A, B, C> {
    * Adding private keyword works, but the annotation is stripped away in declaration.
    * Turns out if we use an empty string, it doesn't show up in intelliSense.
    */
-  protected ''?: { a: A; b: B; c: C };
+  protected ''?: T;
 }
 
 type NavigationHelpersCommon<
@@ -236,16 +240,26 @@ type NavigationHelpersCommon<
   canGoBack(): boolean;
 
   /**
-   * Returns the navigation prop from the parent navigator,
+   * Returns the name of the navigator specified in the `name` prop.
+   * If no name is specified, returns `undefined`.
+   */
+  getId(): string | undefined;
+
+  /**
+   * Returns the navigation helpers from a parent navigator based on the ID.
+   * If an ID is provided, the navigation helper from the parent navigator with matching ID (including current) will be returned.
+   * If no ID is provided, the navigation helper from the immediate parent navigator will be returned.
+   *
+   * @param id Optional ID of a parent navigator.
    */
-  getParent<T = NavigationProp<ParamListBase> | undefined>(): T;
+  getParent<T = NavigationHelpers<ParamListBase> | undefined>(id?: string): T;
 
   /**
    * Returns the navigator's state.
    * Note that this method doesn't re-render screen when the result changes. So don't use it in `render`.
    */
   getState(): State;
-} & PrivateValueStore<ParamList, keyof ParamList, {}>;
+} & PrivateValueStore<[ParamList, unknown, unknown]>;
 
 export type NavigationHelpers<
   ParamList extends ParamListBase,
@@ -291,10 +305,20 @@ export type NavigationContainerProps = {
 export type NavigationProp<
   ParamList extends {},
   RouteName extends keyof ParamList = Keyof<ParamList>,
+  NavigatorID extends string | undefined = undefined,
   State extends NavigationState = NavigationState<ParamList>,
   ScreenOptions extends {} = {},
   EventMap extends EventMapBase = {}
-> = NavigationHelpersCommon<ParamList, State> & {
+> = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
+  /**
+   * Returns the navigation prop from a parent navigator based on the ID.
+   * If an ID is provided, the navigation prop from the parent navigator with matching ID (including current) will be returned.
+   * If no ID is provided, the navigation prop from the immediate parent navigator will be returned.
+   *
+   * @param id Optional ID of a parent navigator.
+   */
+  getParent<T = NavigationProp<ParamListBase> | undefined>(id?: NavigatorID): T;
+
   /**
    * Update the param object for the route.
    * The new params will be shallow merged with the old one.
@@ -311,7 +335,7 @@ export type NavigationProp<
    */
   setOptions(options: Partial<ScreenOptions>): void;
 } & EventConsumer<EventMap & EventMapCore<State>> &
-  PrivateValueStore<ParamList, RouteName, EventMap>;
+  PrivateValueStore<[ParamList, RouteName, EventMap]>;
 
 export type RouteProp<
   ParamList extends ParamListBase,
@@ -319,7 +343,7 @@ export type RouteProp<
 > = Route<Extract<RouteName, string>, ParamList[RouteName]>;
 
 export type CompositeNavigationProp<
-  A extends NavigationProp<ParamListBase, string, any, any>,
+  A extends NavigationProp<ParamListBase, string, any, any, any>,
   B extends NavigationHelpersCommon<ParamListBase, any>
 > = Omit<A & B, keyof NavigationProp<any>> &
   NavigationProp<
@@ -334,30 +358,42 @@ export type CompositeNavigationProp<
      * Ideally it should work for any of them, but it's not possible to infer that way
      */
     A extends NavigationProp<any, infer R> ? R : string,
+    /**
+     * ID from both navigation objects needs to be combined for `getParent`
+     */
+    | (A extends NavigationProp<any, any, infer I> ? I : never)
+    | (B extends NavigationProp<any, any, infer J> ? J : never),
     /**
      * The type of state should refer to the state specified in the first type
      */
-    A extends NavigationProp<any, any, infer S> ? S : NavigationState,
+    A extends NavigationProp<any, any, any, infer S> ? S : NavigationState,
     /**
      * Screen options from both navigation objects needs to be combined
      * This allows typechecking `setOptions`
      */
-    (A extends NavigationProp<any, any, any, infer O> ? O : {}) &
-      (B extends NavigationProp<any, any, any, infer P> ? P : {}),
+    (A extends NavigationProp<any, any, any, any, infer O> ? O : {}) &
+      (B extends NavigationProp<any, any, any, any, infer P> ? P : {}),
     /**
      * Event consumer config should refer to the config specified in the first type
      * This allows typechecking `addListener`/`removeListener`
      */
-    A extends NavigationProp<any, any, any, any, infer E> ? E : {}
+    A extends NavigationProp<any, any, any, any, any, infer E> ? E : {}
   >;
 
 export type CompositeScreenProps<
   A extends {
-    navigation: NavigationProp<ParamListBase, string, any, any>;
+    navigation: NavigationProp<
+      ParamListBase,
+      string,
+      string | undefined,
+      any,
+      any,
+      any
+    >;
     route: RouteProp<ParamListBase>;
   },
   B extends {
-    navigation: NavigationHelpersCommon<ParamListBase, any>;
+    navigation: NavigationHelpersCommon<any, any>;
   }
 > = {
   navigation: CompositeNavigationProp<A['navigation'], B['navigation']>;
@@ -366,7 +402,7 @@ export type CompositeScreenProps<
 
 export type Descriptor<
   ScreenOptions extends {},
-  Navigation extends NavigationProp<any, any, any, any, any>,
+  Navigation extends NavigationProp<any, any, any, any, any, any>,
   Route extends RouteProp<any, any>
 > = {
   /**
@@ -393,12 +429,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 +475,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 +525,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
@@ -142,22 +143,29 @@ export default function useDescriptors<
       string,
       Descriptor<
         ScreenOptions,
-        NavigationProp<ParamListBase, string, State, ScreenOptions, EventMap> &
+        NavigationProp<
+          ParamListBase,
+          string,
+          string | undefined,
+          State,
+          ScreenOptions,
+          EventMap
+        > &
           ActionHelpers,
         RouteProp<ParamListBase>
       >
     >
   >((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) => {
@@ -583,6 +645,7 @@ export default function useNavigationBuilder<
     NavigationAction,
     EventMap
   >({
+    id: options.id,
     onAction,
     getState,
     emitter,