@react-navigation/core 8.0.0-alpha.23 → 8.0.0-alpha.25

package/src/index.tsx

@@ -4,6 +4,7 @@ export {
   createNavigatorFactory,
   type TypedNavigatorFactory,
 } from './createNavigatorFactory';
+export { getLoaderForState as UNSTABLE_getLoaderForState } from './DataLoading';
 export { findFocusedRoute } from './findFocusedRoute';
 export { getActionFromState } from './getActionFromState';
 export { getFocusedRouteNameFromRoute } from './getFocusedRouteNameFromRoute';
@@ -47,6 +48,7 @@ export type {
   EventMapBase,
   EventMapCore,
   GenericNavigation,
+  NavigationContainerEventMap,
   NavigationContainerProps,
   NavigationContainerRef,
   NavigationContainerRefWithCurrent,
@@ -58,6 +60,7 @@ export type {
   NavigatorScreenParams,
   NavigatorTypeBagBase,
   NavigatorTypeBagFor,
+  NestedNavigatorsForParamList,
   PathConfig,
   PathConfigMap,
   RootNavigator,

package/src/types.tsx

@@ -287,6 +287,45 @@ export class PrivateValueStore<T extends [any, any, any, any]> {
   protected ''?: T;
 }
 
+type NavigatorLike =
+  | {
+      Navigator: React.ComponentType<any>;
+      Screen: unknown;
+      Group: unknown;
+    }
+  | {
+      config: unknown;
+      getComponent: () => React.ComponentType<any>;
+    };
+
+type ParamListForNavigator<T extends {}> = T extends NavigatorLike
+  ? T extends PrivateValueStore<[infer ParamList extends {}, any, any, any]>
+    ? ParamList
+    : T
+  : T;
+
+// Remove `undefined` before checking for nested navigator params.
+// If nothing remains, avoid matching `never` against `NavigatorScreenParams`
+type NestedNavigatorForScreenParams<T, Params = NotUndefined<T>> = [
+  Params,
+] extends [never]
+  ? never
+  : Params extends NavigatorScreenParams<infer Navigator>
+    ? Navigator extends PrivateValueStore<[any, any, any, any]>
+      ? Navigator extends NavigatorLike
+        ? Navigator
+        : never
+      : never
+    : never;
+
+export type NestedNavigatorsForParamList<ParamList extends {}> = {
+  [RouteName in keyof ParamList as NestedNavigatorForScreenParams<
+    ParamList[RouteName]
+  > extends never
+    ? never
+    : RouteName]: NestedNavigatorForScreenParams<ParamList[RouteName]>;
+};
+
 type NavigateOptions = {
   merge?: boolean | undefined;
   pop?: boolean | undefined;
@@ -390,7 +429,7 @@ type NavigationHelpersCommon<
 
 type ParamType<
   ParamList extends {},
-  RouteName extends keyof ParamList | unknown,
+  RouteName,
   IsPartial extends boolean = false,
 > = RouteName extends keyof ParamList
   ? ParamList[RouteName] extends undefined
@@ -685,16 +724,16 @@ export type RouteConfigComponent<
        * React component to render for this screen.
        */
       component: ScreenComponentType<ParamList, RouteName>;
-      getComponent?: never | undefined;
-      children?: never | undefined;
+      getComponent?: never;
+      children?: never;
     }
   | {
       /**
        * Lazily get a React component to render for this screen.
        */
       getComponent: () => ScreenComponentType<ParamList, RouteName>;
-      component?: never | undefined;
-      children?: never | undefined;
+      component?: never;
+      children?: never;
     }
   | {
       /**
@@ -704,8 +743,8 @@ export type RouteConfigComponent<
         route: RouteProp<ParamList, RouteName>;
         navigation: any;
       }) => React.ReactNode;
-      component?: never | undefined;
-      getComponent?: never | undefined;
+      component?: never;
+      getComponent?: never;
     };
 
 export type RouteConfigProps<
@@ -912,15 +951,19 @@ export type NavigationContainerEventMap = {
       /**
        * The data object passed when emitting the event.
        */
-      data: unknown;
+      data?: unknown;
       /**
        * The key of the target route which received the event.
        */
-      target: string | undefined;
+      target?: string | undefined;
       /**
        * Whether `event.preventDefault()` was called on this event.
        */
-      defaultPrevented: boolean | undefined;
+      defaultPrevented?: boolean | undefined;
+      /**
+       * Prevent the default action which happens on this event.
+       */
+      preventDefault?: (() => void) | undefined;
     };
   };
 };
