@react-navigation/core 8.0.0-alpha.2 → 8.0.0-alpha.20

package/src/types.tsx

@@ -14,6 +14,7 @@ import type {
   FlatType,
   KeyOf,
   NotUndefined,
+  StandardSchemaV1,
   UnionToIntersection,
 } from './utilities';
 
@@ -54,13 +55,8 @@ export interface RootNavigator {}
 export interface Theme {}
 
 export type RootParamList =
-  RootNavigator extends TypedNavigatorInternal<
-    infer ParamList,
-    any,
-    any,
-    any,
-    any,
-    any
+  RootNavigator extends PrivateValueStore<
+    [infer ParamList extends {}, any, any, any]
   >
     ? ParamList
     : {};
@@ -82,58 +78,68 @@ export type DefaultNavigatorOptions<
    * Layout for the navigator.
    * Useful for wrapping with a component with access to navigator's state and options.
    */
-  layout?: (props: {
-    state: State;
-    navigation: NavigationHelpers<ParamList>;
-    descriptors: Record<
-      string,
-      Descriptor<
-        ScreenOptions,
-        NavigationProp<
-          ParamList,
-          keyof ParamList,
-          State,
-          ScreenOptions,
-          EventMap
-        >,
-        RouteProp<ParamList>
-      >
-    >;
-    children: React.ReactNode;
-  }) => React.ReactElement;
+  layout?:
+    | ((props: {
+        state: State;
+        navigation: NavigationHelpers<ParamList>;
+        descriptors: Record<
+          string,
+          Descriptor<
+            ScreenOptions,
+            NavigationProp<
+              ParamList,
+              keyof ParamList,
+              State,
+              ScreenOptions,
+              EventMap
+            >,
+            RouteProp<ParamList>
+          >
+        >;
+        children: React.ReactNode;
+      }) => React.ReactElement)
+    | undefined;
 
   /**
    * Event listeners for all the screens in the navigator.
    */
   screenListeners?:
-    | ScreenListeners<State, EventMap>
-    | ((props: {
-        route: RouteProp<ParamList>;
-        navigation: Navigation;
-      }) => ScreenListeners<State, EventMap>);
+    | (
+        | ScreenListeners<State, EventMap>
+        | ((props: {
+            route: RouteProp<ParamList>;
+            navigation: Navigation;
+          }) => ScreenListeners<State, EventMap>)
+      )
+    | undefined;
 
   /**
    * Default options for all screens under this navigator.
    */
   screenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: RouteProp<ParamList>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Layout for all screens under this navigator.
    */
-  screenLayout?: (
-    props: ScreenLayoutArgs<
-      ParamList,
-      keyof ParamList,
-      ScreenOptions,
-      Navigation
-    >
-  ) => React.ReactElement;
+  screenLayout?:
+    | ((
+        props: ScreenLayoutArgs<
+          ParamList,
+          keyof ParamList,
+          ScreenOptions,
+          Navigation
+        >
+      ) => React.ReactElement)
+    | undefined;
 
   /**
    * A function returning overrides for the underlying router used by the navigator.
@@ -142,9 +148,11 @@ export type DefaultNavigatorOptions<
    *
    * This must be a pure function and cannot reference outside dynamic variables.
    */
-  router?: <Action extends NavigationAction>(
-    original: Router<State, Action>
-  ) => Partial<Router<State, Action>>;
+  router?:
+    | (<Action extends NavigationAction>(
+        original: Router<State, Action>
+      ) => Partial<Router<State, Action>>)
+    | undefined;
 
   /**
    * What should happen when the available route names change.
@@ -165,15 +173,15 @@ export type DefaultNavigatorOptions<
    * - Direct navigation is only handled for `NAVIGATE` actions.
    * - Unhandled state is restored only if the current state becomes invalid, i.e. it doesn't contain any currently defined screens.
    */
-  routeNamesChangeBehavior?: 'firstMatch' | 'lastUnhandled';
+  routeNamesChangeBehavior?: ('firstMatch' | 'lastUnhandled') | undefined;
 };
 
 export type EventMapBase = Record<
   string,
-  { data?: any; canPreventDefault?: boolean }
+  { data?: any; canPreventDefault?: boolean | undefined }
 >;
 
