@amazon-devices/react-navigation__routers 7.0.1759135970 → 8.0.9000000000

package/src/TabRouter.tsx

@@ -1,6 +1,7 @@
 import { nanoid } from 'nanoid/non-secure';
 
-import BaseRouter from './BaseRouter';
+import { BaseRouter } from './BaseRouter';
+import { createParamsFromAction } from './createParamsFromAction';
 import type {
   CommonNavigationAction,
   DefaultRouterOptions,
@@ -19,13 +20,23 @@ export type TabActionType = {
 };
 
 export type BackBehavior =
-  | 'initialRoute'
   | 'firstRoute'
-  | 'history'
+  | 'initialRoute'
   | 'order'
+  | 'history'
+  | 'fullHistory'
   | 'none';
 
 export type TabRouterOptions = DefaultRouterOptions & {
+  /**
+   * Control how going back should behave
+   * - `firstRoute` - return to the first defined route
+   * - `initialRoute` - return to the route from `initialRouteName`
+   * - `order` - return to the route defined before the focused route
+   * - `history` - return to last visited route; if the same route is visited multiple times, the older entries are dropped from the history
+   * - `fullHistory` - return to last visited route; doesn't drop duplicate entries unlike `history` - matches behavior of web pages
+   * - `none` - do not handle going back
+   */
   backBehavior?: BackBehavior;
 };
 
@@ -40,7 +51,11 @@ export type TabNavigationState<ParamList extends ParamListBase> = Omit<
   /**
    * List of previously visited route keys.
    */
-  history: { type: 'route'; key: string }[];
+  history: { type: 'route'; key: string; params?: object | undefined }[];
+  /**
+   * List of routes' key, which are supposed to be preloaded before navigating to.
+   */
+  preloadedRouteKeys: string[];
 };
 
 export type TabActionHelpers<ParamList extends ParamListBase> = {
@@ -50,18 +65,23 @@ export type TabActionHelpers<ParamList extends ParamListBase> = {
    * @param name Name of the route for the tab.
    * @param [params] Params object for the route.
    */
-  jumpTo<RouteName extends Extract<keyof ParamList, string>>(
-    ...args: undefined extends ParamList[RouteName]
-      ? [screen: RouteName] | [screen: RouteName, params: ParamList[RouteName]]
-      : [screen: RouteName, params: ParamList[RouteName]]
+  jumpTo<RouteName extends keyof ParamList>(
+    ...args: RouteName extends unknown
+      ? undefined extends ParamList[RouteName]
+        ? [screen: RouteName, params?: ParamList[RouteName]]
+        : [screen: RouteName, params: ParamList[RouteName]]
+      : never
   ): void;
 };
 
 const TYPE_ROUTE = 'route' as const;
 
 export const TabActions = {
-  jumpTo(name: string, params?: object): TabActionType {
-    return { type: 'JUMP_TO', payload: { name, params } };
+  jumpTo(name: string, params?: object) {
+    return {
+      type: 'JUMP_TO',
+      payload: { name, params },
+    } as const satisfies TabActionType;
   },
 };
 
@@ -71,13 +91,22 @@ const getRouteHistory = (
   backBehavior: BackBehavior,
   initialRouteName: string | undefined
 ) => {
-  const history = [{ type: TYPE_ROUTE, key: routes[index].key }];
+  const history = [
+    {
+      type: TYPE_ROUTE,
+      key: routes[index].key,
+    },
+  ];
+
   let initialRouteIndex;
 
   switch (backBehavior) {
     case 'order':
       for (let i = index; i > 0; i--) {
-        history.unshift({ type: TYPE_ROUTE, key: routes[i - 1].key });
+        history.unshift({
+          type: TYPE_ROUTE,
+          key: routes[i - 1].key,
+        });
       }
       break;
     case 'firstRoute':
@@ -102,6 +131,7 @@ const getRouteHistory = (
       }
       break;
     case 'history':
+    case 'fullHistory':
       // The history will fill up on navigation
       break;
   }
@@ -115,14 +145,37 @@ const changeIndex = (
   backBehavior: BackBehavior,
   initialRouteName: string | undefined
 ) => {
-  let history;
+  let history = state.history;
+
+  if (backBehavior === 'history' || backBehavior === 'fullHistory') {
+    const currentRoute = state.routes[index];
 
-  if (backBehavior === 'history') {
-    const currentKey = state.routes[index].key;
+    if (backBehavior === 'history') {
+      // Remove the existing key from the history to de-duplicate it
+      history = history.filter((it) =>
+        it.type === 'route' ? it.key !== currentRoute.key : false
+      );
+    } else if (backBehavior === 'fullHistory') {
+      const lastHistoryRouteItemIndex = history.findLastIndex(
+        (item) => item.type === 'route'
+      );
+
+      if (currentRoute.key === history[lastHistoryRouteItemIndex]?.key) {
+        // For full-history, only remove if it matches the last route
+        // Useful for drawer, if current route was in history, then drawer state changed
+        // Then we only need to move the route to the front
+        history = [
+          ...history.slice(0, lastHistoryRouteItemIndex),
+          ...history.slice(lastHistoryRouteItemIndex + 1),
+        ];
+      }
+    }
 
-    history = state.history
-      .filter((it) => (it.type === 'route' ? it.key !== currentKey : false))
-      .concat({ type: TYPE_ROUTE, key: currentKey });
+    history = history.concat({
+      type: TYPE_ROUTE,
+      key: currentRoute.key,
+      params: backBehavior === 'fullHistory' ? currentRoute.params : undefined,
+    });
   } else {
     history = getRouteHistory(
       state.routes,
@@ -139,7 +192,7 @@ const changeIndex = (
   };
 };
 
-export default function TabRouter({
+export function TabRouter({
   initialRouteName,
   backBehavior = 'firstRoute',
 }: TabRouterOptions) {
@@ -178,11 +231,12 @@ export default function TabRouter({
         routeNames,
         history,
         routes,
+        preloadedRouteKeys: [],
       };
     },
 
     getRehydratedState(partialState, { routeNames, routeParamList }) {
-      let state = partialState;
+      const state = partialState;
 
       if (state.stale === false) {
         return state;
@@ -207,8 +261,8 @@ export default function TabRouter({
                   ...(route ? route.params : undefined),
                 }
               : route
-              ? route.params
-              : undefined,
+                ? route.params
+                : undefined,
         } as Route<string>;
       });
 
@@ -217,9 +271,10 @@ export default function TabRouter({
         routes.length - 1
       );
 
+      const routeKeys = routes.map((route) => route.key);
+
       const history =
-        state.history?.filter((it) => routes.find((r) => r.key === it.key)) ??
-        [];
+        state.history?.filter((it) => routeKeys.includes(it.key)) ?? [];
 
       return changeIndex(
         {
@@ -230,6 +285,10 @@ export default function TabRouter({
           routeNames,
           history,
           routes,
+          preloadedRouteKeys:
+            state.preloadedRouteKeys?.filter((key) =>
+              routeKeys.includes(key)
+            ) ?? [],
         },
         index,
         backBehavior,
@@ -293,28 +352,21 @@ export default function TabRouter({
     getStateForAction(state, action, { routeParamList, routeGetIdList }) {
       switch (action.type) {
         case 'JUMP_TO':
-        case 'NAVIGATE': {
-          let index = -1;
-
-          if (action.type === 'NAVIGATE' && action.payload.key) {
-            index = state.routes.findIndex(
-              (route) => route.key === action.payload.key
-            );
-          } else {
-            index = state.routes.findIndex(
-              (route) => route.name === action.payload.name
-            );
-          }
+        case 'NAVIGATE':
+        case 'NAVIGATE_DEPRECATED': {
+          const index = state.routes.findIndex(
+            (route) => route.name === action.payload.name
+          );
 
           if (index === -1) {
             return null;
           }
 
-          return changeIndex(
+          const updatedState = changeIndex(
             {
               ...state,
-              routes: state.routes.map((route, i) => {
-                if (i !== index) {
+              routes: state.routes.map((route) => {
+                if (route.name !== action.payload.name) {
                   return route;
                 }
 
@@ -331,7 +383,8 @@ export default function TabRouter({
                 let params;
 
                 if (
-                  action.type === 'NAVIGATE' &&
+                  (action.type === 'NAVIGATE' ||
+                    action.type === 'NAVIGATE_DEPRECATED') &&
                   action.payload.merge &&
                   currentId === nextId
                 ) {
@@ -345,13 +398,7 @@ export default function TabRouter({
                         }
                       : route.params;
                 } else {
-                  params =
-                    routeParamList[route.name] !== undefined
-                      ? {
-                          ...routeParamList[route.name],
-                          ...action.payload.params,
-                        }
-                      : action.payload.params;
+                  params = createParamsFromAction({ action, routeParamList });
                 }
 
                 const path =
@@ -368,6 +415,46 @@ export default function TabRouter({
             backBehavior,
             initialRouteName
           );
+
+          return {
+            ...updatedState,
+            preloadedRouteKeys: updatedState.preloadedRouteKeys.filter(
+              (key) => key !== state.routes[updatedState.index].key
+            ),
+          };
+        }
+
+        case 'SET_PARAMS':
+        case 'REPLACE_PARAMS': {
+          const nextState = BaseRouter.getStateForAction(state, action);
+
+          if (nextState !== null) {
+            const index = nextState.index;
+
+            if (index != null) {
+              const focusedRoute = nextState.routes[index];
+              const historyItemIndex = state.history.findLastIndex(
+                (item) => item.key === focusedRoute.key
+              );
+
+              let updatedHistory = state.history;
+
+              if (historyItemIndex !== -1) {
+                updatedHistory = [...state.history];
+                updatedHistory[historyItemIndex] = {
+                  ...updatedHistory[historyItemIndex],
+                  params: focusedRoute.params,
+                };
+              }
+
+              return {
+                ...nextState,
+                history: updatedHistory,
+              };
+            }
+          }
+
+          return nextState;
         }
 
         case 'GO_BACK': {
@@ -375,8 +462,9 @@ export default function TabRouter({
             return null;
           }
 
-          const previousKey = state.history[state.history.length - 2].key;
-          const index = state.routes.findIndex(
+          const previousHistoryItem = state.history[state.history.length - 2];
+          const previousKey = previousHistoryItem?.key;
+          const index = state.routes.findLastIndex(
             (route) => route.key === previousKey
           );
 
@@ -384,22 +472,73 @@ export default function TabRouter({
             return null;
           }
 
+          let routes = state.routes;
+
+          if (
+            backBehavior === 'fullHistory' &&
+            routes[index].params !== previousHistoryItem.params
+          ) {
+            routes = [...state.routes];
+            routes[index] = {
+              ...routes[index],
+              params: previousHistoryItem.params,
+            };
+          }
+
           return {
             ...state,
+            routes,
+            preloadedRouteKeys: state.preloadedRouteKeys.filter(
+              (key) => key !== state.routes[index].key
+            ),
             history: state.history.slice(0, -1),
             index,
           };
         }
 
+        case 'PRELOAD': {
+          const routeIndex = state.routes.findIndex(
+            (route) => route.name === action.payload.name
+          );
+
+          if (routeIndex === -1) {
+            return null;
+          }
+
+          const route = state.routes[routeIndex];
+
+          const getId = routeGetIdList[route.name];
+
+          const currentId = getId?.({ params: route.params });
+          const nextId = getId?.({ params: action.payload.params });
+
+          const key =
+            currentId === nextId ? route.key : `${route.name}-${nanoid()}`;
+
+          const params = createParamsFromAction({ action, routeParamList });
+          const newRoute =
+            params !== route.params ? { ...route, key, params } : route;
+
+          return {
+            ...state,
+            preloadedRouteKeys: state.preloadedRouteKeys
+              .filter((key) => key !== route.key)
+              .concat(newRoute.key),
+            routes: state.routes.map((route, index) =>
+              index === routeIndex ? newRoute : route
+            ),
+            history:
+              key === route.key
+                ? state.history
+                : state.history.filter((record) => record.key !== route.key),
+          };
+        }
+
         default:
           return BaseRouter.getStateForAction(state, action);
       }
     },
 
-    shouldActionChangeFocus(action) {
-      return action.type === 'NAVIGATE';
-    },
-
     actionCreators: TabActions,
   };
 

package/src/createParamsFromAction.tsx

@@ -0,0 +1,22 @@
+import type { ParamListBase } from './types';
+
+type Options = {
+  action: {
+    payload: {
+      name: string;
+      params?: object;
+    };
+  };
+  routeParamList: ParamListBase;
+};
+
+export function createParamsFromAction({ action, routeParamList }: Options) {
+  const { name, params } = action.payload;
+
+  return routeParamList[name] !== undefined
+    ? {
+        ...routeParamList[name],
+        ...params,
+      }
+    : params;
+}

package/src/createRouteFromAction.tsx

@@ -0,0 +1,24 @@
+import { nanoid } from 'nanoid/non-secure';
+
+import { createParamsFromAction } from './createParamsFromAction';
+import type { ParamListBase } from './types';
+
+type Options = {
+  action: {
+    payload: {
+      name: string;
+      params?: object;
+    };
+  };
+  routeParamList: ParamListBase;
+};
+
+export function createRouteFromAction({ action, routeParamList }: Options) {
+  const { name } = action.payload;
+
+  return {
+    key: `${name}-${nanoid()}`,
+    name,
+    params: createParamsFromAction({ action, routeParamList }),
+  };
+}

package/src/index.tsx

@@ -2,7 +2,7 @@ import * as CommonActions from './CommonActions';
 
 export { CommonActions };
 
-export { default as BaseRouter } from './BaseRouter';
+export { BaseRouter } from './BaseRouter';
 export type {
   DrawerActionHelpers,
   DrawerActionType,
@@ -10,19 +10,19 @@ export type {
   DrawerRouterOptions,
   DrawerStatus,
 } from './DrawerRouter';
-export { DrawerActions, default as DrawerRouter } from './DrawerRouter';
+export { DrawerActions, DrawerRouter } from './DrawerRouter';
 export type {
   StackActionHelpers,
   StackActionType,
   StackNavigationState,
   StackRouterOptions,
 } from './StackRouter';
-export { StackActions, default as StackRouter } from './StackRouter';
+export { StackActions, StackRouter } from './StackRouter';
 export type {
   TabActionHelpers,
   TabActionType,
   TabNavigationState,
   TabRouterOptions,
 } from './TabRouter';
-export { TabActions, default as TabRouter } from './TabRouter';
+export { TabActions, TabRouter } from './TabRouter';
 export * from './types';

package/src/types.tsx

@@ -2,9 +2,9 @@ import type * as CommonActions from './CommonActions';
 
 export type CommonNavigationAction = CommonActions.Action;
 
-type NavigationRoute<
+export type NavigationRoute<
   ParamList extends ParamListBase,
-  RouteName extends keyof ParamList
+  RouteName extends keyof ParamList,
 > = Route<Extract<RouteName, string>, ParamList[RouteName]> & {
   state?: NavigationState | PartialState<NavigationState>;
 };
@@ -64,7 +64,7 @@ export type PartialState<State extends NavigationState> = Partial<
 
 export type Route<
   RouteName extends string,
-  Params extends object | undefined = object | undefined
+  Params extends object | undefined = object | undefined,
 > = Readonly<{
   /**
    * Unique key for the route.
@@ -130,7 +130,7 @@ export type DefaultRouterOptions<RouteName extends string = string> = {
 export type RouterFactory<
   State extends NavigationState,
   Action extends NavigationAction,
-  RouterOptions extends DefaultRouterOptions
+  RouterOptions extends DefaultRouterOptions,
 > = (options: RouterOptions) => Router<State, Action>;
 
 export type RouterConfigOptions = {
@@ -145,7 +145,7 @@ export type RouterConfigOptions = {
 
 export type Router<
   State extends NavigationState,
-  Action extends NavigationAction
+  Action extends NavigationAction,
 > = {
   /**
    * Type of the router. Should match the `type` property in state.