@amazon-devices/react-navigation__routers 2.0.1758683737

package/src/TabRouter.tsx

@@ -0,0 +1,407 @@
+import { nanoid } from 'nanoid/non-secure';
+
+import BaseRouter from './BaseRouter';
+import type {
+  CommonNavigationAction,
+  DefaultRouterOptions,
+  NavigationState,
+  ParamListBase,
+  PartialState,
+  Route,
+  Router,
+} from './types';
+
+export type TabActionType = {
+  type: 'JUMP_TO';
+  payload: { name: string; params?: object };
+  source?: string;
+  target?: string;
+};
+
+export type BackBehavior =
+  | 'initialRoute'
+  | 'firstRoute'
+  | 'history'
+  | 'order'
+  | 'none';
+
+export type TabRouterOptions = DefaultRouterOptions & {
+  backBehavior?: BackBehavior;
+};
+
+export type TabNavigationState<ParamList extends ParamListBase> = Omit<
+  NavigationState<ParamList>,
+  'history'
+> & {
+  /**
+   * Type of the router, in this case, it's tab.
+   */
+  type: 'tab';
+  /**
+   * List of previously visited route keys.
+   */
+  history: { type: 'route'; key: string }[];
+};
+
+export type TabActionHelpers<ParamList extends ParamListBase> = {
+  /**
+   * Jump to an existing tab.
+   *
+   * @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]]
+  ): void;
+};
+
+const TYPE_ROUTE = 'route' as const;
+
+export const TabActions = {
+  jumpTo(name: string, params?: object): TabActionType {
+    return { type: 'JUMP_TO', payload: { name, params } };
+  },
+};
+
+const getRouteHistory = (
+  routes: Route<string>[],
+  index: number,
+  backBehavior: BackBehavior,
+  initialRouteName: string | undefined
+) => {
+  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 });
+      }
+      break;
+    case 'firstRoute':
+      if (index !== 0) {
+        history.unshift({
+          type: TYPE_ROUTE,
+          key: routes[0].key,
+        });
+      }
+      break;
+    case 'initialRoute':
+      initialRouteIndex = routes.findIndex(
+        (route) => route.name === initialRouteName
+      );
+      initialRouteIndex = initialRouteIndex === -1 ? 0 : initialRouteIndex;
+
+      if (index !== initialRouteIndex) {
+        history.unshift({
+          type: TYPE_ROUTE,
+          key: routes[initialRouteIndex].key,
+        });
+      }
+      break;
+    case 'history':
+      // The history will fill up on navigation
+      break;
+  }
+
+  return history;
+};
+
+const changeIndex = (
+  state: TabNavigationState<ParamListBase>,
+  index: number,
+  backBehavior: BackBehavior,
+  initialRouteName: string | undefined
+) => {
+  let history;
+
+  if (backBehavior === 'history') {
+    const currentKey = state.routes[index].key;
+
+    history = state.history
+      .filter((it) => (it.type === 'route' ? it.key !== currentKey : false))
+      .concat({ type: TYPE_ROUTE, key: currentKey });
+  } else {
+    history = getRouteHistory(
+      state.routes,
+      index,
+      backBehavior,
+      initialRouteName
+    );
+  }
+
+  return {
+    ...state,
+    index,
+    history,
+  };
+};
+
+export default function TabRouter({
+  initialRouteName,
+  backBehavior = 'firstRoute',
+}: TabRouterOptions) {
+  const router: Router<
+    TabNavigationState<ParamListBase>,
+    TabActionType | CommonNavigationAction
+  > = {
+    ...BaseRouter,
+
+    type: 'tab',
+
+    getInitialState({ routeNames, routeParamList }) {
+      const index =
+        initialRouteName !== undefined && routeNames.includes(initialRouteName)
+          ? routeNames.indexOf(initialRouteName)
+          : 0;
+
+      const routes = routeNames.map((name) => ({
+        name,
+        key: `${name}-${nanoid()}`,
+        params: routeParamList[name],
+      }));
+
+      const history = getRouteHistory(
+        routes,
+        index,
+        backBehavior,
+        initialRouteName
+      );
+
+      return {
+        stale: false,
+        type: 'tab',
+        key: `tab-${nanoid()}`,
+        index,
+        routeNames,
+        history,
+        routes,
+      };
+    },
+
+    getRehydratedState(partialState, { routeNames, routeParamList }) {
+      let state = partialState;
+
+      if (state.stale === false) {
+        return state;
+      }
+
+      const routes = routeNames.map((name) => {
+        const route = (
+          state as PartialState<TabNavigationState<ParamListBase>>
+        ).routes.find((r) => r.name === name);
+
+        return {
+          ...route,
+          name,
+          key:
+            route && route.name === name && route.key
+              ? route.key
+              : `${name}-${nanoid()}`,
+          params:
+            routeParamList[name] !== undefined
+              ? {
+                  ...routeParamList[name],
+                  ...(route ? route.params : undefined),
+                }
+              : route
+              ? route.params
+              : undefined,
+        } as Route<string>;
+      });
+
+      const index = Math.min(
+        Math.max(routeNames.indexOf(state.routes[state?.index ?? 0]?.name), 0),
+        routes.length - 1
+      );
+
+      const history =
+        state.history?.filter((it) => routes.find((r) => r.key === it.key)) ??
+        [];
+
+      return changeIndex(
+        {
+          stale: false,
+          type: 'tab',
+          key: `tab-${nanoid()}`,
+          index,
+          routeNames,
+          history,
+          routes,
+        },
+        index,
+        backBehavior,
+        initialRouteName
+      );
+    },
+
+    getStateForRouteNamesChange(
+      state,
+      { routeNames, routeParamList, routeKeyChanges }
+    ) {
+      const routes = routeNames.map(
+        (name) =>
+          state.routes.find(
+            (r) => r.name === name && !routeKeyChanges.includes(r.name)
+          ) || {
+            name,
+            key: `${name}-${nanoid()}`,
+            params: routeParamList[name],
+          }
+      );
+
+      const index = Math.max(
+        0,
+        routeNames.indexOf(state.routes[state.index].name)
+      );
+
+      let history = state.history.filter(
+        // Type will always be 'route' for tabs, but could be different in a router extending this (e.g. drawer)
+        (it) => it.type !== 'route' || routes.find((r) => r.key === it.key)
+      );
+
+      if (!history.length) {
+        history = getRouteHistory(
+          routes,
+          index,
+          backBehavior,
+          initialRouteName
+        );
+      }
+
+      return {
+        ...state,
+        history,
+        routeNames,
+        routes,
+        index,
+      };
+    },
+
+    getStateForRouteFocus(state, key) {
+      const index = state.routes.findIndex((r) => r.key === key);
+
+      if (index === -1 || index === state.index) {
+        return state;
+      }
+
+      return changeIndex(state, index, backBehavior, initialRouteName);
+    },
+
+    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
+            );
+          }
+
+          if (index === -1) {
+            return null;
+          }
+
+          return changeIndex(
+            {
+              ...state,
+              routes: state.routes.map((route, i) => {
+                if (i !== index) {
+                  return route;
+                }
+
+                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()}`;
+
+                let params;
+
+                if (
+                  action.type === 'NAVIGATE' &&
+                  action.payload.merge &&
+                  currentId === nextId
+                ) {
+                  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 path =
+                  action.type === 'NAVIGATE' && action.payload.path != null
+                    ? action.payload.path
+                    : route.path;
+
+                return params !== route.params || path !== route.path
+                  ? { ...route, key, path, params }
+                  : route;
+              }),
+            },
+            index,
+            backBehavior,
+            initialRouteName
+          );
+        }
+
+        case 'GO_BACK': {
+          if (state.history.length === 1) {
+            return null;
+          }
+
+          const previousKey = state.history[state.history.length - 2].key;
+          const index = state.routes.findIndex(
+            (route) => route.key === previousKey
+          );
+
+          if (index === -1) {
+            return null;
+          }
+
+          return {
+            ...state,
+            history: state.history.slice(0, -1),
+            index,
+          };
+        }
+
+        default:
+          return BaseRouter.getStateForAction(state, action);
+      }
+    },
+
+    shouldActionChangeFocus(action) {
+      return action.type === 'NAVIGATE';
+    },
+
+    actionCreators: TabActions,
+  };
+
+  return router;
+}

package/src/index.tsx

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

package/src/types.tsx

@@ -0,0 +1,228 @@
+import type * as CommonActions from './CommonActions';
+
+export type CommonNavigationAction = CommonActions.Action;
+
+type NavigationRoute<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList
+> = Route<Extract<RouteName, string>, ParamList[RouteName]> & {
+  state?: NavigationState | PartialState<NavigationState>;
+};
+
+export type NavigationState<ParamList extends ParamListBase = ParamListBase> =
+  Readonly<{
+    /**
+     * Unique key for the navigation state.
+     */
+    key: string;
+    /**
+     * Index of the currently focused route.
+     */
+    index: number;
+    /**
+     * List of valid route names as defined in the screen components.
+     */
+    routeNames: Extract<keyof ParamList, string>[];
+    /**
+     * Alternative entries for history.
+     */
+    history?: unknown[];
+    /**
+     * List of rendered routes.
+     */
+    routes: NavigationRoute<ParamList, keyof ParamList>[];
+    /**
+     * Custom type for the state, whether it's for tab, stack, drawer etc.
+     * During rehydration, the state will be discarded if type doesn't match with router type.
+     * It can also be used to detect the type of the navigator we're dealing with.
+     */
+    type: string;
+    /**
+     * Whether the navigation state has been rehydrated.
+     */
+    stale: false;
+  }>;
+
+export type InitialState = Readonly<
+  Partial<Omit<NavigationState, 'stale' | 'routes'>> & {
+    routes: (Omit<Route<string>, 'key'> & { state?: InitialState })[];
+  }
+>;
+
+export type PartialRoute<R extends Route<string>> = Omit<R, 'key'> & {
+  key?: string;
+  state?: PartialState<NavigationState>;
+};
+
+export type PartialState<State extends NavigationState> = Partial<
+  Omit<State, 'stale' | 'routes'>
+> &
+  Readonly<{
+    stale?: true;
+    routes: PartialRoute<Route<State['routeNames'][number]>>[];
+  }>;
+
+export type Route<
+  RouteName extends string,
+  Params extends object | undefined = object | undefined
+> = Readonly<{
+  /**
+   * Unique key for the route.
+   */
+  key: string;
+  /**
+   * User-provided name for the route.
+   */
+  name: RouteName;
+  /**
+   * Path associated with the route.
+   * Usually present when the screen was opened from a deep link.
+   */
+  path?: string;
+}> &
+  (undefined extends Params
+    ? Readonly<{
+        /**
+         * Params for this route
+         */
+        params?: Readonly<Params>;
+      }>
+    : Readonly<{
+        /**
+         * Params for this route
+         */
+        params: Readonly<Params>;
+      }>);
+
+export type ParamListBase = Record<string, object | undefined>;
+
+export type NavigationAction = Readonly<{
+  /**
+   * Type of the action (e.g. `NAVIGATE`)
+   */
+  type: string;
+  /**
+   * Additional data for the action
+   */
+  payload?: object;
+  /**
+   * Key of the route which dispatched this action.
+   */
+  source?: string;
+  /**
+   * Key of the navigator which should handle this action.
+   */
+  target?: string;
+}>;
+
+export type ActionCreators<Action extends NavigationAction> = {
+  [key: string]: (...args: any) => Action;
+};
+
+export type DefaultRouterOptions<RouteName extends string = string> = {
+  /**
+   * Name of the route to focus by on initial render.
+   * If not specified, usually the first route is used.
+   */
+  initialRouteName?: RouteName;
+};
+
+export type RouterFactory<
+  State extends NavigationState,
+  Action extends NavigationAction,
+  RouterOptions extends DefaultRouterOptions
+> = (options: RouterOptions) => Router<State, Action>;
+
+export type RouterConfigOptions = {
+  routeNames: string[];
+  routeParamList: ParamListBase;
+  routeGetIdList: Record<
+    string,
+    | ((options: { params?: Record<string, any> }) => string | undefined)
+    | undefined
+  >;
+};
+
+export type Router<
+  State extends NavigationState,
+  Action extends NavigationAction
+> = {
+  /**
+   * Type of the router. Should match the `type` property in state.
+   * If the type doesn't match, the state will be discarded during rehydration.
+   */
+  type: State['type'];
+
+  /**
+   * Initialize the navigation state.
+   *
+   * @param options.routeNames List of valid route names as defined in the screen components.
+   * @param options.routeParamsList Object containing params for each route.
+   */
+  getInitialState(options: RouterConfigOptions): State;
+
+  /**
+   * Rehydrate the full navigation state from a given partial state.
+   *
+   * @param partialState Navigation state to rehydrate from.
+   * @param options.routeNames List of valid route names as defined in the screen components.
+   * @param options.routeParamsList Object containing params for each route.
+   */
+  getRehydratedState(
+    partialState: PartialState<State> | State,
+    options: RouterConfigOptions
+  ): State;
+
+  /**
+   * Take the current state and updated list of route names, and return a new state.
+   *
+   * @param state State object to update.
+   * @param options.routeNames New list of route names.
+   * @param options.routeParamsList Object containing params for each route.
+   */
+  getStateForRouteNamesChange(
+    state: State,
+    options: RouterConfigOptions & {
+      /**
+       * List of routes whose key has changed even if they still have the same name.
+       * This allows to remove screens declaratively.
+       */
+      routeKeyChanges: string[];
+    }
+  ): State;
+
+  /**
+   * Take the current state and key of a route, and return a new state with the route focused
+   *
+   * @param state State object to apply the action on.
+   * @param key Key of the route to focus.
+   */
+  getStateForRouteFocus(state: State, key: string): State;
+
+  /**
+   * Take the current state and action, and return a new state.
+   * If the action cannot be handled, return `null`.
+   *
+   * @param state State object to apply the action on.
+   * @param action Action object to apply.
+   * @param options.routeNames List of valid route names as defined in the screen components.
+   * @param options.routeParamsList Object containing params for each route.
+   */
+  getStateForAction(
+    state: State,
+    action: Action,
+    options: RouterConfigOptions
+  ): State | PartialState<State> | null;
+
+  /**
+   * Whether the action should also change focus in parent navigator
+   *
+   * @param action Action object to check.
+   */
+  shouldActionChangeFocus(action: NavigationAction): boolean;
+
+  /**
+   * Action creators for the router.
+   */
+  actionCreators?: ActionCreators<Action>;
+};