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

package/src/StaticNavigation.tsx

@@ -1,4 +1,8 @@
-import type { NavigationState, ParamListBase } from '@react-navigation/routers';
+import type {
+  NavigationState,
+  ParamListBase,
+  Route,
+} from '@react-navigation/routers';
 import * as React from 'react';
 import { isValidElementType } from 'react-is';
 
@@ -7,10 +11,11 @@ import {
   getPatternParts,
   type PatternPart,
 } from './getPatternParts';
+import { StaticTreeContext } from './StaticTreeContext';
 import type {
-  DefaultNavigatorOptions,
   EventMapBase,
   NavigationListBase,
+  NavigatorProps,
   NavigatorScreenParams,
   NavigatorTypeBagBase,
   NavigatorTypeBagFor,
@@ -27,6 +32,8 @@ import type {
   HasArguments,
   InferParamsFromLinking,
   KeysOf,
+  NoExcessObject,
+  NotUndefinedObject,
   StandardSchemaV1,
   UnionToIntersection,
   ValidPathPattern,
@@ -81,14 +88,15 @@ type ParamsForScreen<T> = [T] extends [{ config: any }]
 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.
+// 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
-  | ValidPathPattern
-  | { path: ValidPathPattern }
-  | { parse: Record<string, unknown> }
+type ShouldInferFromLinking<Linking> = Linking extends {
+  parse: Record<string, unknown>;
+}
   ? true
-  : false;
+  : Linking extends ValidPathPattern | { path: ValidPathPattern }
+    ? true
+    : false;
 
 /**
  * Params type derived from both linking and screen.
@@ -104,7 +112,13 @@ type ShouldInferFromLinking<Linking> = Linking extends
 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>> & 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>
@@ -124,15 +138,7 @@ type ParamListForScreens<Screens> = {
     : ParamsForScreenEntry<Screens[Key]>;
 };
 
-type ParamListForGroups<
-  Groups extends
-    | Readonly<{
-        [key: string]: {
-          screens: {};
-        };
-      }>
-    | undefined,
-> = Groups extends {
+type ParamListForGroups<Groups> = Groups extends {
   [key: string]: {
     screens: infer Screens;
   };
@@ -140,27 +146,20 @@ type ParamListForGroups<
   ? ParamListForScreens<UnionToIntersection<Screens>>
   : {};
 
-type RouteTypeBase = {
-  key: string;
-  name: string;
-  path?: string | undefined;
-  history?: { type: 'params'; params: object }[] | undefined;
-};
-
-type RouteType<Params, P = AnyToUnknown<Params>> = Readonly<
-  RouteTypeBase &
+type StaticRoute<Params, P = AnyToUnknown<Params>> = Readonly<
+  Omit<Route<string>, 'params'> &
     (undefined extends Params
       ? {
           /**
            * Params for this route
            */
-          params?: P;
+          params?: P extends object ? Readonly<P> : P;
         }
       : {
           /**
            * Params for this route
            */
-          params: P;
+          params: Readonly<P>;
         })
 >;
 
@@ -221,23 +220,25 @@ type StaticScreenConfigLinkingAlias = {
   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)[];
