@react-navigation/core 7.0.0-alpha.8 → 7.0.0-rc.0

package/src/types.tsx

@@ -24,15 +24,12 @@ type Keyof<T extends {}> = Extract<keyof T, string>;
 
 export type DefaultNavigatorOptions<
   ParamList extends ParamListBase,
+  NavigatorID extends string | undefined,
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
+  Navigation,
 > = 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.
@@ -71,7 +68,7 @@ export type DefaultNavigatorOptions<
     | ScreenListeners<State, EventMap>
     | ((props: {
         route: RouteProp<ParamList>;
-        navigation: any;
+        navigation: Navigation;
       }) => ScreenListeners<State, EventMap>);
 
   /**
@@ -81,7 +78,7 @@ export type DefaultNavigatorOptions<
     | ScreenOptions
     | ((props: {
         route: RouteProp<ParamList>;
-        navigation: any;
+        navigation: Navigation;
         theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
@@ -90,7 +87,7 @@ export type DefaultNavigatorOptions<
    */
   screenLayout?: (props: {
     route: RouteProp<ParamList, keyof ParamList>;
-    navigation: any;
+    navigation: Navigation;
     theme: ReactNavigation.Theme;
     children: React.ReactElement;
   }) => React.ReactElement;
@@ -98,10 +95,19 @@ export type DefaultNavigatorOptions<
   /**
    A function returning a state, which may be set after modifying the routes name.
    */
-  getStateForRouteNamesChange?: (
+  UNSTABLE_getStateForRouteNamesChange?: (
     state: NavigationState
   ) => PartialState<NavigationState> | undefined;
-};
+} & (NavigatorID extends string
+    ? {
+        /**
+         * Optional ID for the navigator. Can be used with `navigation.getParent(id)` to refer to a parent.
+         */
+        id: NavigatorID;
+      }
+    : {
+        id?: undefined;
+      });
 
 export type EventMapBase = Record<
   string,
@@ -555,7 +561,7 @@ export type ScreenListeners<
   EventMap extends EventMapBase,
 > = Partial<{
   [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
-    EventMap,
+    EventMap & EventMapCore<State>,
     EventName
   >;
 }>;
@@ -602,12 +608,13 @@ export type RouteConfigComponent<
       getComponent?: never;
     };
 
-export type RouteConfig<
+export type RouteConfigProps<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList,
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
+  Navigation,
 > = {
   /**
    * Optional key for this screen. This doesn't need to be unique.
@@ -628,7 +635,7 @@ export type RouteConfig<
     | ScreenOptions
     | ((props: {
         route: RouteProp<ParamList, RouteName>;
-        navigation: any;
+        navigation: Navigation;
         theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
@@ -639,7 +646,7 @@ export type RouteConfig<
     | ScreenListeners<State, EventMap>
     | ((props: {
         route: RouteProp<ParamList, RouteName>;
-        navigation: any;
+        navigation: Navigation;
       }) => ScreenListeners<State, EventMap>);
 
   /**
@@ -648,8 +655,8 @@ export type RouteConfig<
    * e.g. for styling, error boundaries, suspense, etc.
    */
   layout?: (props: {
-    route: RouteProp<ParamList, keyof ParamList>;
-    navigation: any;
+    route: RouteProp<ParamList, RouteName>;
+    navigation: Navigation;
     theme: ReactNavigation.Theme;
     children: React.ReactElement;
   }) => React.ReactElement;
@@ -670,11 +677,29 @@ export type RouteConfig<
    * Initial params object for the route.
    */
   initialParams?: Partial<ParamList[RouteName]>;
-} & RouteConfigComponent<ParamList, RouteName>;
+};
+
+export type RouteConfig<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends EventMapBase,
+  Navigation,
+> = RouteConfigProps<
+  ParamList,
+  RouteName,
+  State,
+  ScreenOptions,
+  EventMap,
+  Navigation
+> &
+  RouteConfigComponent<ParamList, RouteName>;
 
 export type RouteGroupConfig<
   ParamList extends ParamListBase,
   ScreenOptions extends {},