@@ -1000,8 +1043,8 @@ export type RouteForName<
 // Look up route object by checking each level and recursing into the nested param lists
 // This avoids building a union of all routes, which doesn't scale on large trees
 type RouteForNameInternal<ParamList extends {}, RouteName extends string> =
-  | (RouteName extends infer Name extends KeyOf<ParamList>
-      ? RouteProp<ParamList, Name>
+  | (RouteName extends KeyOf<ParamList>
+      ? RouteProp<ParamList, RouteName>
       : never)
   | RouteForNameNested<NestedParamLists<ParamList>, RouteName>;
 
@@ -1010,11 +1053,7 @@ type RouteForNameNested<ParamLists, RouteName extends string> =
   // e.g. if ParamLists is A | B
   // TypeScript evaluates the branch once per member (A, then B)
   // and unions the outcomes
-  // The infer ParamList extends {} just captures the current member
-  // and re-asserts the {} constraint that RouteForNameInternal requires
-  ParamLists extends infer ParamList extends {}
-    ? RouteForNameInternal<ParamList, RouteName>
-    : never;
+  ParamLists extends {} ? RouteForNameInternal<ParamLists, RouteName> : never;
 
 /**
  * Union of param lists of the nested navigators in a param list.
@@ -1022,7 +1061,7 @@ type RouteForNameNested<ParamLists, RouteName extends string> =
 export type NestedParamLists<ParamList extends {}> = {
   [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
     ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<infer T>
-      ? T
+      ? ParamListForNavigator<T>
       : never
     : never;
 }[keyof ParamList];
@@ -1030,7 +1069,9 @@ export type NestedParamLists<ParamList extends {}> = {
 type ParamListRoute<ParamList extends {}> = {
   [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
     ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<infer T>
-      ? ParamListRoute<T> | RouteProp<ParamList, RouteName>
+      ?
+          | ParamListRoute<ParamListForNavigator<T>>
+          | RouteProp<ParamList, RouteName>
       : RouteProp<ParamList, RouteName>
     : RouteProp<ParamList, RouteName>;
 }[keyof ParamList];
@@ -1056,13 +1097,15 @@ type BasicNavigationList<
       ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<
           infer T
         >
-        ? keyof T extends ExcludedRouteNames
-          ? {}
-          : BasicNavigationList<
-              T,
-              ExcludedRouteNames,
-              NavigationProp<ParamList, RouteName>
-            >
+        ? ParamListForNavigator<T> extends infer NestedParamList extends {}
+          ? keyof NestedParamList extends ExcludedRouteNames
+            ? {}
+            : BasicNavigationList<
+                NestedParamList,
+                ExcludedRouteNames,
+                NavigationProp<ParamList, RouteName>
+              >
+          : {}
         : {}
       : {}) &
       (RouteName extends ExcludedRouteNames
@@ -1076,6 +1119,96 @@ type BasicNavigationList<
   }[keyof ParamList]
 >;
 
+type InheritedParentParams<ParentParamList, ParamList> = {
+  [K in keyof ParentParamList as K extends keyof ParamList
+    ? never
+    : string extends K
+      ? never
+      : K]: ParentParamList[K];
+};
+
+type GenericNavigationComposite<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  Parent,
+> =
+  Parent extends NavigationProp<any, any, any, any, any>
+    ? ParamListOfNavigationProp<Parent> extends infer ParentParamList
+      ? NavigationProp<
+          ParamList & InheritedParentParams<ParentParamList, ParamList>,
+          RouteName
+        > & { getParent: Parent['getParent'] }
+      : never
+    : NavigationProp<ParamList, RouteName>;
+
+type NavigationListForScreenParams<
+  T extends {},
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = T extends PrivateValueStore<[any, any, any, any]> & NavigatorLike
+  ? NavigationListForNestedInternal<
+      T,
+      GenericNavigationComposite<ParamList, RouteName, Parent>
+    >
+  : NavigationListForParamListScreenParams<
+      T,
+      ParamList,
+      RouteName,
+      ExcludedRouteNames,
+      Parent
+    >;
+
+type NavigationListForParamListScreenParams<
+  T extends {},
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> =
+  // `T` is only ever a plain param list here, since navigators are routed to
+  // `NavigationListForNestedInternal` by `NavigationListForScreenParams`.
+  // So there's no navigator to unwrap with `ParamListForNavigator`.
+  T extends ParamListBase
+    ? BasicNavigationListForParamList<
+        T,
+        ExcludedRouteNames,
+        GenericNavigationComposite<ParamList, RouteName, Parent>
+      >
+    : {};
+
+type BasicNavigationListForParamList<
+  ParamList extends ParamListBase,
+  ExcludedRouteNames,
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = UnionToIntersection<
+  {
+    [RouteName in keyof ParamList]: (NavigatorScreenParams<{}> extends ParamList[RouteName]
+      ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<
+          infer T
+        >
+        ? NavigationListForScreenParams<
+            T,
+            ParamList,
+            RouteName,
+            ExcludedRouteNames,
+            Parent
+          >
+        : {}
+      : {}) &
+      (RouteName extends ExcludedRouteNames
+        ? {}
+        : {
+            [Key in RouteName]: GenericNavigationComposite<
+              ParamList,
+              RouteName,
+              Parent
+            >;
+          });
+  }[keyof ParamList]
+>;
+
 export type NavigationListForNavigator<Navigator> =
   Navigator extends PrivateValueStore<infer Value> ? Value[1] : {};
 
@@ -1094,13 +1227,14 @@ type NavigationListForNestedInternal<
   Parent = undefined,
   NavigatorList extends Record<string, any> =
     NavigationListForNavigator<Navigator>,
+  Navigators = NestedNavigatorsOf<Navigator>,
   // This navigator's own routes, each composed with the accumulated parent.
   // It's threaded into the recursion as the parent for nested navigators so
   // each route is composed with its ancestors exactly once, instead of
   // re-wrapping the whole descendant list at every level (which is quadratic
   // in the nesting depth).
   ComposedList = ComposeNavigationList<NavigatorList, Parent>,
-> = Navigator extends {
+> = (Navigator extends {
   readonly config: {
     readonly screens?: infer Screens;
     readonly groups?: infer Groups;
@@ -1109,7 +1243,69 @@ type NavigationListForNestedInternal<
   ? ComposedList &
       NavigationListForScreens<ComposedList, Screens> &
       NavigationListForGroups<ComposedList, Groups>
-  : ComposedList;
+  : ComposedList) &
+  NavigationListForNestedNavigators<ComposedList, Navigators> &
+  NavigationListForDynamicNestedParamLists<Navigator, ComposedList, Navigators>;
+
+type NavigationListForDynamicNestedParamLists<
+  Navigator,
+  ParentList,
+  Navigators,
+> = Navigator extends { readonly config: unknown }
+  ? {}
+  : Navigator extends PrivateValueStore<[infer ParamList, any, any, any]>
+    ? NavigationListForNestedParamLists<ParentList, ParamList, Navigators>
+    : {};
+
+// Map of route name to nested navigator type
+// inferred from `NavigatorScreenParams<typeof Navigator>`
+type NestedNavigatorsOf<Navigator> =
+  Navigator extends PrivateValueStore<[any, any, any, infer Nesting]>
+    ? Nesting extends Record<string, any>
+      ? Nesting
+      : {}
+    : {};
+
+// Like `NavigationListForScreens`, but reads nested navigators from the brand
+// map instead of a static config.
+type NavigationListForNestedNavigators<ParentList, Navigators> =
+  UnionToIntersection<
+    {
+      [K in keyof Navigators]: K extends keyof ParentList
+        ? NavigationListForNestedInternal<Navigators[K], ParentList[K]>
+        : {};
+    }[keyof Navigators]
+  >;
+
+// Fallback for dynamic nested routes declared through NavigatorScreenParams<ParamList>.
+// Param-list branches expose generic navigation props, while nested navigator
+// entries still recover their concrete navigator props.
+type NavigationListForNestedParamLists<ParentList, ParamList, Navigators> =
+  ParentList extends Record<string, any>
+    ? ParamList extends ParamListBase
+      ? UnionToIntersection<
+          {
+            [K in keyof ParamList]: K extends keyof Navigators
+              ? {}
+              : K extends keyof ParentList
+                ? NavigatorScreenParams<{}> extends ParamList[K]
+                  ? NotUndefined<ParamList[K]> extends NavigatorScreenParams<
+                      infer T
+                    >
+                    ? NavigationListForScreenParams<
+                        T,
+                        ParamList,
+                        K,
+                        keyof ParentList,
+                        ParentList[K]
+                      >
+                    : {}
+                  : {}
+                : {};
+          }[keyof ParamList]
+        >
+      : {}
+    : {};
 
 // Compose every entry in a navigator's list with the accumulated parent.
 // When there's no parent (root navigator), the list is returned as-is so the
@@ -1230,20 +1426,39 @@ export type NavigatorTypeBagFor<
   ParamList extends {},
 > = TypeBag & { ParamList: ParamList };
 
-type TypedNavigatorComponent<Bag extends NavigatorTypeBagBase> =
+export type NavigatorProps<
+  ParamList extends ParamListBase,
+  State extends NavigationState,
+  ScreenOptions extends {},
+  EventMap extends EventMapBase,
+  Navigation,
+  Navigator extends React.ComponentType<any>,
+> = Omit<
+  React.ComponentProps<Navigator>,
+  keyof DefaultNavigatorOptions<any, any, any, any, any>
+> &
+  DefaultNavigatorOptions<
+    ParamList,
+    State,
+    ScreenOptions,
+    EventMap,
+    Navigation
+  >;
+
+type TypedNavigatorStaticComponent<Bag extends NavigatorTypeBagBase> =
   React.ComponentType<
-    Omit<
-      React.ComponentProps<
-        TypedNavigatorInternal<
+    Partial<
+      Omit<
+        NavigatorProps<
           Bag['ParamList'],
           Bag['State'],
           Bag['ScreenOptions'],
           Bag['EventMap'],
-          Bag['NavigationList'],
+          Bag['NavigationList'][keyof Bag['ParamList']],
           Bag['Navigator']
-        >['Navigator']
-      >,
-      'children'
+        >,
+        'children'
+      >
     >
   >;
 
@@ -1261,15 +1476,16 @@ type TypedNavigatorStatic<
   config: Config;
   with: (
     Component: React.ComponentType<{
-      Navigator: TypedNavigatorComponent<Bag>;
+      Navigator: TypedNavigatorStaticComponent<Bag>;
     }>
   ) => TypedNavigatorStaticDecorated<Bag, Config>;
-  getComponent: () => TypedNavigatorComponent<Bag>;
+  getComponent: () => TypedNavigatorStaticComponent<Bag>;
 };
 
 export type TypedNavigator<
   Bag extends NavigatorTypeBagBase,
   Config = unknown,
+  Nesting = unknown,
 > = (undefined extends Config
   ? TypedNavigatorInternal<
       Bag['ParamList'],
@@ -1281,7 +1497,7 @@ export type TypedNavigator<
     >
   : TypedNavigatorStatic<Bag, Config>) &
   PrivateValueStore<
-    [Bag['ParamList'], Bag['NavigationList'], unknown, unknown]
+    [Bag['ParamList'], Bag['NavigationList'], unknown, Nesting]
   >;
 
 type TypedNavigatorInternal<
@@ -1296,17 +1512,14 @@ type TypedNavigatorInternal<
    * Navigator component which manages the child screens.
    */
   Navigator: React.ComponentType<
-    Omit<
-      React.ComponentProps<Navigator>,
-      keyof DefaultNavigatorOptions<any, any, any, any, any>
-    > &
-      DefaultNavigatorOptions<
-        ParamList,
-        State,
-        ScreenOptions,
-        EventMap,
-        NavigationList[keyof ParamList]
-      >
+    NavigatorProps<
+      ParamList,
+      State,
+      ScreenOptions,
+      EventMap,
+      NavigationList[keyof ParamList],
+      Navigator
+    >
   >;
   /**
    * Component used for grouping multiple route configuration.
@@ -1329,7 +1542,17 @@ type TypedNavigatorInternal<
   ) => null;
 };
 
-export type NavigatorScreenParams<ParamList extends {}> =
+declare const NavigatorScreenParamsSymbol: unique symbol;
+
+type NavigatorScreenParamsBrand<T extends {}> = {
+  // Preserve the original generic for inference without affecting assignability.
+  // - The symbol key hides the property from normal object usage
+  // - The actual type is intersected for inference
+  // - The `any` makes the property effectively `any` for assignability
+  readonly [NavigatorScreenParamsSymbol]?: any & { readonly type: T };
+};
+
+type NavigatorScreenParamsForParamList<ParamList extends {}> =
   | {
       screen?: never;
       params?: never;
@@ -1364,6 +1587,10 @@ export type NavigatorScreenParams<ParamList extends {}> =
           };
     }[keyof ParamList];
 
+export type NavigatorScreenParams<ParamList extends {}> =
+  NavigatorScreenParamsForParamList<ParamListForNavigator<ParamList>> &
+    NavigatorScreenParamsBrand<ParamList>;
+
 type ParseConfig<Params> = {
   [K in keyof Params]?:
     | ((value: string) => Params[K])
@@ -1412,7 +1639,12 @@ type PathConfigAlias<Params> = {
 };
 
 export type PathConfig<Params> = FlatType<
-  Partial<PathConfigAlias<Params>> & {
+  Partial<Omit<PathConfigAlias<Params>, 'path'>> & {
+    /**
+     * Path string to match against.
+     * e.g. `/users/:id` will match `/users/1` and extract `id` param as `1`.
+     */
+    path?: string | undefined;
     /**
      * An object mapping the param name to a function which converts the param value to a string.
      * By default, all params are converted to strings using `String(value)`.
@@ -1431,16 +1663,20 @@ export type PathConfig<Params> = FlatType<
      */
     alias?: (string | PathConfigAlias<Params>)[] | undefined;
   } & (NonNullable<Params> extends NavigatorScreenParams<infer ParamList>
-      ? {
-          /**
-           * Path configuration for child screens.
-           */
-          screens?: PathConfigMap<ParamList> | undefined;
-          /**
-           * Name of the initial route to use for the navigator when the path matches.
-           */
-          initialRouteName?: Extract<keyof ParamList, string> | undefined;
-        }
+      ? ParamListForNavigator<ParamList> extends infer ChildParamList extends {}
+        ? {
+            /**
+             * Path configuration for child screens.
+             */
+            screens?: PathConfigMap<ChildParamList> | undefined;
+            /**
+             * Name of the initial route to use for the navigator when the path matches.
+             */
+            initialRouteName?:
+              | Extract<keyof ChildParamList, string>
+              | undefined;
+          }
+        : {}
       : {})
 >;
 

