@react-navigation/core 6.4.8 → 7.0.0-alpha.1

package/src/index.tsx

@@ -1,27 +1,36 @@
-export { default as BaseNavigationContainer } from './BaseNavigationContainer';
-export { default as createNavigationContainerRef } from './createNavigationContainerRef';
-export { default as createNavigatorFactory } from './createNavigatorFactory';
-export { default as CurrentRenderContext } from './CurrentRenderContext';
-export { default as findFocusedRoute } from './findFocusedRoute';
-export { default as getActionFromState } from './getActionFromState';
-export { default as getFocusedRouteNameFromRoute } from './getFocusedRouteNameFromRoute';
-export { default as getPathFromState } from './getPathFromState';
-export { default as getStateFromPath } from './getStateFromPath';
-export { default as NavigationContainerRefContext } from './NavigationContainerRefContext';
-export { default as NavigationContext } from './NavigationContext';
-export { default as NavigationHelpersContext } from './NavigationHelpersContext';
-export { default as NavigationRouteContext } from './NavigationRouteContext';
-export { default as PreventRemoveContext } from './PreventRemoveContext';
-export { default as PreventRemoveProvider } from './PreventRemoveProvider';
+export { BaseNavigationContainer } from './BaseNavigationContainer';
+export { createNavigationContainerRef } from './createNavigationContainerRef';
+export { createNavigatorFactory } from './createNavigatorFactory';
+export { CurrentRenderContext } from './CurrentRenderContext';
+export { findFocusedRoute } from './findFocusedRoute';
+export { getActionFromState } from './getActionFromState';
+export { getFocusedRouteNameFromRoute } from './getFocusedRouteNameFromRoute';
+export { getPathFromState } from './getPathFromState';
+export { getStateFromPath } from './getStateFromPath';
+export { NavigationContainerRefContext } from './NavigationContainerRefContext';
+export { NavigationContext } from './NavigationContext';
+export { NavigationHelpersContext } from './NavigationHelpersContext';
+export { NavigationIndependentTree } from './NavigationIndependentTree';
+export { NavigationRouteContext } from './NavigationRouteContext';
+export { PreventRemoveContext } from './PreventRemoveContext';
+export { PreventRemoveProvider } from './PreventRemoveProvider';
+export {
+  type StaticNavigation,
+  type StaticParamList,
+  type StaticScreenProps,
+  createComponentForStaticNavigation,
+  createPathConfigForStaticNavigation,
+} from './StaticNavigation';
 export * from './types';
-export { default as useFocusEffect } from './useFocusEffect';
-export { default as useIsFocused } from './useIsFocused';
-export { default as useNavigation } from './useNavigation';
-export { default as useNavigationBuilder } from './useNavigationBuilder';
-export { default as useNavigationContainerRef } from './useNavigationContainerRef';
-export { default as useNavigationState } from './useNavigationState';
-export { default as UNSTABLE_usePreventRemove } from './usePreventRemove';
-export { default as usePreventRemoveContext } from './usePreventRemoveContext';
-export { default as useRoute } from './useRoute';
-export { default as validatePathConfig } from './validatePathConfig';
+export { useFocusEffect } from './useFocusEffect';
+export { useIsFocused } from './useIsFocused';
+export { useNavigation } from './useNavigation';
+export { useNavigationBuilder } from './useNavigationBuilder';
+export { useNavigationContainerRef } from './useNavigationContainerRef';
+export { useNavigationIndependentTree } from './useNavigationIndependentTree';
+export { useNavigationState } from './useNavigationState';
+export { UNSTABLE_usePreventRemove } from './usePreventRemove';
+export { usePreventRemoveContext } from './usePreventRemoveContext';
+export { useRoute } from './useRoute';
+export { validatePathConfig } from './validatePathConfig';
 export * from '@react-navigation/routers';

package/src/isArrayEqual.tsx

@@ -2,7 +2,7 @@
  * Compare two arrays with primitive values as the content.
  * We need to make sure that both values and order match.
  */
