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

package/src/useNavigationBuilder.tsx

@@ -1,68 +1,53 @@
 import {
   CommonActions,
-  DefaultRouterOptions,
-  NavigationAction,
-  NavigationState,
-  ParamListBase,
-  PartialState,
-  Route,
-  Router,
-  RouterConfigOptions,
-  RouterFactory,
+  type DefaultRouterOptions,
+  type NavigationAction,
+  type NavigationState,
+  type ParamListBase,
+  type PartialState,
+  type Route,
+  type Router,
+  type RouterConfigOptions,
+  type RouterFactory,
 } from '@react-navigation/routers';
 import * as React from 'react';
 import { isValidElementType } from 'react-is';
-
-import Group from './Group';
-import isArrayEqual from './isArrayEqual';
-import isRecordEqual from './isRecordEqual';
-import NavigationHelpersContext from './NavigationHelpersContext';
-import NavigationRouteContext from './NavigationRouteContext';
-import NavigationStateContext from './NavigationStateContext';
-import PreventRemoveProvider from './PreventRemoveProvider';
-import Screen from './Screen';
+import useLatestCallback from 'use-latest-callback';
+
+import { Group } from './Group';
+import { isArrayEqual } from './isArrayEqual';
+import { isRecordEqual } from './isRecordEqual';
+import { NavigationHelpersContext } from './NavigationHelpersContext';
+import { NavigationRouteContext } from './NavigationRouteContext';
+import { NavigationStateContext } from './NavigationStateContext';
+import { PreventRemoveProvider } from './PreventRemoveProvider';
+import { Screen } from './Screen';
 import {
-  DefaultNavigatorOptions,
-  EventMapBase,
-  EventMapCore,
-  NavigatorScreenParams,
+  type DefaultNavigatorOptions,
+  type EventMapBase,
+  type EventMapCore,
+  type NavigatorScreenParams,
   PrivateValueStore,
-  RouteConfig,
-  RouteProp,
+  type RouteConfig,
 } from './types';
-import useChildListeners from './useChildListeners';
-import useComponent from './useComponent';
-import useCurrentRender from './useCurrentRender';
-import useDescriptors, { ScreenConfigWithParent } from './useDescriptors';
-import useEventEmitter from './useEventEmitter';
-import useFocusedListenersChildrenAdapter from './useFocusedListenersChildrenAdapter';
-import useFocusEvents from './useFocusEvents';
-import useKeyedChildListeners from './useKeyedChildListeners';
-import useNavigationHelpers from './useNavigationHelpers';
-import useOnAction from './useOnAction';
-import useOnGetState from './useOnGetState';
-import useOnRouteFocus from './useOnRouteFocus';
-import useRegisterNavigator from './useRegisterNavigator';
-import useScheduleUpdate from './useScheduleUpdate';
+import { useChildListeners } from './useChildListeners';
+import { useComponent } from './useComponent';
+import { useCurrentRender } from './useCurrentRender';
+import { type ScreenConfigWithParent, useDescriptors } from './useDescriptors';
+import { useEventEmitter } from './useEventEmitter';
+import { useFocusedListenersChildrenAdapter } from './useFocusedListenersChildrenAdapter';
+import { useFocusEvents } from './useFocusEvents';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
+import { useKeyedChildListeners } from './useKeyedChildListeners';
+import { useNavigationHelpers } from './useNavigationHelpers';
+import { useOnAction } from './useOnAction';
+import { useOnGetState } from './useOnGetState';
+import { useOnRouteFocus } from './useOnRouteFocus';
+import { useRegisterNavigator } from './useRegisterNavigator';
 
 // This is to make TypeScript compiler happy
-// eslint-disable-next-line babel/no-unused-expressions
 PrivateValueStore;
 
-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>;
@@ -79,7 +64,7 @@ const isValidKey = (key: unknown) =>
 const getRouteConfigsFromChildren = <
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 >(
   children: React.ReactNode,
   groupKey?: string,
@@ -87,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>[]
@@ -110,6 +96,7 @@ const getRouteConfigsFromChildren = <
         acc.push({
           keys: [groupKey, child.props.navigationKey],
           options: groupOptions,
+          layout: groupLayout,
           props: child.props as RouteConfig<
             ParamListBase,
             string,
@@ -118,6 +105,7 @@ const getRouteConfigsFromChildren = <
             EventMap
           >,
         });
+
         return acc;
       }
 