-      /**
-       * 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;
-    })
+  | (StaticScreenConfigLinkingAlias & StaticScreenConfigLinkingExtras)
   | null
   | undefined;
 
@@ -287,7 +288,7 @@ export type StaticScreenConfig<
   options?:
     | ScreenOptions
     | ((props: {
-        route: RouteType<Params>;
+        route: StaticRoute<Params>;
         navigation: Navigation;
         theme: Theme;
       }) => ScreenOptions);
@@ -307,7 +308,7 @@ export type StaticScreenConfig<
   listeners?:
     | ScreenListeners<State, EventMap>
     | ((props: {
-        route: RouteType<Params>;
+        route: StaticRoute<Params>;
         navigation: Navigation;
       }) => ScreenListeners<State, EventMap>);
 
@@ -327,7 +328,7 @@ export type StaticScreenConfig<
    *
    */
   layout?: (props: {
-    route: RouteType<Params>;
+    route: StaticRoute<Params>;
     options: ScreenOptions;
     navigation: Navigation;
     theme: Theme;
@@ -354,7 +355,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.
@@ -376,11 +379,27 @@ 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,
+  const ProvidedOptions extends
+    | Bag['ScreenOptions']
+    | ((...args: never[]) => unknown) = Bag['ScreenOptions'],
 >(
   config: StaticScreenConfig<
     Linking,
@@ -389,7 +408,10 @@ export type StaticScreenFactory<in out Bag extends NavigatorTypeBagBase> = <
     Bag['ScreenOptions'],
     Bag['EventMap'],
     Bag['NavigationList'][keyof Bag['ParamList']]
-  >
+  > & {
+    options?: ProvidedOptions &
+      NoExcessOptions<ProvidedOptions, Bag['ScreenOptions']>;
+  }
 ) => StaticScreenConfig<
   Linking,
   Screen,
@@ -455,51 +477,33 @@ type StaticConfigGroup<
   >;
 };
 
-export type StaticConfig<Bag extends NavigatorTypeBagBase> =
-  StaticConfigInternal<
+export type StaticConfig<
+  Bag extends NavigatorTypeBagBase,
+  Screens = StaticConfigScreens<
     Bag['ParamList'],
     Bag['State'],
     Bag['ScreenOptions'],
     Bag['EventMap'],
-    Bag['NavigationList'],
-    Bag['Navigator']
-  >;
-
-type StaticConfigInternal<
-  ParamList extends ParamListBase,
-  State extends NavigationState,
-  ScreenOptions extends {},
-  EventMap extends EventMapBase,
-  NavigationList extends NavigationListBase<ParamList>,
-  Navigator extends React.ComponentType<any>,
-  Screens = StaticConfigScreens<
-    ParamList,
-    State,
-    ScreenOptions,
-    EventMap,
-    NavigationList
+    Bag['NavigationList']
   >,
   Groups = {
     [key: string]: StaticConfigGroup<
-      ParamList,
-      State,
-      ScreenOptions,
-      EventMap,
-      NavigationList
+      Bag['ParamList'],
+      Bag['State'],
+      Bag['ScreenOptions'],
+      Bag['EventMap'],
+      Bag['NavigationList']
     >;
   },
 > = Omit<
-  Omit<
-    React.ComponentProps<Navigator>,
-    keyof DefaultNavigatorOptions<any, any, any, any, any>
-  > &
-    DefaultNavigatorOptions<
-      ParamList,
-      State,
-      ScreenOptions,
-      EventMap,
-      NavigationList[keyof ParamList]
-    >,
+  NavigatorProps<
+    Bag['ParamList'],
+    Bag['State'],
+    Bag['ScreenOptions'],
+    Bag['EventMap'],
+    Bag['NavigationList'][keyof Bag['ParamList']],
+    Bag['Navigator']
+  >,
   'screens' | 'children'
 > &
   (
@@ -525,6 +529,67 @@ type StaticConfigInternal<
       }
   );
 
