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

package/src/types.tsx

@@ -14,6 +14,9 @@ declare global {
   namespace ReactNavigation {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
     interface RootParamList {}
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface Theme {}
   }
 }
 
@@ -23,17 +26,44 @@ export type DefaultNavigatorOptions<
   ParamList extends ParamListBase,
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  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.
    */
   children: React.ReactNode;
+
+  /**
+   * Layout for the navigator.
+   * Useful for wrapping with a component with access to navigator's state and options.
+   */
+  layout?: (props: {
+    state: State;
+    navigation: NavigationHelpers<ParamList>;
+    descriptors: Record<
+      string,
+      Descriptor<
+        ScreenOptions,
+        NavigationProp<
+          ParamList,
+          keyof ParamList,
+          string | undefined,
+          State,
+          ScreenOptions,
+          EventMap
+        >,
+        RouteProp<ParamList>
+      >
+    >;
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
   /**
    * Event listeners for all the screens in the navigator.
    */
@@ -43,6 +73,7 @@ export type DefaultNavigatorOptions<
         route: RouteProp<ParamList>;
         navigation: any;
       }) => ScreenListeners<State, EventMap>);
+
   /**
    * Default options for all screens under this navigator.
    */
@@ -51,7 +82,25 @@ export type DefaultNavigatorOptions<
     | ((props: {
         route: RouteProp<ParamList>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
+
+  /**
+   * Layout for all screens under this navigator.
+   */
+  screenLayout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
+  /**
+   A function returning a state, which may be set after modifying the routes name.
+   */
+  getStateForRouteNamesChange?: (
+    state: NavigationState
+  ) => PartialState<NavigationState> | undefined;
 };
 
 export type EventMapBase = Record<
@@ -69,7 +118,7 @@ export type EventMapCore<State extends NavigationState> = {
 export type EventArg<
   EventName extends string,
   CanPreventDefault extends boolean | undefined = false,
-  Data = undefined
+  Data = undefined,
 > = {
   /**
    * Type of the event (e.g. `focus`, `blur`)
@@ -94,7 +143,7 @@ export type EventArg<
 
 export type EventListenerCallback<
   EventMap extends EventMapBase,
-  EventName extends keyof EventMap
+  EventName extends keyof EventMap,
 > = (
   e: EventArg<
     Extract<EventName, string>,
@@ -162,7 +211,7 @@ export class PrivateValueStore<T extends [any, any, any]> {
 
 type NavigationHelpersCommon<
   ParamList extends ParamListBase,
-  State extends NavigationState = NavigationState
+  State extends NavigationState = NavigationState,
 > = {
   /**
    * Dispatch an action or an update function to the router.
@@ -251,6 +300,22 @@ type NavigationHelpersCommon<
       : never
   ): void;
 
+  /**
+   * Preloads the route in current navigation tree.
+   *
+   * @param name Name of the route to navigate to.
+   * @param [params] Params object for the route.
+   */
+  preload<RouteName extends keyof ParamList>(
+    ...args: RouteName extends unknown
+      ? undefined extends ParamList[RouteName]
+        ?
+            | [screen: RouteName]
+            | [screen: RouteName, params: ParamList[RouteName]]
+        : [screen: RouteName, params: ParamList[RouteName]]
+      : never
+  ): void;
+
   /**
    * Reset the navigation state to the provided state.
    *
@@ -297,11 +362,18 @@ type NavigationHelpersCommon<
    * Note that this method doesn't re-render screen when the result changes. So don't use it in `render`.
    */
   getState(): State;
+  /**
+   * Schedules the given state to be used as navigation state when the list of screens defined in the navigator changes
+   * instead of automatically calculating the new state, e.g. due to conditional rendering or dynamically defining screens.
+   *
+   * @param state Navigation state object.
+   */
+  setStateForNextRouteNamesChange(state: PartialState<State> | State): void;
 } & PrivateValueStore<[ParamList, unknown, unknown]>;
 
 export type NavigationHelpers<
   ParamList extends ParamListBase,
-  EventMap extends EventMapBase = {}
+  EventMap extends EventMapBase = {},
 > = NavigationHelpersCommon<ParamList> &
   EventEmitter<EventMap> & {
     /**
@@ -342,6 +414,10 @@ export type NavigationContainerProps = {
    * @deprecated Use nested navigation API instead
    */
   navigationInChildEnabled?: boolean;
+  /**
+   * Theme object for the UI elements.
+   */
+  theme?: ReactNavigation.Theme;
   /**
    * Children elements to render.
    */
@@ -354,7 +430,7 @@ export type NavigationProp<
   NavigatorID extends string | undefined = undefined,
   State extends NavigationState = NavigationState<ParamList>,
   ScreenOptions extends {} = {},
-  EventMap extends EventMapBase = {}
+  EventMap extends EventMapBase = {},
 > = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
   /**
    * Returns the navigation prop from a parent navigator based on the ID.
@@ -389,12 +465,12 @@ export type NavigationProp<
 
 export type RouteProp<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList = Keyof<ParamList>
+  RouteName extends keyof ParamList = Keyof<ParamList>,
 > = Route<Extract<RouteName, string>, ParamList[RouteName]>;
 
 export type CompositeNavigationProp<
   A extends NavigationProp<ParamListBase, string, any, any, any>,
-  B extends NavigationHelpersCommon<ParamListBase, any>
+  B extends NavigationHelpersCommon<ParamListBase, any>,
 > = Omit<A & B, keyof NavigationProp<any>> &
   NavigationProp<
     /**
@@ -442,7 +518,7 @@ export type CompositeScreenProps<
   },
   B extends {
     navigation: NavigationHelpersCommon<any, any>;
-  }
+  },
 > = {
   navigation: CompositeNavigationProp<A['navigation'], B['navigation']>;
   route: A['route'];
@@ -451,7 +527,7 @@ export type CompositeScreenProps<
 export type Descriptor<
   ScreenOptions extends {},
   Navigation extends NavigationProp<any, any, any, any, any, any>,
-  Route extends RouteProp<any, any>
+  Route extends RouteProp<any, any>,
 > = {
   /**
    * Render the component associated with this route.
@@ -476,7 +552,7 @@ export type Descriptor<
 
 export type ScreenListeners<
   State extends NavigationState,
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = Partial<{
   [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
     EventMap,
@@ -486,7 +562,7 @@ export type ScreenListeners<
 
 type ScreenComponentType<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList
+  RouteName extends keyof ParamList,
 > =
   | React.ComponentType<{
       route: RouteProp<ParamList, RouteName>;
@@ -496,7 +572,7 @@ type ScreenComponentType<
 
 export type RouteConfigComponent<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList
+  RouteName extends keyof ParamList,
 > =
   | {
       /**
@@ -531,7 +607,7 @@ export type RouteConfig<
   RouteName extends keyof ParamList,
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = {
   /**
    * Optional key for this screen. This doesn't need to be unique.
@@ -553,6 +629,7 @@ export type RouteConfig<
     | ((props: {
         route: RouteProp<ParamList, RouteName>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
   /**
@@ -565,6 +642,18 @@ export type RouteConfig<
         navigation: any;
       }) => ScreenListeners<State, EventMap>);
 
+  /**
+   * Layout for this screen.
+   * Useful for wrapping the screen with custom containers.
+   * e.g. for styling, error boundaries, suspense, etc.
+   */
+  layout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
   /**
    * Function to return an unique ID for this screen.
    * Receives an object with the route params.
@@ -585,7 +674,7 @@ export type RouteConfig<
 
 export type RouteGroupConfig<
   ParamList extends ParamListBase,
-  ScreenOptions extends {}
+  ScreenOptions extends {},
 > = {
   /**
    * Optional key for the screens in this group.
@@ -601,7 +690,20 @@ export type RouteGroupConfig<
     | ((props: {
         route: RouteProp<ParamList, keyof ParamList>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
+
+  /**
+   * Layout for the screens inside the group.
+   * This will override the `screenLayout` of parent group or navigator.
+   */
+  screenLayout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
   /**
    * Children React Elements to extract the route configuration from.
    * Only `Screen`, `Group` and `React.Fragment` are supported as children.
@@ -673,6 +775,14 @@ export type NavigationContainerRef<ParamList extends {}> =
        * Whether the navigation container is ready to handle actions.
        */
       isReady(): boolean;
+      /**
+       * Stub function for setOptions on navigation object for use with useNavigation.
+       */
+      setOptions(): never;
+      /**
+       * Stub function for getParent on navigation object for use with useNavigation.
+       */
+      getParent(): undefined;
     };
 
 export type NavigationContainerRefWithCurrent<ParamList extends {}> =
@@ -685,7 +795,7 @@ export type TypedNavigator<
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
-  Navigator extends React.ComponentType<any>
+  Navigator extends React.ComponentType<any>,
 > = {
   /**
    * Navigator component which manages the child screens.
@@ -779,12 +889,18 @@ export type PathConfig<ParamList extends {}> = {
    * Name of the initial route to use for the navigator when the path matches.
    */
   initialRouteName?: keyof ParamList;
+  /**
+   * A function returning a state, which may be set after modifying the routes name.
+   */
+  getStateForRouteNamesChange?: (
+    state: NavigationState
+  ) => PartialState<NavigationState> | undefined;
 };
 
 export type PathConfigMap<ParamList extends {}> = {
   [RouteName in keyof ParamList]?: NonNullable<
     ParamList[RouteName]
-  > extends NavigatorScreenParams<infer T>
+  > extends NavigatorScreenParams<infer T extends {}>
     ? string | PathConfig<T>
     : string | Omit<PathConfig<{}>, 'screens' | 'initialRouteName'>;
 };

package/src/useDescriptors.tsx

@@ -2,18 +2,20 @@ import type {
   NavigationAction,
   NavigationState,
   ParamListBase,
+  PartialState,
   Router,
 } from '@react-navigation/routers';
 import * as React from 'react';
 
 import {
-  AddKeyedListener,
-  AddListener,
+  type AddKeyedListener,
+  type AddListener,
   NavigationBuilderContext,
 } from './NavigationBuilderContext';
 import { NavigationContext } from './NavigationContext';
 import { NavigationRouteContext } from './NavigationRouteContext';
 import { SceneView } from './SceneView';
+import { ThemeContext } from './theming/ThemeContext';
 import type {
   Descriptor,
   EventMapBase,
@@ -29,24 +31,33 @@ import { useRouteCache } from './useRouteCache';
 export type ScreenConfigWithParent<
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = {
   keys: (string | undefined)[];
   options: (ScreenOptionsOrCallback<ScreenOptions> | undefined)[] | undefined;
+  layout: ScreenLayout | undefined;
   props: RouteConfig<ParamListBase, string, State, ScreenOptions, EventMap>;
 };
 
+type ScreenLayout = (props: {
+  route: RouteProp<ParamListBase, string>;
+  navigation: any;
+  theme: ReactNavigation.Theme;
+  children: React.ReactElement;
+}) => React.ReactElement;
+
 type ScreenOptionsOrCallback<ScreenOptions extends {}> =
   | ScreenOptions
   | ((props: {
       route: RouteProp<ParamListBase, string>;
       navigation: any;
+      theme: ReactNavigation.Theme;
     }) => ScreenOptions);
 
 type Options<
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = {
   state: State;
   screens: Record<
@@ -54,14 +65,8 @@ type Options<
     ScreenConfigWithParent<State, ScreenOptions, EventMap>
   >;
   navigation: NavigationHelpers<ParamListBase>;
-  screenOptions?: ScreenOptionsOrCallback<ScreenOptions>;
-  defaultScreenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamListBase>;
-        navigation: any;
-        options: ScreenOptions;
-      }) => ScreenOptions);
+  screenOptions: ScreenOptionsOrCallback<ScreenOptions> | undefined;
+  screenLayout: ScreenLayout | undefined;
   onAction: (action: NavigationAction) => boolean;
   getState: () => State;
   setState: (state: State) => void;
@@ -84,13 +89,13 @@ export function useDescriptors<
   State extends NavigationState,
   ActionHelpers extends Record<string, () => void>,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 >({
   state,
   screens,
   navigation,
   screenOptions,
-  defaultScreenOptions,
+  screenLayout,
   onAction,
   getState,
   setState,
@@ -100,6 +105,7 @@ export function useDescriptors<
   router,
   emitter,
 }: Options<State, ScreenOptions, EventMap>) {
+  const theme = React.useContext(ThemeContext);
   const [options, setOptions] = React.useState<Record<string, ScreenOptions>>(
     {}
   );
@@ -130,7 +136,12 @@ export function useDescriptors<
     ]
   );
 
-  const navigations = useNavigationCache<State, ScreenOptions, EventMap>({
+  const { base, navigations } = useNavigationCache<
+    State,
+    ScreenOptions,
+    EventMap,
+    ActionHelpers
+  >({
     state,
     getState,
     navigation,
@@ -141,27 +152,20 @@ export function useDescriptors<
 
   const routes = useRouteCache(state.routes);
 
-  return routes.reduce<
-    Record<
+  const getOptions = (
+    route: RouteProp<ParamListBase, string>,
+    navigation: NavigationProp<
+      ParamListBase,
       string,
-      Descriptor<
-        ScreenOptions,
-        NavigationProp<
-          ParamListBase,
-          string,
-          string | undefined,
-          State,
-          ScreenOptions,
-          EventMap
-        > &
-          ActionHelpers,
-        RouteProp<ParamListBase>
-      >
-    >
-  >((acc, route, i) => {
+      string | undefined,
+      State,
+      ScreenOptions,
+      EventMap
+    >,
+    overrides: Record<string, ScreenOptions>
+  ) => {
     const config = screens[route.name];
     const screen = config.props;
-    const navigation = navigations[route.key];
 
     const optionsList = [
       // The default `screenOptions` passed to the navigator
@@ -173,30 +177,35 @@ export function useDescriptors<
       // The `options` prop passed to `Screen` elements,
       screen.options,
       // The options set via `navigation.setOptions`
-      options[route.key],
+      overrides,
     ];
 
-    const customOptions = optionsList.reduce<ScreenOptions>(
+    return optionsList.reduce<ScreenOptions>(
       (acc, curr) =>
         Object.assign(
           acc,
           // @ts-expect-error: we check for function but TS still complains
-          typeof curr !== 'function' ? curr : curr({ route, navigation })
+          typeof curr !== 'function' ? curr : curr({ route, navigation, theme })
         ),
       {} as ScreenOptions
     );
+  };
 
-    const mergedOptions = {
-      ...(typeof defaultScreenOptions === 'function'
-        ? // @ts-expect-error: ts gives incorrect error here
-          defaultScreenOptions({
-            route,
-            navigation,
-            options: customOptions,
-          })
-        : defaultScreenOptions),
-      ...customOptions,
-    };
+  const render = (
+    route: RouteProp<ParamListBase, string>,
+    navigation: NavigationProp<
+      ParamListBase,
+      string,
+      string | undefined,
+      State,
+      ScreenOptions,
+      EventMap
+    >,
+    customOptions: ScreenOptions,
+    routeState: NavigationState | PartialState<NavigationState> | undefined
+  ) => {
+    const config = screens[route.name];
+    const screen = config.props;
 
     const clearOptions = () =>
       setOptions((o) => {
@@ -209,24 +218,74 @@ export function useDescriptors<
         return o;
       });
 
-    const element = (
+    const layout =
+      // The `layout` prop passed to `Screen` elements,
+      screen.layout ??
+      // The `screenLayout` props passed to `Group` elements
+      config.layout ??
+      // The default `screenLayout` passed to the navigator
+      screenLayout;
+
+    let element = (
+      <SceneView
+        navigation={navigation}
+        route={route}
+        screen={screen}
+        routeState={routeState}
+        getState={getState}
+        setState={setState}
+        options={customOptions}
+        clearOptions={clearOptions}
+      />
+    );
+
+    if (layout != null) {
+      element = layout({
+        route,
+        navigation,
+        // @ts-expect-error: in practice `theme` will be defined
+        theme,
+        children: element,
+      });
+    }
+
+    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}
-            />
+            {element}
           </NavigationRouteContext.Provider>
         </NavigationContext.Provider>
       </NavigationBuilderContext.Provider>
     );
+  };
+
+  const descriptors = routes.reduce<
+    Record<
+      string,
+      Descriptor<
+        ScreenOptions,
+        NavigationProp<
+          ParamListBase,
+          string,
+          string | undefined,
+          State,
+          ScreenOptions,
+          EventMap
+        > &
+          ActionHelpers,
+        RouteProp<ParamListBase>
+      >
+    >
+  >((acc, route, i) => {
+    const navigation = navigations[route.key];
+    const customOptions = getOptions(route, navigation, options[route.key]);
+    const element = render(
+      route,
+      navigation,
+      customOptions,
+      state.routes[i].state
+    );
 
     acc[route.key] = {
       route,
@@ -235,9 +294,44 @@ export function useDescriptors<
       render() {
         return element;
       },
-      options: mergedOptions as ScreenOptions,
+      options: customOptions as ScreenOptions,
     };
 
     return acc;
   }, {});
+
+  /**
+   * Create a descriptor object for a route.
+   *
+   * @param route Route object for which the descriptor should be created
+   * @param placeholder Whether the descriptor should be a placeholder, e.g. for a route not yet in the state
+   * @returns Descriptor object
+   */
+  const describe = (route: RouteProp<ParamListBase>, placeholder: boolean) => {
+    if (!placeholder) {
+      if (!(route.key in descriptors)) {
+        throw new Error(`Couldn't find a route with the key ${route.key}.`);
+      }
+
+      return descriptors[route.key];
+    }
+
+    const navigation = base;
+    const customOptions = getOptions(route, navigation, {});
+    const element = render(route, navigation, customOptions, undefined);
+
+    return {
+      route,
+      navigation,
+      render() {
+        return element;
+      },
+      options: customOptions as ScreenOptions,
+    };
+  };
+
+  return {
+    describe,
+    descriptors,
+  };
 }

package/src/useFocusEffect.tsx

@@ -14,6 +14,7 @@ type EffectCallback = () => undefined | void | (() => void);
 export function useFocusEffect(effect: EffectCallback) {
   const navigation = useNavigation();
 
+  // eslint-disable-next-line prefer-rest-params
   if (arguments[1] !== undefined) {
     const message =
       "You passed a second argument to 'useFocusEffect', but it only accepts one argument. " +

package/src/useFocusedListenersChildrenAdapter.tsx

@@ -2,8 +2,8 @@ import type { ParamListBase } from '@react-navigation/routers';
 import * as React from 'react';
 
 import {
-  FocusedNavigationCallback,
-  FocusedNavigationListener,
+  type FocusedNavigationCallback,
+  type FocusedNavigationListener,
   NavigationBuilderContext,
 } from './NavigationBuilderContext';
 import type { NavigationHelpers } from './types';

package/src/useIsomorphicLayoutEffect.native.tsx

@@ -0,0 +1,3 @@
+import { useLayoutEffect } from 'react';
+
+export const useIsomorphicLayoutEffect = useLayoutEffect;

package/src/useIsomorphicLayoutEffect.tsx

@@ -0,0 +1,7 @@
+import { useEffect, useLayoutEffect } from 'react';
+
+/**
+ * Use `useEffect` during SSR and `useLayoutEffect` in the browser to avoid warnings.
+ */
+export const useIsomorphicLayoutEffect =
+  typeof document !== 'undefined' ? useLayoutEffect : useEffect;