@react-navigation/core 7.0.0-alpha.6 → 7.0.0-alpha.8

package/src/theming/useTheme.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import { ThemeContext } from './ThemeContext';
+
+export function useTheme() {
+  const theme = React.useContext(ThemeContext);
+
+  if (theme == null) {
+    throw new Error(
+      "Couldn't find a theme. Is your component inside NavigationContainer or does it have a theme?"
+    );
+  }
+
+  return theme;
+}

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 {}
   }
 }
 
@@ -29,13 +32,15 @@ export type DefaultNavigatorOptions<
    * 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 component for the navigator.
+   * Layout for the navigator.
    * Useful for wrapping with a component with access to navigator's state and options.
    */
   layout?: (props: {
@@ -58,6 +63,7 @@ export type DefaultNavigatorOptions<
     >;
     children: React.ReactNode;
   }) => React.ReactElement;
+
   /**
    * Event listeners for all the screens in the navigator.
    */
@@ -67,6 +73,7 @@ export type DefaultNavigatorOptions<
         route: RouteProp<ParamList>;
         navigation: any;
       }) => ScreenListeners<State, EventMap>);
+
   /**
    * Default options for all screens under this navigator.
    */
@@ -75,7 +82,19 @@ 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.
    */
@@ -281,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.
    *
@@ -379,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.
    */