+  Navigation,
 > = {
   /**
    * Optional key for the screens in this group.
@@ -689,7 +714,7 @@ export type RouteGroupConfig<
     | ScreenOptions
     | ((props: {
         route: RouteProp<ParamList, keyof ParamList>;
-        navigation: any;
+        navigation: Navigation;
         theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
@@ -699,7 +724,7 @@ export type RouteGroupConfig<
    */
   screenLayout?: (props: {
     route: RouteProp<ParamList, keyof ParamList>;
-    navigation: any;
+    navigation: Navigation;
     theme: ReactNavigation.Theme;
     children: React.ReactElement;
   }) => React.ReactElement;
@@ -775,6 +800,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 {}> =
@@ -782,11 +815,77 @@ export type NavigationContainerRefWithCurrent<ParamList extends {}> =
     current: NavigationContainerRef<ParamList> | null;
   };
 
+export type NavigationListBase<ParamList extends ParamListBase> = {
+  [RouteName in keyof ParamList]: unknown;
+};
+
+export type TypeBag<
+  ParamList extends ParamListBase,
+  NavigatorID extends string | undefined,
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends EventMapBase,
+  NavigationList extends NavigationListBase<ParamList>,
+  Navigator extends React.ComponentType<any>,
+> = {
+  ParamList: ParamList;
+  NavigatorID: NavigatorID;
+  State: State;
+  ScreenOptions: ScreenOptions;
+  EventMap: EventMap;
+  NavigationList: NavigationList;
+  Navigator: Navigator;
+};
+
+export type NavigatorTypeBagBase = {
+  ParamList: ParamListBase;
+  NavigatorID: string | undefined;
+  State: NavigationState;
+  ScreenOptions: {};
+  EventMap: EventMapBase;
+  NavigationList: NavigationListBase<ParamListBase>;
+  Navigator: React.ComponentType<any>;
+};
+
+export type NavigatorTypeBag<
+  ParamList extends ParamListBase,
+  NavigatorID extends string | undefined,
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends EventMapBase,
+  NavigationList extends NavigationListBase<ParamList>,
+  Navigator extends React.ComponentType<any>,
+> = {
+  ParamList: ParamList;
+  NavigatorID: NavigatorID;
+  State: State;
+  ScreenOptions: ScreenOptions;
+  EventMap: EventMap;
+  NavigationList: NavigationList;
+  Navigator: Navigator;
+};
+
 export type TypedNavigator<
+  Bag extends NavigatorTypeBagBase,
+  Config = unknown,
+> = TypedNavigatorInternal<
+  Bag['ParamList'],
+  Bag['NavigatorID'],
+  Bag['State'],
+  Bag['ScreenOptions'],
+  Bag['EventMap'],
+  Bag['NavigationList'],
+  Bag['Navigator']
+> &
+  (undefined extends Config ? {} : { config: Config });
+
+type TypedNavigatorInternal<
   ParamList extends ParamListBase,
+  NavigatorID extends string | undefined,
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
+  NavigationList extends NavigationListBase<ParamList>,
   Navigator extends React.ComponentType<any>,
 > = {
   /**
@@ -795,19 +894,35 @@ export type TypedNavigator<
   Navigator: React.ComponentType<
     Omit<
       React.ComponentProps<Navigator>,
-      keyof DefaultNavigatorOptions<any, any, any, any>
+      keyof DefaultNavigatorOptions<any, any, any, any, any, any>
     > &
-      DefaultNavigatorOptions<ParamList, State, ScreenOptions, EventMap>
+      DefaultNavigatorOptions<
+        ParamList,
+        NavigatorID,
+        State,
+        ScreenOptions,
+        EventMap,
+        NavigationList[keyof ParamList]
+      >
   >;
   /**
    * Component used for grouping multiple route configuration.
    */
-  Group: React.ComponentType<RouteGroupConfig<ParamList, ScreenOptions>>;
+  Group: React.ComponentType<
+    RouteGroupConfig<ParamList, ScreenOptions, NavigationList[keyof ParamList]>
+  >;
   /**
    * Component used for specifying route configuration.
    */
   Screen: <RouteName extends keyof ParamList>(
-    _: RouteConfig<ParamList, RouteName, State, ScreenOptions, EventMap>
+    _: RouteConfig<
+      ParamList,
+      RouteName,
+      State,
+      ScreenOptions,
+      EventMap,
+      NavigationList[RouteName]
+    >
   ) => null;
 };
 

