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

package/src/StaticNavigation.tsx

@@ -1,17 +1,19 @@
-import type {
-  NavigationState,
-  ParamListBase,
-  Route,
-} from '@react-navigation/routers';
+import type { NavigationState, ParamListBase } from '@react-navigation/routers';
 import * as React from 'react';
 import { isValidElementType } from 'react-is';
 
+import {
+  combinePatternParts,
+  getPatternParts,
+  type PatternPart,
+} from './getPatternParts';
 import type {
   DefaultNavigatorOptions,
   EventMapBase,
   NavigationListBase,
   NavigatorScreenParams,
   NavigatorTypeBagBase,
+  NavigatorTypeBagFor,
   PathConfig,
   PathConfigMap,
   RouteGroupConfig,
@@ -21,68 +23,92 @@ import type {
 import { useRoute } from './useRoute';
 import type {
   AnyToUnknown,
-  ExtractParamStrings,
-  ExtractParamsType,
   FlatType,
   HasArguments,
-  InferParse,
-  InferPath,
+  InferParamsFromLinking,
   KeysOf,
+  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 every nested route's params include `undefined`, the nested navigator
+// itself can be omitted. Otherwise, require `NavigatorScreenParams`.
+type ParamsForNestedNavigator<
+  T extends { config: any },
+  ParamList extends {} = StaticParamList<T>,
+  Params = NavigatorScreenParams<ParamList>,
+> = {
+  // Map each route to `never` when params are optional, or name when params are required
+  // If every route has optional params, the resulting union is `never`
+  [RouteName in keyof ParamList]-?: undefined extends ParamList[RouteName]
+    ? never
+    : RouteName;
+}[keyof ParamList] 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 for query params.
+// This avoids inferring non-literals like 'string' without parse.
+type ShouldInferFromLinking<Linking> = Linking extends
+  | ValidPathPattern
+  | { path: ValidPathPattern }
+  | { parse: Record<string, unknown> }
+  ? 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 }]
+      ? FlatType<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,10 +117,11 @@ type ParamListForScreens<Screens> = {
     any,
     any,
     any,
+    any,
     any
   >
     ? ParamsForConfig<Linking, Screen>
-    : ParamsForScreen<Screens[Key]>;
+    : ParamsForScreenEntry<Screens[Key]>;
 };
 
 type ParamListForGroups<
@@ -113,25 +140,25 @@ 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 RouteType<Params, P = AnyToUnknown<Params>> = Readonly<
+  {
+    key: string;
+    name: string;
+    path?: string | undefined;
+    history?: { type: 'params'; params: object }[] | undefined;
+  } & (undefined extends Params
+    ? {
+        /**
+         * Params for this route
+         */
+        params?: P;
+      }
+    : {
+        /**
+         * Params for this route
+         */
+        params: P;
+      })
 >;
 
 type StaticScreenConfigLinkingAlias = {
@@ -147,7 +174,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,7 +184,11 @@ 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)`.
@@ -170,6 +201,21 @@ 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;
 };
 
 export type StaticScreenConfigLinking =
@@ -179,12 +225,22 @@ export type StaticScreenConfigLinking =
        * 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;
     })
+  | null
   | undefined;
 
 export type StaticScreenConfigScreen =
   | React.ComponentType<any>
-  | StaticNavigation<any, any, any>;
+  | StaticNavigation<any>;
 
 export type StaticScreenConfig<
   Linking extends StaticScreenConfigLinking,
@@ -319,24 +375,48 @@ export type StaticScreenConfig<
   navigationKey?: string;
 };
 
+export type StaticScreenFactory<in out Bag extends NavigatorTypeBagBase> = <
+  const Linking extends StaticScreenConfigLinking,
+  const Screen extends StaticScreenConfigScreen,
+>(
+  config: StaticScreenConfig<
+    Linking,
+    Screen,
+    Bag['State'],
+    Bag['ScreenOptions'],
+    Bag['EventMap'],
+    Bag['NavigationList'][keyof Bag['ParamList']]
+  >
+) => 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,
@@ -360,27 +440,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.
    */
@@ -410,16 +469,26 @@ type StaticConfigInternal<
   EventMap extends EventMapBase,
   NavigationList extends NavigationListBase<ParamList>,
   Navigator extends React.ComponentType<any>,
+  Screens = StaticConfigScreens<
+    ParamList,
+    State,
+    ScreenOptions,
+    EventMap,
+    NavigationList
+  >,
+  Groups = {
+    [key: string]: StaticConfigGroup<
+      ParamList,
+      State,
+      ScreenOptions,
+      EventMap,
+      NavigationList
+    >;
+  },
 > = Omit<
   Omit<
     React.ComponentProps<Navigator>,
-    keyof DefaultNavigatorOptions<
-      ParamListBase,
-      NavigationState,
-      {},
-      EventMapBase,
-      NavigationList[keyof ParamList]
-    >
+    keyof DefaultNavigatorOptions<any, any, any, any, any>
   > &
     DefaultNavigatorOptions<
       ParamList,
@@ -435,49 +504,21 @@ type StaticConfigInternal<
         /**
          * 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;
       }
   );
 
@@ -485,7 +526,9 @@ type StaticConfigInternal<
  * 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;
   };
@@ -503,11 +546,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: StaticConfig<NavigatorTypeBag>;
+  getComponent: () => React.ComponentType<{}>;
 };
 
 const MemoizedScreen = React.memo(
@@ -542,16 +585,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 +629,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 +684,51 @@ 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 (
+      <Navigator
+        {...rest}
+        {...props}
+        screenOptions={screenOptions}
+        screenListeners={screenListeners}
+      >
+        {children}
+      </Navigator>
+    );
   };
 
   NavigatorComponent.displayName = displayName;
@@ -648,33 +736,113 @@ export function createComponentForStaticNavigation(
   return NavigatorComponent;
 }
 
-type LinkingForGroup =
-  | Pick<PathConfig<any>, 'path' | 'stringify' | 'parse'>
-  | string;
-
 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>
-        >;
-      };
+  config: ConfigForPathConfig;
+};
+
+type ConfigForPathConfig = {
+  initialRouteName?: string;
+  screens?: Record<string, ScreenForPathConfig>;
+  groups?: Record<string, { screens: Record<string, ScreenForPathConfig> }>;
+};
+
+type LinkingForPathConfig =
+  | string
+  | (Partial<StaticScreenConfigLinkingAlias> & {
+      alias?: (string | StaticScreenConfigLinkingAlias)[];
+      initialRouteName?: string | undefined;
+      screens?: PathConfigMap<ParamListBase> | undefined;
+    })
+  | null
+  | undefined;
+
+type ScreenValueForPathConfig = React.ComponentType<{}> | TreeForPathConfig;
+
+type ScreenForPathConfig =
+  | ScreenValueForPathConfig
+  | {
+      screen: ScreenValueForPathConfig;
+      linking?: LinkingForPathConfig;
     };
+
+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 +864,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 +925,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;
@@ -849,7 +1083,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 +1093,6 @@ export function createPathConfigForStaticNavigation(
           screens,
           createPathConfigForScreens(
             t.config.screens,
-            undefined,
             o?.initialRouteName ?? t.config.initialRouteName
           )
         );
@@ -871,7 +1104,6 @@ export function createPathConfigForStaticNavigation(
             screens,
             createPathConfigForScreens(
               group.screens,
-              group.linking,
               o?.initialRouteName ?? t.config.initialRouteName
             )
           );
@@ -886,11 +1118,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>;
 }