@react-navigation/core 6.4.5 → 7.0.0-alpha.0

package/src/types.tsx

@@ -52,17 +52,6 @@ export type DefaultNavigatorOptions<
         route: RouteProp<ParamList>;
         navigation: any;
       }) => ScreenOptions);
-  /**
-   * Default options specified by the navigator.
-   * It receives the custom options in the arguments if a function is specified.
-   */
-  defaultScreenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList>;
-        navigation: any;
-        options: ScreenOptions;
-      }) => ScreenOptions);
 };
 
 export type EventMapBase = Record<
@@ -182,7 +171,7 @@ type NavigationHelpersCommon<
    * @param action Action object or update function.
    */
   dispatch(
-    action: NavigationAction | ((state: State) => NavigationAction)
+    action: NavigationAction | ((state: Readonly<State>) => NavigationAction)
   ): void;
 
   /**
@@ -192,7 +181,7 @@ type NavigationHelpersCommon<
    * @param [params] Params object for the route.
    */
   navigate<RouteName extends keyof ParamList>(
-    ...args: // this first condition allows us to iterate over a union type
+    ...args: // This condition allows us to iterate over a union type
     // This is to avoid getting a union of all the params from `ParamList[RouteName]`,
     // which will get our types all mixed up if a union RouteName is passed in.
     RouteName extends unknown
@@ -209,18 +198,56 @@ type NavigationHelpersCommon<
   /**
    * Navigate to a route in current navigation tree.
    *
-   * @param route Object with `key` or `name` for the route to navigate to, and a `params` object.
+   * @param route Object with `name` for the route to navigate to, and a `params` object.
    */
   navigate<RouteName extends keyof ParamList>(
     options: RouteName extends unknown
-      ?
-          | { key: string; params?: ParamList[RouteName]; merge?: boolean }
-          | {
-              name: RouteName;
-              key?: string;
-              params: ParamList[RouteName];
-              merge?: boolean;
-            }
+      ? {
+          name: RouteName;
+          params: ParamList[RouteName];
+          path?: string;
+          merge?: boolean;
+        }
+      : never
+  ): void;
+
+  /**
+   * Navigate to a route in current navigation tree.
+   *
+   * @deprecated Use `navigate` instead.
+   *
+   * @param name Route name of the route.
+   * @param [params] Params object for the route.
+   */
+  navigateDeprecated<RouteName extends keyof ParamList>(
+    ...args: // This condition allows us to iterate over a union type
+    // This is to avoid getting a union of all the params from `ParamList[RouteName]`,
+    // which will get our types all mixed up if a union RouteName is passed in.
+    RouteName extends unknown
+      ? // This condition checks if the params are optional,
+        // which means it's either undefined or a union with undefined
+        undefined extends ParamList[RouteName]
+        ?
+            | [screen: RouteName] // if the params are optional, we don't have to provide it
+            | [screen: RouteName, params: ParamList[RouteName]]
+        : [screen: RouteName, params: ParamList[RouteName]]
+      : never
+  ): void;
+
+  /**
+   * Navigate to a route in current navigation tree.
+   *
+   * @deprecated Use `navigate` instead.
+   *
+   * @param route Object with `name` for the route to navigate to, and a `params` object.
+   */
+  navigateDeprecated<RouteName extends keyof ParamList>(
+    options: RouteName extends unknown
+      ? {
+          name: RouteName;
+          params: ParamList[RouteName];
+          merge?: boolean;
+        }
       : never
   ): void;
 
@@ -296,17 +323,25 @@ export type NavigationContainerProps = {
   /**
    * Callback which is called with the latest navigation state when it changes.
    */
-  onStateChange?: (state: NavigationState | undefined) => void;
+  onStateChange?: (state: Readonly<NavigationState> | undefined) => void;
+  /**
+   * Callback which is called after the navigation tree mounts.
+   */
+  onReady?: () => void;
   /**
    * Callback which is called when an action is not handled.
    */
-  onUnhandledAction?: (action: NavigationAction) => void;
+  onUnhandledAction?: (action: Readonly<NavigationAction>) => void;
   /**
-   * Whether this navigation container should be independent of parent containers.
-   * If this is not set to `true`, this container cannot be nested inside another container.
-   * Setting it to `true` disconnects any children navigators from parent container.
+   * Whether child navigator should handle a navigation action.
+   * The child navigator needs to be mounted before it can handle the action.
+   * Defaults to `false`.
+   *
+   * This will be removed in the next major release.
+   *
+   * @deprecated Use nested navigation API instead
    */
-  independent?: boolean;
+  navigationInChildEnabled?: boolean;
   /**
    * Children elements to render.
    */
@@ -346,7 +381,7 @@ export type NavigationProp<
    * Update the options for the route.
    * The options object will be shallow merged with default options object.
    *
-   * @param options Options object for the route.
+   * @param update Options object or a callback which takes the options from navigator config and returns a new options object.
    */
   setOptions(options: Partial<ScreenOptions>): void;
 } & EventConsumer<EventMap & EventMapCore<State>> &
@@ -383,11 +418,9 @@ export type CompositeNavigationProp<
      */
     A extends NavigationProp<any, any, any, infer S> ? S : NavigationState,
     /**
-     * Screen options from both navigation objects needs to be combined
-     * This allows typechecking `setOptions`
+     * Screen options should refer to the options specified in the first type
      */
-    (A extends NavigationProp<any, any, any, any, infer O> ? O : {}) &
-      (B extends NavigationProp<any, any, any, any, infer P> ? P : {}),
+    A extends NavigationProp<any, any, any, any, infer O> ? O : {},
     /**
      * Event consumer config should refer to the config specified in the first type
      * This allows typechecking `addListener`/`removeListener`
@@ -538,7 +571,11 @@ export type RouteConfig<
    * For a given screen name, there will always be only one screen corresponding to an ID.
    * If `undefined` is returned, it acts same as no `getId` being specified.
    */
-  getId?: ({ params }: { params: ParamList[RouteName] }) => string | undefined;
+  getId?: ({
+    params,
+  }: {
+    params: Readonly<ParamList[RouteName]>;
+  }) => string | undefined;
 
   /**
    * Initial params object for the route.
@@ -672,16 +709,13 @@ export type TypedNavigator<
   ) => null;
 };
 
-export type NavigatorScreenParams<
-  ParamList,
-  State extends NavigationState = NavigationState
-> =
+export type NavigatorScreenParams<ParamList extends {}> =
   | {
       screen?: never;
       params?: never;
       initial?: never;
       path?: string;
-      state: PartialState<State> | State | undefined;
+      state: PartialState<NavigationState> | NavigationState | undefined;
     }
   | {
       [RouteName in keyof ParamList]: undefined extends ParamList[RouteName]
@@ -702,18 +736,55 @@ export type NavigatorScreenParams<
     }[keyof ParamList];
 
 export type PathConfig<ParamList extends {}> = {
+  /**
+   * Path string to match against.
+   * e.g. `/users/:id` will match `/users/1` and extract `id` param as `1`.
+   */
   path?: string;
+  /**
+   * Whether the path should be consider parent paths or use the exact path.
+   * By default, paths are relating to the path config on the parent screen.
+   * If `exact` is set to `true`, the parent path configuration is not used.
+   */
   exact?: boolean;
+  /**
+   * An object mapping the param name to a function which parses the param value.
+   *
+   * @example
+   * ```js
+   * parse: {
+   *   id: Number,
+   *   date: (value) => new Date(value)
+   * }
+   * ```
+   */
   parse?: Record<string, (value: string) => any>;
+  /**
+   * An object mapping the param name to a function which converts the param value to a string.
+   * By default, all params are converted to strings using `String(value)`.
+   *
+   * @example
+   * ```js
+   * stringify: {
+   *   date: (value) => value.toISOString()
+   * }
+   * ```
+   */
   stringify?: Record<string, (value: any) => string>;
+  /**
+   * Path configuration for child screens.
+   */
   screens?: PathConfigMap<ParamList>;
+  /**
+   * Name of the initial route to use for the navigator when the path matches.
+   */
   initialRouteName?: keyof ParamList;
 };
 
 export type PathConfigMap<ParamList extends {}> = {
   [RouteName in keyof ParamList]?: NonNullable<
     ParamList[RouteName]
-  > extends NavigatorScreenParams<infer T, any>
+  > extends NavigatorScreenParams<infer T>
     ? string | PathConfig<T>
     : string | Omit<PathConfig<{}>, 'screens' | 'initialRouteName'>;
 };