+type NoExcessOptions<Provided, Allowed extends {}> = Provided extends (
+  ...args: never[]
+) => infer Return
+  ? (...args: never[]) => Allowed & NoExcessObject<Return, Allowed>
+  : NoExcessObject<Provided, Allowed>;
+
+type NoExcessScreen<Screen, ScreenOptions extends {}> = Screen extends {
+  screen: unknown;
+  options: unknown;
+}
+  ? { options: NoExcessOptions<Screen['options'], ScreenOptions> }
+  : unknown;
+
+type NoExcessScreens<Screens, ScreenOptions extends {}> = {
+  [RouteName in keyof Screens]: NoExcessScreen<
+    Screens[RouteName],
+    ScreenOptions
+  >;
+};
+
+type NoExcessGroups<
+  Groups,
+  Bag extends NavigatorTypeBagBase,
+  ScreenOptions extends {},
+> = {
+  [GroupName in keyof Groups]: NoExcessObject<
+    Groups[GroupName],
+    StaticConfigGroup<
+      ParamListBase,
+      NavigationState,
+      {},
+      EventMapBase,
+      NavigationListBase<ParamListBase>
+    >
+  > &
+    NoExcessStaticConfig<Groups[GroupName], Bag, ScreenOptions>;
+};
+
+// 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'],
+> = (Config extends { screenOptions: infer ProvidedOptions }
+  ? {
+      screenOptions: NoExcessOptions<ProvidedOptions, ScreenOptions>;
+    }
+  : unknown) &
+  (Config extends { screens: infer Screens }
+    ? {
+        screens: NoExcessScreens<Screens, ScreenOptions>;
+      }
+    : unknown) &
+  (Config extends { groups: infer Groups }
+    ? {
+        groups: NoExcessGroups<Groups, Bag, ScreenOptions>;
+      }
+    : unknown);
+
 /**
  * Props for a screen component which is rendered by a static navigator.
  * Takes the route params as a generic argument.
@@ -533,7 +598,7 @@ export type StaticScreenProps<
   in out T extends Record<string, unknown> | undefined,
 > = {
   route: {
-    params: T;
+    readonly params: T;
   };
 };
 
@@ -723,14 +788,16 @@ export function createComponentForStaticConfig<
         : { ...rest.screenListeners, ...props.screenListeners };
 
     return (
-      <Navigator
-        {...rest}
-        {...props}
-        screenOptions={screenOptions}
-        screenListeners={screenListeners}
-      >
-        {children}
-      </Navigator>
+      <StaticTreeContext.Provider value={tree}>
+        <Navigator
+          {...rest}
+          {...props}
+          screenOptions={screenOptions}
+          screenListeners={screenListeners}
+        >
+          {children}
+        </Navigator>
+      </StaticTreeContext.Provider>
     );
   };
 
@@ -739,7 +806,7 @@ export function createComponentForStaticConfig<
   return NavigatorComponent;
 }
 
-type TreeForPathConfig = {
+export type TreeForPathConfig = {
   config: ConfigForPathConfig;
 };
 
@@ -751,11 +818,7 @@ type ConfigForPathConfig = {
 
 type LinkingForPathConfig =
   | string
-  | (Partial<StaticScreenConfigLinkingAlias> & {
-      alias?: (string | StaticScreenConfigLinkingAlias)[];
-      initialRouteName?: string | undefined;
-      screens?: PathConfigMap<ParamListBase> | undefined;
-    })
+  | (Partial<StaticScreenConfigLinkingAlias> & StaticScreenConfigLinkingExtras)
   | null
   | undefined;
 
@@ -765,7 +828,9 @@ type ScreenForPathConfig =
   | ScreenValueForPathConfig
   | {
       screen: ScreenValueForPathConfig;
+      initialParams?: object;
       linking?: LinkingForPathConfig;
+      UNSTABLE_loader?: unknown;
     };
 
 type PathConfigMapForStaticNavigation = Record<

package/src/StaticTreeContext.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+import type { TreeForPathConfig } from './StaticNavigation';
+
+export const StaticTreeContext = React.createContext<
+  TreeForPathConfig | undefined
+>(undefined);

package/src/checkSerializable.tsx

@@ -1,16 +1,18 @@
-type Result =
-  | { serializable: true }
-  | {
-      serializable: false;
-      location: (string | number)[];
-      reason: string;
-    };
+type Success = { serializable: true };
+
+type Failure = {
+  serializable: false;
+  location: (string | number)[];
+  reason: string;
+};
+
+type Result = Success | Failure;
 
 const checkSerializableWithoutCircularReference = (
   o: { [key: string]: any },
   seen: Set<any>,
   location: (string | number)[]
-): Result => {
+): Failure | undefined => {
   if (
     o === undefined ||
     o === null ||
@@ -18,7 +20,7 @@ const checkSerializableWithoutCircularReference = (
     typeof o === 'number' ||
     typeof o === 'string'
   ) {
-    return { serializable: true };
+    return undefined;
   }
 
   if (
@@ -52,7 +54,7 @@ const checkSerializableWithoutCircularReference = (
       );
       location.pop();
 
-      if (!childResult.serializable) {
+      if (childResult) {
         seen.delete(o);
         return childResult;
       }
@@ -67,7 +69,7 @@ const checkSerializableWithoutCircularReference = (
       );
       location.pop();
 
-      if (!childResult.serializable) {
+      if (childResult) {
         seen.delete(o);
         return childResult;
       }
@@ -76,9 +78,13 @@ const checkSerializableWithoutCircularReference = (
 
   seen.delete(o);
 
-  return { serializable: true };
+  return undefined;
 };
 
-export function checkSerializable(o: { [key: string]: any }) {
-  return checkSerializableWithoutCircularReference(o, new Set<any>(), []);
+export function checkSerializable(o: { [key: string]: any }): Result {
+  return (
+    checkSerializableWithoutCircularReference(o, new Set<any>(), []) ?? {
+      serializable: true,
+    }
+  );
 }

package/src/createNavigationContainerRef.tsx

@@ -30,6 +30,8 @@ export function createNavigationContainerRef<
 
   const listeners: Record<string, ((...args: any[]) => void)[]> = {};
 
+  let current: NavigationContainerRef<ParamList> | null = null;
+
   const removeListener = (
     event: string,
     callback: (...args: any[]) => void
@@ -37,9 +39,12 @@ export function createNavigationContainerRef<
     if (listeners[event]) {
       listeners[event] = listeners[event].filter((cb) => cb !== callback);
     }
-  };
 
-  let current: NavigationContainerRef<ParamList> | null = null;
+    current?.removeListener(
+      event as keyof NavigationContainerEventMap,
+      callback
+    );
+  };
 
   const ref: NavigationContainerRefWithCurrent<ParamList> = {
     get current() {
@@ -68,7 +73,11 @@ export function createNavigationContainerRef<
     },
     ...methods.reduce<any>((acc, name) => {
       acc[name] = (...args: any[]) => {
-        if (current == null) {
+        if (name === 'removeListener') {
+          const [event, callback] = args;
+
+          removeListener(event, callback);
+        } else if (current == null) {
           switch (name) {
             case 'addListener': {
               const [event, callback] = args;
@@ -78,12 +87,6 @@ export function createNavigationContainerRef<
 
               return () => removeListener(event, callback);
             }
-            case 'removeListener': {
-              const [event, callback] = args;
-
-              removeListener(event, callback);
-              break;
-            }
             default:
               console.error(NOT_INITIALIZED_ERROR);
           }

package/src/createNavigatorFactory.tsx

@@ -5,39 +5,48 @@ import { Group } from './Group';
 import { Screen } from './Screen';
 import {
   createComponentForStaticConfig,
+  type NoExcessStaticConfig,
   type StaticConfig,
   type StaticParamList,
 } from './StaticNavigation';
 import type {
   NavigatorTypeBagBase,
   NavigatorTypeBagFor,
+  NestedNavigatorsForParamList,
   TypedNavigator,
 } from './types';
-import type { KeysOf } from './utilities';
+import type { KeysOf, NoExcessObject } from './utilities';
+
+type NavigatorNesting<ParamList extends ParamListBase, Nesting> = {
+  [RouteName in keyof ParamList]?: unknown;
+} & Record<Exclude<KeysOf<Nesting>, keyof ParamList>, never>;
+
+type ValidNavigatorNesting<ParamList extends ParamListBase, Nesting> =
+  Nesting extends NavigatorNesting<ParamList, Nesting> ? Nesting : never;
+
+type AnyStaticConfig<TypeBag extends NavigatorTypeBagBase> = StaticConfig<
+  NavigatorTypeBagFor<TypeBag, ParamListBase>
+>;
 
 export type TypedNavigatorFactory<in out TypeBag extends NavigatorTypeBagBase> =
   {
-    <const ParamList extends ParamListBase>(): TypedNavigator<
+    <
+      const ParamList extends ParamListBase,
+      const Nesting extends NavigatorNesting<ParamList, Nesting> =
+        ValidNavigatorNesting<
+          ParamList,
+          NestedNavigatorsForParamList<ParamList>
+        >,
+    >(): TypedNavigator<
       NavigatorTypeBagFor<TypeBag, ParamList>,
-      undefined
+      undefined,
+      Nesting
     >;
     <
-      const Config extends StaticConfig<
-        NavigatorTypeBagFor<TypeBag, ParamListBase>
-      > &
-        // TS only checks for excess properties for non-generic object literal types.
-        // Since `Config` is generic, extra keys satisfy the constraint and slip through.
-        // So we force any key in `Config` that isn't a known key to have the type `never`,
-        // Thus causing an error for any extra key.
-        Record<
-          Exclude<
-            keyof Config,
-            KeysOf<StaticConfig<NavigatorTypeBagFor<TypeBag, ParamListBase>>>
-          >,
-          never
-        >,
+      const Config extends AnyStaticConfig<TypeBag> &
+        NoExcessObject<Config, AnyStaticConfig<TypeBag>>,
     >(
-      config: Config
+      config: Config & NoExcessStaticConfig<NoInfer<Config>, TypeBag>
     ): TypedNavigator<
       NavigatorTypeBagFor<TypeBag, StaticParamList<{ config: Config }>>,
       Config