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

package/src/getPathFromState.tsx

@@ -16,12 +16,22 @@ type State = NavigationState | Omit<PartialState<NavigationState>, 'stale'>;
 
 type StringifyConfig = Record<string, ((value: unknown) => string) | undefined>;
 
+type SerializedParamValue = string | string[] | null;
+
 type ConfigItem = {
   parts?: PatternPart[] | undefined;
+  ownParts: PatternPart[];
   stringify?: StringifyConfig | undefined;
   screens?: Record<string, ConfigItem> | undefined;
 };
 
+const serializeParamValue = (value: unknown): SerializedParamValue =>
+  value === null
+    ? null
+    : Array.isArray(value)
+      ? value.map(String)
+      : String(value);
+
 const encodePathParam = (value: string) => {
   let result = '';
 
@@ -170,8 +180,6 @@ export function getPathFromState<ParamList extends {}>(
   let path = '/';
   let current: State | undefined = state;
 
-  const allParams: Record<string, string> = {};
-
   while (current) {
     let index: number = typeof current.index === 'number' ? current.index : 0;
 
@@ -186,7 +194,11 @@ export function getPathFromState<ParamList extends {}>(
 
     let parts: PatternPart[] | undefined;
 
-    let focusedParams: Record<string, string> | undefined;
+    // Values for each pattern part object, so the same param name
+    // at different nesting levels gets the value from its own level
+    const partValues = new Map<PatternPart, SerializedParamValue | undefined>();
+
+    let focusedParams: Record<string, SerializedParamValue> | undefined;
     let currentOptions = configs;
 
     // Keep all the route names that appeared during going deeper in config in case the pattern is resolved to undefined
@@ -203,12 +215,14 @@ export function getPathFromState<ParamList extends {}>(
 
       parts = config.parts;
 
+      const ownParts = config.ownParts;
+
       nestedRouteNames.push(route.name);
 
       if (route.params) {
         const options = config;
         const params = route.params as Record<string, unknown>;
-        const currentParams: Record<string, string> = {};
+        const currentParams: Record<string, SerializedParamValue> = {};
 
         for (const key in params) {
           const value = params[key];
@@ -216,7 +230,7 @@ export function getPathFromState<ParamList extends {}>(
           if (value === undefined) {
             let optional = false;
 
-            for (const part of options.parts ?? []) {
+            for (const part of ownParts) {
               if (part.param === key) {
                 optional = part.optional === true;
                 break;
@@ -228,39 +242,52 @@ export function getPathFromState<ParamList extends {}>(
             }
           }
 
-          const stringify = options.stringify?.[key] ?? String;
+          const stringify = options.stringify?.[key];
 
-          currentParams[key] = stringify(value);
+          currentParams[key] = stringify
+            ? stringify(value)
+            : serializeParamValue(value);
         }
 
-        if (parts?.length) {
-          Object.assign(allParams, currentParams);
+        const claimedParams = new Set<string>();
+
+        for (const part of ownParts) {
+          if (part.param && part.param in currentParams) {
+            const value = currentParams[part.param];
+
+            if (value !== undefined) {
+              partValues.set(part, value);
+              claimedParams.add(part.param);
+            }
+          }
         }
 
         if (focusedRoute === route) {
           // If this is the focused route, keep the params for later use
           // We save it here since it's been stringified already
+          // Params claimed by the pattern shouldn't be repeated in the query string
           focusedParams = {};
 
           for (const key in currentParams) {
-            let inPattern = false;
-
-            for (const part of parts ?? []) {
-              if (part.param === key) {
-                inPattern = true;
-                break;
-              }
-            }
-
             const value = currentParams[key];
 
-            if (!inPattern && value !== undefined && value !== 'undefined') {
+            if (
+              !claimedParams.has(key) &&
+              value !== undefined &&
+              value !== 'undefined'
+            ) {
               focusedParams[key] = value;
             }
           }
         }
       }
 
+      for (const part of ownParts) {
+        if (part.param && !partValues.has(part)) {
+          partValues.set(part, undefined);
+        }
+      }
+
       // If there is no `screens` property or no nested state, we return pattern
       const routeState = getRouteState(route, config);
 
@@ -298,7 +325,9 @@ export function getPathFromState<ParamList extends {}>(
       if (parts) {
         let index = 0;
 
-        for (const { segment, param, optional } of parts) {
+        for (const part of parts) {
+          const { segment, param, optional } = part;
+
           if (index > 0) {
             path += '/';
           }
@@ -315,7 +344,7 @@ export function getPathFromState<ParamList extends {}>(
 
           // If the path has a pattern for a param, put the param in the path
           if (param) {
-            const value = allParams[param];
+            const value = partValues.get(part);
 
             if (value === undefined && optional) {
               // Optional params without value assigned in route.params should be ignored
@@ -341,7 +370,7 @@ export function getPathFromState<ParamList extends {}>(
       const params = focusedRoute.params as Record<string, unknown>;
 
       for (const key in params) {
-        const value = String(params[key]);
+        const value = serializeParamValue(params[key]);
 
         if (value !== 'undefined') {
           focusedParams[key] = value;
@@ -385,14 +414,13 @@ const createConfigItem = (
   parentParts?: PatternPart[]
 ): ConfigItem => {
   if (typeof config === 'string') {
-    // If a string is specified as the value of the key(e.g. Foo: '/path'), use it as the pattern
-    const parts = getPatternParts(config);
+    const ownParts = getPatternParts(config);
 
     if (parentParts) {
-      return { parts: [...parentParts, ...parts] };
+      return { parts: [...parentParts, ...ownParts], ownParts };
     }
 
-    return { parts };
+    return { parts: ownParts, ownParts };
   }
 
   if (config.exact && config.path === undefined) {
@@ -403,14 +431,12 @@ const createConfigItem = (
 
   // If an object is specified as the value (e.g. Foo: { ... }),
   // It can have `path` property and `screens` prop which has nested configs
+  const ownParts = config.path ? getPatternParts(config.path) : [];
   const parts =
     config.exact !== true
-      ? [
-          ...(parentParts || []),
-          ...(config.path ? getPatternParts(config.path) : []),
-        ]
-      : config.path
-        ? getPatternParts(config.path)
+      ? [...(parentParts || []), ...ownParts]
+      : ownParts.length
+        ? ownParts
         : undefined;
 
   const screens =
@@ -420,6 +446,7 @@ const createConfigItem = (
 
   return {
     parts,
+    ownParts,
     stringify: config.stringify,
     screens,
   };

package/src/getPatternParts.tsx

@@ -15,6 +15,8 @@ export function getPatternParts(path: string): PatternPart[] {
 
   let isRegex = false;
   let isParam = false;
+  let isEscaped = false;
+  let isInCharClass = false;
   let regexInnerParens = 0;
 
   // One extra iteration to add the last character
@@ -34,7 +36,7 @@ export function getPatternParts(path: string): PatternPart[] {
           `Encountered ':' in the middle of a segment in path: ${path}`
         );
       }
-    } else if (char === '(') {
+    } else if (char === '(' && !isEscaped && !isInCharClass) {
       if (isParam) {
         if (isRegex) {
           // The '(' is part of the regex if we're already inside one
@@ -47,7 +49,7 @@ export function getPatternParts(path: string): PatternPart[] {
           `Encountered '(' without preceding ':' in path: ${path}`
         );
       }
-    } else if (char === ')') {
+    } else if (char === ')' && !isEscaped && !isInCharClass) {
       if (isParam && isRegex) {
         if (regexInnerParens) {
           // The ')' is part of the regex if we're already inside one
@@ -102,6 +104,17 @@ export function getPatternParts(path: string): PatternPart[] {
     if (isRegex) {
       current.regex = current.regex || '';
       current.regex += char;
+
+      // Track escapes and character classes so parens inside them are not special
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === '\\') {
+        isEscaped = true;
+      } else if (char === '[') {
+        isInCharClass = true;
+      } else if (char === ']') {
+        isInCharClass = false;
+      }
     }
 
     if (isParam && !isRegex) {

package/src/getStateFromPath.tsx

@@ -39,7 +39,12 @@ type RouteConfig = {
   regex?: RegExp | undefined;
   pattern: string;
   segments: string[];
-  params: { screen: string; name: string; index: number }[];
+  params: {
+    screen: string;
+    name: string;
+    index: number;
+    regex?: RegExp | undefined;
+  }[];
   routeNames: string[];
   parse?: ParseConfig | undefined;
   explicitParamNames?: Set<string> | undefined;
@@ -69,6 +74,7 @@ type ConfigResources = {
   configs: RouteConfig[];
   configsByScreen: Record<string, RouteConfig[]>;
   configsByPattern: Record<string, RouteConfig[]>;
+  prefixRegex?: RegExp | undefined;
 };
 
 const INVALID_SCHEMA_RESULT_ERROR =
@@ -88,6 +94,17 @@ const NESTED_SCREEN_PARAM_NAMES = [
   'pop',
 ];
 
+const getStaticSegmentPattern = (segment: string) =>
+  Array.from(segment, (char) => {
+    const encoded = encodeURIComponent(char);
+    const percentEncoded =
+      encoded === char
+        ? `%${char.charCodeAt(0).toString(16).padStart(2, '0').toUpperCase()}`
+        : encoded;
+
+    return `(?:${escape(char)}|${escape(percentEncoded)})`;
+  }).join('');
+
 const getExplicitParamNames = (parse?: ParseConfig) => {
   const names: string[] = [];
 
@@ -161,8 +178,13 @@ export function getStateFromPath<ParamList extends {}>(
   options?: Options<ParamList>,
   previous?: NavigationState
 ): ResultState | undefined {
-  const { initialRoutes, configs, configsByScreen, configsByPattern } =
-    getConfigResources(options);
+  const {
+    initialRoutes,
+    configs,
+    configsByScreen,
+    configsByPattern,
+    prefixRegex,
+  } = getConfigResources(options);
 
   const screens = options?.screens;
 
@@ -183,24 +205,20 @@ export function getStateFromPath<ParamList extends {}>(
   let remaining = path
     .replace(/\/+/g, '/') // Replace multiple slash (//) with single ones
     .replace(/^\//, '') // Remove extra leading slash
-    .replace(/\?.*$/, ''); // Remove query params which we will handle later
+    .replace(/\?.*$/, '') // Remove query params which we will handle later
+    .replace(/%[0-9a-f]{2}/gi, (m) => m.toUpperCase()); // Normalize percent-encoding as hex digits are case-insensitive
 
   // 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 (prefixRegex) {
+    const prefixMatch = remaining.match(prefixRegex);
 
-    // If the path doesn't start with the prefix, it's not a match
-    if (!remaining.startsWith(normalizedPrefix)) {
+    if (prefixMatch == null) {
       return undefined;
     }
 
-    // Remove the prefix from the path
-    remaining = remaining.replace(normalizedPrefix, '');
+    remaining = remaining.slice(prefixMatch[0].length);
   }
 
   if (screens === undefined) {
@@ -358,6 +376,19 @@ function getConfigResources<ParamList extends {}>(
 function prepareConfigResources(options?: Options<{}>) {
   const initialRoutes = getInitialRoutes(options);
   const configs = getSortedNormalizedConfigs(initialRoutes, options?.screens);
+  const prefix = options?.path?.replace(/^\//, '');
+
+  let prefixRegex: RegExp | undefined;
+
+  if (prefix) {
+    const normalizedPrefix = prefix.endsWith('/') ? prefix : `${prefix}/`;
+    const prefixPattern = normalizedPrefix
+      .split('/')
+      .map(getStaticSegmentPattern)
+      .join('/');
+
+    prefixRegex = new RegExp(`^${prefixPattern}`);
+  }
 
   const configsByScreen: Record<string, RouteConfig[]> = {};
   const configsByPattern: Record<string, RouteConfig[]> = {};
@@ -380,6 +411,7 @@ function prepareConfigResources(options?: Options<{}>) {
     configs,
     configsByScreen,
     configsByPattern,
+    prefixRegex,
   };
 }
 
@@ -428,7 +460,21 @@ function getSortedNormalizedConfigs(
     // If 2 patterns are same, move the one with less route names up
     // This is an error state, so it's only useful for consistent error messages
     if (isArrayEqual(a.segments, b.segments)) {
-      return b.routeNames.join('>').localeCompare(a.routeNames.join('>'));
+      if (
+        a.routeNames.length > b.routeNames.length &&
+        arrayStartsWith(a.routeNames, b.routeNames)
+      ) {
+        return -1;
+      }
+
+      if (
+        b.routeNames.length > a.routeNames.length &&
+        arrayStartsWith(b.routeNames, a.routeNames)
+      ) {
+        return 1;
+      }
+
+      return a.routeNames.length - b.routeNames.length || a.order - b.order;
     }
 
     // If one of the patterns starts with the other, it's more exhaustive
@@ -585,6 +631,12 @@ const matchAgainstConfig = (
           return undefined;
         }
 
+        // Percent-encoded values are matched permissively
+        // So validate the decoded value against the custom regex
+        if (param.regex && value !== decoded && !param.regex.test(decoded)) {
+          return undefined;
+        }
+
         const parser = routeConfig.parse?.[param.name];
 
         if (!parser) {
@@ -799,20 +851,27 @@ const createConfigItem = (
       segments.push(part.segment);
 
       if (part.param) {
-        const reg = part.regex || '[^/]+';
+        // A custom regex may not match the percent-encoded form of the value
+        // So also accept segments containing an encoded character and validate them after decoding
+        const reg = part.regex
+          ? `(?:${part.regex})|(?=[^/]*%[0-9A-F]{2})[^/]+`
+          : '[^/]+';
 
         regexString += `(((?<${PARAM_GROUP_PREFIX}${index}>${reg})\\/)${part.optional ? '?' : ''})`;
         params.push({
           index,
           screen: part.screen,
           name: part.param,
+          regex: part.regex ? new RegExp(`^(?:${part.regex})$`) : undefined,
         });
 
         if (part.screen === screen) {
           pathParamNames.add(part.param);
         }
+      } else if (part.segment === '*') {
+        regexString += `.*\\/`;
       } else {
-        regexString += `${part.segment === '*' ? '.*' : escape(part.segment)}\\/`;
+        regexString += `${getStaticSegmentPattern(part.segment)}\\/`;
       }
 
       index++;
@@ -1083,7 +1142,8 @@ const parseQueryParams = (
 ):
   | { valid: true; params?: Record<string, unknown> | undefined }
   | { valid: false } => {
-  const query = path.split('?')[1];
+  const queryIndex = path.indexOf('?');
+  const query = queryIndex === -1 ? undefined : path.slice(queryIndex + 1);
   const params: Record<string, unknown> = query ? queryString.parse(query) : {};
 
   // Path params should always win over same-named query params.

package/src/index.tsx

@@ -11,6 +11,10 @@ export { getFocusedRouteNameFromRoute } from './getFocusedRouteNameFromRoute';
 export { getPathFromState } from './getPathFromState';
 export { getStateFromPath } from './getStateFromPath';
 export { NavigationContainerRefContext } from './NavigationContainerRefContext';
+export {
+  type FocusedRouteState,
+  NavigationFocusedRouteStateContext,
+} from './NavigationFocusedRouteStateContext';
 export { NavigationHelpersContext } from './NavigationHelpersContext';
 export { NavigationIndependentTree } from './NavigationIndependentTree';
 export { NavigationMetaContext } from './NavigationMetaContext';
@@ -61,6 +65,7 @@ export type {
   NavigatorTypeBagBase,
   NavigatorTypeBagFor,
   NestedNavigatorsForParamList,
+  ParamListForNavigator,
   PathConfig,
   PathConfigMap,
   RootNavigator,

package/src/types.tsx

@@ -93,7 +93,7 @@ export type DefaultNavigatorOptions<
               ScreenOptions,
               EventMap
             >,
-            RouteProp<ParamList>
+            ScreenRouteProp<ParamList>
           >
         >;
         children: React.ReactNode;
@@ -107,7 +107,7 @@ export type DefaultNavigatorOptions<
     | (
         | ScreenListeners<State, EventMap>
         | ((props: {
-            route: RouteProp<ParamList>;
+            route: ScreenRouteProp<ParamList>;
             navigation: Navigation;
           }) => ScreenListeners<State, EventMap>)
       )
@@ -120,7 +120,7 @@ export type DefaultNavigatorOptions<
     | (
         | ScreenOptions
         | ((props: {
-            route: RouteProp<ParamList>;
+            route: ScreenRouteProp<ParamList>;
             navigation: Navigation;
             theme: Theme;
           }) => ScreenOptions)
@@ -298,7 +298,7 @@ type NavigatorLike =
       getComponent: () => React.ComponentType<any>;
     };
 
-type ParamListForNavigator<T extends {}> = T extends NavigatorLike
+export type ParamListForNavigator<T extends {}> = T extends NavigatorLike
   ? T extends PrivateValueStore<[infer ParamList extends {}, any, any, any]>
     ? ParamList
     : T
@@ -569,6 +569,13 @@ export type RouteProp<
   in out RouteName extends keyof ParamList = KeyOf<ParamList>,
 > = Route<Extract<RouteName, string>, ParamList[RouteName]>;
 
+type ScreenRouteProp<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = KeyOf<ParamList>,
+> = {
+  [Name in Extract<RouteName, string>]: RouteProp<ParamList, Name>;
+}[Extract<RouteName, string>];
+
 export type CompositeNavigationProp<
   A extends NavigationProp<ParamListBase, any, any, any, any>,
   B extends NavigationProp<ParamListBase, any, any, any, any>,
@@ -662,7 +669,7 @@ export type ScreenLayoutArgs<
   in out ScreenOptions extends {},
   in out Navigation,
 > = {
-  route: RouteProp<ParamList, RouteName>;
+  route: ScreenRouteProp<ParamList, RouteName>;
   options: ScreenOptions;
   navigation: Navigation;
   theme: Theme;
@@ -860,7 +867,7 @@ export type RouteGroupConfig<
     | (
         | ScreenOptions
         | ((props: {
-            route: RouteProp<ParamList, keyof ParamList>;
+            route: ScreenRouteProp<ParamList>;
             navigation: Navigation;
             theme: Theme;
           }) => ScreenOptions)
@@ -1647,7 +1654,7 @@ export type PathConfig<Params> = FlatType<
     path?: string | undefined;
     /**
      * 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)`.
      * Keys are constrained to valid param names when Params type is provided.
      *
      * @example

package/src/useDescriptors.tsx

@@ -315,7 +315,7 @@ export function useDescriptors<
       render() {
         return element;
       },
-      options: customOptions as ScreenOptions,
+      options: customOptions,
     };
 
     return acc;

package/src/useFocusEvents.tsx

@@ -51,7 +51,12 @@ export function useFocusEvents<State extends NavigationState>({
   React.useEffect(() => {
     const lastFocusedKey = lastFocusedKeyRef.current;
 
-    lastFocusedKeyRef.current = currentFocusedKey;
+    const isFocused = navigation ? navigation.isFocused() : true;
+
+    if (isFocused) {
+      // Remember the current route as focused if the navigator is focused
+      lastFocusedKeyRef.current = currentFocusedKey;
+    }
 
     // We wouldn't have `lastFocusedKey` on initial mount
     // Fire focus event for the current route on mount if there's no parent navigator
@@ -61,10 +66,7 @@ export function useFocusEvents<State extends NavigationState>({
 
     // We should only emit events when the focused key changed and navigator is focused
     // When navigator is not focused, screens inside shouldn't receive focused status either
-    if (
-      lastFocusedKey === currentFocusedKey ||
-      !(navigation ? navigation.isFocused() : true)
-    ) {
+    if (lastFocusedKey === currentFocusedKey || !isFocused) {
       return;
     }
 

package/src/useLazyValue.tsx

@@ -1,11 +1,11 @@
 import * as React from 'react';
 
-export function useLazyValue<T>(create: () => T) {
+export function useLazyValue<T>(create: () => T): T {
   const lazyRef = React.useRef<T>(undefined);
 
   if (lazyRef.current === undefined) {
     lazyRef.current = create();
   }
 
-  return lazyRef.current as T;
+  return lazyRef.current;
 }

package/src/useNavigationBuilder.tsx

@@ -337,7 +337,7 @@ export function useNavigationBuilder<
 
   const isNestedParamsConsumed =
     typeof route?.params === 'object' && route.params != null
-      ? consumedParams?.isConsumed(route.params)
+      ? consumedParams?.has(route.params)
       : false;
 
   const {
@@ -571,7 +571,14 @@ export function useNavigationBuilder<
         return [stateBeforeInitialization, hydratedState, true, paramsForState];
       }
 
-      return [undefined, hydratedState, false, paramsForState];
+      return [
+        undefined,
+        hydratedState,
+        false,
+        // Current state is already initialized
+        // So params weren't used, and need to be handled later
+        isStateInitialized(currentState) ? undefined : paramsForState,
+      ];
     }
     // We explicitly don't include routeNames, route.params etc. in the dep list
     // below. We want to avoid forcing a new state to be calculated in those cases
@@ -719,18 +726,16 @@ export function useNavigationBuilder<
         : nextState;
   }
 
-  const setConsumedParams = consumedParams?.setConsumed;
-
   React.useEffect(() => {
     if (
-      setConsumedParams &&
+      consumedParams &&
       didConsumeNestedParams &&
       typeof route?.params === 'object' &&
       route.params != null
     ) {
-      setConsumedParams(route.params);
+      consumedParams.set(route.params, true);
     }
-  }, [didConsumeNestedParams, route?.params, setConsumedParams]);
+  }, [consumedParams, didConsumeNestedParams, route?.params]);
 
   const shouldUpdate = state !== nextState;