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

package/src/useDescriptors.tsx

@@ -2,17 +2,20 @@ import type {
   NavigationAction,
   NavigationState,
   ParamListBase,
+  PartialState,
   Router,
 } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationBuilderContext, {
-  AddKeyedListener,
-  AddListener,
+import {
+  type AddKeyedListener,
+  type 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 { ThemeContext } from './theming/ThemeContext';
 import type {
   Descriptor,
   EventMapBase,
@@ -22,30 +25,39 @@ 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,
   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<
@@ -53,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;
@@ -79,17 +85,17 @@ 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 {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 >({
   state,
   screens,
   navigation,
   screenOptions,
-  defaultScreenOptions,
+  screenLayout,
   onAction,
   getState,
   setState,
@@ -99,6 +105,7 @@ export default function useDescriptors<
   router,
   emitter,
 }: Options<State, ScreenOptions, EventMap>) {
+  const theme = React.useContext(ThemeContext);
   const [options, setOptions] = React.useState<Record<string, ScreenOptions>>(
     {}
   );
@@ -129,7 +136,12 @@ export default function useDescriptors<
     ]
   );
 
-  const navigations = useNavigationCache<State, ScreenOptions, EventMap>({
+  const { base, navigations } = useNavigationCache<
+    State,
+    ScreenOptions,
+    EventMap,
+    ActionHelpers
+  >({
     state,
     getState,
     navigation,
@@ -140,27 +152,20 @@ export default 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
@@ -172,30 +177,35 @@ export default 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) => {
@@ -208,24 +218,74 @@ export default 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,
@@ -234,9 +294,44 @@ export default 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/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,9 +11,10 @@ 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();
 
+  // 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/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, {
-  FocusedNavigationCallback,
-  FocusedNavigationListener,
+import {
+  type FocusedNavigationCallback,
+  type 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/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;

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,8 @@
+import { type NavigationState } from '@react-navigation/routers';
 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,8 +10,10 @@ import type { NavigationProp } from './types';
  *
  * @returns Navigation prop of the parent screen.
  */
-export default function useNavigation<
-  T = NavigationProp<ReactNavigation.RootParamList>
+export function useNavigation<
+  T = Omit<NavigationProp<ReactNavigation.RootParamList>, 'getState'> & {
+    getState(): NavigationState | undefined;
+  },
 >(): T {
   const root = React.useContext(NavigationContainerRefContext);
   const navigation = React.useContext(NavigationContext);