package/src/useEventEmitter.tsx

@@ -13,12 +13,15 @@ type Listeners = Set<(e: any) => void>;
  * Hook to manage the event system used by the navigator to notify screens of various events.
  */
 export function useEventEmitter<T extends Record<string, any>>(
-  listen?: (e: any) => void
+  listen?: (e: any) => void,
+  onPostEmit?: (e: any) => void
 ): NavigationEventEmitter<T> {
   const listenRef = React.useRef(listen);
+  const onPostEmitRef = React.useRef(onPostEmit);
 
-  React.useEffect(() => {
+  React.useInsertionEffect(() => {
     listenRef.current = listen;
+    onPostEmitRef.current = onPostEmit;
   });
 
   const listeners = React.useRef<Record<string, Record<string, Listeners>>>(
@@ -124,6 +127,8 @@ export function useEventEmitter<T extends Record<string, any>>(
 
       callbacks?.forEach((cb) => cb(event));
 
+      onPostEmitRef.current?.(event);
+
       return event as any;
     },
     []

package/src/useKeyedChildListeners.tsx

@@ -28,8 +28,10 @@ export function useKeyedChildListeners() {
       keyedListeners[type][key] = listener;
 
       return () => {
-        // @ts-expect-error: according to ref stated above you can use `key` to index type
-        keyedListeners[type][key] = undefined;
+        if (keyedListeners[type][key] === listener) {
+          // @ts-expect-error: according to ref stated above you can use `key` to index type
+          keyedListeners[type][key] = undefined;
+        }
       };
     },
     [keyedListeners]

package/src/useNavigation.tsx

@@ -1,10 +1,7 @@
 import * as React from 'react';
 
 import { NavigationContainerRefContext } from './NavigationContainerRefContext';
-import {
-  NavigationContext,
-  NavigationRouteNameContext,
-} from './NavigationProvider';
+import { NavigationContext } from './NavigationProvider';
 import type {
   GenericNavigation,
   NavigationListForNavigator,
@@ -46,23 +43,7 @@ export function useNavigation(name?: string): unknown {
     return navigation ?? root;
   }
 
-  const routeName = React.use(NavigationRouteNameContext);
-
-  // Generally, this condition isn't needed as `getParent(name)` works for current screen
-  // However, it'll throw if the hook is used in a preloaded screen
-  if (routeName === name) {
-    if (navigation === undefined) {
-      throw new Error(
-        `Couldn't find a navigation object for '${name}'. This is not expected.`
-      );
-    }
-
-    return navigation;
-  }
-
-  // We get parent first so that `getParent(name)` is not called in preloaded screens
-  // It's ok since `getParent` also works for current screen, so parent is not skipped
-  const parent = navigation?.getParent()?.getParent(name);
+  const parent = navigation?.getParent(name);
 
   if (parent === undefined) {
     throw new Error(