package/src/useDescriptors.tsx

@@ -36,7 +36,14 @@ export type ScreenConfigWithParent<
   keys: (string | undefined)[];
   options: (ScreenOptionsOrCallback<ScreenOptions> | undefined)[] | undefined;
   layout: ScreenLayout | undefined;
-  props: RouteConfig<ParamListBase, string, State, ScreenOptions, EventMap>;
+  props: RouteConfig<
+    ParamListBase,
+    string,
+    State,
+    ScreenOptions,
+    EventMap,
+    unknown
+  >;
 };
 
 type ScreenLayout = (props: {

package/src/useFocusEffect.tsx

@@ -71,7 +71,7 @@ export function useFocusEffect(effect: EffectCallback) {
       }
     };
 
-    // We need to run the effect on intial render/dep changes if the screen is focused
+    // We need to run the effect on initial render/dep changes if the screen is focused
     if (navigation.isFocused()) {
       cleanup = callback();
       isFocused = true;
@@ -79,7 +79,7 @@ export function useFocusEffect(effect: EffectCallback) {
 
     const unsubscribeFocus = navigation.addListener('focus', () => {
       // If callback was already called for focus, avoid calling it again
-      // The focus event may also fire on intial render, so we guard against runing the effect twice
+      // The focus event may also fire on initial render, so we guard against running the effect twice
       if (isFocused) {
         return;
       }

package/src/useLazyValue.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+
+export function useLazyValue<T>(create: () => T) {
+  const lazyRef = React.useRef<T>();
+
+  if (lazyRef.current === undefined) {
+    lazyRef.current = create();
+  }
+
+  return lazyRef.current as T;
+}

package/src/useNavigation.tsx

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

package/src/useNavigationBuilder.tsx

@@ -14,6 +14,7 @@ import * as React from 'react';
 import { isValidElementType } from 'react-is';
 import useLatestCallback from 'use-latest-callback';
 
+import { deepFreeze } from './deepFreeze';
 import { Group } from './Group';
 import { isArrayEqual } from './isArrayEqual';
 import { isRecordEqual } from './isRecordEqual';
@@ -39,6 +40,7 @@ import { useFocusedListenersChildrenAdapter } from './useFocusedListenersChildre
 import { useFocusEvents } from './useFocusEvents';
 import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 import { useKeyedChildListeners } from './useKeyedChildListeners';
+import { useLazyValue } from './useLazyValue';
 import { useNavigationHelpers } from './useNavigationHelpers';
 import { useOnAction } from './useOnAction';
 import { useOnGetState } from './useOnGetState';
@@ -102,7 +104,8 @@ const getRouteConfigsFromChildren = <
             string,
             State,
             ScreenOptions,
-            EventMap
+            EventMap,
+            unknown
           >,
         });
 
@@ -251,9 +254,11 @@ export function useNavigationBuilder<
   createRouter: RouterFactory<State, any, RouterOptions>,
   options: DefaultNavigatorOptions<
     ParamListBase,
+    string | undefined,
     State,
     ScreenOptions,
-    EventMap
+    EventMap,
+    any
   > &
     RouterOptions
 ) {
@@ -272,16 +277,27 @@ export function useNavigationBuilder<
     ...rest
   } = options;
 
-  const { current: router } = React.useRef<Router<State, any>>(
-    createRouter(rest as unknown as RouterOptions)
-  );
-
   const routeConfigs = getRouteConfigsFromChildren<
     State,
     ScreenOptions,
     EventMap
   >(children);
 
+  const router = useLazyValue<Router<State, any>>(() => {
+    if (
+      rest.initialRouteName != null &&
+      routeConfigs.every(
+        (config) => config.props.name !== rest.initialRouteName
+      )
+    ) {
+      throw new Error(
+        `Couldn't find a screen named '${rest.initialRouteName}' to use as 'initialRouteName'.`
+      );
+    }
+
+    return createRouter(rest as unknown as RouterOptions);
+  });
+
   const screens = routeConfigs.reduce<
     Record<string, ScreenConfigWithParent<State, ScreenOptions, EventMap>>
   >((acc, config) => {
@@ -457,7 +473,7 @@ export function useNavigationBuilder<
 
   let state =
     // If the state isn't initialized, or stale, use the state we initialized instead
-    // The state won't update until there's a change needed in the state we have initalized locally
+    // The state won't update until there's a change needed in the state we have initialized locally
     // So it'll be `undefined` or stale until the first navigation event happens
     isStateInitialized(currentState)
       ? (currentState as State)
@@ -470,7 +486,7 @@ export function useNavigationBuilder<
     !isRecordEqual(routeKeyList, previousRouteKeyList)
   ) {
     const navigatorStateForNextRouteNamesChange =
-      options.getStateForRouteNamesChange?.(state);
+      options.UNSTABLE_getStateForRouteNamesChange?.(state);
     // When the list of route names change, the router should handle it to remove invalid routes
     nextState = navigatorStateForNextRouteNamesChange
       ? // @ts-expect-error this is ok
@@ -556,6 +572,10 @@ export function useNavigationBuilder<
   state = nextState;
 
   React.useEffect(() => {
+    // In strict mode, React will double-invoke effects.
+    // So we need to reset the flag if component was not unmounted
+    stateCleanedUp.current = false;
+
     setKey(navigatorKey);
 
     if (!getIsInitial()) {
@@ -578,9 +598,11 @@ export function useNavigationBuilder<
   const getState = useLatestCallback((): State => {
     const currentState = shouldUpdate ? nextState : getCurrentState();
 
-    return (
-      isStateInitialized(currentState) ? currentState : initializedState
-    ) as State;
+    return deepFreeze(
+      (isStateInitialized(currentState)
+        ? currentState
+        : initializedState) as State
+    );
   });
 
   const emitter = useEventEmitter<EventMapCore<State>>((e) => {

package/src/useRouteCache.tsx

@@ -7,7 +7,7 @@ import type { RouteProp } from './types';
 type RouteCache = Map<string, RouteProp<ParamListBase>>;
 
 /**
- * Utilites such as `getFocusedRouteNameFromRoute` need to access state.
+ * Utilities such as `getFocusedRouteNameFromRoute` need to access state.
  * So we need a way to suppress the warning for those use cases.
  * This is fine since they are internal utilities and this is not public API.
  */
@@ -41,6 +41,22 @@ export function useRouteCache<State extends NavigationState>(
       proxy = routeWithoutState;
     }
 
+    if (process.env.NODE_ENV !== 'production') {
+      // FIXME: since the state is updated with mutation, the route object cannot be frozen
+      // As a workaround, loop through the object and make the properties readonly
+      for (const key in proxy) {
+        // @ts-expect-error: this is fine since we are looping through the object
+        const value = proxy[key];
+
+        Object.defineProperty(proxy, key, {
+          enumerable: true,
+          configurable: true,
+          writable: false,
+          value,
+        });
+      }
+    }
+
     Object.defineProperty(proxy, CHILD_STATE, {
       enumerable: false,
       configurable: true,

package/src/useSyncState.tsx

@@ -1,14 +1,27 @@
 import * as React from 'react';
 
+import { deepFreeze } from './deepFreeze';
+
 const createStore = <T,>(getInitialState: () => T) => {
   const listeners: (() => void)[] = [];
 
-  let state: T = getInitialState();
+  let initialized = false;
+  let state: T;
+
+  const getState = () => {
+    if (initialized) {
+      return state;
+    }
 
-  const getState = () => state;
+    initialized = true;
+    state = deepFreeze(getInitialState());
+
+    return state;
+  };
 
   const setState = (newState: T) => {
-    state = newState;
+    state = deepFreeze(newState);
+
     listeners.forEach((listener) => listener());
   };