@@ -590,6 +629,7 @@ export type RouteConfig<
     | ((props: {
         route: RouteProp<ParamList, RouteName>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
   /**
@@ -602,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.
@@ -638,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.

package/src/useDescriptors.tsx

@@ -2,6 +2,7 @@ import type {
   NavigationAction,
   NavigationState,
   ParamListBase,
+  PartialState,
   Router,
 } from '@react-navigation/routers';
 import * as React from 'react';
@@ -14,6 +15,7 @@ import {
 import { NavigationContext } from './NavigationContext';
 import { NavigationRouteContext } from './NavigationRouteContext';
 import { SceneView } from './SceneView';
+import { ThemeContext } from './theming/ThemeContext';
 import type {
   Descriptor,
   EventMapBase,
@@ -33,14 +35,23 @@ export type ScreenConfigWithParent<
 > = {
   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<
@@ -54,7 +65,8 @@ type Options<
     ScreenConfigWithParent<State, ScreenOptions, EventMap>
   >;
   navigation: NavigationHelpers<ParamListBase>;
-  screenOptions?: ScreenOptionsOrCallback<ScreenOptions>;
+  screenOptions: ScreenOptionsOrCallback<ScreenOptions> | undefined;
+  screenLayout: ScreenLayout | undefined;
   onAction: (action: NavigationAction) => boolean;
   getState: () => State;
   setState: (state: State) => void;
@@ -83,6 +95,7 @@ export function useDescriptors<
   screens,
   navigation,
   screenOptions,
+  screenLayout,
   onAction,
   getState,
   setState,
@@ -92,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>>(
     {}
   );
@@ -122,7 +136,12 @@ export function useDescriptors<
     ]
   );
 
-  const navigations = useNavigationCache<State, ScreenOptions, EventMap>({
+  const { base, navigations } = useNavigationCache<
+    State,
+    ScreenOptions,
+    EventMap,
+    ActionHelpers
+  >({
     state,
     getState,
     navigation,
@@ -133,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
@@ -165,18 +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 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) => {
@@ -189,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={customOptions}
-              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,
@@ -220,4 +299,39 @@ export function useDescriptors<
 
     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/useNavigationBuilder.tsx

@@ -72,7 +72,8 @@ const getRouteConfigsFromChildren = <
     State,
     ScreenOptions,
     EventMap
-  >['options']
+  >['options'],
+  groupLayout?: ScreenConfigWithParent<State, ScreenOptions, EventMap>['layout']
 ) => {
   const configs = React.Children.toArray(children).reduce<
     ScreenConfigWithParent<State, ScreenOptions, EventMap>[]
@@ -95,6 +96,7 @@ const getRouteConfigsFromChildren = <
         acc.push({
           keys: [groupKey, child.props.navigationKey],
           options: groupOptions,
+          layout: groupLayout,
           props: child.props as RouteConfig<
             ParamListBase,
             string,
@@ -103,6 +105,7 @@ const getRouteConfigsFromChildren = <
             EventMap
           >,
         });
+
         return acc;
       }
 
@@ -124,8 +127,9 @@ const getRouteConfigsFromChildren = <
             child.type !== Group
               ? groupOptions
               : groupOptions != null
-              ? [...groupOptions, child.props.screenOptions]
-              : [child.props.screenOptions]
+                ? [...groupOptions, child.props.screenOptions]
+                : [child.props.screenOptions],
+            child.props.screenLayout ?? groupLayout
           )
         );
         return acc;
@@ -146,8 +150,8 @@ const getRouteConfigsFromChildren = <
                 : ''
             }`
           : typeof child === 'object'
-          ? JSON.stringify(child)
-          : `'${String(child)}'`
+            ? JSON.stringify(child)
+            : `'${String(child)}'`
       }). To render this component in the navigator, pass it in the 'component' prop to 'Screen'.`
     );
   }, []);
@@ -259,7 +263,15 @@ export function useNavigationBuilder<
     | NavigatorRoute
     | undefined;
 
-  const { children, layout, screenOptions, screenListeners, ...rest } = options;
+  const {
+    children,
+    layout,
+    screenOptions,
+    screenLayout,
+    screenListeners,
+    ...rest
+  } = options;
+
   const { current: router } = React.useRef<Router<State, any>>(
     createRouter(rest as unknown as RouterOptions)
   );
@@ -679,7 +691,7 @@ export function useNavigationBuilder<
     getStateListeners: keyedListeners.getState,
   });
 
-  const descriptors = useDescriptors<
+  const { describe, descriptors } = useDescriptors<
     State,
     ActionHelpers,
     ScreenOptions,
@@ -689,6 +701,7 @@ export function useNavigationBuilder<
     screens,
     navigation,
     screenOptions,
+    screenLayout,
     onAction,
     getState,
     setState,
@@ -727,6 +740,7 @@ export function useNavigationBuilder<
   return {
     state,
     navigation,
+    describe,
     descriptors,
     NavigationContent,
   };

package/src/useNavigationCache.tsx

@@ -29,22 +29,25 @@ type Options<
   emitter: NavigationEventEmitter<EventMap>;
 };
 
-type NavigationCache<
+type NavigationItem<
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends Record<string, any>,
-> = Record<
+> = NavigationProp<
+  ParamListBase,
   string,
-  NavigationProp<
-    ParamListBase,
-    string,
-    string | undefined,
-    State,
-    ScreenOptions,
-    EventMap
-  >
+  string | undefined,
+  State,
+  ScreenOptions,
+  EventMap
 >;
 
+type NavigationCache<
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends Record<string, any>,
+> = Record<string, NavigationItem<State, ScreenOptions, EventMap>>;
+
 /**
  * Hook to cache navigation objects for each screen in the navigator.
  * It's important to cache them to make sure navigation objects don't change between renders.
@@ -54,6 +57,7 @@ export function useNavigationCache<
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends Record<string, any>,
+  ActionHelpers extends Record<string, () => void>,
 >({
   state,
   getState,
@@ -64,20 +68,72 @@ export function useNavigationCache<
 }: Options<State, ScreenOptions, EventMap>) {
   const { stackRef } = React.useContext(NavigationBuilderContext);
 
+  const base = React.useMemo((): NavigationItem<
+    State,
+    ScreenOptions,
+    EventMap
+  > &
+    ActionHelpers => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { emit, ...rest } = navigation;
+
+    const actions = {
+      ...router.actionCreators,
+      ...CommonActions,
+    };
+
+    const dispatch = () => {
+      throw new Error(
+        'Actions cannot be dispatched from a placeholder screen.'
+      );
+    };
+
+    const helpers = Object.keys(actions).reduce<Record<string, () => void>>(
+      (acc, name) => {
+        acc[name] = dispatch;
+
+        return acc;
+      },
+      {}
+    ) as ActionHelpers;
+
+    return {
+      ...rest,
+      ...helpers,
+      addListener: () => {
+        // Event listeners are not supported for placeholder screens
+
+        return () => {
+          // Empty function
+        };
+      },
+      removeListener: () => {
+        // Event listeners are not supported for placeholder screens
+      },
+      dispatch,
+      getParent: (id?: string) => {
+        if (id !== undefined && id === rest.getId()) {
+          return base;
+        }
+
+        return rest.getParent(id);
+      },
+      setOptions: () => {
+        throw new Error('Options cannot be set from a placeholder screen.');
+      },
+      isFocused: () => false,
+    };
+  }, [navigation, router.actionCreators]);
+
   // Cache object which holds navigation objects for each screen
   // We use `React.useMemo` instead of `React.useRef` coz we want to invalidate it when deps change
   // In reality, these deps will rarely change, if ever
   const cache = React.useMemo(
     () => ({ current: {} as NavigationCache<State, ScreenOptions, EventMap> }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [getState, navigation, setOptions, router, emitter]
+    [base, getState, navigation, setOptions, emitter]
   );
 
-  const actions = {
-    ...router.actionCreators,
-    ...CommonActions,
-  };
-
   cache.current = state.routes.reduce<
     NavigationCache<State, ScreenOptions, EventMap>
   >((acc, route) => {
@@ -91,9 +147,6 @@ export function useNavigationCache<
       // If a cached navigation object already exists, reuse it
       acc[route.key] = previous;
     } else {
-      // eslint-disable-next-line @typescript-eslint/no-unused-vars
-      const { emit, ...rest } = navigation;
-
       const dispatch = (thunk: Thunk) => {
         const action = typeof thunk === 'function' ? thunk(getState()) : thunk;
 
@@ -124,6 +177,11 @@ export function useNavigationCache<
         }
       };
 
+      const actions = {
+        ...router.actionCreators,
+        ...CommonActions,
+      };
+
       const helpers = Object.keys(actions).reduce<Record<string, () => void>>(
         (acc, name) => {
           acc[name] = (...args: any) =>
@@ -138,19 +196,19 @@ export function useNavigationCache<
       );
 
       acc[route.key] = {
-        ...rest,
+        ...base,
         ...helpers,
         // FIXME: too much work to fix the types for now
         ...(emitter.create(route.key) as any),
         dispatch: (thunk: Thunk) => withStack(() => dispatch(thunk)),
         getParent: (id?: string) => {
-          if (id !== undefined && id === rest.getId()) {
+          if (id !== undefined && id === base.getId()) {
             // If the passed id is the same as the current navigation id,
             // we return the cached navigation object for the relevant route
             return acc[route.key];
           }
 
-          return rest.getParent(id);
+          return base.getParent(id);
         },
         setOptions: (options: object) => {
           setOptions((o) => ({
@@ -175,5 +233,8 @@ export function useNavigationCache<
     return acc;
   }, {});
 
-  return cache.current;
+  return {
+    base,
+    navigations: cache.current,
+  };
 }