package/src/useDescriptors.tsx

@@ -99,7 +99,9 @@ export default function useDescriptors<
   router,
   emitter,
 }: Options<State, ScreenOptions, EventMap>) {
-  const [options, setOptions] = React.useState<Record<string, object>>({});
+  const [options, setOptions] = React.useState<Record<string, ScreenOptions>>(
+    {}
+  );
   const { onDispatchAction, onOptionsChange, stackRef } = React.useContext(
     NavigationBuilderContext
   );
@@ -177,6 +179,7 @@ export default function useDescriptors<
       (acc, curr) =>
         Object.assign(
           acc,
+          // @ts-expect-error: we check for function but TS still complains
           typeof curr !== 'function' ? curr : curr({ route, navigation })
         ),
       {} as ScreenOptions
@@ -205,29 +208,31 @@ export default function useDescriptors<
         return o;
       });
 
+    const element = (
+      <NavigationBuilderContext.Provider key={route.key} value={context}>
+        <NavigationContext.Provider value={navigation}>
+          <NavigationRouteContext.Provider value={route}>
+            <SceneView
+              navigation={navigation}
+              route={route}
+              screen={screen}
+              routeState={state.routes[i].state}
+              getState={getState}
+              setState={setState}
+              options={mergedOptions}
+              clearOptions={clearOptions}
+            />
+          </NavigationRouteContext.Provider>
+        </NavigationContext.Provider>
+      </NavigationBuilderContext.Provider>
+    );
+
     acc[route.key] = {
       route,
       // @ts-expect-error: it's missing action helpers, fix later
       navigation,
       render() {
-        return (
-          <NavigationBuilderContext.Provider key={route.key} value={context}>
-            <NavigationContext.Provider value={navigation}>
-              <NavigationRouteContext.Provider value={route}>
-                <SceneView
-                  navigation={navigation}
-                  route={route}
-                  screen={screen}
-                  routeState={state.routes[i].state}
-                  getState={getState}
-                  setState={setState}
-                  options={mergedOptions}
-                  clearOptions={clearOptions}
-                />
-              </NavigationRouteContext.Provider>
-            </NavigationContext.Provider>
-          </NavigationBuilderContext.Provider>
-        );
+        return element;
       },
       options: mergedOptions as ScreenOptions,
     };

