@amazon-devices/react-navigation__routers 7.0.1759135970 → 8.0.9000000000

package/src/StackRouter.tsx

@@ -1,9 +1,12 @@
 import { nanoid } from 'nanoid/non-secure';
 
-import BaseRouter from './BaseRouter';
+import { BaseRouter } from './BaseRouter';
+import { createParamsFromAction } from './createParamsFromAction';
+import { createRouteFromAction } from './createRouteFromAction';
 import type {
   CommonNavigationAction,
   DefaultRouterOptions,
+  NavigationRoute,
   NavigationState,
   ParamListBase,
   Route,
@@ -13,7 +16,7 @@ import type {
 export type StackActionType =
   | {
       type: 'REPLACE';
-      payload: { name: string; key?: string | undefined; params?: object };
+      payload: { name: string; params?: object };
       source?: string;
       target?: string;
     }
@@ -33,6 +36,16 @@ export type StackActionType =
       type: 'POP_TO_TOP';
       source?: string;
       target?: string;
+    }
+  | {
+      type: 'POP_TO';
+      payload: {
+        name: string;
+        params?: object;
+        merge?: boolean;
+      };
+      source?: string;
+      target?: string;
     };
 
 export type StackRouterOptions = DefaultRouterOptions;
@@ -43,31 +56,39 @@ export type StackNavigationState<ParamList extends ParamListBase> =
      * Type of the router, in this case, it's stack.
      */
     type: 'stack';
+    /**
+     * List of routes, which are supposed to be preloaded before navigating to.
+     */
+    preloadedRoutes: NavigationRoute<ParamList, keyof ParamList>[];
   };
 
 export type StackActionHelpers<ParamList extends ParamListBase> = {
   /**
    * Replace the current route with a new one.
    *
-   * @param name Route name of the new route.
+   * @param name Name of the new route.
    * @param [params] Params object for the new route.
    */
   replace<RouteName extends keyof ParamList>(
-    ...args: undefined extends ParamList[RouteName]
-      ? [screen: RouteName] | [screen: RouteName, params: ParamList[RouteName]]
-      : [screen: RouteName, params: ParamList[RouteName]]
+    ...args: {
+      [Screen in keyof ParamList]: undefined extends ParamList[Screen]
+        ? [screen: Screen] | [screen: Screen, params: ParamList[Screen]]
+        : [screen: Screen, params: ParamList[Screen]];
+    }[RouteName]
   ): void;
 
   /**
    * Push a new screen onto the stack.
    *
-   * @param name Name of the route for the tab.
+   * @param name Name of the route to push onto the stack.
    * @param [params] Params object for the route.
    */
   push<RouteName extends keyof ParamList>(
-    ...args: undefined extends ParamList[RouteName]
-      ? [screen: RouteName] | [screen: RouteName, params: ParamList[RouteName]]
-      : [screen: RouteName, params: ParamList[RouteName]]
+    ...args: {
+      [Screen in keyof ParamList]: undefined extends ParamList[Screen]
+        ? [screen: Screen] | [screen: Screen, params: ParamList[Screen]]
+        : [screen: Screen, params: ParamList[Screen]];
+    }[RouteName]
   ): void;
 
   /**
@@ -79,24 +100,70 @@ export type StackActionHelpers<ParamList extends ParamListBase> = {
    * Pop to the first route in the stack, dismissing all other screens.
    */
   popToTop(): void;
+
+  /**
+   * Pop any screens to go back to the specified screen.
+   * If the specified screen doesn't exist, it'll be added to the stack.
+   *
+   * @param name Name of the route to navigate to.
+   * @param [params] Params object for the route.
+   * @param [merge] Whether to merge the params onto the route.
+   */
+  popTo<RouteName extends keyof ParamList>(
+    ...args: {
+      [Screen in keyof ParamList]: undefined extends ParamList[Screen]
+        ?
+            | [screen: Screen]
+            | [screen: Screen, params: ParamList[Screen]]
+            | [screen: Screen, params: ParamList[Screen], merge: boolean]
+        :
+            | [screen: Screen, params: ParamList[Screen]]
+            | [screen: Screen, params: ParamList[Screen], merge: boolean];
+    }[RouteName]
+  ): void;
 };
 
 export const StackActions = {
-  replace(name: string, params?: object): StackActionType {
-    return { type: 'REPLACE', payload: { name, params } };
+  replace(name: string, params?: object) {
+    return {
+      type: 'REPLACE',
+      payload: { name, params },
+    } as const satisfies StackActionType;
   },
-  push(name: string, params?: object): StackActionType {
-    return { type: 'PUSH', payload: { name, params } };
+  push(name: string, params?: object) {
+    return {
+      type: 'PUSH',
+      payload: { name, params },
+    } as const satisfies StackActionType;
   },
-  pop(count: number = 1): StackActionType {
-    return { type: 'POP', payload: { count } };
+  pop(count: number = 1) {
+    return {
+      type: 'POP',
+      payload: { count },
+    } as const satisfies StackActionType;
   },
-  popToTop(): StackActionType {
-    return { type: 'POP_TO_TOP' };
+  popToTop() {
+    return { type: 'POP_TO_TOP' } as const satisfies StackActionType;
+  },
+  popTo(name: string, params?: object, options?: { merge?: boolean }) {
+    if (typeof options === 'boolean') {
+      console.warn(
+        `Passing a boolean as the third argument to 'popTo' is deprecated. Pass '{ merge: true }' instead.`
+      );
+    }
+
+    return {
+      type: 'POP_TO',
+      payload: {
+        name,
+        params,
+        merge: typeof options === 'boolean' ? options : options?.merge,
+      },
+    } as const satisfies StackActionType;
   },
 };
 
-export default function StackRouter(options: StackRouterOptions) {
+export function StackRouter(options: StackRouterOptions) {
   const router: Router<
     StackNavigationState<ParamListBase>,
     CommonNavigationAction | StackActionType
@@ -118,6 +185,7 @@ export default function StackRouter(options: StackRouterOptions) {
         key: `stack-${nanoid()}`,
         index: 0,
         routeNames,
+        preloadedRoutes: [],
         routes: [
           {
             key: `${initialRouteName}-${nanoid()}`,
@@ -129,7 +197,7 @@ export default function StackRouter(options: StackRouterOptions) {
     },
 
     getRehydratedState(partialState, { routeNames, routeParamList }) {
-      let state = partialState;
+      const state = partialState;
 
       if (state.stale === false) {
         return state;
@@ -137,20 +205,35 @@ export default function StackRouter(options: StackRouterOptions) {
 
       const routes = state.routes
         .filter((route) => routeNames.includes(route.name))
-        .map(
-          (route) =>
-            ({
-              ...route,
-              key: route.key || `${route.name}-${nanoid()}`,
-              params:
-                routeParamList[route.name] !== undefined
-                  ? {
-                      ...routeParamList[route.name],
-                      ...route.params,
-                    }
-                  : route.params,
-            } as Route<string>)
-        );
+        .map((route) => ({
+          ...route,
+          key: route.key || `${route.name}-${nanoid()}`,
+          params:
+            routeParamList[route.name] !== undefined
+              ? {
+                  ...routeParamList[route.name],
+                  ...route.params,
+                }
+              : route.params,
+        }));
+
+      const preloadedRoutes =
+        state.preloadedRoutes
+          ?.filter((route) => routeNames.includes(route.name))
+          .map(
+            (route) =>
+              ({
+                ...route,
+                key: route.key || `${route.name}-${nanoid()}`,
+                params:
+                  routeParamList[route.name] !== undefined
+                    ? {
+                        ...routeParamList[route.name],
+                        ...route.params,
+                      }
+                    : route.params,
+              }) as Route<string>
+          ) ?? [];
 
       if (routes.length === 0) {
         const initialRouteName =
@@ -172,6 +255,7 @@ export default function StackRouter(options: StackRouterOptions) {
         index: routes.length - 1,
         routeNames,
         routes,
+        preloadedRoutes,
       };
     },
 
@@ -226,105 +310,223 @@ export default function StackRouter(options: StackRouterOptions) {
 
       switch (action.type) {
         case 'REPLACE': {
-          const index =
+          const currentIndex =
             action.target === state.key && action.source
               ? state.routes.findIndex((r) => r.key === action.source)
               : state.index;
 
-          if (index === -1) {
+          if (currentIndex === -1) {
             return null;
           }
 
-          const { name, key, params } = action.payload;
-
-          if (!state.routeNames.includes(name)) {
+          if (!state.routeNames.includes(action.payload.name)) {
             return null;
           }
 
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
+
+          // Re-use preloaded route if available
+          let route = state.preloadedRoutes.find(
+            (route) =>
+              route.name === action.payload.name &&
+              id === getId?.({ params: route.params })
+          );
+
+          if (!route) {
+            route = createRouteFromAction({ action, routeParamList });
+          }
+
           return {
             ...state,
-            routes: state.routes.map((route, i) =>
-              i === index
-                ? {
-                    key: key !== undefined ? key : `${name}-${nanoid()}`,
-                    name,
-                    params:
-                      routeParamList[name] !== undefined
-                        ? {
-                            ...routeParamList[name],
-                            ...params,
-                          }
-                        : params,
-                  }
-                : route
+            routes: state.routes.map((r, i) =>
+              i === currentIndex ? route : r
+            ),
+            preloadedRoutes: state.preloadedRoutes.filter(
+              (r) => r.key !== route.key
             ),
           };
         }
 
         case 'PUSH':
-          if (state.routeNames.includes(action.payload.name)) {
-            const getId = options.routeGetIdList[action.payload.name];
-            const id = getId?.({ params: action.payload.params });
-
-            const route = id
-              ? state.routes.find(
-                  (route) =>
-                    route.name === action.payload.name &&
-                    id === getId?.({ params: route.params })
-                )
-              : undefined;
+        case 'NAVIGATE': {
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
+          }
 
-            let routes: Route<string>[];
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
 
-            if (route) {
-              routes = state.routes.filter((r) => r.key !== route.key);
-              routes.push({
-                ...route,
-                params:
-                  routeParamList[action.payload.name] !== undefined
-                    ? {
-                        ...routeParamList[action.payload.name],
-                        ...action.payload.params,
-                      }
-                    : action.payload.params,
-              });
-            } else {
-              routes = [
-                ...state.routes,
-                {
-                  key: `${action.payload.name}-${nanoid()}`,
-                  name: action.payload.name,
-                  params:
-                    routeParamList[action.payload.name] !== undefined
-                      ? {
-                          ...routeParamList[action.payload.name],
-                          ...action.payload.params,
-                        }
-                      : action.payload.params,
-                },
-              ];
+          let route: Route<string> | undefined;
+
+          if (id !== undefined) {
+            route = state.routes.find(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
+          } else {
+            const currentRoute = state.routes[state.index];
+
+            // If the route matches the current one, then navigate to it
+            if (
+              action.type === 'NAVIGATE' &&
+              action.payload.name === currentRoute.name
+            ) {
+              route = currentRoute;
             }
+          }
+
+          if (!route) {
+            route = state.preloadedRoutes.find(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
+          }
+
+          let params;
+
+          if (action.type === 'NAVIGATE' && action.payload.merge && route) {
+            params =
+              action.payload.params !== undefined ||
+              routeParamList[action.payload.name] !== undefined
+                ? {
+                    ...routeParamList[action.payload.name],
+                    ...route.params,
+                    ...action.payload.params,
+                  }
+                : route.params;
+          } else {
+            params = createParamsFromAction({ action, routeParamList });
+          }
+
+          let routes: Route<string>[];
+
+          if (route) {
+            const routeKey = route.key;
+
+            routes = state.routes.filter((r) => r.key !== routeKey);
+            routes.push({
+              ...route,
+              path:
+                action.type === 'NAVIGATE' && action.payload.path !== undefined
+                  ? action.payload.path
+                  : route.path,
+              params,
+            });
+          } else {
+            routes = [
+              ...state.routes,
+              {
+                key: `${action.payload.name}-${nanoid()}`,
+                name: action.payload.name,
+                path:
+                  action.type === 'NAVIGATE' ? action.payload.path : undefined,
+                params,
+              },
+            ];
+          }
+
+          return {
+            ...state,
+            index: routes.length - 1,
+            preloadedRoutes: state.preloadedRoutes.filter(
+              (route) => routes[routes.length - 1].key !== route.key
+            ),
+            routes,
+          };
+        }
+
+        case 'NAVIGATE_DEPRECATED': {
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
+          }
+
+          if (
+            state.preloadedRoutes.find(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            )
+          ) {
+            return null;
+          }
+
+          // If the route already exists, navigate to that
+          let index = -1;
+
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
+
+          if (id !== undefined) {
+            index = state.routes.findIndex(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
+          } else if (state.routes[state.index].name === action.payload.name) {
+            index = state.index;
+          } else {
+            index = state.routes.findLastIndex(
+              (route) => route.name === action.payload.name
+            );
+          }
+
+          if (index === -1) {
+            const routes = [
+              ...state.routes,
+              createRouteFromAction({ action, routeParamList }),
+            ];
 
             return {
               ...state,
-              index: routes.length - 1,
               routes,
+              index: routes.length - 1,
             };
           }
 
-          return null;
+          const route = state.routes[index];
+
+          let params;
+
+          if (action.payload.merge) {
+            params =
+              action.payload.params !== undefined ||
+              routeParamList[route.name] !== undefined
+                ? {
+                    ...routeParamList[route.name],
+                    ...route.params,
+                    ...action.payload.params,
+                  }
+                : route.params;
+          } else {
+            params = createParamsFromAction({ action, routeParamList });
+          }
+
+          return {
+            ...state,
+            index,
+            routes: [
+              ...state.routes.slice(0, index),
+              params !== route.params
+                ? { ...route, params }
+                : state.routes[index],
+            ],
+          };
+        }
 
         case 'POP': {
-          const index =
+          const currentIndex =
             action.target === state.key && action.source
               ? state.routes.findIndex((r) => r.key === action.source)
               : state.index;
 
-          if (index > 0) {
-            const count = Math.max(index - action.payload.count + 1, 1);
+          if (currentIndex > 0) {
+            const count = Math.max(currentIndex - action.payload.count + 1, 1);
             const routes = state.routes
               .slice(0, count)
-              .concat(state.routes.slice(index + 1));
+              .concat(state.routes.slice(currentIndex + 1));
 
             return {
               ...state,
@@ -346,126 +548,97 @@ export default function StackRouter(options: StackRouterOptions) {
             options
           );
 
-        case 'NAVIGATE':
-          if (
-            action.payload.name !== undefined &&
-            !state.routeNames.includes(action.payload.name)
-          ) {
+        case 'POP_TO': {
+          const currentIndex =
+            action.target === state.key && action.source
+              ? state.routes.findLastIndex((r) => r.key === action.source)
+              : state.index;
+
+          if (currentIndex === -1) {
             return null;
           }
 
-          if (action.payload.key || action.payload.name) {
-            // If the route already exists, navigate to that
-            let index = -1;
-
-            const getId =
-              // `getId` and `key` can't be used together
-              action.payload.key === undefined &&
-              action.payload.name !== undefined
-                ? options.routeGetIdList[action.payload.name]
-                : undefined;
-            const id = getId?.({ params: action.payload.params });
-
-            if (id) {
-              index = state.routes.findIndex(
-                (route) =>
-                  route.name === action.payload.name &&
-                  id === getId?.({ params: route.params })
-              );
-            } else if (
-              (state.routes[state.index].name === action.payload.name &&
-                action.payload.key === undefined) ||
-              state.routes[state.index].key === action.payload.key
-            ) {
-              index = state.index;
-            } else {
-              for (let i = state.routes.length - 1; i >= 0; i--) {
-                if (
-                  (state.routes[i].name === action.payload.name &&
-                    action.payload.key === undefined) ||
-                  state.routes[i].key === action.payload.key
-                ) {
-                  index = i;
-                  break;
-                }
+          if (!state.routeNames.includes(action.payload.name)) {
+            return null;
+          }
+
+          // If the route already exists, navigate to it
+          let index = -1;
+
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
+
+          if (id !== undefined) {
+            index = state.routes.findIndex(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
+          } else if (state.routes[currentIndex].name === action.payload.name) {
+            index = currentIndex;
+          } else {
+            for (let i = currentIndex; i >= 0; i--) {
+              if (state.routes[i].name === action.payload.name) {
+                index = i;
+                break;
               }
             }
+          }
 
-            if (
-              index === -1 &&
-              action.payload.key &&
-              action.payload.name === undefined
-            ) {
-              return null;
-            }
+          // If the route doesn't exist, remove the current route and add the new one
+          if (index === -1) {
+            // Re-use preloaded route if available
+            let route = state.preloadedRoutes.find(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
 
-            if (index === -1 && action.payload.name !== undefined) {
-              const routes = [
-                ...state.routes,
-                {
-                  key:
-                    action.payload.key ?? `${action.payload.name}-${nanoid()}`,
-                  name: action.payload.name,
-                  path: action.payload.path,
-                  params:
-                    routeParamList[action.payload.name] !== undefined
-                      ? {
-                          ...routeParamList[action.payload.name],
-                          ...action.payload.params,
-                        }
-                      : action.payload.params,
-                },
-              ];
-
-              return {
-                ...state,
-                routes,
-                index: routes.length - 1,
-              };
+            if (!route) {
+              route = createRouteFromAction({ action, routeParamList });
             }
 
-            const route = state.routes[index];
-
-            let params;
-
-            if (action.payload.merge) {
-              params =
-                action.payload.params !== undefined ||
-                routeParamList[route.name] !== undefined
-                  ? {
-                      ...routeParamList[route.name],
-                      ...route.params,
-                      ...action.payload.params,
-                    }
-                  : route.params;
-            } else {
-              params =
-                routeParamList[route.name] !== undefined
-                  ? {
-                      ...routeParamList[route.name],
-                      ...action.payload.params,
-                    }
-                  : action.payload.params;
-            }
+            const routes = state.routes.slice(0, currentIndex).concat(route);
 
             return {
               ...state,
-              index,
-              routes: [
-                ...state.routes.slice(0, index),
-                params !== route.params ||
-                (action.payload.path && action.payload.path !== route.path)
-                  ? {
-                      ...route,
-                      path: action.payload.path ?? route.path,
-                      params,
-                    }
-                  : state.routes[index],
-              ],
+              index: routes.length - 1,
+              routes,
+              preloadedRoutes: state.preloadedRoutes.filter(
+                (r) => r.key !== route.key
+              ),
             };
           }
 
-          return null;
+          const route = state.routes[index];
+
+          let params;
+
+          if (action.payload.merge) {
+            params =
+              action.payload.params !== undefined ||
+              routeParamList[route.name] !== undefined
+                ? {
+                    ...routeParamList[route.name],
+                    ...route.params,
+                    ...action.payload.params,
+                  }
+                : route.params;
+          } else {
+            params = createParamsFromAction({ action, routeParamList });
+          }
+
+          return {
+            ...state,
+            index,
+            routes: [
+              ...state.routes.slice(0, index),
+              params !== route.params
+                ? { ...route, params }
+                : state.routes[index],
+            ],
+          };
+        }
 
         case 'GO_BACK':
           if (state.index > 0) {
@@ -483,6 +656,47 @@ export default function StackRouter(options: StackRouterOptions) {
 
           return null;
 
+        case 'PRELOAD': {
+          const getId = options.routeGetIdList[action.payload.name];
+          const id = getId?.({ params: action.payload.params });
+
+          let route: Route<string> | undefined;
+
+          if (id !== undefined) {
+            route = state.routes.find(
+              (route) =>
+                route.name === action.payload.name &&
+                id === getId?.({ params: route.params })
+            );
+          }
+
+          if (route) {
+            return {
+              ...state,
+              routes: state.routes.map((r) => {
+                if (r.key !== route?.key) {
+                  return r;
+                }
+                return {
+                  ...r,
+                  params: createParamsFromAction({ action, routeParamList }),
+                };
+              }),
+            };
+          } else {
+            return {
+              ...state,
+              preloadedRoutes: state.preloadedRoutes
+                .filter(
+                  (r) =>
+                    r.name !== action.payload.name ||
+                    id !== getId?.({ params: r.params })
+                )
+                .concat(createRouteFromAction({ action, routeParamList })),
+            };
+          }
+        }
+
         default:
           return BaseRouter.getStateForAction(state, action);
       }