-export default function isArrayEqual(a: any[], b: any[]) {
+export function isArrayEqual(a: any[], b: any[]) {
   if (a === b) {
     return true;
   }

package/src/isRecordEqual.tsx

@@ -1,10 +1,7 @@
 /**
  * Compare two records with primitive values as the content.
  */
-export default function isRecordEqual(
-  a: Record<string, any>,
-  b: Record<string, any>
-) {
+export function isRecordEqual(a: Record<string, any>, b: Record<string, any>) {
   if (a === b) {
     return true;
   }

package/src/types.tsx

@@ -171,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;
 
   /**
@@ -181,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
@@ -198,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;
 
@@ -285,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.
    */
@@ -335,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>> &
@@ -372,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`
@@ -527,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.
@@ -661,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]
@@ -691,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/useChildListeners.tsx

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

package/src/useComponent.tsx

@@ -11,7 +11,7 @@ const NavigationContent = ({ render, children }: Props) => {
   return render(children);
 };
 
-export default function useComponent(render: Render) {
+export function useComponent(render: Render) {
   const renderRef = React.useRef<Render | null>(render);
 
   // Normally refs shouldn't be mutated in render

package/src/useCurrentRender.tsx

@@ -1,7 +1,7 @@
 import type { NavigationState, ParamListBase } from '@react-navigation/routers';
 import * as React from 'react';
 
-import CurrentRenderContext from './CurrentRenderContext';
+import { CurrentRenderContext } from './CurrentRenderContext';
 import type {
   Descriptor,
   NavigationHelpers,
@@ -22,11 +22,7 @@ type Options = {
  * Write the current options, so that server renderer can get current values
  * Mutating values like this is not safe in async mode, but it doesn't apply to SSR
  */
-export default function useCurrentRender({
-  state,
-  navigation,
-  descriptors,
-}: Options) {
+export function useCurrentRender({ state, navigation, descriptors }: Options) {
   const current = React.useContext(CurrentRenderContext);
 
   if (current && navigation.isFocused()) {

package/src/useDescriptors.tsx

@@ -6,13 +6,14 @@ import type {
 } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationBuilderContext, {
+import {
   AddKeyedListener,
   AddListener,
+  NavigationBuilderContext,
 } from './NavigationBuilderContext';
-import NavigationContext from './NavigationContext';
-import NavigationRouteContext from './NavigationRouteContext';
-import SceneView from './SceneView';
+import { NavigationContext } from './NavigationContext';
+import { NavigationRouteContext } from './NavigationRouteContext';
+import { SceneView } from './SceneView';
 import type {
   Descriptor,
   EventMapBase,
@@ -22,8 +23,8 @@ import type {
   RouteProp,
 } from './types';
 import type { NavigationEventEmitter } from './useEventEmitter';
-import useNavigationCache from './useNavigationCache';
-import useRouteCache from './useRouteCache';
+import { useNavigationCache } from './useNavigationCache';
+import { useRouteCache } from './useRouteCache';
 
 export type ScreenConfigWithParent<
   State extends NavigationState,
@@ -79,7 +80,7 @@ type Options<
  * - Options specified by the screen for the navigator
  * - Navigation object intended for the route
  */
-export default function useDescriptors<
+export function useDescriptors<
   State extends NavigationState,
   ActionHelpers extends Record<string, () => void>,
   ScreenOptions extends {},
@@ -99,7 +100,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 +180,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 +209,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/useEventEmitter.tsx

@@ -12,7 +12,7 @@ type Listeners = ((e: any) => void)[];
 /**
  * Hook to manage the event system used by the navigator to notify screens of various events.
  */
-export default function useEventEmitter<T extends Record<string, any>>(
+export function useEventEmitter<T extends Record<string, any>>(
   listen?: (e: any) => void
 ): NavigationEventEmitter<T> {
   const listenRef = React.useRef(listen);

package/src/useFocusEffect.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 
-import useNavigation from './useNavigation';
+import { useNavigation } from './useNavigation';
 
 type EffectCallback = () => undefined | void | (() => void);
 
@@ -11,7 +11,7 @@ type EffectCallback = () => undefined | void | (() => void);
  *
  * @param callback Memoized callback containing the effect, should optionally return a cleanup function.
  */
-export default function useFocusEffect(effect: EffectCallback) {
+export function useFocusEffect(effect: EffectCallback) {
   const navigation = useNavigation();
 
   if (arguments[1] !== undefined) {

package/src/useFocusEvents.tsx

@@ -1,7 +1,7 @@
 import type { NavigationState } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationContext from './NavigationContext';
+import { NavigationContext } from './NavigationContext';
 import type { EventMapCore } from './types';
 import type { NavigationEventEmitter } from './useEventEmitter';
 
@@ -13,7 +13,7 @@ type Options<State extends NavigationState> = {
 /**
  * Hook to take care of emitting `focus` and `blur` events.
  */
-export default function useFocusEvents<State extends NavigationState>({
+export function useFocusEvents<State extends NavigationState>({
   state,
   emitter,
 }: Options<State>) {

package/src/useFocusedListenersChildrenAdapter.tsx

@@ -1,9 +1,10 @@
 import type { ParamListBase } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationBuilderContext, {
+import {
   FocusedNavigationCallback,
   FocusedNavigationListener,
+  NavigationBuilderContext,
 } from './NavigationBuilderContext';
 import type { NavigationHelpers } from './types';
 
@@ -15,7 +16,7 @@ type Options = {
 /**
  * Hook for passing focus callback to children
  */
-export default function useFocusedListenersChildrenAdapter({
+export function useFocusedListenersChildrenAdapter({
   navigation,
   focusedListeners,
 }: Options) {

package/src/useIsFocused.tsx

@@ -1,13 +1,13 @@
 import * as React from 'react';
 import { useState } from 'react';
 
-import useNavigation from './useNavigation';
+import { useNavigation } from './useNavigation';
 
 /**
  * Hook to get the current focus state of the screen. Returns a `true` if screen is focused, otherwise `false`.
  * This can be used if a component needs to render something based on the focus state.
  */
-export default function useIsFocused(): boolean {
+export function useIsFocused(): boolean {
   const navigation = useNavigation();
   const [isFocused, setIsFocused] = useState(navigation.isFocused);
 

package/src/useKeyedChildListeners.tsx

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

package/src/useNavigation.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 
-import NavigationContainerRefContext from './NavigationContainerRefContext';
-import NavigationContext from './NavigationContext';
+import { NavigationContainerRefContext } from './NavigationContainerRefContext';
+import { NavigationContext } from './NavigationContext';
 import type { NavigationProp } from './types';
 
 /**
@@ -9,7 +9,7 @@ import type { NavigationProp } from './types';
  *
  * @returns Navigation prop of the parent screen.
  */
-export default function useNavigation<
+export function useNavigation<
   T = NavigationProp<ReactNavigation.RootParamList>
 >(): T {
   const root = React.useContext(NavigationContainerRefContext);