@react-navigation/core 8.0.0-alpha.3 → 8.0.0-alpha.31

package/src/StaticNavigation.tsx

@@ -6,12 +6,19 @@ import type {
 import * as React from 'react';
 import { isValidElementType } from 'react-is';
 
+import {
+  combinePatternParts,
+  getPatternParts,
+  type PatternPart,
+} from './getPatternParts';
+import { StaticTreeContext } from './StaticTreeContext';
 import type {
-  DefaultNavigatorOptions,
   EventMapBase,
   NavigationListBase,
+  NavigatorProps,
   NavigatorScreenParams,
   NavigatorTypeBagBase,
+  NavigatorTypeBagFor,
   PathConfig,
   PathConfigMap,
   RouteGroupConfig,
@@ -21,68 +28,107 @@ import type {
 import { useRoute } from './useRoute';
 import type {
   AnyToUnknown,
-  ExtractParamStrings,
-  ExtractParamsType,
   FlatType,
   HasArguments,
-  InferParse,
-  InferPath,
+  InferParamsFromLinking,
   KeysOf,
+  NoExcessCallbackReturn,
+  NoExcessObject,
+  NoExcessValue,
+  NotUndefinedObject,
+  StandardSchemaV1,
   UnionToIntersection,
   ValidPathPattern,
 } from './utilities';
 
-type ParamsForScreenComponent<T> = T extends (...args: any[]) => any
-  ? HasArguments<T> extends true
-    ? T extends React.ComponentType<{ route: { params: infer Params } }>
-      ? Params
-      : undefined
+type ScreenComponentParams<T> = [T] extends [
+  React.ComponentType<{ route: { params: infer Params } }>,
+]
+  ? Params
+  : undefined;
+
+type ParamsForScreenComponent<T> = [T] extends [(...args: any[]) => any]
+  ? // Don't infer params from a parameterless function component
+    // It'd infer `unknown` - but we want `undefined` if no params are accepted
+    HasArguments<T> extends true
+    ? ScreenComponentParams<T>
     : undefined
-  : T extends React.ComponentType<{ route: { params: infer Params } }>
-    ? Params
+  : ScreenComponentParams<T>;
+
+// If the initial route's params include `undefined`, the nested navigator itself can be optional.
+// If no initial route is specified, check if every nested route's params include `undefined`.
+// Otherwise the nested navigator needs to be required.
+type ParamsForNestedNavigator<
+  T extends { config: any },
+  ParamList extends {} = StaticParamList<T>,
+  Params = NavigatorScreenParams<ParamList>,
+  RouteNames extends keyof ParamList = T['config'] extends {
+    initialRouteName: infer RouteName extends keyof ParamList;
+  }
+    ? RouteName
+    : keyof ParamList,
+> = {
+  [RouteName in RouteNames]-?: undefined extends ParamList[RouteName]
+    ? never
+    : RouteName;
+}[RouteNames] extends never
+  ? Params | undefined
+  : Params;
+
+// If the screens were constructed from a `Record<K, V>`,
+// the screen value (`T`) may be a union.
+// A naked `T extends ...` conditional would distribute over every screen in the union,
+// creating a large params union per route.
+// Wrapping `T` in a tuple checks the union as a whole instead of distributing,
+// https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+type ParamsForScreen<T> = [T] extends [{ config: any }]
+  ? ParamsForNestedNavigator<T>
+  : [T] extends [React.ComponentType<any>]
+    ? ParamsForScreenComponent<T>
     : undefined;
 
-type ParamsForScreen<T> =
-  // Nested navigator in screen property
-  T extends { screen: StaticNavigation<any, any, any> }
-    ? NavigatorScreenParams<StaticParamList<T['screen']>> | undefined
-    : // Direct nested navigator
-      T extends StaticNavigation<any, any, any>
-      ? NavigatorScreenParams<StaticParamList<T>> | undefined
-      : T extends {
-            screen: React.ComponentType<any>;
-          }
-        ? ParamsForScreenComponent<T['screen']>
-        : ParamsForScreenComponent<T>;
-
-type ParamsForLinking<Linking> = Linking extends { path: string }
-  ? ExtractParamsType<
-      ExtractParamStrings<InferPath<Linking>>,
-      InferParse<Linking>
-    >
-  : Linking extends string
-    ? ExtractParamsType<ExtractParamStrings<Linking>, undefined>
-    : undefined;
+// Unlike `ParamsForScreen`, we want to distribute for `Record<string, Component | StaticNavigation>`
+// This creates union like:
+// `C extends C ? ParamsForScreen<C> : never) | (S extends S ? ParamsForScreen<S> : never)`
+// `= ParamsForScreen<C> | ParamsForScreen<S>`
+type ParamsForScreenEntry<T> = T extends T ? ParamsForScreen<T> : never;
+
+// Only infer params from linking if it's a pattern (i.e., contains ':')
+// or if parse is present, which can also define query params.
+// This avoids inferring non-literals like 'string' without parse.
+type ShouldInferFromLinking<Linking> = Linking extends {
+  parse: Record<string, unknown>;
+}
+  ? true
+  : Linking extends ValidPathPattern | { path: ValidPathPattern }
+    ? true
+    : false;
 
 /**
- * Inferred params type based on both linking config and screen.
- * - When linking is undefined: infers params from screen
- * - When screen is a nested navigator: merges path params with navigator screen params
- * - Otherwise: merges path params with screen component params
+ * Params type derived from both linking and screen.
+ *
+ * - Linking has no extractable params (no ':' in path, no `parse`): returns
+ *   screen params alone.
+ * - Linking has params + screen is a nested navigator: intersects path params
+ *   with the navigator's screen params.
+ * - Linking has params + screen is a component without route params: returns
+ *   path params alone (avoids `LP & undefined = never`).
+ * - Linking has params + screen has route params: intersects them.
  */
-type ParamsForConfig<Linking, Screen> = undefined extends Linking
-  ? ParamsForScreen<Screen>
-  : // Only infer params from linking if it's a pattern (i.e., contains ':')
-    // This avoids inferring non-literals like 'string'
-    Linking extends ValidPathPattern | { path: ValidPathPattern }
-    ? Screen extends StaticNavigation<any, any, any>
-      ? FlatType<ParamsForLinking<Linking>> & ParamsForScreen<Screen>
-      : // Don't combine if `undefined`, otherwise it'll result in `never`
-        undefined extends ParamsForScreen<Screen>
-        ? // Only flatten when not a navigator to keep it legible
-          FlatType<ParamsForLinking<Linking>>
-        : FlatType<ParamsForLinking<Linking> & ParamsForScreen<Screen>>
-    : ParamsForScreen<Screen>;
+type ParamsForConfig<Linking, Screen, Params = ParamsForScreen<Screen>> =
+  ShouldInferFromLinking<Linking> extends true
+    ? [Screen] extends [{ config: any }]
+      ? undefined extends Params
+        ? FlatType<InferParamsFromLinking<Linking>> & Params
+        : // Optional linking params make the whole route params type optional when intersected.
+          // e.g. `({...} | undefined) & NavigatorScreenParams<{...}>` adds `| undefined` to the whole type.
+          // But if nested navigator had required params, it should still be required.
+          // So we remove `| undefined` from linking params before intersecting with nested navigator params.
+          FlatType<NotUndefinedObject<InferParamsFromLinking<Linking>>> & Params
+      : undefined extends Params
+        ? FlatType<InferParamsFromLinking<Linking>>
+        : FlatType<InferParamsFromLinking<Linking> & Params>
+    : Params;
 
 type ParamListForScreens<Screens> = {
   [Key in KeysOf<Screens>]: Screens[Key] extends StaticScreenConfig<
@@ -91,21 +137,16 @@ type ParamListForScreens<Screens> = {
     any,
     any,
     any,
+    any,
+    any,
+    any,
     any
   >
     ? ParamsForConfig<Linking, Screen>
-    : ParamsForScreen<Screens[Key]>;
+    : ParamsForScreenEntry<Screens[Key]>;
 };
 
-type ParamListForGroups<
-  Groups extends
-    | Readonly<{
-        [key: string]: {
-          screens: {};
-        };
-      }>
-    | undefined,
-> = Groups extends {
+type ParamListForGroups<Groups> = Groups extends {
   [key: string]: {
     screens: infer Screens;
   };
@@ -113,26 +154,22 @@ type ParamListForGroups<
   ? ParamListForScreens<UnionToIntersection<Screens>>
   : {};
 
-type RouteType<Params> = Readonly<
-  FlatType<
-    Omit<Route<string, AnyToUnknown<Params>>, 'params'> &
-      Readonly<
-        undefined extends Params
-          ? {
-              /**
-               * Params for this route
-               */
-              params?: AnyToUnknown<Params>;
-            }
-          : {
-              /**
-               * Params for this route
-               */
-              params: AnyToUnknown<Params>;
-            }
-      >
-  >
->;
+type StaticRouteBase = Readonly<Omit<Route<string>, 'params'>>;
+
+type StaticRoute<Params, P = AnyToUnknown<Params>> = StaticRouteBase &
+  (undefined extends Params
+    ? {
+        /**
+         * Params for this route
+         */
+        readonly params?: P extends object ? Readonly<P> : P;
+      }
+    : {
+        /**
+         * Params for this route
+         */
+        readonly params: Readonly<P>;
+      });
 
 type StaticScreenConfigLinkingAlias = {
   /**
@@ -147,7 +184,7 @@ type StaticScreenConfigLinkingAlias = {
    */
   exact?: boolean;
   /**
-   * 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
@@ -157,10 +194,14 @@ type StaticScreenConfigLinkingAlias = {
    * }
    * ```
    */
-  parse?: Record<string, (value: string) => unknown>;
+  parse?: Record<
+    string,
+    | ((value: string) => unknown)
+    | StandardSchemaV1<string | string[] | null | undefined, unknown>
+  >;
   /**
    * 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)`.
+   * By default, arrays and null are preserved for query params, and other values are converted using `String(value)`.
    *
    * @example
    * ```js
@@ -170,31 +211,60 @@ type StaticScreenConfigLinkingAlias = {
    * ```
    */
   stringify?: Record<string, (value: unknown) => string>;
+  /**
+   * Whether this path can resolve to multiple routes.
+   * Both routes should specify `shared: true` for this to work.
+   *
+   * When automatic path generation is enabled,
+   * screens using the same path pattern and the same screen component
+   * or navigator will be automatically marked as shared.
+   * Explicitly specifying the option overrides the automatic detection.
+   *
+   * 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;
+};
+
+type StaticScreenConfigLinkingExtras = {
+  /**
+   * Additional path alias that will be matched to the same screen.
+   */
+  alias?: (string | StaticScreenConfigLinkingAlias)[];
+  /**
+   * Name of the initial route to use for the nested navigator when the path matches.
+   */
+  initialRouteName?: string | undefined;
+  /**
+   * Path configuration for child screens in the nested navigator.
+   * Only supported when the screen renders a navigator with dynamic API.
+   */
+  screens?: PathConfigMap<ParamListBase> | undefined;
 };
 
 export type StaticScreenConfigLinking =
   | string
-  | (StaticScreenConfigLinkingAlias & {
-      /**
-       * Additional path alias that will be matched to the same screen.
-       */
-      alias?: (string | StaticScreenConfigLinkingAlias)[];
-    })
+  | (StaticScreenConfigLinkingAlias & StaticScreenConfigLinkingExtras)
+  | null
   | undefined;
 
 export type StaticScreenConfigScreen =
   | React.ComponentType<any>
-  | StaticNavigation<any, any, any>;
-
-export type StaticScreenConfig<
-  Linking extends StaticScreenConfigLinking,
-  Screen,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  Navigation,
-  Params = ParamsForConfig<Linking, Screen>,
-> = {
+  | StaticNavigation<any>;
+
+export interface StaticScreenConfig<
+  out Linking extends StaticScreenConfigLinking,
+  out Screen,
+  in out State extends NavigationState,
+  in out ScreenOptions extends {},
+  in out EventMap extends EventMapBase,
+  in out Navigation,
+  in out Params = ParamsForConfig<Linking, Screen>,
+  in out ProvidedOptions extends {} = {},
+  in out ProvidedListeners extends {} = {},
+> {
   /**
    * Static navigation config or Component to render for the screen.
    */
@@ -228,10 +298,10 @@ export type StaticScreenConfig<
   options?:
     | ScreenOptions
     | ((props: {
-        route: RouteType<Params>;
+        route: StaticRoute<Params>;
         navigation: Navigation;
         theme: Theme;
-      }) => ScreenOptions);
+      }) => NoExcessCallbackReturn<ProvidedOptions, ScreenOptions>);
 
   /**
    * Event listeners for this screen.
@@ -248,9 +318,12 @@ export type StaticScreenConfig<
   listeners?:
     | ScreenListeners<State, EventMap>
     | ((props: {
-        route: RouteType<Params>;
+        route: StaticRoute<Params>;
         navigation: Navigation;
-      }) => ScreenListeners<State, EventMap>);
+      }) => NoExcessCallbackReturn<
+        ProvidedListeners,
+        ScreenListeners<State, EventMap>
+      >);
 
   /**
    * Layout for this screen.
@@ -268,7 +341,7 @@ export type StaticScreenConfig<
    *
    */
   layout?: (props: {
-    route: RouteType<Params>;
+    route: StaticRoute<Params>;
     options: ScreenOptions;
     navigation: Navigation;
     theme: Theme;
@@ -295,7 +368,9 @@ export type StaticScreenConfig<
    * getId: ({ params }) => params?.userId,
    * ```
    */
-  getId?: (props: { params: AnyToUnknown<Params> }) => string | undefined;
+  getId?: (props: {
+    params: AnyToUnknown<Params extends object ? Readonly<Params> : Params>;
+  }) => string | undefined;
 
   /**
    * Linking config for the screen.
@@ -317,31 +392,75 @@ export type StaticScreenConfig<
    * Optional key for this screen.
    */
   navigationKey?: string;
-};
+
+  /**
+   * Loader function to start loading data when the screen is navigated to.
+   *
+   * @example
+   * ```js
+   * UNSTABLE_loader: ({ params }) => loadProfile(params.id),
+   * ```
+   */
+  UNSTABLE_loader?: (options: {
+    name: string;
+    params: AnyToUnknown<Params>;
+  }) => Promise<void>;
+}
+
+export type StaticScreenFactory<in out Bag extends NavigatorTypeBagBase> = <
+  const Linking extends StaticScreenConfigLinking,
+  const Screen extends StaticScreenConfigScreen,
+  ProvidedOptions extends {} = {},
+  ProvidedListeners extends {} = {},
+>(
+  config: StaticScreenConfig<
+    Linking,
+    Screen,
+    Bag['State'],
+    Bag['ScreenOptions'],
+    Bag['EventMap'],
+    Bag['NavigationList'][keyof Bag['ParamList']],
+    ParamsForConfig<Linking, Screen>,
+    ProvidedOptions,
+    ProvidedListeners
+  >
+) => StaticScreenConfig<
+  Linking,
+  Screen,
+  Bag['State'],
+  Bag['ScreenOptions'],
+  Bag['EventMap'],
+  Bag['NavigationList'][keyof Bag['ParamList']]
+>;
+
+/**
+ * Helper to create a typed `createXScreen` for static configuration.
+ */
+export function createScreenFactory<
+  TypeBag extends NavigatorTypeBagBase,
+>(): StaticScreenFactory<NavigatorTypeBagFor<TypeBag, ParamListBase>> {
+  return ((config: unknown) => config) as never;
+}
 
 type StaticConfigScreens<
-  ParamList extends ParamListBase,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  NavigationList extends NavigationListBase<ParamList>,
+  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>,
 > = {
   [RouteName in keyof ParamList]:
-    | React.ComponentType<any>
-    | StaticNavigation<any, any, any>
+    | StaticScreenConfigScreen
     | StaticScreenConfig<
-        | {
-            path: string;
-            parse?: Record<string, (value: string) => any>;
-          }
-        | string
-        | undefined,
-        StaticNavigation<any, any, any> | React.ComponentType<any>,
+        StaticScreenConfigLinking,
+        StaticScreenConfigScreen,
         State,
         ScreenOptions,
         EventMap,
         NavigationList[RouteName],
-        any
+        any,
+        {},
+        {}
       >;
 };
 
@@ -360,27 +479,6 @@ type StaticConfigGroup<
    * This can be useful for conditional rendering of group of screens.
    */
   if?: () => boolean;
-  /**
-   * Linking config for the screens in the group.
-   * This can be a string to specify the path, or an object following properties:
-   * - `path`
-   * - `stringify`
-   * - `parse`
-   *
-   * The path specified will be prepended to the paths of the screens in the group.
-   * The `parse` and `stringify` properties will be merged.
-   *
-   * @example
-   * ```js
-   * linking: {
-   *   path: 'users/:id',
-   *   parse: {
-   *     id: (id) => parseInt(id, 10),
-   *   }
-   * },
-   * ```
-   */
-  linking?: LinkingForGroup;
   /**
    * Static navigation config or Component to render for the screen.
    */
@@ -393,101 +491,160 @@ type StaticConfigGroup<
   >;
 };
 
-export type StaticConfig<Bag extends NavigatorTypeBagBase> =
-  StaticConfigInternal<
+type StaticConfigScreensForBag<Bag extends NavigatorTypeBagBase> =
+  StaticConfigScreens<
     Bag['ParamList'],
     Bag['State'],
     Bag['ScreenOptions'],
     Bag['EventMap'],
-    Bag['NavigationList'],
-    Bag['Navigator']
+    Bag['NavigationList']
   >;
 
-type StaticConfigInternal<
-  ParamList extends ParamListBase,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  NavigationList extends NavigationListBase<ParamList>,
-  Navigator extends React.ComponentType<any>,
-> = Omit<
-  Omit<
-    React.ComponentProps<Navigator>,
-    keyof DefaultNavigatorOptions<
-      ParamListBase,
-      NavigationState,
-      {},
-      EventMapBase,
-      NavigationList[keyof ParamList]
-    >
-  > &
-    DefaultNavigatorOptions<
-      ParamList,
-      State,
-      ScreenOptions,
-      EventMap,
-      NavigationList[keyof ParamList]
-    >,
+type StaticConfigGroupsForBag<Bag extends NavigatorTypeBagBase> = {
+  [key: string]: StaticConfigGroup<
+    Bag['ParamList'],
+    Bag['State'],
+    Bag['ScreenOptions'],
+    Bag['EventMap'],
+    Bag['NavigationList']
+  >;
+};
+
+type StaticConfigCommon<Bag extends NavigatorTypeBagBase> = Omit<
+  NavigatorProps<
+    Bag['ParamList'],
+    Bag['State'],
+    Bag['ScreenOptions'],
+    Bag['EventMap'],
+    Bag['NavigationList'][keyof Bag['ParamList']],
+    Bag['Navigator']
+  >,
   'screens' | 'children'
-> &
+>;
+
+export type StaticConfigBase<
+  Bag extends NavigatorTypeBagBase,
+  Screens = StaticConfigScreensForBag<Bag>,
+  Groups = StaticConfigGroupsForBag<Bag>,
+> = StaticConfigCommon<Bag> & {
+  /**
+   * Screens to render in the navigator and their configuration.
+   */
+  screens?: Screens;
+  /**
+   * Groups of screens to render in the navigator and their configuration.
+   */
+  groups?: Groups;
+};
+
+export type StaticConfig<
+  Bag extends NavigatorTypeBagBase,
+  Screens = StaticConfigScreensForBag<Bag>,
+  Groups = StaticConfigGroupsForBag<Bag>,
+> = StaticConfigCommon<Bag> &
   (
     | {
         /**
          * Screens to render in the navigator and their configuration.
          */
-        screens: StaticConfigScreens<
-          ParamList,
-          State,
-          ScreenOptions,
-          EventMap,
-          NavigationList
-        >;
+        screens: Screens;
         /**
          * Groups of screens to render in the navigator and their configuration.
          */
-        groups?: {
-          [key: string]: StaticConfigGroup<
-            ParamList,
-            State,
-            ScreenOptions,
-            EventMap,
-            NavigationList
-          >;
-        };
+        groups?: Groups;
       }
     | {
         /**
          * Screens to render in the navigator and their configuration.
          */
-        screens?: StaticConfigScreens<
-          ParamList,
-          State,
-          ScreenOptions,
-          EventMap,
-          NavigationList
-        >;
+        screens?: Screens;
         /**
          * Groups of screens to render in the navigator and their configuration.
          */
-        groups: {
-          [key: string]: StaticConfigGroup<
-            ParamList,
-            State,
-            ScreenOptions,
-            EventMap,
-            NavigationList
-          >;
-        };
+        groups: Groups;
       }
   );
 
+type NoExcessScreen<
+  Screen,
+  ScreenOptions extends {},
+  Listeners extends {},
+> = (Screen extends { screen: unknown; options: unknown }
+  ? { options: NoExcessValue<Screen['options'], ScreenOptions> }
+  : unknown) &
+  (Screen extends { screen: unknown; listeners: unknown }
+    ? { listeners: NoExcessValue<Screen['listeners'], Listeners> }
+    : unknown);
+
+type NoExcessScreens<
+  Screens,
+  ScreenOptions extends {},
+  Listeners extends {},
+> = {
+  [RouteName in keyof Screens]: NoExcessScreen<
+    Screens[RouteName],
+    ScreenOptions,
+    Listeners
+  >;
+};
+
+type NoExcessGroups<
+  Groups,
+  Bag extends NavigatorTypeBagBase,
+  ScreenOptions extends {},
+  Listeners extends {},
+> = {
+  [GroupName in keyof Groups]: NoExcessObject<
+    Groups[GroupName],
+    StaticConfigGroup<
+      ParamListBase,
+      NavigationState,
+      {},
+      EventMapBase,
+      NavigationListBase<ParamListBase>
+    >
+  > &
+    NoExcessStaticConfig<Groups[GroupName], Bag, ScreenOptions, Listeners>;
+};
+
+// Each property is probed with `Config extends { key: infer X }` and the results are intersected.
+// These conditionals stay deferred while the config is inferred, so they don't interfere with the inference.
+// Indexed access (`Config['screens']`) or a mapped type over the whole config breaks the param list inference.
+export type NoExcessStaticConfig<
+  Config,
+  Bag extends NavigatorTypeBagBase,
+  ScreenOptions extends {} = Bag['ScreenOptions'],
+  Listeners extends {} = ScreenListeners<Bag['State'], Bag['EventMap']>,
+> = (Config extends { screenOptions: infer ProvidedOptions }
+  ? {
+      screenOptions: NoExcessValue<ProvidedOptions, ScreenOptions>;
+    }
+  : unknown) &
+  (Config extends { screenListeners: infer ProvidedListeners }
+    ? {
+        screenListeners: NoExcessValue<ProvidedListeners, Listeners>;
+      }
+    : unknown) &
+  (Config extends { screens: infer Screens }
+    ? {
+        screens: NoExcessScreens<Screens, ScreenOptions, Listeners>;
+      }
+    : unknown) &
+  (Config extends { groups: infer Groups }
+    ? {
+        groups: NoExcessGroups<Groups, Bag, ScreenOptions, Listeners>;
+      }
+    : unknown);
+
 /**
  * Props for a screen component which is rendered by a static navigator.
  * Takes the route params as a generic argument.
  */
-export type StaticScreenProps<T extends Record<string, unknown> | undefined> = {
+export type StaticScreenProps<
+  in out T extends Record<string, unknown> | undefined,
+> = {
   route: {
-    params: T;
+    readonly params: T;
   };
 };
 
@@ -503,11 +660,11 @@ export type StaticParamList<
     ParamListForGroups<T['config']['groups']>
 >;
 
-export type StaticNavigation<NavigatorProps, GroupProps, ScreenProps> = {
-  Navigator: React.ComponentType<NavigatorProps>;
-  Group: React.ComponentType<GroupProps>;
-  Screen: React.ComponentType<ScreenProps>;
-  config: StaticConfig<NavigatorTypeBagBase>;
+export type StaticNavigation<
+  in out NavigatorTypeBag extends NavigatorTypeBagBase,
+> = {
+  config: StaticConfigBase<NavigatorTypeBag>;
+  getComponent: () => React.ComponentType<{}>;
 };
 
 const MemoizedScreen = React.memo(
@@ -542,16 +699,13 @@ const getItemsFromScreens = (
         component = screen;
       } else if ('config' in screen) {
         isNavigator = true;
-        component = createComponentForStaticNavigation(
-          screen,
-          `${name}Navigator`
-        );
+        component = screen.getComponent();
       }
     } else if (isValidElementType(item)) {
       component = item;
     } else if ('config' in item) {
       isNavigator = true;
-      component = createComponentForStaticNavigation(item, `${name}Navigator`);
+      component = item.getComponent();
     }
 
     if (component == null) {
@@ -589,10 +743,17 @@ const getItemsFromScreens = (
  * @param displayName Name of the component to be displayed in React DevTools.
  * @returns A component which renders the navigator.
  */
-export function createComponentForStaticNavigation(
-  tree: StaticNavigation<any, any, any>,
+export function createComponentForStaticConfig<
+  T extends {
+    Navigator: React.ComponentType<any>;
+    Group: React.ComponentType<any>;
+    Screen: React.ComponentType<any>;
+    config: StaticConfig<NavigatorTypeBagBase>;
+  },
+>(
+  tree: T,
   displayName: string
-): React.ComponentType<{}> {
+): React.ComponentType<Omit<React.ComponentProps<T['Navigator']>, 'children'>> {
   const { Navigator, Group, Screen, config } = tree;
   const { screens, groups, ...rest } = config;
 
@@ -637,10 +798,53 @@ export function createComponentForStaticNavigation(
     }
   }
 
-  const NavigatorComponent = () => {
+  if (items.length === 0) {
+    throw new Error(
+      "Couldn't find any screens in the 'screens' or 'groups' property. Make sure to define at least one screen in the configuration."
+    );
+  }
+
+  const NavigatorComponent = ({ children: _, ...props }: typeof rest) => {
     const children = items.map((item) => item());
 
-    return <Navigator {...rest}>{children}</Navigator>;
+    const screenOptions =
+      typeof props.screenOptions === 'function' ||
+      typeof rest.screenOptions === 'function'
+        ? (options: unknown) => ({
+            ...(typeof rest.screenOptions === 'function'
+              ? rest.screenOptions(options)
+              : rest.screenOptions),
+            ...(typeof props.screenOptions === 'function'
+              ? props.screenOptions(options)
+              : props.screenOptions),
+          })
+        : { ...rest.screenOptions, ...props.screenOptions };
+
+    const screenListeners =
+      typeof props.screenListeners === 'function' ||
+      typeof rest.screenListeners === 'function'
+        ? (options: unknown) => ({
+            ...(typeof rest.screenListeners === 'function'
+              ? rest.screenListeners(options)
+              : rest.screenListeners),
+            ...(typeof props.screenListeners === 'function'
+              ? props.screenListeners(options)
+              : props.screenListeners),
+          })
+        : { ...rest.screenListeners, ...props.screenListeners };
+
+    return (
+      <StaticTreeContext.Provider value={tree}>
+        <Navigator
+          {...rest}
+          {...props}
+          screenOptions={screenOptions}
+          screenListeners={screenListeners}
+        >
+          {children}
+        </Navigator>
+      </StaticTreeContext.Provider>
+    );
   };
 
   NavigatorComponent.displayName = displayName;
@@ -648,33 +852,111 @@ export function createComponentForStaticNavigation(
   return NavigatorComponent;
 }
 
-type LinkingForGroup =
-  | Pick<PathConfig<any>, 'path' | 'stringify' | 'parse'>
-  | string;
+export type TreeForPathConfig = {
+  config: ConfigForPathConfig;
+};
 
-type TreeForPathConfig = {
-  config: {
-    initialRouteName?: string;
-    screens?: StaticConfigScreens<
-      ParamListBase,
-      NavigationState,
-      {},
-      EventMapBase,
-      Record<string, unknown>
-    >;
-    groups?: {
-      [key: string]: {
-        linking?: LinkingForGroup;
-        screens: StaticConfigScreens<
-          ParamListBase,
-          NavigationState,
-          {},
-          EventMapBase,
-          Record<string, unknown>
-        >;
-      };
+type ConfigForPathConfig = {
+  initialRouteName?: string;
+  screens?: Record<string, ScreenForPathConfig>;
+  groups?: Record<string, { screens: Record<string, ScreenForPathConfig> }>;
+};
+
+type LinkingForPathConfig =
+  | string
+  | (Partial<StaticScreenConfigLinkingAlias> & StaticScreenConfigLinkingExtras)
+  | null
+  | undefined;
+
+type ScreenValueForPathConfig = React.ComponentType<{}> | TreeForPathConfig;
+
+type ScreenForPathConfig =
+  | ScreenValueForPathConfig
+  | {
+      screen: ScreenValueForPathConfig;
+      initialParams?: object;
+      linking?: LinkingForPathConfig;
+      UNSTABLE_loader?: unknown;
     };
+
+type PathConfigMapForStaticNavigation = Record<
+  string,
+  string | PathConfigForStaticNavigation | undefined
+>;
+
+type PathConfigForStaticNavigation = Omit<
+  PathConfig<ParamListBase>,
+  'screens'
+> & {
+  initialRouteName?: string | undefined;
+  screens?: PathConfigMapForStaticNavigation | undefined;
+};
+
+// Mark screens that resolve to the same pattern and same component or navigator
+const markSharedPathConfigs = (
+  screens: PathConfigMapForStaticNavigation,
+  sources: WeakMap<PathConfigForStaticNavigation, ScreenValueForPathConfig>,
+  blocked: WeakSet<PathConfigForStaticNavigation>
+) => {
+  const candidates = new Map<string, PathConfigForStaticNavigation[]>();
+
+  const collect = (
+    screens: PathConfigMapForStaticNavigation,
+    parentParts: PatternPart[],
+    disabled: boolean
+  ) => {
+    for (const config of Object.values(screens)) {
+      if (config == null || typeof config === 'string') {
+        continue;
+      }
+
+      const parts =
+        typeof config.path === 'string'
+          ? combinePatternParts(
+              parentParts,
+              getPatternParts(config.path),
+              config.exact
+            )
+          : parentParts;
+
+      if (sources.has(config) && typeof config.path === 'string') {
+        if (disabled) {
+          blocked.add(config);
+        }
+
+        const pattern = parts.map((part) => part.segment).join('/');
+        const entries = candidates.get(pattern) ?? [];
+
+        entries.push(config);
+        candidates.set(pattern, entries);
+      }
+
+      if (config.screens) {
+        collect(config.screens, parts, disabled || config.shared === false);
+      }
+    }
   };
+
+  collect(screens, [], false);
+
+  for (const entries of candidates.values()) {
+    for (const entry of entries) {
+      const source = sources.get(entry);
+
+      if (
+        entry.shared === undefined &&
+        !blocked.has(entry) &&
+        entries.some(
+          (candidate) =>
+            candidate !== entry &&
+            !blocked.has(candidate) &&
+            sources.get(candidate) === source
+        )
+      ) {
+        entry.shared = true;
+      }
+    }
+  }
 };
 
 /**
@@ -696,32 +978,49 @@ type TreeForPathConfig = {
  * };
  * ```
  */
-export function createPathConfigForStaticNavigation(
+export function createPathConfigForStaticNavigation<ParamList extends {}>(
   tree: TreeForPathConfig,
   options?: {
-    initialRouteName?: string;
+    initialRouteName?: string | undefined;
   },
   auto?: boolean
-): PathConfigMap<ParamListBase> | undefined {
+): PathConfigMap<ParamList> | undefined {
   let initialScreenHasPath: boolean = false;
   let initialScreenConfig: PathConfig<{}> | undefined;
+  let hasEmptyPath = false;
+
+  const blocked = new WeakSet<PathConfigForStaticNavigation>();
+  const sources = new WeakMap<
+    PathConfigForStaticNavigation,
+    ScreenValueForPathConfig
+  >();
 
   const createPathConfigForTree = (
     t: TreeForPathConfig,
-    o: { initialRouteName?: string } | undefined,
+    o: { initialRouteName?: string | undefined } | undefined,
     // If a screen is a leaf node, but inside a screen with path,
     // It should not be used for initial detection
-    skipInitialDetection: boolean
+    skipInitialDetection: boolean,
+    allowAutoEmptyPath: boolean
   ) => {
+    const initialRouteName = o?.initialRouteName ?? t.config.initialRouteName;
+
+    if (initialRouteName != null) {
+      const routeNames = new Set(Object.keys(t.config.screens ?? {}));
+
+      for (const group of Object.values(t.config.groups ?? {})) {
+        Object.keys(group.screens).forEach((name) => routeNames.add(name));
+      }
+
+      if (!routeNames.has(initialRouteName)) {
+        throw new Error(
+          `Couldn't find a screen named '${initialRouteName}' to use as 'initialRouteName'.`
+        );
+      }
+    }
+
     const createPathConfigForScreens = (
-      screens: StaticConfigScreens<
-        ParamListBase,
-        NavigationState,
-        {},
-        EventMapBase,
-        Record<string, unknown>
-      >,
-      groupLinking: LinkingForGroup | undefined,
+      screens: Record<string, ScreenForPathConfig>,
       initialRouteName: string | undefined
     ) => {
       return Object.fromEntries(
@@ -740,95 +1039,144 @@ export function createPathConfigForStaticNavigation(
             return 0;
           })
           .map(([key, item]) => {
-            const screenConfig: PathConfig<{}> = {};
-            const groupPath =
-              typeof groupLinking === 'string'
-                ? groupLinking
-                : groupLinking?.path;
-
-            const normalizePath = (path: string) => {
-              return `${groupPath ?? ''}/${path}`
-                .replace(/^\//, '') // Remove extra leading slash
-                .replace(/\/$/, ''); // Remove extra trailing slash
-            };
-
-            if ('linking' in item) {
+            const screenConfig: PathConfigForStaticNavigation = {};
+
+            sources.set(
+              screenConfig,
+              typeof item === 'object' && 'screen' in item ? item.screen : item
+            );
+
+            const normalizePath = (path: string) =>
+              path.replace(/^\/+|\/+$/g, '');
+
+            if ('linking' in item && item.linking !== undefined) {
               if (typeof item.linking === 'string') {
                 screenConfig.path = item.linking;
-              } else {
-                Object.assign(screenConfig, item.linking);
+              } else if (
+                item.linking != null &&
+                typeof item.linking === 'object'
+              ) {
+                Object.assign(screenConfig, { ...item.linking });
               }
             }
 
-            if (typeof groupLinking !== 'string') {
-              if (groupLinking?.parse != null) {
-                screenConfig.parse = {
-                  ...groupLinking.parse,
-                  ...screenConfig.parse,
-                };
-              }
-
-              if (groupLinking?.stringify != null) {
-                screenConfig.stringify = {
-                  ...groupLinking.stringify,
-                  ...screenConfig.stringify,
-                };
-              }
+            if (screenConfig.exact && screenConfig.path == null) {
+              throw new Error(
+                "A 'path' needs to be specified when specifying 'exact: true'. If you don't want this screen in the URL, specify it as empty string, e.g. `path: ''`."
+              );
             }
 
             if (typeof screenConfig.path === 'string') {
               screenConfig.path = normalizePath(screenConfig.path);
             }
 
+            if (screenConfig.alias != null) {
+              screenConfig.alias = screenConfig.alias.map((alias) => {
+                if (typeof alias === 'string') {
+                  return normalizePath(alias);
+                }
+
+                return {
+                  ...alias,
+                  path: normalizePath(alias.path),
+                };
+              });
+            }
+
             let screens;
 
+            const hasExplicitScreens =
+              'screens' in screenConfig && screenConfig.screens != null;
+            const hasDisabledLinking =
+              'linking' in item && item.linking === null;
+            const childOptions =
+              'initialRouteName' in screenConfig &&
+              typeof screenConfig.initialRouteName === 'string'
+                ? { initialRouteName: screenConfig.initialRouteName }
+                : undefined;
+
+            if (
+              hasExplicitScreens &&
+              childOptions != null &&
+              !Object.keys(screenConfig.screens ?? {}).includes(
+                childOptions.initialRouteName
+              )
+            ) {
+              throw new Error(
+                `Couldn't find a screen named '${childOptions.initialRouteName}' to use as 'initialRouteName'.`
+              );
+            }
+
             const skipInitialDetectionInChild =
               skipInitialDetection ||
               (screenConfig.path != null && screenConfig.path !== '');
+            const allowAutoEmptyPathInChild =
+              allowAutoEmptyPath &&
+              (initialRouteName == null || key === initialRouteName);
 
-            if ('config' in item) {
+            if (
+              !hasExplicitScreens &&
+              !hasDisabledLinking &&
+              'config' in item
+            ) {
               screens = createPathConfigForTree(
                 item,
-                undefined,
-                skipInitialDetectionInChild
+                childOptions,
+                skipInitialDetectionInChild,
+                allowAutoEmptyPathInChild
               );
             } else if (
+              !hasExplicitScreens &&
+              !hasDisabledLinking &&
               'screen' in item &&
               'config' in item.screen &&
               (item.screen.config.screens || item.screen.config.groups)
             ) {
               screens = createPathConfigForTree(
                 item.screen,
-                undefined,
-                skipInitialDetectionInChild
+                childOptions,
+                skipInitialDetectionInChild,
+                allowAutoEmptyPathInChild
               );
             }
 
             if (screens) {
-              // @ts-expect-error - we can't type this properly
               screenConfig.screens = screens;
             }
 
             if (
               auto &&
               !('screens' in screenConfig && screenConfig.screens) &&
-              // Skip generating path for screens that specify linking config as `undefined` or `null` explicitly
-              !('linking' in item && item.linking == null)
+              // Skip generating path for screens that specify linking config as `null` explicitly
+              !hasDisabledLinking
             ) {
               if (screenConfig.path != null) {
                 if (!skipInitialDetection) {
-                  if (key === initialRouteName && screenConfig.path != null) {
-                    initialScreenHasPath = true;
-                  } else if (screenConfig.path === '') {
+                  if (screenConfig.path === '') {
                     // We encounter a leaf screen with empty path,
                     // Clear the initial screen config as it's not needed anymore
                     initialScreenConfig = undefined;
+                    hasEmptyPath = true;
+
+                    if (allowAutoEmptyPath && key === initialRouteName) {
+                      initialScreenHasPath = true;
+                    }
+                  } else if (
+                    allowAutoEmptyPath &&
+                    key === initialRouteName &&
+                    // Keep an already discovered fallback unless the initial route
+                    // explicitly uses an empty path.
+                    initialScreenConfig == null
+                  ) {
+                    initialScreenHasPath = true;
                   }
                 }
               } else {
                 if (
-                  !groupPath &&
                   !skipInitialDetection &&
+                  allowAutoEmptyPath &&
+                  (initialRouteName == null || key === initialRouteName) &&
+                  !hasEmptyPath &&
                   initialScreenConfig == null
                 ) {
                   initialScreenConfig = screenConfig;
@@ -836,8 +1184,8 @@ export function createPathConfigForStaticNavigation(
 
                 screenConfig.path = normalizePath(
                   key
-                    .replace(/([A-Z]+)/g, '-$1')
-                    .replace(/^-/, '')
+                    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+                    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
                     .toLowerCase()
                 );
               }
@@ -849,7 +1197,7 @@ export function createPathConfigForStaticNavigation(
       );
     };
 
-    const screens = {};
+    const screens: PathConfigMapForStaticNavigation = {};
 
     // Loop through the config to find screens and groups
     // So we add the screens and groups in the same order as they are defined
@@ -859,7 +1207,6 @@ export function createPathConfigForStaticNavigation(
           screens,
           createPathConfigForScreens(
             t.config.screens,
-            undefined,
             o?.initialRouteName ?? t.config.initialRouteName
           )
         );
@@ -871,7 +1218,6 @@ export function createPathConfigForStaticNavigation(
             screens,
             createPathConfigForScreens(
               group.screens,
-              group.linking,
               o?.initialRouteName ?? t.config.initialRouteName
             )
           );
@@ -886,11 +1232,17 @@ export function createPathConfigForStaticNavigation(
     return screens;
   };
 
-  const screens = createPathConfigForTree(tree, options, false);
+  const screens = createPathConfigForTree(tree, options, false, true);
 
   if (auto && initialScreenConfig && !initialScreenHasPath) {
     initialScreenConfig.path = '';
   }
 
-  return screens;
+  if (!screens) {
+    return undefined;
+  }
+
+  markSharedPathConfigs(screens, sources, blocked);
+
+  return screens as PathConfigMap<ParamList>;
 }