@@ -139,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;
@@ -161,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'.`
     );
   }, []);
@@ -252,12 +241,12 @@ const getRouteConfigsFromChildren = <
  * @param options Options object containing `children` and additional options for the router.
  * @returns An object containing `state`, `navigation`, `descriptors` objects.
  */
-export default function useNavigationBuilder<
+export function useNavigationBuilder<
   State extends NavigationState,
   RouterOptions extends DefaultRouterOptions,
   ActionHelpers extends Record<string, () => void>,
   ScreenOptions extends {},
-  EventMap extends Record<string, any>
+  EventMap extends Record<string, any>,
 >(
   createRouter: RouterFactory<State, any, RouterOptions>,
   options: DefaultNavigatorOptions<
@@ -266,7 +255,6 @@ export default function useNavigationBuilder<
     ScreenOptions,
     EventMap
   > &
-    NavigationBuilderOptions<ScreenOptions> &
     RouterOptions
 ) {
   const navigatorKey = useRegisterNavigator();
@@ -275,17 +263,17 @@ export default function useNavigationBuilder<
     | NavigatorRoute
     | undefined;
 
-  const { children, 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),
-      ...(route?.params &&
-      route.params.state == null &&
-      route.params.initial !== false &&
-      typeof route.params.screen === 'string'
-        ? { initialRouteName: route.params.screen }
-        : null),
-    })
+    createRouter(rest as unknown as RouterOptions)
   );
 
   const routeConfigs = getRouteConfigsFromChildren<
@@ -362,12 +350,7 @@ export default function useNavigationBuilder<
 
   const stateCleanedUp = React.useRef(false);
 