package/src/useNavigationBuilder.tsx

@@ -28,6 +28,7 @@ import {
   NavigatorScreenParams,
   PrivateValueStore,
   RouteConfig,
+  RouteProp,
 } from './types';
 import useChildListeners from './useChildListeners';
 import useComponent from './useComponent';
@@ -48,9 +49,23 @@ import useScheduleUpdate from './useScheduleUpdate';
 // eslint-disable-next-line babel/no-unused-expressions
 PrivateValueStore;
 
-type NavigatorRoute<State extends NavigationState> = {
+type NavigationBuilderOptions<ScreenOptions extends {}> = {
+  /**
+   * Default options specified by the navigator.
+   * It receives the custom options in the arguments if a function is specified.
+   */
+  defaultScreenOptions?:
+    | ScreenOptions
+    | ((props: {
+        route: RouteProp<ParamListBase>;
+        navigation: any;
+        options: ScreenOptions;
+      }) => ScreenOptions);
+};
+
+type NavigatorRoute = {
   key: string;
-  params?: NavigatorScreenParams<ParamListBase, State>;
+  params?: NavigatorScreenParams<ParamListBase>;
 };
 
 const isValidKey = (key: unknown) =>
@@ -138,7 +153,12 @@ const getRouteConfigsFromChildren = <
           ? `'${
               typeof child.type === 'string' ? child.type : child.type?.name
             }'${
-              child.props?.name ? ` for the screen '${child.props.name}'` : ''
+              child.props != null &&
+              typeof child.props === 'object' &&
+              'name' in child.props &&
+              child.props?.name
+                ? ` for the screen '${child.props.name}'`
+                : ''
             }`
           : typeof child === 'object'
           ? JSON.stringify(child)
@@ -246,12 +266,13 @@ export default function useNavigationBuilder<
     ScreenOptions,
     EventMap
   > &
+    NavigationBuilderOptions<ScreenOptions> &
     RouterOptions
 ) {
   const navigatorKey = useRegisterNavigator();
 
   const route = React.useContext(NavigationRouteContext) as
-    | NavigatorRoute<State>
+    | NavigatorRoute
     | undefined;
 
   const { children, screenListeners, ...rest } = options;
@@ -401,7 +422,7 @@ export default function useNavigationBuilder<
     } else {
       return [
         router.getRehydratedState(
-          route?.params?.state ?? (currentState as PartialState<State>),
+          (route?.params?.state ?? currentState) as PartialState<State>,
           {
             routeNames,
             routeParamList: initialRouteParamList,

package/src/useNavigationCache.tsx

@@ -13,6 +13,7 @@ import type { NavigationEventEmitter } from './useEventEmitter';
 
 type Options<
   State extends NavigationState,
+  ScreenOptions extends {},
   EventMap extends Record<string, any>
 > = {
   state: State;
@@ -20,7 +21,9 @@ type Options<
   navigation: NavigationHelpers<ParamListBase> &
     Partial<NavigationProp<ParamListBase, string, any, any, any>>;
   setOptions: (
-    cb: (options: Record<string, object>) => Record<string, object>
+    cb: (
+      options: Record<string, ScreenOptions>
+    ) => Record<string, ScreenOptions>
   ) => void;
   router: Router<State, NavigationAction>;
   emitter: NavigationEventEmitter<EventMap>;
@@ -58,7 +61,7 @@ export default function useNavigationCache<
   setOptions,
   router,
   emitter,
-}: Options<State, EventMap>) {
+}: Options<State, ScreenOptions, EventMap>) {
   const { stackRef } = React.useContext(NavigationBuilderContext);
 
   // Cache object which holds navigation objects for each screen
@@ -149,11 +152,12 @@ export default function useNavigationCache<
 
           return rest.getParent(id);
         },
-        setOptions: (options: object) =>
+        setOptions: (options: object) => {
           setOptions((o) => ({
             ...o,
             [route.key]: { ...o[route.key], ...options },
-          })),
+          }));
+        },
         isFocused: () => {
           const state = getState();
 

package/src/useNavigationIndependentTree.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+import NavigationIndependentTreeContext from './NavigationIndependentTreeContext';
+
+export default function useNavigationIndependentTree() {
+  return React.useContext(NavigationIndependentTreeContext);
+}

package/src/useOnAction.tsx

@@ -7,6 +7,7 @@ import type {
 } from '@react-navigation/routers';
 import * as React from 'react';
 
+import DeprecatedNavigationInChildContext from './DeprecatedNavigationInChildContext';
 import NavigationBuilderContext, {
   ChildActionListener,
   ChildBeforeRemoveListener,
@@ -51,6 +52,9 @@ export default function useOnAction({
     addListener: addListenerParent,
     onDispatchAction,
   } = React.useContext(NavigationBuilderContext);
+  const navigationInChildEnabled = React.useContext(
+    DeprecatedNavigationInChildContext
+  );
 
   const routerConfigOptionsRef =
     React.useRef<RouterConfigOptions>(routerConfigOptions);
@@ -126,12 +130,15 @@ export default function useOnAction({
         }
       }
 
-      // If the action wasn't handled by current navigator or a parent navigator, let children handle it
-      for (let i = actionListeners.length - 1; i >= 0; i--) {
-        const listener = actionListeners[i];
+      if (typeof action.target === 'string' || navigationInChildEnabled) {
+        // If the action wasn't handled by current navigator or a parent navigator, let children handle it
+        // Handling this when target isn't specified is deprecated and will be removed in the future
+        for (let i = actionListeners.length - 1; i >= 0; i--) {
+          const listener = actionListeners[i];
 
-        if (listener(action, visitedNavigators)) {
-          return true;
+          if (listener(action, visitedNavigators)) {
+            return true;
+          }
         }
       }
 
@@ -142,6 +149,7 @@ export default function useOnAction({
       beforeRemoveListeners,
       emitter,
       getState,
+      navigationInChildEnabled,
       key,
       onActionParent,
       onDispatchAction,