-export type EventMapCore<State extends NavigationState> = {
+export type EventMapCore<in out State extends NavigationState> = {
   focus: { data: undefined };
   blur: { data: undefined };
   state: { data: { state: State } };
@@ -189,7 +197,10 @@ export type EventArg<
    * Type of the event (e.g. `focus`, `blur`)
    */
   readonly type: EventName;
-  readonly target?: string;
+  /**
+   * Key of the route which received the event.
+   */
+  readonly target?: string | undefined;
 } & (CanPreventDefault extends true
   ? {
       /**
@@ -203,15 +214,14 @@ export type EventArg<
     }
   : {}) &
   (undefined extends Data
-    ? { readonly data?: Readonly<Data> }
+    ? { readonly data?: Readonly<Data> | undefined }
     : { readonly data: Readonly<Data> });
 
 export type EventListenerCallback<
-  EventMap extends EventMapBase,
-  EventName extends keyof EventMap,
-  EventCanPreventDefault extends
-    | boolean
-    | undefined = EventMap[EventName]['canPreventDefault'],
+  in out EventMap extends EventMapBase,
+  in out EventName extends keyof EventMap,
+  in out EventCanPreventDefault extends boolean | undefined =
+    EventMap[EventName]['canPreventDefault'],
 > = (
   e: EventArg<
     EventName,
@@ -220,7 +230,7 @@ export type EventListenerCallback<
   >
 ) => void;
 
-export type EventConsumer<EventMap extends EventMapBase> = {
+export type EventConsumer<in out EventMap extends EventMapBase> = {
   /**
    * Subscribe to events from the parent navigator.
    *
@@ -237,7 +247,7 @@ export type EventConsumer<EventMap extends EventMapBase> = {
   ): void;
 };
 
-export type EventEmitter<EventMap extends EventMapBase> = {
+export type EventEmitter<in out EventMap extends EventMapBase> = {
   /**
    * Emit an event to child screens.
    *
@@ -263,7 +273,7 @@ export type EventEmitter<EventMap extends EventMapBase> = {
   >;
 };
 
-export class PrivateValueStore<T extends [any, any, any]> {
+export class PrivateValueStore<T extends [any, any, any, any]> {
   /**
    * UGLY HACK! DO NOT USE THE TYPE!!!
    *
@@ -311,12 +321,18 @@ type NavigationHelpersCommon<
         ? [
             screen: RouteName,
             params?: ParamList[RouteName],
-            options?: { merge?: boolean; pop?: boolean },
+            options?: {
+              merge?: boolean | undefined;
+              pop?: boolean | undefined;
+            },
           ]
         : [
             screen: RouteName,
             params: ParamList[RouteName],
-            options?: { merge?: boolean; pop?: boolean },
+            options?: {
+              merge?: boolean | undefined;
+              pop?: boolean | undefined;
+            },
           ]
       : never
   ): void;
@@ -335,9 +351,9 @@ type NavigationHelpersCommon<
       ? {
           name: RouteName;
           params: ParamList[RouteName];
-          path?: string;
-          merge?: boolean;
-          pop?: boolean;
+          path?: string | undefined;
+          merge?: boolean | undefined;
+          pop?: boolean | undefined;
         }
       : never
   ): void;
@@ -392,7 +408,7 @@ type NavigationHelpersCommon<
    * So don't use it in `render`.
    */
   getState(): State;
-} & PrivateValueStore<[ParamList, unknown, unknown]>;
+};
 
 type ParamType<
   ParamList extends {},
@@ -407,8 +423,8 @@ type ParamType<
   : unknown;
 
 type NavigationHelpersRoute<
-  ParamList extends {},
-  RouteName extends keyof ParamList = KeyOf<ParamList>,
+  in out ParamList extends {},
+  in out RouteName extends keyof ParamList = KeyOf<ParamList>,
 > = {
   /**
    * Update the param object for the route.
@@ -440,43 +456,51 @@ export type NavigationHelpers<
   EventMap extends EventMapBase = {},
 > = NavigationHelpersCommon<ParamList> &
   EventEmitter<EventMap> &
-  NavigationHelpersRoute<ParamList, keyof ParamList>;
+  NavigationHelpersRoute<ParamList, keyof ParamList> &
+  PrivateValueStore<[ParamList, unknown, unknown, unknown]>;
 
 export type NavigationContainerProps = {
   /**
    * Initial state object for the navigation tree.
    */
-  initialState?: InitialState;
+  initialState?: InitialState | undefined;
   /**
    * Callback which is called with the latest navigation state when it changes.
    */
-  onStateChange?: (state: Readonly<NavigationState> | undefined) => void;
+  onStateChange?:
+    | ((state: Readonly<NavigationState> | undefined) => void)
+    | undefined;
   /**
    * Callback which is called after the navigation tree mounts.
    */
-  onReady?: () => void;
+  onReady?: (() => void) | undefined;
   /**
    * Callback which is called when an action is not handled.
    */
-  onUnhandledAction?: (action: Readonly<NavigationAction>) => void;
+  onUnhandledAction?:
+    | ((action: Readonly<NavigationAction>) => void)
+    | undefined;
   /**
    * Theme object for the UI elements.
    */
-  theme?: Theme;
+  theme?: Theme | undefined;
   /**
    * Children elements to render.
    */
   children: React.ReactNode;
 };
 
-export type NavigationProp<
+// Everything in `NavigationProp` except `getParent` and the private brand.
+// The composite navigation prop intersects this directly, so it doesn't have
+// to walk `NavigationProp`'s members with `Omit` to drop `getParent`/the brand.
+type NavigationPropBase<
   ParamList extends {},
   RouteName extends keyof ParamList = KeyOf<ParamList>,
   State extends NavigationState = NavigationState<ParamList>,
   ScreenOptions extends {} = {},
   EventMap extends EventMapBase = {},
   ActionHelpers extends Record<string, (...args: any) => void> = {},
-> = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
+> = NavigationHelpersCommon<ParamList, State> & {
   /**
    * Update the options for the route.
    * The options object will be shallow merged with default options object.
@@ -484,6 +508,25 @@ export type NavigationProp<
    * @param options Partial options object for the current screen.
    */
   setOptions(options: Partial<ScreenOptions>): void;
+} & NavigationHelpersRoute<ParamList, RouteName> &
+  ActionHelpers &
+  EventConsumer<EventMap & EventMapCore<State>>;
+
+export type NavigationProp<
+  ParamList extends {},
+  RouteName extends keyof ParamList = KeyOf<ParamList>,
+  State extends NavigationState = NavigationState<ParamList>,
+  ScreenOptions extends {} = {},
+  EventMap extends EventMapBase = {},
+  ActionHelpers extends Record<string, (...args: any) => void> = {},
+> = NavigationPropBase<
+  ParamList,
+  RouteName,
+  State,
+  ScreenOptions,
+  EventMap,
+  ActionHelpers
+> & {
   /**
    * Returns the navigation prop of the parent screen.
    * If a route name is provided, the navigation prop from the parent screen with matching route name (including current) will be returned.
@@ -502,58 +545,93 @@ export type NavigationProp<
     ActionHelpers
   >;
   getParent(): NavigationProp<ParamListBase> | undefined;
-} & NavigationHelpersRoute<ParamList, RouteName> &
-  ActionHelpers &
-  EventConsumer<EventMap & EventMapCore<State>> &
-  PrivateValueStore<[ParamList, RouteName, EventMap]>;
+} & PrivateValueStore<[ParamList, RouteName, EventMap, ActionHelpers]>;
 
 export type RouteProp<
-  ParamList extends ParamListBase,
-  RouteName extends keyof ParamList = KeyOf<ParamList>,
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList = KeyOf<ParamList>,
 > = Route<Extract<RouteName, string>, ParamList[RouteName]>;
 
 export type CompositeNavigationProp<
   A extends NavigationProp<ParamListBase, any, any, any, any>,
   B extends NavigationProp<ParamListBase, any, any, any, any>,
-> = Omit<A & B, keyof NavigationProp<any, any, any, any, any>> &
-  Omit<
-    NavigationProp<
-      /**
-       * Param list from both navigation objects needs to be combined
-       * For example, we should be able to navigate to screens in both A and B
-       */
-      (A extends NavigationHelpersCommon<infer T> ? T : never) &
-        (B extends NavigationHelpersCommon<infer U> ? U : never),
-      /**
-       * The route name should refer to the route name specified in the first type
-       * Ideally it should work for any of them, but it's not possible to infer that way
-       */
-      A extends NavigationProp<any, infer R> ? R : string,
-      /**
-       * The type of state should refer to the state specified in the first type
-       */
-      A extends NavigationProp<any, any, infer S> ? S : NavigationState,
-      /**
-       * Screen options should refer to the options specified in the first type
-       */
-      A extends NavigationProp<any, any, any, infer O> ? O : {},
-      /**
-       * Event consumer config should refer to the config specified in the first type
-       * This allows typechecking `addListener`/`removeListener`
-       */
-      A extends NavigationProp<any, any, any, any, infer E> ? E : {}
-    >,
-    'getParent'
-  > & {
-    getParent: A['getParent'] & B['getParent'];
-  };
+> = CompositeNavigationPropInternal<
+  A,
+  B,
+  /**
+   * Param list from both navigation objects needs to be combined
+   * For example, we should be able to navigate to screens in both A and B
+   */
+  ParamListOfNavigationProp<A> & ParamListOfNavigationProp<B>,
+  /**
+   * The route name should refer to the route name specified in the first type
+   */
+  RouteNameOfNavigationProp<A>,
+  /**
+   * Event map should refer to the config specified in the first type
+   */
+  EventMapOfNavigationProp<A>
+>;
+
+type CompositeNavigationPropInternal<
+  A extends NavigationProp<ParamListBase, any, any, any, any>,
+  B extends NavigationProp<ParamListBase, any, any, any, any>,
+  ParamList extends {},
+  RouteName extends keyof ParamList,
+  EventMap extends EventMapBase,
+> = // Action helpers are read from the private brand (4th slot) instead of
+  // `Omit<A & B, keyof NavigationProp>`, which had to walk the whole (possibly
+  // deeply composed) member set of `A & B` to drop the standard members.
+  ActionHelpersOfNavigationProp<A> &
+    ActionHelpersOfNavigationProp<B> &
+    // Intersect the brand-free base directly instead of `Omit`-ing `getParent`
+    // off a full `NavigationProp`, so we skip a mapped-type pass per composite.
+    NavigationPropBase<
+      ParamList,
+      RouteName,
+      StateOfNavigationProp<A>,
+      ScreenOptionsOfNavigationProp<A>,
+      EventMap
+    > & {
+      getParent: A['getParent'] & B['getParent'];
+    } & PrivateValueStore<
+      [
+        ParamList,
+        RouteName,
+        EventMap,
+        ActionHelpersOfNavigationProp<A> & ActionHelpersOfNavigationProp<B>,
+      ]
+    >;
+
+type PrivateValueOfNavigationProp<T> =
+  T extends PrivateValueStore<infer Value> ? Value : [never, unknown, {}, {}];
+
+type ParamListOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[0];
+
+type RouteNameOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[1];
+
+type ActionHelpersOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[3];
+
+type StateOfNavigationProp<T> = T extends {
+  getState: () => infer State extends NavigationState;
+}
+  ? State
+  : NavigationState;
+
+type ScreenOptionsOfNavigationProp<T> = T extends {
+  setOptions: (options: Partial<infer ScreenOptions>) => void;
+}
+  ? ScreenOptions
+  : {};
+
+type EventMapOfNavigationProp<T> = PrivateValueOfNavigationProp<T>[2];
 
 export type CompositeScreenProps<
-  A extends {
+  in out A extends {
     navigation: NavigationProp<ParamListBase, string, any, any, any>;
     route: RouteProp<ParamListBase>;
   },
-  B extends {
+  in out B extends {
     navigation: NavigationProp<ParamListBase, string, any, any, any>;
   },
 > = {
@@ -562,10 +640,10 @@ export type CompositeScreenProps<
 };
 
 export type ScreenLayoutArgs<
-  ParamList extends ParamListBase,
-  RouteName extends keyof ParamList,
-  ScreenOptions extends {},
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList,
+  in out ScreenOptions extends {},
+  in out Navigation,
 > = {
   route: RouteProp<ParamList, RouteName>;
   options: ScreenOptions;
@@ -575,9 +653,9 @@ export type ScreenLayoutArgs<
 };
 
 export type Descriptor<
-  ScreenOptions extends {},
-  Navigation extends NavigationProp<any, any, any, any, any>,
-  Route extends RouteProp<any, any>,
+  out ScreenOptions extends {},
+  out Navigation extends NavigationProp<ParamListBase, any, any, any, any>,
+  out Route extends RouteProp<any, any>,
 > = {
   /**
    * Render the component associated with this route.
@@ -601,8 +679,8 @@ export type Descriptor<
 };
 
 export type ScreenListeners<
-  State extends NavigationState,
-  EventMap extends EventMapBase,
+  in out State extends NavigationState,
+  in out EventMap extends EventMapBase,
 > = Partial<{
   [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
     EventMap & EventMapCore<State>,
@@ -629,16 +707,16 @@ export type RouteConfigComponent<
        * React component to render for this screen.
        */
       component: ScreenComponentType<ParamList, RouteName>;
-      getComponent?: never;
-      children?: never;
+      getComponent?: never | undefined;
+      children?: never | undefined;
     }
   | {
       /**
        * Lazily get a React component to render for this screen.
        */
       getComponent: () => ScreenComponentType<ParamList, RouteName>;
-      component?: never;
-      children?: never;
+      component?: never | undefined;
+      children?: never | undefined;
     }
   | {
       /**
@@ -648,24 +726,24 @@ export type RouteConfigComponent<
         route: RouteProp<ParamList, RouteName>;
         navigation: any;
       }) => React.ReactNode;
-      component?: never;
-      getComponent?: never;
+      component?: never | undefined;
+      getComponent?: never | undefined;
     };
 
 export type RouteConfigProps<
-  ParamList extends ParamListBase,
-  RouteName extends keyof ParamList,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out RouteName extends keyof ParamList,
+  in out State extends NavigationState,
+  in out ScreenOptions extends {},
+  in out EventMap extends EventMapBase,
+  in out Navigation,
 > = {
   /**
    * Optional key for this screen. This doesn't need to be unique.
    * If the key changes, existing screens with this name will be removed or reset.
    * Useful when we have some common screens and have conditional rendering.
    */
-  navigationKey?: string;
+  navigationKey?: string | undefined;
 
   /**
    * Route name of this screen.
@@ -676,31 +754,39 @@ export type RouteConfigProps<
    * Navigator options for this screen.
    */
   options?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList, RouteName>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: RouteProp<ParamList, RouteName>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Event listeners for this screen.
    */
   listeners?:
-    | ScreenListeners<State, EventMap>
-    | ((props: {
-        route: RouteProp<ParamList, RouteName>;
-        navigation: Navigation;
-      }) => ScreenListeners<State, EventMap>);
+    | (
+        | ScreenListeners<State, EventMap>
+        | ((props: {
+            route: RouteProp<ParamList, RouteName>;
+            navigation: Navigation;
+          }) => ScreenListeners<State, EventMap>)
+      )
+    | undefined;
 
   /**
    * Layout for this screen.
    * Useful for wrapping the screen with custom containers.
    * e.g. for styling, error boundaries, suspense, etc.
    */
-  layout?: (
-    props: ScreenLayoutArgs<ParamList, RouteName, ScreenOptions, Navigation>
-  ) => React.ReactElement;
+  layout?:
+    | ((
+        props: ScreenLayoutArgs<ParamList, RouteName, ScreenOptions, Navigation>
+      ) => React.ReactElement)
+    | undefined;
 
   /**
    * Function to return an unique ID for this screen.
@@ -708,16 +794,18 @@ export type RouteConfigProps<
    * For a given screen name, there will always be only one screen corresponding to an ID.
    * If `undefined` is returned, it acts same as no `getId` being specified.
    */
-  getId?: ({
-    params,
-  }: {
-    params: Readonly<ParamList[RouteName]>;
-  }) => string | undefined;
+  getId?:
+    | (({
+        params,
+      }: {
+        params: Readonly<ParamList[RouteName]>;
+      }) => string | undefined)
+    | undefined;
 
   /**
    * Initial params object for the route.
    */
-  initialParams?: Partial<ParamList[RouteName]>;
+  initialParams?: Partial<ParamList[RouteName]> | undefined;
 };
 
 export type RouteConfig<
@@ -738,43 +826,49 @@ export type RouteConfig<
   RouteConfigComponent<ParamList, RouteName>;
 
 export type RouteGroupConfig<
-  ParamList extends ParamListBase,
-  ScreenOptions extends {},
-  Navigation,
+  in out ParamList extends ParamListBase,
+  in out ScreenOptions extends {},
+  in out Navigation,
 > = {
   /**
    * Optional key for the screens in this group.
    * If the key changes, all existing screens in this group will be removed or reset.
    */
-  navigationKey?: string;
+  navigationKey?: string | undefined;
 
   /**
    * Navigator options for this screen.
    */
   screenOptions?:
-    | ScreenOptions
-    | ((props: {
-        route: RouteProp<ParamList, keyof ParamList>;
-        navigation: Navigation;
-        theme: Theme;
-      }) => ScreenOptions);
+    | (
+        | ScreenOptions
+        | ((props: {
+            route: RouteProp<ParamList, keyof ParamList>;
+            navigation: Navigation;
+            theme: Theme;
+          }) => ScreenOptions)
+      )
+    | undefined;
 
   /**
    * Layout for the screens inside the group.
    * This will override the `screenLayout` of parent group or navigator.
    */
   screenLayout?:
-    | ((
-        props: ScreenLayoutArgs<
-          ParamList,
-          keyof ParamList,
-          ScreenOptions,
-          Navigation
-        >
-      ) => React.ReactElement)
-    | {
-        // FIXME: TypeScript doesn't seem to infer `navigation` correctly without this
-      };
+    | (
+        | ((
+            props: ScreenLayoutArgs<
+              ParamList,
+              keyof ParamList,
+              ScreenOptions,
+              Navigation
+            >
+          ) => React.ReactElement)
+        | {
+            // FIXME: TypeScript doesn't seem to infer `navigation` correctly without this
+          }
+      )
+    | undefined;
 
   /**
    * Children React Elements to extract the route configuration from.
@@ -826,6 +920,31 @@ export type NavigationContainerEventMap = {
       stack: string | undefined;
     };
   };
+  /**
+   * Event that fires when an event is emitted.
+   * Only intended for debugging purposes, don't use it for app logic.
+   * This event will be emitted after all listeners have been called.
+   */
+  __unsafe_event__: {
+    data: {
+      /**
+       * The type of the event that was emitted.
+       */
+      type: string;
+      /**
+       * The data object passed when emitting the event.
+       */
+      data: unknown;
+      /**
+       * The key of the target route which received the event.
+       */
+      target: string | undefined;
+      /**
+       * Whether `event.preventDefault()` was called on this event.
+       */
+      defaultPrevented: boolean | undefined;
+    };
+  };
 };
 
 /**
@@ -894,7 +1013,12 @@ export type GenericNavigation<ParamList extends {}> = Omit<
 export type RouteForName<
   ParamList extends {},
   RouteName extends string,
-> = Extract<ParamListRoute<ParamList>, { name: RouteName }>;
+> = RouteForNameInternal<RouteName, ParamListRoute<ParamList>>;
+
+type RouteForNameInternal<
+  RouteName extends string,
+  Routes,
+> = string extends RouteName ? Routes : Extract<Routes, { name: RouteName }>;
 
 type ParamListRoute<ParamList extends {}> = {
   [RouteName in keyof ParamList]: NavigatorScreenParams<{}> extends ParamList[RouteName]
@@ -910,11 +1034,10 @@ type MaybeParamListRoute<ParamList extends {}> = ParamList extends ParamListBase
 
 type BasicNavigationComposite<
   Navigation extends NavigationProp<any, any, any, any, any>,
-  Parent,
-> =
-  Parent extends NavigationProp<any, any, any, any, any>
-    ? CompositeNavigationProp<Navigation, Parent>
-    : Navigation;
+  Parent extends NavigationProp<any, any, any, any, any> | undefined,
+> = Parent extends undefined
+  ? Navigation
+  : CompositeNavigationProp<Navigation, NonNullable<Parent>>;
 
 type BasicNavigationList<
   ParamList extends {},
@@ -926,11 +1049,13 @@ type BasicNavigationList<
       ? NotUndefined<ParamList[RouteName]> extends NavigatorScreenParams<
           infer T
         >
-        ? BasicNavigationList<
-            T,
-            ExcludedRouteNames,
-            NavigationProp<ParamList, RouteName>
-          >
+        ? keyof T extends ExcludedRouteNames
+          ? {}
+          : BasicNavigationList<
+              T,
+              ExcludedRouteNames,
+              NavigationProp<ParamList, RouteName>
+            >
         : {}
       : {}) &
       (RouteName extends ExcludedRouteNames
@@ -945,161 +1070,220 @@ type BasicNavigationList<
 >;
 
 export type NavigationListForNavigator<Navigator> =
-  Navigator extends TypedNavigator<infer Bag, any>
-    ? Bag['NavigationList']
-    : Navigator extends PrivateValueStore<[any, infer NavigationList, any]>
-      ? NavigationList
-      : {};
-
-export type NavigationListForNested<Navigator> = FlatType<
-  NavigationListForNestedInternal<Navigator> &
-    (Navigator extends TypedNavigator<infer Bag, any>
-      ? BasicNavigationList<
-          Bag['ParamList'],
-          keyof NavigationListForNestedInternal<Navigator>,
-          undefined
-        >
-      : Navigator extends PrivateValueStore<[infer ParamList, any, any]>
-        ? ParamList extends {}
-          ? BasicNavigationList<
-              ParamList,
-              keyof NavigationListForNestedInternal<Navigator>,
-              undefined
-            >
-          : {}
-        : {})
->;
-
-type NavigationListForNestedInternal<Navigator> =
-  NavigationListForNavigator<Navigator> &
-    NavigationListForStaticConfig<
-      NavigationListForNavigator<Navigator>,
-      Navigator
-    >;
-
-type NavigationListWithComposite<
-  Parent extends NavigationProp<any, any, any, any, any>,
-  NavigatorList extends Record<string, any>,
-> = {
-  [K in keyof NavigatorList]: CompositeNavigationProp<NavigatorList[K], Parent>;
-};
-
-type NavigationListForStaticConfig<ParentList, Navigator> = Navigator extends {
+  Navigator extends PrivateValueStore<infer Value> ? Value[1] : {};
+
+export type NavigationListForNested<Navigator> =
+  NavigationListForNestedInternal<Navigator> extends infer NavigationList
+    ? Navigator extends PrivateValueStore<[infer ParamList, any, any, any]>
+      ? ParamList extends {}
+        ? NavigationList &
+            BasicNavigationList<ParamList, keyof NavigationList, undefined>
+        : NavigationList
+      : NavigationList
+    : never;
+
+type NavigationListForNestedInternal<
+  Navigator,
+  Parent = undefined,
+  NavigatorList extends Record<string, any> =
+    NavigationListForNavigator<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 {
   readonly config: {
-    screens?: any;
-    groups?: any;
+    readonly screens?: infer Screens;
+    readonly groups?: infer Groups;
   };
 }
-  ? NavigationListForScreens<ParentList, Navigator['config']['screens']> &
-      NavigationListForGroups<ParentList, Navigator['config']['groups']>
+  ? ComposedList &
+      NavigationListForScreens<ComposedList, Screens> &
+      NavigationListForGroups<ComposedList, Groups>
+  : ComposedList;
+
+// 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
+// common shallow case doesn't pay for a redundant mapped type.
+type ComposeNavigationList<NavigatorList extends Record<string, any>, Parent> =
+  Parent extends NavigationProp<any, any, any, any, any>
+    ? {
+        [K in keyof NavigatorList]: CompositeNavigationProp<
+          NavigatorList[K],
+          Parent
+        >;
+      }
+    : NavigatorList;
+
+type NavigationListForScreens<ParentList, Screens> = Screens extends {}
+  ? UnionToIntersection<
+      {
+        // Only check screens with static config to avoid overly-complex types
+        // Otherwise TypeScript fails to load the types due to complexity
+        [K in keyof Screens]: Screens[K] extends { config: any }
+          ? K extends keyof ParentList
+            ? NavigationListForNestedInternal<Screens[K], ParentList[K]>
+            : never
+          : Screens[K] extends { screen: { config: any } }
+            ? K extends keyof ParentList
+              ? NavigationListForNestedInternal<
+                  Screens[K]['screen'],
+                  ParentList[K]
+                >
+              : never
+            : never;
+      }[keyof Screens]
+    >
   : {};
 
-type NavigationListForScreens<ParentList, Screens> = UnionToIntersection<
-  {
-    // Only check screens with static config to avoid overly-complex types
-    // Otherwise TypeScript fails to load the types due to complexity
-    [K in keyof Screens]: ParentList extends Record<K, any>
-      ? Screens[K] extends { config: any }
-        ? NavigationListWithComposite<
-            ParentList[K],
-            NavigationListForNested<Screens[K]>
-          >
-        : Screens[K] extends { screen: { config: any } }
-          ? NavigationListWithComposite<
-              ParentList[K],
-              NavigationListForNested<Screens[K]['screen']>
-            >
-          : {}
-      : {};
-  }[keyof Screens]
->;
-
-type NavigationListForGroups<ParentList, Groups> =
-  Groups extends Record<string, { screens: any }>
-    ? UnionToIntersection<
-        {
-          [K in keyof Groups]: NavigationListForScreens<
-            ParentList,
-            Groups[K]['screens']
-          >;
-        }[keyof Groups]
-      >
-    : {};
+type NavigationListForGroups<ParentList, Groups> = Groups extends {}
+  ? UnionToIntersection<
+      {
+        [K in keyof Groups]: Groups[K] extends { screens: any }
+          ? NavigationListForScreens<ParentList, Groups[K]['screens']>
+          : never;
+      }[keyof Groups]
+    >
+  : {};
 
-export type NavigationContainerRef<ParamList extends {}> =
-  NavigationHelpers<ParamList> &
-    EventConsumer<NavigationContainerEventMap> & {
-      /**
-       * Reset the navigation state of the root navigator to the provided state.
-       *
-       * @param state Navigation state object.
-       */
-      resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
-      /**
-       * Get the rehydrated navigation state of the navigation tree.
-       */
-      getRootState(): NavigationState;
-      /**
-       * Get the currently focused navigation route.
-       */
-      getCurrentRoute(): MaybeParamListRoute<ParamList> | undefined;
-      /**
-       * Get the currently focused route's options.
-       */
-      getCurrentOptions(): object | undefined;
-      /**
-       * 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 NavigationContainerRef<ParamList extends {}> = Omit<
+  NavigationHelpers<ParamList>,
+  keyof NavigationHelpersRoute<{}>
+> &
+  NavigationHelpersRoute<{}> &
+  EventConsumer<NavigationContainerEventMap> & {
+    /**
+     * Reset the navigation state of the root navigator to the provided state.
+     *
+     * @param state Navigation state object.
+     */
+    resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
+    /**
+     * Get the rehydrated navigation state of the navigation tree.
+     */
+    getRootState(): NavigationState;
+    /**
+     * Get the currently focused navigation route.
+     */
+    getCurrentRoute(): MaybeParamListRoute<ParamList> | undefined;
+    /**
+     * Get the currently focused route's options.
+     */
+    getCurrentOptions(): object | undefined;
+    /**
+     * Whether the navigation container is ready to handle actions.
+     */
+    isReady(): boolean;
+    /**
+     * Stub function for setOptions on navigation object for use with useNavigation.
+     */
+    setOptions(): never;
+  };
 
 export type NavigationContainerRefWithCurrent<ParamList extends {}> =
   NavigationContainerRef<ParamList> & {
     current: NavigationContainerRef<ParamList> | null;
   };
 
-export type NavigationListBase<ParamList extends ParamListBase> = {
+export type NavigationListBase<in out ParamList extends ParamListBase> = {
   [RouteName in keyof ParamList]: unknown;
 };
 
-export type NavigatorTypeBagBase = {
+// Only use action helpers if all values are functions
+type ActionHelpersOf<T> =
+  T extends Record<string, (...args: any) => void> ? T : {};
+
+export interface NavigatorTypeBagBase {
   ParamList: {};
   State: NavigationState;
   ScreenOptions: {};
   EventMap: {};
-  NavigationList: NavigationListBase<ParamListBase>;
+  ActionHelpers: {};
+  NavigationList: {
+    [RouteName in keyof this['ParamList']]: NavigationProp<
+      this['ParamList'],
+      RouteName,
+      this['State'],
+      this['ScreenOptions'],
+      this['EventMap'],
+      ActionHelpersOf<this['ActionHelpers']>
+    >;
+  };
   Navigator: React.ComponentType<any>;
+}
+
+/**
+ * Adds a proper `ParamList` to a type bag interface
+ * So it can be used as `this['ParamList']`
+ */
+export type NavigatorTypeBagFor<
+  TypeBag extends NavigatorTypeBagBase,
+  ParamList extends {},
+> = TypeBag & { ParamList: ParamList };
+
+type TypedNavigatorComponent<Bag extends NavigatorTypeBagBase> =
+  React.ComponentType<
+    Omit<
+      React.ComponentProps<
+        TypedNavigatorInternal<
+          Bag['ParamList'],
+          Bag['State'],
+          Bag['ScreenOptions'],
+          Bag['EventMap'],
+          Bag['NavigationList'],
+          Bag['Navigator']
+        >['Navigator']
+      >,
+      'children'
+    >
+  >;
+
+type TypedNavigatorStaticDecorated<Bag extends NavigatorTypeBagBase, Config> = {
+  getComponent: () => React.ComponentType<{}>;
+  config: Config;
+} & PrivateValueStore<
+  [Bag['ParamList'], Bag['NavigationList'], unknown, unknown]
+>;
+
+type TypedNavigatorStatic<
+  in out Bag extends NavigatorTypeBagBase,
+  in out Config,
+> = {
+  config: Config;
+  with: (
+    Component: React.ComponentType<{
+      Navigator: TypedNavigatorComponent<Bag>;
+    }>
+  ) => TypedNavigatorStaticDecorated<Bag, Config>;
+  getComponent: () => TypedNavigatorComponent<Bag>;
 };
 
 export type TypedNavigator<
   Bag extends NavigatorTypeBagBase,
   Config = unknown,
-> = TypedNavigatorInternal<
-  Bag['ParamList'],
-  Bag['State'],
-  Bag['ScreenOptions'],
-  Bag['EventMap'],
-  Bag['NavigationList'],
-  Bag['Navigator']
-> &
-  (undefined extends Config ? {} : { config: Config }) &
-  PrivateValueStore<[Bag['ParamList'], Bag['NavigationList'], unknown]>;
+> = (undefined extends Config
+  ? TypedNavigatorInternal<
+      Bag['ParamList'],
+      Bag['State'],
+      Bag['ScreenOptions'],
+      Bag['EventMap'],
+      Bag['NavigationList'],
+      Bag['Navigator']
+    >
+  : TypedNavigatorStatic<Bag, Config>) &
+  PrivateValueStore<
+    [Bag['ParamList'], Bag['NavigationList'], unknown, unknown]
+  >;
 
 type TypedNavigatorInternal<
-  ParamList extends ParamListBase,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  NavigationList extends NavigationListBase<ParamList>,
-  Navigator extends React.ComponentType<any>,
+  in out ParamList extends ParamListBase,
+  in out State extends NavigationState,
+  in out ScreenOptions extends {},
+  in out EventMap extends EventMapBase,
+  in out NavigationList extends NavigationListBase<ParamList>,
+  in out Navigator extends React.ComponentType<any>,
 > = {
   /**
    * Navigator component which manages the child screens.
@@ -1145,33 +1329,38 @@ export type NavigatorScreenParams<ParamList extends {}> =
       merge?: never;
       initial?: never;
       pop?: never;
-      path?: string;
+      preload?: never;
+      path?: string | undefined;
       state: PartialState<NavigationState> | NavigationState | undefined;
     }
   | {
       [RouteName in keyof ParamList]: undefined extends ParamList[RouteName]
         ? {
             screen: RouteName;
-            params?: ParamList[RouteName];
-            merge?: boolean;
-            initial?: boolean;
-            path?: string;
-            pop?: boolean;
+            params?: ParamList[RouteName] | undefined;
+            merge?: boolean | undefined;
+            initial?: boolean | undefined;
+            path?: string | undefined;
+            pop?: boolean | undefined;
+            preload?: boolean | undefined;
             state?: never;
           }
         : {
             screen: RouteName;
             params: ParamList[RouteName];
-            merge?: boolean;
-            initial?: boolean;
-            path?: string;
-            pop?: boolean;
+            merge?: boolean | undefined;
+            initial?: boolean | undefined;
+            path?: string | undefined;
+            pop?: boolean | undefined;
+            preload?: boolean | undefined;
             state?: never;
           };
     }[keyof ParamList];
 
 type ParseConfig<Params> = {
-  [K in keyof Params]?: (value: string) => Params[K];
+  [K in keyof Params]?:
+    | ((value: string) => Params[K])
+    | StandardSchemaV1<string | string[] | null | undefined, Params[K]>;
 };
 
 type StringifyConfig<Params> = {
@@ -1189,9 +1378,9 @@ type PathConfigAlias<Params> = {
    * By default, paths are relating to the path config on the parent screen.
    * If `exact` is set to `true`, the parent path configuration is not used.
    */
-  exact?: boolean;
+  exact?: boolean | undefined;
   /**
-   * An object mapping the param name to a function which parses the param value.
+   * An object mapping the param name to a parser function or a Standard Schema.
    *
    * @example
    * ```js
@@ -1201,7 +1390,18 @@ type PathConfigAlias<Params> = {
    * }
    * ```
    */
-  parse?: ParseConfig<Params>;
+  parse?: ParseConfig<Params> | undefined;
+  /**
+   * Whether this path can resolve to multiple routes.
+   * Both routes should specify `shared: true` for this to work.
+   * By default, a path can only resolve to one route.
+   *
+   * This is useful when same screen used in multiple navigators,
+   * e.g. tabs with stacks containing profile screen in each stack.
+   *
+   * The path defined first will be the canonical path.
+   */
+  shared?: boolean | undefined;
 };
 
 export type PathConfig<Params> = FlatType<
@@ -1218,25 +1418,28 @@ export type PathConfig<Params> = FlatType<
      * }
      * ```
      */
-    stringify?: StringifyConfig<Params>;
+    stringify?: StringifyConfig<Params> | undefined;
     /**
      * Additional path alias that will be matched to the same screen.
      */
-    alias?: (string | PathConfigAlias<Params>)[];
+    alias?: (string | PathConfigAlias<Params>)[] | undefined;
   } & (NonNullable<Params> extends NavigatorScreenParams<infer ParamList>
       ? {
           /**
            * Path configuration for child screens.
            */
-          screens?: PathConfigMap<ParamList>;
+          screens?: PathConfigMap<ParamList> | undefined;
           /**
            * Name of the initial route to use for the navigator when the path matches.
            */
-          initialRouteName?: keyof ParamList;
+          initialRouteName?: Extract<keyof ParamList, string> | undefined;
         }
       : {})
 >;
 
 export type PathConfigMap<ParamList extends {}> = {
-  [RouteName in keyof ParamList]?: string | PathConfig<ParamList[RouteName]>;
+  [RouteName in keyof ParamList]?:
+    | string
+    | PathConfig<ParamList[RouteName]>
+    | undefined;
 };