-  const cleanUpState = React.useCallback(() => {
-    setCurrentState(undefined);
-    stateCleanedUp.current = true;
-  }, [setCurrentState]);
-
-  const setState = React.useCallback(
+  const setState = useLatestCallback(
     (state: NavigationState | PartialState<NavigationState> | undefined) => {
       if (stateCleanedUp.current) {
         // State might have been already cleaned up due to unmount
@@ -375,9 +358,9 @@ export default function useNavigationBuilder<
         // This would lead to old data preservation on main navigator unmount
         return;
       }
+
       setCurrentState(state);
-    },
-    [setCurrentState]
+    }
   );
 
   const [initializedState, isFirstStateInitialization] = React.useMemo(() => {
@@ -409,7 +392,11 @@ export default function useNavigationBuilder<
     // So we need to rehydrate it to make it usable
     if (
       (currentState === undefined || !isStateValid(currentState)) &&
-      route?.params?.state == null
+      route?.params?.state == null &&
+      !(
+        typeof route?.params?.screen === 'string' &&
+        route?.params?.initial !== false
+      )
     ) {
       return [
         router.getInitialState({
@@ -420,9 +407,29 @@ export default function useNavigationBuilder<
         true,
       ];
     } else {
+      let stateFromParams;
+
+      if (route?.params?.state != null) {
+        stateFromParams = route.params.state;
+      } else if (
+        typeof route?.params?.screen === 'string' &&
+        route?.params?.initial !== false
+      ) {
+        stateFromParams = {
+          index: 0,
+          routes: [
+            {
+              name: route.params.screen,
+              params: route.params.params,
+              path: route.params.path,
+            },
+          ],
+        };
+      }
+
       return [
         router.getRehydratedState(
-          (route?.params?.state ?? currentState) as PartialState<State>,
+          (stateFromParams ?? currentState) as PartialState<State>,
           {
             routeNames,
             routeParamList: initialRouteParamList,
@@ -462,17 +469,26 @@ export default function useNavigationBuilder<
     !isArrayEqual(state.routeNames, routeNames) ||
     !isRecordEqual(routeKeyList, previousRouteKeyList)
   ) {
+    const navigatorStateForNextRouteNamesChange =
+      options.getStateForRouteNamesChange?.(state);
     // When the list of route names change, the router should handle it to remove invalid routes
-    nextState = router.getStateForRouteNamesChange(state, {
-      routeNames,
-      routeParamList,
-      routeGetIdList,
-      routeKeyChanges: Object.keys(routeKeyList).filter(
-        (name) =>
-          previousRouteKeyList.hasOwnProperty(name) &&
-          routeKeyList[name] !== previousRouteKeyList[name]
-      ),
-    });
+    nextState = navigatorStateForNextRouteNamesChange
+      ? // @ts-expect-error this is ok
+        router.getRehydratedState(navigatorStateForNextRouteNamesChange, {
+          routeNames,
+          routeParamList,
+          routeGetIdList,
+        })
+      : router.getStateForRouteNamesChange(state, {
+          routeNames,
+          routeParamList,
+          routeGetIdList,
+          routeKeyChanges: Object.keys(routeKeyList).filter(
+            (name) =>
+              name in previousRouteKeyList &&
+              routeKeyList[name] !== previousRouteKeyList[name]
+          ),
+        });
   }
 
   const previousNestedParamsRef = React.useRef(route?.params);
@@ -527,7 +543,7 @@ export default function useNavigationBuilder<
 
   const shouldUpdate = state !== nextState;
 
-  useScheduleUpdate(() => {
+  useIsomorphicLayoutEffect(() => {
     if (shouldUpdate) {
       // If the state needs to be updated, we'll schedule an update
       setState(nextState);
@@ -551,34 +567,24 @@ export default function useNavigationBuilder<
 
     return () => {
       // We need to clean up state for this navigator on unmount
-      // We do it in a timeout because we need to detect if another navigator mounted in the meantime
-      // For example, if another navigator has started rendering, we should skip cleanup
-      // Otherwise, our cleanup step will cleanup state for the other navigator and re-initialize it
-      setTimeout(() => {
-        if (getCurrentState() !== undefined && getKey() === navigatorKey) {
-          cleanUpState();
-        }
-      }, 0);
+      if (getCurrentState() !== undefined && getKey() === navigatorKey) {
+        setCurrentState(undefined);
+        stateCleanedUp.current = true;
+      }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
-  // We initialize this ref here to avoid a new getState getting initialized
-  // whenever initializedState changes. We want getState to have access to the
-  // latest initializedState, but don't need it to change when that happens
-  const initializedStateRef = React.useRef<State>();
-  initializedStateRef.current = initializedState;
-
-  const getState = React.useCallback((): State => {
-    const currentState = getCurrentState();
+  const getState = useLatestCallback((): State => {
+    const currentState = shouldUpdate ? nextState : getCurrentState();
 
-    return isStateInitialized(currentState)
-      ? (currentState as State)
-      : (initializedStateRef.current as State);
-  }, [getCurrentState, isStateInitialized]);
+    return (
+      isStateInitialized(currentState) ? currentState : initializedState
+    ) as State;
+  });
 
   const emitter = useEventEmitter<EventMapCore<State>>((e) => {
-    let routeNames = [];
+    const routeNames = [];
 
     let route: Route<string> | undefined;
 
@@ -685,7 +691,7 @@ export default function useNavigationBuilder<
     getStateListeners: keyedListeners.getState,
   });
 
-  const descriptors = useDescriptors<
+  const { describe, descriptors } = useDescriptors<
     State,
     ActionHelpers,
     ScreenOptions,
@@ -694,8 +700,8 @@ export default function useNavigationBuilder<
     state,
     screens,
     navigation,
-    screenOptions: options.screenOptions,
-    defaultScreenOptions: options.defaultScreenOptions,
+    screenOptions,
+    screenLayout,
     onAction,
     getState,
     setState,
@@ -713,15 +719,28 @@ export default function useNavigationBuilder<
     descriptors,
   });
 
-  const NavigationContent = useComponent((children: React.ReactNode) => (
-    <NavigationHelpersContext.Provider value={navigation}>
-      <PreventRemoveProvider>{children}</PreventRemoveProvider>
-    </NavigationHelpersContext.Provider>
-  ));
+  const NavigationContent = useComponent((children: React.ReactNode) => {
+    const element =
+      layout != null
+        ? layout({
+            state,
+            descriptors,
+            navigation,
+            children,
+          })
+        : children;
+
+    return (
+      <NavigationHelpersContext.Provider value={navigation}>
+        <PreventRemoveProvider>{element}</PreventRemoveProvider>
+      </NavigationHelpersContext.Provider>
+    );
+  });
 
   return {
     state,
     navigation,
+    describe,
     descriptors,
     NavigationContent,
   };

package/src/useNavigationCache.tsx

@@ -1,20 +1,20 @@
 import {
   CommonActions,
-  NavigationAction,
-  NavigationState,
-  ParamListBase,
-  Router,
+  type NavigationAction,
+  type NavigationState,
+  type ParamListBase,
+  type Router,
 } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationBuilderContext from './NavigationBuilderContext';
+import { NavigationBuilderContext } from './NavigationBuilderContext';
 import type { NavigationHelpers, NavigationProp } from './types';
 import type { NavigationEventEmitter } from './useEventEmitter';
 
 type Options<
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends Record<string, any>
+  EventMap extends Record<string, any>,
 > = {
   state: State;
   getState: () => State;
@@ -29,31 +29,35 @@ type Options<
   emitter: NavigationEventEmitter<EventMap>;
 };
 
-type NavigationCache<
+type NavigationItem<
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends Record<string, any>
-> = Record<
+  EventMap extends Record<string, any>,
+> = 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.
  * This lets us apply optimizations like `React.memo` to minimize re-rendering screens.
  */
-export default function useNavigationCache<
+export function useNavigationCache<
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends Record<string, any>
+  EventMap extends Record<string, any>,
+  ActionHelpers extends Record<string, () => void>,
 >({
   state,
   getState,
@@ -64,20 +68,72 @@ export default 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 default 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 default 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 default 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 default function useNavigationCache<
     return acc;
   }, {});
 
-  return cache.current;
+  return {
+    base,
+    navigations: cache.current,
+  };
 }

package/src/useNavigationContainerRef.tsx

@@ -1,10 +1,10 @@
 import * as React from 'react';
 
-import createNavigationContainerRef from './createNavigationContainerRef';
+import { createNavigationContainerRef } from './createNavigationContainerRef';
 import type { NavigationContainerRefWithCurrent } from './types';
 
-export default function useNavigationContainerRef<
-  ParamList extends {} = ReactNavigation.RootParamList
+export function useNavigationContainerRef<
+  ParamList extends {} = ReactNavigation.RootParamList,
 >(): NavigationContainerRefWithCurrent<ParamList> {
   const navigation =
     React.useRef<NavigationContainerRefWithCurrent<ParamList> | null>(null);

package/src/useNavigationHelpers.tsx

@@ -1,19 +1,18 @@
 import {
   CommonActions,
-  NavigationAction,
-  NavigationState,
-  ParamListBase,
-  Router,
+  type NavigationAction,
+  type NavigationState,
+  type ParamListBase,
+  type Router,
 } from '@react-navigation/routers';
 import * as React from 'react';
 
-import NavigationContext from './NavigationContext';
-import { NavigationHelpers, PrivateValueStore } from './types';
-import UnhandledActionContext from './UnhandledActionContext';
+import { NavigationContext } from './NavigationContext';
+import { type NavigationHelpers, PrivateValueStore } from './types';
+import { UnhandledActionContext } from './UnhandledActionContext';
 import type { NavigationEventEmitter } from './useEventEmitter';
 
 // This is to make TypeScript compiler happy
-// eslint-disable-next-line babel/no-unused-expressions
 PrivateValueStore;
 
 type Options<State extends NavigationState, Action extends NavigationAction> = {
@@ -28,11 +27,11 @@ type Options<State extends NavigationState, Action extends NavigationAction> = {
  * Navigation object with helper methods to be used by a navigator.
  * This object includes methods for common actions as well as methods the parent screen's navigation object.
  */
-export default function useNavigationHelpers<
+export function useNavigationHelpers<
   State extends NavigationState,
   ActionHelpers extends Record<string, () => void>,
   Action extends NavigationAction,
-  EventMap extends Record<string, any>
+  EventMap extends Record<string, any>,
 >({
   id: navigatorId,
   onAction,