@react-navigation/core 7.0.0-alpha.1 → 7.0.0-alpha.11

package/src/getStateFromPath.tsx

@@ -11,6 +11,7 @@ import type { PathConfigMap } from './types';
 import { validatePathConfig } from './validatePathConfig';
 
 type Options<ParamList extends {}> = {
+  path?: string;
   initialRouteName?: string;
   screens: PathConfigMap<ParamList>;
 };
@@ -70,7 +71,7 @@ export function getStateFromPath<ParamList extends {}>(
     validatePathConfig(options);
   }
 
-  let initialRoutes: InitialRouteConfig[] = [];
+  const initialRoutes: InitialRouteConfig[] = [];
 
   if (options?.initialRouteName) {
     initialRoutes.push({
@@ -89,6 +90,21 @@ export function getStateFromPath<ParamList extends {}>(
   // Make sure there is a trailing slash
   remaining = remaining.endsWith('/') ? remaining : `${remaining}/`;
 
+  const prefix = options?.path?.replace(/^\//, ''); // Remove extra leading slash
+
+  if (prefix) {
+    // Make sure there is a trailing slash
+    const normalizedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+
+    // If the path doesn't start with the prefix, it's not a match
+    if (!remaining.startsWith(normalizedPrefix)) {
+      return undefined;
+    }
+
+    // Remove the prefix from the path
+    remaining = remaining.replace(normalizedPrefix, '');
+  }
+
   if (screens === undefined) {
     // When no config is specified, use the path segments as route names
     const routes = remaining
@@ -271,29 +287,71 @@ const matchAgainstConfigs = (remaining: string, configs: RouteConfig[]) => {
 
     // If our regex matches, we need to extract params from the path
     if (match) {
-      const matchedParams = config.pattern
-        ?.split('/')
-        .filter((p) => p.startsWith(':'))
-        .reduce<Record<string, any>>(
-          (acc, p, i) =>
-            Object.assign(acc, {
-              // The param segments appear every second item starting from 2 in the regex match result
-              [p]: match![(i + 1) * 2].replace(/\//, ''),
+      const matchResult = config.pattern?.split('/').reduce<{
+        pos: number; // Position of the current path param segment in the path (e.g in pattern `a/:b/:c`, `:a` is 0 and `:b` is 1)
+        matchedParams: Record<string, Record<string, string>>; // The extracted params
+      }>(
+        (acc, p, index) => {
+          if (!p.startsWith(':')) {
+            return acc;
+          }
+
+          // Path parameter so increment position for the segment
+          acc.pos += 1;
+
+          const decodedParamSegment = decodeURIComponent(
+            // The param segments appear every second item starting from 2 in the regex match result
+            match![(acc.pos + 1) * 2]
+          );
+
+          Object.assign(acc.matchedParams, {
+            [p]: Object.assign(acc.matchedParams[p] || {}, {
+              [index]: decodedParamSegment.replace(/\//, ''),
             }),
-          {}
-        );
+          });
+
+          return acc;
+        },
+        { pos: -1, matchedParams: {} }
+      );
+
+      const matchedParams = matchResult.matchedParams || {};
 
       routes = config.routeNames.map((name) => {
-        const config = configs.find((c) => c.screen === name);
-        const params = config?.path
+        const routeConfig = configs.find((c) => {
+          // Check matching name AND pattern in case same screen is used at different levels in config
+          return c.screen === name && config.pattern.startsWith(c.pattern);
+        });
+
+        // Normalize pattern to remove any leading, trailing slashes, duplicate slashes etc.
+        const normalizedPath = routeConfig?.path
+          .split('/')
+          .filter(Boolean)
+          .join('/');
+
+        // Get the number of segments in the initial pattern
+        const numInitialSegments = routeConfig?.pattern
+          // Extract the prefix from the pattern by removing the ending path pattern (e.g pattern=`a/b/c/d` and normalizedPath=`c/d` becomes `a/b`)
+          .replace(new RegExp(`${escape(normalizedPath!)}$`), '')
+          ?.split('/').length;
+
+        const params = normalizedPath
           ?.split('/')
-          .filter((p) => p.startsWith(':'))
-          .reduce<Record<string, any>>((acc, p) => {
-            const value = matchedParams[p];
+          .reduce<Record<string, unknown>>((acc, p, index) => {
+            if (!p.startsWith(':')) {
+              return acc;
+            }
+
+            // Get the real index of the path parameter in the matched path
+            // by offsetting by the number of segments in the initial pattern
+            const offset = numInitialSegments ? numInitialSegments - 1 : 0;
+            const value = matchedParams[p]?.[index + offset];
 
             if (value) {
               const key = p.replace(/^:/, '').replace(/\?$/, '');
-              acc[key] = config.parse?.[key] ? config.parse[key](value) : value;
+              acc[key] = routeConfig?.parse?.[key]
+                ? routeConfig.parse[key](value)
+                : value;
             }
 
             return acc;
@@ -507,7 +565,6 @@ const createNestedStateObject = (
   initialRoutes: InitialRouteConfig[],
   flatConfig?: RouteConfig[]
 ) => {
-  let state: InitialState;
   let route = routes.shift() as ParsedRoute;
   const parentScreens: string[] = [];
 
@@ -515,7 +572,11 @@ const createNestedStateObject = (
 
   parentScreens.push(route.name);
 
-  state = createStateObject(initialRoute, route, routes.length === 0);
+  const state: InitialState = createStateObject(
+    initialRoute,
+    route,
+    routes.length === 0
+  );
 
   if (routes.length > 0) {
     let nestedState = state;

package/src/index.tsx

@@ -15,12 +15,15 @@ export { NavigationRouteContext } from './NavigationRouteContext';
 export { PreventRemoveContext } from './PreventRemoveContext';
 export { PreventRemoveProvider } from './PreventRemoveProvider';
 export {
+  createComponentForStaticNavigation,
+  createPathConfigForStaticNavigation,
   type StaticNavigation,
   type StaticParamList,
   type StaticScreenProps,
-  createComponentForStaticNavigation,
-  createPathConfigForStaticNavigation,
 } from './StaticNavigation';
+export { ThemeContext } from './theming/ThemeContext';
+export { ThemeProvider } from './theming/ThemeProvider';
+export { useTheme } from './theming/useTheme';
 export * from './types';
 export { useFocusEffect } from './useFocusEffect';
 export { useIsFocused } from './useIsFocused';
@@ -29,7 +32,7 @@ export { useNavigationBuilder } from './useNavigationBuilder';
 export { useNavigationContainerRef } from './useNavigationContainerRef';
 export { useNavigationIndependentTree } from './useNavigationIndependentTree';
 export { useNavigationState } from './useNavigationState';
-export { UNSTABLE_usePreventRemove } from './usePreventRemove';
+export { usePreventRemove } from './usePreventRemove';
 export { usePreventRemoveContext } from './usePreventRemoveContext';
 export { useRoute } from './useRoute';
 export { validatePathConfig } from './validatePathConfig';

package/src/theming/ThemeContext.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+export const ThemeContext = React.createContext<
+  ReactNavigation.Theme | undefined
+>(undefined);
+
+ThemeContext.displayName = 'ThemeContext';

package/src/theming/ThemeProvider.tsx

@@ -0,0 +1,14 @@
+import * as React from 'react';
+
+import { ThemeContext } from './ThemeContext';
+
+type Props = {
+  value: ReactNavigation.Theme | undefined;
+  children: React.ReactNode;
+};
+
+export function ThemeProvider({ value, children }: Props) {
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}

package/src/theming/useTheme.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+import { ThemeContext } from './ThemeContext';
+
+export function useTheme() {
+  const theme = React.useContext(ThemeContext);
+
+  if (theme == null) {
+    throw new Error(
+      "Couldn't find a theme. Is your component inside NavigationContainer or does it have a theme?"
+    );
+  }
+
+  return theme;
+}

package/src/types.tsx

@@ -14,6 +14,9 @@ declare global {
   namespace ReactNavigation {
     // eslint-disable-next-line @typescript-eslint/no-empty-interface
     interface RootParamList {}
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface Theme {}
   }
 }
 
@@ -23,17 +26,44 @@ export type DefaultNavigatorOptions<
   ParamList extends ParamListBase,
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = DefaultRouterOptions<Keyof<ParamList>> & {
   /**
    * Optional ID for the navigator. Can be used with `navigation.getParent(id)` to refer to a parent.
    */
   id?: string;
+
   /**
    * Children React Elements to extract the route configuration from.
    * Only `Screen`, `Group` and `React.Fragment` are supported as children.
    */
   children: React.ReactNode;
+
+  /**
+   * Layout for the navigator.
+   * Useful for wrapping with a component with access to navigator's state and options.
+   */
+  layout?: (props: {
+    state: State;
+    navigation: NavigationHelpers<ParamList>;
+    descriptors: Record<
+      string,
+      Descriptor<
+        ScreenOptions,
+        NavigationProp<
+          ParamList,
+          keyof ParamList,
+          string | undefined,
+          State,
+          ScreenOptions,
+          EventMap
+        >,
+        RouteProp<ParamList>
+      >
+    >;
+    children: React.ReactNode;
+  }) => React.ReactElement;
+
   /**
    * Event listeners for all the screens in the navigator.
    */
@@ -43,6 +73,7 @@ export type DefaultNavigatorOptions<
         route: RouteProp<ParamList>;
         navigation: any;
       }) => ScreenListeners<State, EventMap>);
+
   /**
    * Default options for all screens under this navigator.
    */
@@ -51,7 +82,25 @@ export type DefaultNavigatorOptions<
     | ((props: {
         route: RouteProp<ParamList>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
+
+  /**
+   * Layout for all screens under this navigator.
+   */
+  screenLayout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
+  /**
+   A function returning a state, which may be set after modifying the routes name.
+   */
+  getStateForRouteNamesChange?: (
+    state: NavigationState
+  ) => PartialState<NavigationState> | undefined;
 };
 
 export type EventMapBase = Record<
@@ -69,7 +118,7 @@ export type EventMapCore<State extends NavigationState> = {
 export type EventArg<
   EventName extends string,
   CanPreventDefault extends boolean | undefined = false,
-  Data = undefined
+  Data = undefined,
 > = {
   /**
    * Type of the event (e.g. `focus`, `blur`)
@@ -94,7 +143,7 @@ export type EventArg<
 
 export type EventListenerCallback<
   EventMap extends EventMapBase,
-  EventName extends keyof EventMap
+  EventName extends keyof EventMap,
 > = (
   e: EventArg<
     Extract<EventName, string>,
@@ -162,7 +211,7 @@ export class PrivateValueStore<T extends [any, any, any]> {
 
 type NavigationHelpersCommon<
   ParamList extends ParamListBase,
-  State extends NavigationState = NavigationState
+  State extends NavigationState = NavigationState,
 > = {
   /**
    * Dispatch an action or an update function to the router.
@@ -251,6 +300,22 @@ type NavigationHelpersCommon<
       : never
   ): void;
 
+  /**
+   * Preloads the route in current navigation tree.
+   *
+   * @param name Name of the route to navigate to.
+   * @param [params] Params object for the route.
+   */
+  preload<RouteName extends keyof ParamList>(
+    ...args: RouteName extends unknown
+      ? undefined extends ParamList[RouteName]
+        ?
+            | [screen: RouteName]
+            | [screen: RouteName, params: ParamList[RouteName]]
+        : [screen: RouteName, params: ParamList[RouteName]]
+      : never
+  ): void;
+
   /**
    * Reset the navigation state to the provided state.
    *
@@ -297,11 +362,18 @@ type NavigationHelpersCommon<
    * Note that this method doesn't re-render screen when the result changes. So don't use it in `render`.
    */
   getState(): State;
+  /**
+   * Schedules the given state to be used as navigation state when the list of screens defined in the navigator changes
+   * instead of automatically calculating the new state, e.g. due to conditional rendering or dynamically defining screens.
+   *
+   * @param state Navigation state object.
+   */
+  setStateForNextRouteNamesChange(state: PartialState<State> | State): void;
 } & PrivateValueStore<[ParamList, unknown, unknown]>;
 
 export type NavigationHelpers<
   ParamList extends ParamListBase,
-  EventMap extends EventMapBase = {}
+  EventMap extends EventMapBase = {},
 > = NavigationHelpersCommon<ParamList> &
   EventEmitter<EventMap> & {
     /**
@@ -342,6 +414,10 @@ export type NavigationContainerProps = {
    * @deprecated Use nested navigation API instead
    */
   navigationInChildEnabled?: boolean;
+  /**
+   * Theme object for the UI elements.
+   */
+  theme?: ReactNavigation.Theme;
   /**
    * Children elements to render.
    */
@@ -354,7 +430,7 @@ export type NavigationProp<
   NavigatorID extends string | undefined = undefined,
   State extends NavigationState = NavigationState<ParamList>,
   ScreenOptions extends {} = {},
-  EventMap extends EventMapBase = {}
+  EventMap extends EventMapBase = {},
 > = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
   /**
    * Returns the navigation prop from a parent navigator based on the ID.
@@ -389,12 +465,12 @@ export type NavigationProp<
 
 export type RouteProp<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList = Keyof<ParamList>
+  RouteName extends keyof ParamList = Keyof<ParamList>,
 > = Route<Extract<RouteName, string>, ParamList[RouteName]>;
 
 export type CompositeNavigationProp<
   A extends NavigationProp<ParamListBase, string, any, any, any>,
-  B extends NavigationHelpersCommon<ParamListBase, any>
+  B extends NavigationHelpersCommon<ParamListBase, any>,
 > = Omit<A & B, keyof NavigationProp<any>> &
   NavigationProp<
     /**
@@ -442,7 +518,7 @@ export type CompositeScreenProps<
   },
   B extends {
     navigation: NavigationHelpersCommon<any, any>;
-  }
+  },
 > = {
   navigation: CompositeNavigationProp<A['navigation'], B['navigation']>;
   route: A['route'];
@@ -451,7 +527,7 @@ export type CompositeScreenProps<
 export type Descriptor<
   ScreenOptions extends {},
   Navigation extends NavigationProp<any, any, any, any, any, any>,
-  Route extends RouteProp<any, any>
+  Route extends RouteProp<any, any>,
 > = {
   /**
    * Render the component associated with this route.
@@ -476,7 +552,7 @@ export type Descriptor<
 
 export type ScreenListeners<
   State extends NavigationState,
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = Partial<{
   [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<
     EventMap,
@@ -486,7 +562,7 @@ export type ScreenListeners<
 
 type ScreenComponentType<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList
+  RouteName extends keyof ParamList,
 > =
   | React.ComponentType<{
       route: RouteProp<ParamList, RouteName>;
@@ -496,7 +572,7 @@ type ScreenComponentType<
 
 export type RouteConfigComponent<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList
+  RouteName extends keyof ParamList,
 > =
   | {
       /**
@@ -531,7 +607,7 @@ export type RouteConfig<
   RouteName extends keyof ParamList,
   State extends NavigationState,
   ScreenOptions extends {},
-  EventMap extends EventMapBase
+  EventMap extends EventMapBase,
 > = {
   /**
    * Optional key for this screen. This doesn't need to be unique.
@@ -553,6 +629,7 @@ export type RouteConfig<
     | ((props: {
         route: RouteProp<ParamList, RouteName>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
 
   /**
@@ -565,6 +642,18 @@ export type RouteConfig<
         navigation: any;
       }) => ScreenListeners<State, EventMap>);
 
+  /**
+   * Layout for this screen.
+   * Useful for wrapping the screen with custom containers.
+   * e.g. for styling, error boundaries, suspense, etc.
+   */
+  layout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
   /**
    * Function to return an unique ID for this screen.
    * Receives an object with the route params.
@@ -585,7 +674,7 @@ export type RouteConfig<
 
 export type RouteGroupConfig<
   ParamList extends ParamListBase,
-  ScreenOptions extends {}
+  ScreenOptions extends {},
 > = {
   /**
    * Optional key for the screens in this group.
@@ -601,7 +690,20 @@ export type RouteGroupConfig<
     | ((props: {
         route: RouteProp<ParamList, keyof ParamList>;
         navigation: any;
+        theme: ReactNavigation.Theme;
       }) => ScreenOptions);
+
+  /**
+   * Layout for the screens inside the group.
+   * This will override the `screenLayout` of parent group or navigator.
+   */
+  screenLayout?: (props: {
+    route: RouteProp<ParamList, keyof ParamList>;
+    navigation: any;
+    theme: ReactNavigation.Theme;
+    children: React.ReactElement;
+  }) => React.ReactElement;
+
   /**
    * Children React Elements to extract the route configuration from.
    * Only `Screen`, `Group` and `React.Fragment` are supported as children.
@@ -673,6 +775,14 @@ export type NavigationContainerRef<ParamList extends {}> =
        * Whether the navigation container is ready to handle actions.
        */
       isReady(): boolean;
+      /**
+       * Stub function for setOptions on navigation object for use with useNavigation.
+       */
+      setOptions(): never;
+      /**
+       * Stub function for getParent on navigation object for use with useNavigation.
+       */
+      getParent(): undefined;
     };
 
 export type NavigationContainerRefWithCurrent<ParamList extends {}> =
@@ -685,7 +795,7 @@ export type TypedNavigator<
   State extends NavigationState,
   ScreenOptions extends {},
   EventMap extends EventMapBase,
-  Navigator extends React.ComponentType<any>
+  Navigator extends React.ComponentType<any>,
 > = {
   /**
    * Navigator component which manages the child screens.
@@ -779,12 +889,18 @@ export type PathConfig<ParamList extends {}> = {
    * Name of the initial route to use for the navigator when the path matches.
    */
   initialRouteName?: keyof ParamList;
+  /**
+   * A function returning a state, which may be set after modifying the routes name.
+   */
+  getStateForRouteNamesChange?: (
+    state: NavigationState
+  ) => PartialState<NavigationState> | undefined;
 };
 
 export type PathConfigMap<ParamList extends {}> = {
   [RouteName in keyof ParamList]?: NonNullable<
     ParamList[RouteName]
-  > extends NavigatorScreenParams<infer T>
+  > extends NavigatorScreenParams<infer T extends {}>
     ? string | PathConfig<T>
     : string | Omit<PathConfig<{}>, 'screens' | 'initialRouteName'>;
 };