ionic-framework/packages/vue-router/src/router.ts

import type { AnimationBuilder } from "@ionic/vue";
import type {
  Router,
  RouteLocationNormalized,
  NavigationFailure,
  RouteLocationRaw,
} from "vue-router";
import { parseQuery } from "vue-router";

import { createLocationHistory } from "./locationHistory";
import type {
  ExternalNavigationOptions,
  RouteInfo,
  RouteParams,
  RouteAction,
  RouteDirection,
  IonicVueRouterOptions,
  NavigationInformation,
} from "./types";
import { generateId } from "./utils";

// TODO(FW-2969): types

export const createIonRouter = (
  opts: IonicVueRouterOptions,
  router: Router
) => {
  let currentNavigationInfo: NavigationInformation = {
    direction: undefined,
    action: undefined,
    delta: undefined,
  };

  /**
   * Ionic Vue should only react to navigation
   * changes once they have been confirmed and should
   * never affect the outcome of navigation (with the
   * exception of going back or selecting a tab).
   * As a result, we should do our work in afterEach
   * which is fired once navigation is confirmed
   * and any user guards have run.
   */
  router.afterEach(
    (
      to: RouteLocationNormalized,
      _: RouteLocationNormalized,
      failure?: NavigationFailure
    ) => {
      if (failure) return;

      const { direction, action, delta } = currentNavigationInfo;

      /**
       * When calling router.replace, we are not informed
       * about the replace action in opts.history.listen
       * but we can check to see if the latest routing action
       * was a replace action by looking at the history state.
       * We need to use opts.history rather than window.history
       * because window.history will be undefined when using SSR.
       */

      currentHistoryPosition = opts.history.state.position as number;

      const replaceAction = opts.history.state.replaced ? "replace" : undefined;
      handleHistoryChange(to, action || replaceAction, direction, delta);

      currentNavigationInfo = {
        direction: undefined,
        action: undefined,
        delta: undefined,
      };
    }
  );

  const locationHistory = createLocationHistory();

  /**
   * Keeping track of the history position
   * allows us to determine if a user is pushing
   * new pages or updating history via the forward
   * and back browser buttons.
   */
  let initialHistoryPosition = opts.history.state.position as number;
  let currentHistoryPosition = opts.history.state.position as number;

  let currentRouteInfo: RouteInfo;
  let incomingRouteParams: RouteParams;

  const historyChangeListeners: any[] = [];

  if (typeof (document as any) !== "undefined") {
    document.addEventListener("ionBackButton", (ev: Event) => {
      (ev as any).detail.register(0, (processNextHandler: () => void) => {
        opts.history.go(-1);
        processNextHandler();
      });
    });
  }

  opts.history.listen((_: any, _x: any, info: any) => {
    /**
     * history.listen only fires on certain
     * event such as when the user clicks the
     * browser back button. It also gives us
     * additional information as to the type
     * of navigation (forward, backward, etc).
     *
     * We can use this to better handle the
     * `handleHistoryChange` call in
     * router.beforeEach
     */
    currentNavigationInfo = {
      delta: info.delta,

      /**
       * Both the browser forward and backward actions
       * are considered "pop" actions, but when going forward
       * we want to make sure the forward animation is used.
       */
      action: info.type === "pop" && info.delta >= 1 ? "push" : info.type,
      direction: info.direction === "" ? "forward" : info.direction,
    };
  });

  const handleNavigateBack = (
    defaultHref?: string,
    routerAnimation?: AnimationBuilder
  ) => {
    const routeInfo = locationHistory.current(
      initialHistoryPosition,
      currentHistoryPosition
    );
    if (routeInfo && routeInfo.pushedByRoute) {
      const prevInfo = locationHistory.findLastLocation(routeInfo);
      if (prevInfo) {
        incomingRouteParams = {
          ...prevInfo,
          routerAction: "pop",
          routerDirection: "back",
          routerAnimation: routerAnimation || routeInfo.routerAnimation,
        };
        if (
          routeInfo.lastPathname === routeInfo.pushedByRoute ||
          /**
           * We need to exclude tab switches/tab
           * context changes here because tabbed
           * navigation is not linear, but router.back()
           * will go back in a linear fashion.
           */
          (prevInfo.pathname === routeInfo.pushedByRoute &&
            /**
             * Tab info can be undefined or '' (empty string)
             * both are false-y values, so we can just use !.
             */
            !routeInfo.tab &&
            !prevInfo.tab)
        ) {
          router.back();
        } else {
          /**
           * When going back to a child page of a tab
           * after being on another tab, we need to use
           * router.go() here instead of pushing or replacing.
           * Consider the following example:
           * /tabs/tab1 --> /tabs/tab1/child1 --> /tabs/tab1/child2
           * --> /tabs/tab2 (via Tab 2 button) --> /tabs/tab1/child2 (via Tab 1 button)
           *
           * Pressing the ion-back-button on /tabs/tab1/child2 should take
           * us back to /tabs/tab1/child1 not /tabs/tab2 because each tab
           * is its own stack.
           *
           * If we called pressed the ion-back-button and this code called
           * router.replace, then the state of /tabs/tab1/child2 would
           * be replaced with /tabs/tab1/child1. However, this means that
           * there would be two /tabs/tab1/child1 entries in the location
           * history as the original /tabs/tab1/child1 entry is still there.
           * As a result, clicking the ion-back-button on /tabs/tab1/child1 does
           * nothing because this code would try to route to the same page
           * we are currently on.
           *
           * If we called router.push instead then we would push a
           * new /tabs/tab1/child1 entry to the location history. This
           * is not good because we would have two /tabs/tab1/child1 entries
           * separated by a /tabs/tab1/child2 entry.
           */
          router.go(prevInfo.position - routeInfo.position);
        }
      } else {
        handleNavigate(defaultHref, "pop", "back");
      }
    } else {
      handleNavigate(defaultHref, "pop", "back");
    }
  };

  const handleNavigate = (
    path: RouteLocationRaw,
    routerAction?: RouteAction,
    routerDirection?: RouteDirection,
    routerAnimation?: AnimationBuilder,
    tab?: string
  ) => {
    setIncomingRouteParams(routerAction, routerDirection, routerAnimation, tab);

    if (routerAction === "push") {
      router.push(path);
    } else {
      router.replace(path);
    }
  };

  // TODO RouteLocationNormalized
  const handleHistoryChange = (
    location: any,
    action?: RouteAction,
    direction?: RouteDirection,
    delta?: number
  ) => {
    let leavingLocationInfo: RouteInfo;
    if (incomingRouteParams) {
      /**
       * If we are replacing the state of a route
       * with another route, the "leaving" route
       * is at the same position in location history
       * as where the replaced route will exist.
       */
      if (incomingRouteParams.routerAction === "replace") {
        leavingLocationInfo = locationHistory.current(
          initialHistoryPosition,
          currentHistoryPosition
        );
      } else if (incomingRouteParams.routerAction === "pop") {
        leavingLocationInfo = locationHistory.current(
          initialHistoryPosition,
          currentHistoryPosition + 1
        );

        /**
         * If the Ionic Router action was "pop"
         * and the browser history action was "replace", then
         * it is the case that the user clicked an IonBackButton
         * that is trying to go back to the route specified
         * by the defaultHref property.
         *
         * The problem is that this route currently does
         * not exist in the browser history, and we cannot
         * prepend an item in the browser's history stack.
         * To work around this, we replace the state of
         * the current item instead.
         * Given this scenario:
         * /page2 --> /page3 --> (back) /page2 --> (defaultHref) /page1
         * We would replace the state of /page2 with the state of /page1.
         *
         * When doing this, we are essentially re-writing past
         * history which makes the future history no longer relevant.
         * As a result, we clear out the location history so that users
         * can begin pushing new routes to the stack.
         *
         * This pattern is aligned with how the browser handles
         * pushing new routes after going back as well as how
         * other stack based operations such as undo/redo work.
         * For example, if you do tasks A, B, C, undo B and C, and
         * then do task D, you cannot "redo" B and C because you
         * rewrote the stack's past history.
         *
         * With browser history, it is a similar concept.
         * Going /page1 --> /page2 --> /page3 and then doing
         * router.go(-2) will bring you back to /page1.
         * If you then push /page4, you have rewritten
         * the past history and you can no longer go
         * forward to /page2 or /page3.
         */
        if (action === "replace") {
          locationHistory.clearHistory();
        }
      } else {
        /**
         * If the routerDirection was specified as "root", then
         * we are replacing the initial state of location history
         * with this incoming route. As a result, the leaving
         * history info is stored at the same location as
         * where the incoming history location will be stored.
         *
         * Otherwise, we can assume this is just another route
         * that will be pushed onto the end of location history,
         * so we can grab the previous item in history relative
         * to where the history state currently is.
         */
        const position =
          incomingRouteParams.routerDirection === "root"
            ? currentHistoryPosition
            : currentHistoryPosition - 1;
        leavingLocationInfo = locationHistory.current(
          initialHistoryPosition,
          position
        );
      }
    } else {
      leavingLocationInfo = currentRouteInfo;
    }

    if (!leavingLocationInfo) {
      leavingLocationInfo = {
        pathname: "",
        search: "",
      };
    }

    const leavingUrl =
      leavingLocationInfo.pathname + leavingLocationInfo.search;
    if (leavingUrl !== location.fullPath) {
      if (!incomingRouteParams) {
        if (action === "replace") {
          incomingRouteParams = {
            routerAction: "replace",
            routerDirection: "none",
          };
        } else if (action === "pop") {
          const routeInfo = locationHistory.current(
            initialHistoryPosition,
            currentHistoryPosition - delta
          );

          if (routeInfo && routeInfo.pushedByRoute) {
            const prevRouteInfo = locationHistory.findLastLocation(
              routeInfo,
              delta
            );
            incomingRouteParams = {
              ...prevRouteInfo,
              routerAction: "pop",
              routerDirection: "back",
            };
          } else {
            incomingRouteParams = {
              routerAction: "pop",
              routerDirection: "none",
            };
          }
        }

        if (!incomingRouteParams) {
          incomingRouteParams = {
            routerAction: "push",
            routerDirection: direction || "forward",
          };
        }
      }

      let routeInfo: RouteInfo;
      if (incomingRouteParams?.id) {
        routeInfo = {
          ...incomingRouteParams,
          lastPathname: leavingLocationInfo.pathname,
        };
      } else {
        const isPushed =
          incomingRouteParams.routerAction === "push" &&
          incomingRouteParams.routerDirection === "forward";
        routeInfo = {
          id: generateId("routeInfo"),
          ...incomingRouteParams,
          lastPathname: leavingLocationInfo.pathname,
          pathname: location.path,
          search: (location.fullPath && location.fullPath.split("?")[1]) || "",
          params: location.params && location.params,
          prevRouteLastPathname: leavingLocationInfo.lastPathname,
        };

        if (isPushed) {
          routeInfo.pushedByRoute =
            leavingLocationInfo.pathname !== ""
              ? leavingLocationInfo.pathname
              : undefined;
        } else if (routeInfo.routerAction === "pop") {
          const route = locationHistory.findLastLocation(routeInfo);
          routeInfo.pushedByRoute = route?.pushedByRoute;
        } else if (
          routeInfo.routerAction === "push" &&
          routeInfo.tab !== leavingLocationInfo.tab
        ) {
          const lastRoute = locationHistory.getCurrentRouteInfoForTab(
            routeInfo.tab
          );
          routeInfo.pushedByRoute = lastRoute?.pushedByRoute;
        } else if (routeInfo.routerAction === "replace") {
          /**
           * When replacing a route, we want to make sure we select the current route
           * that we are on, not the last route in the stack. The last route in the stack
           * is not always the current route.
           * Example:
           * Given the following history: /page1 --> /page2
           * Doing router.go(-1) would bring you to /page1.
           * If you then did router.replace('/page3'), /page1 should
           * be replaced with /page3 even though /page2 is the last
           * item in the stack/
           */
          const currentRouteInfo = locationHistory.current(
            initialHistoryPosition,
            currentHistoryPosition
          );

          /**
           * If going from /home to /child, then replacing from
           * /child to /home, we don't want the route info to
           * say that /home was pushed by /home which is not correct.
           */
          const currentPushedBy = currentRouteInfo?.pushedByRoute;
          const pushedByRoute =
            currentPushedBy !== undefined &&
            currentPushedBy !== routeInfo.pathname
              ? currentPushedBy
              : routeInfo.pushedByRoute;

          routeInfo.lastPathname =
            currentRouteInfo?.pathname || routeInfo.lastPathname;
          routeInfo.pushedByRoute = pushedByRoute;
          routeInfo.routerDirection =
            currentRouteInfo?.routerDirection || routeInfo.routerDirection;
          routeInfo.routerAnimation =
            currentRouteInfo?.routerAnimation || routeInfo.routerAnimation;
          routeInfo.prevRouteLastPathname = currentRouteInfo?.lastPathname;
        }
      }

      routeInfo.position = currentHistoryPosition;
      routeInfo.delta = delta;
      const historySize = locationHistory.size();
      const historyDiff = currentHistoryPosition - initialHistoryPosition;

      /**
       * If the size of location history is greater
       * than the difference between the current history
       * position and the initial history position
       * then we are guaranteed to already have a history
       * item for this route. In other words, a user
       * is navigating within the history without pushing
       * new items within the stack.
       *
       * If the historySize === historyDiff,
       * then we are still re-writing history
       * by replacing the current route state
       * with a new route state. The initial
       * action when loading an app is
       * going to be replace operation, so
       * we want to make sure we exclude that
       * action by ensuring historySize > 0.
       */
      const isReplacing =
        historySize === historyDiff && historySize > 0 && action === "replace";
      if (historySize > historyDiff || isReplacing) {
        /**
         * When navigating back through the history,
         * if users then push a new route the future
         * history stack is no longer relevant. As
         * a result, we need to clear out all entries
         * that appear after the current routeInfo
         * so that we can then append the new history.
         *
         * This does not apply when using router.go
         * as that is traversing through the history,
         * not altering it.
         *
         * Previously we had only updated the existing route
         * and then left the future history alone. That
         * worked for some use cases but was not sufficient
         * in other scenarios.
         */

        if (
          (routeInfo.routerAction === "push" ||
            routeInfo.routerAction === "replace") &&
          delta === undefined
        ) {
          locationHistory.clearHistory(routeInfo);
          locationHistory.add(routeInfo);
        }
      } else {
        locationHistory.add(routeInfo);
      }

      /**
       * If we recently reset the location history
       * then we also need to update the initial
       * history position.
       */
      if (locationHistory.size() === 1) {
        initialHistoryPosition = routeInfo.position;
      }

      currentRouteInfo = routeInfo;
    }
    incomingRouteParams = undefined;
    historyChangeListeners.forEach((cb) => cb(currentRouteInfo));
  };

  const getCurrentRouteInfo = () => currentRouteInfo;

  const canGoBack = (deep = 1) =>
    locationHistory.canGoBack(
      deep,
      initialHistoryPosition,
      currentHistoryPosition
    );

  const navigate = (navigationOptions: ExternalNavigationOptions) => {
    const { routerAnimation, routerDirection, routerLink } = navigationOptions;

    setIncomingRouteParams("push", routerDirection, routerAnimation);

    router.push(routerLink);
  };

  const resetTab = (tab: string) => {
    /**
     * Resetting the tab should go back
     * to the initial view in the tab stack.
     * It should not push a new instance of the
     * root tab page onto the stack.
     *
     * To do this, we get the initial view in the
     * tab stack and subtract the position of that
     * entry from our current position. From there
     * we call router.go() to move us back the
     * appropriate number of positions.
     */
    const routeInfo = locationHistory.getFirstRouteInfoForTab(tab);
    if (routeInfo) {
      router.go(routeInfo.position - currentHistoryPosition);
    }
  };

  const changeTab = (tab: string, path?: string) => {
    if (!path) return;

    const routeInfo = locationHistory.getCurrentRouteInfoForTab(tab);
    const [pathname] = path.split("?");

    if (routeInfo) {
      incomingRouteParams = {
        ...incomingRouteParams,
        routerAction: "push",
        routerDirection: "none",
        tab,
      };

      /**
       * When going back to a tab
       * you just left, it's possible
       * for the route info to be incorrect
       * as the tab you want is not the
       * tab you are on.
       */
      if (routeInfo.pathname === pathname) {
        router.push({
          path: routeInfo.pathname,
          query: parseQuery(routeInfo.search),
        });
      } else {
        router.push({ path: pathname, query: parseQuery(routeInfo.search) });
      }
    } else {
      handleNavigate(pathname, "push", "none", undefined, tab);
    }
  };

  /**
   * This method is invoked by the IonTabs component
   * during a history change callback. It is responsible
   * for ensuring that tabbed routes have the correct
   * "tab" field in its routeInfo object.
   *
   * IonTabs will determine if the current route
   * is in tabs and assign it the correct tab.
   * If the current route is not in tabs,
   * then IonTabs will not invoke this.
   */
  const handleSetCurrentTab = (tab: string) => {
    /**
     * Note that the current page that we
     * are on is not necessarily the last item
     * in the locationHistory stack. As a result,
     * we cannot use locationHistory.last() here.
     */
    const ri = {
      ...locationHistory.current(
        initialHistoryPosition,
        currentHistoryPosition
      ),
    };

    /**
     * handleHistoryChange is tabs-agnostic by design.
     * One side effect of this is that certain tabs
     * routes have extraneous/incorrect information
     * that we need to remove. To not tightly couple
     * handleHistoryChange with tabs, we let the
     * handleSetCurrentTab function. This function is
     * only called by IonTabs.
     */

    if (ri.tab !== tab) {
      ri.tab = tab;
      locationHistory.update(ri);
    }

    /**
     * lastPathname typically equals pushedByRoute
     * when navigating in a linear manner. When switching between
     * tabs, this is almost never the case.
     *
     * Example: /tabs/tabs1 --> /tabs/tab2 --> /tabs/tab1
     * The latest Tab 1 route would have the following information
     * lastPathname: '/tabs/tab2'
     * pushedByRoute: '/tabs/tab2'
     *
     * A tab cannot push another tab, so we need to set
     * pushedByRoute to `undefined`. Alternative way of thinking
     * about this: You cannot swipe to go back from Tab 1 to Tab 2.
     *
     * However, there are some instances where we do want to keep
     * the pushedByRoute. As a result, we need to ensure that
     * we only wipe the pushedByRoute state when the both of the
     * following conditions are met:
     * 1. pushedByRoute is different from lastPathname
     * 2. The tab for the pushedByRoute info is different
     * from the current route tab.
     *
     * Example of when we would not want to clear pushedByRoute:
     * /tabs/tab1 --> /tabs/tab1/child --> /tabs/tab2 --> /tabs/tab1/child
     * The latest Tab 1 Child route would have the following information:
     * lastPathname: '/tabs/tab2'
     * pushedByRoute: '/tabs/tab1
     *
     * In this case, /tabs/tab1/child should be able to swipe to go back
     * to /tabs/tab1 so we want to keep the pushedByRoute.
     */
    const pushedByRoute = locationHistory.findLastLocation(ri);
    if (ri.pushedByRoute !== ri.lastPathname && pushedByRoute?.tab !== tab) {
      ri.pushedByRoute = undefined;
      locationHistory.update(ri);
    }
  };

  const registerHistoryChangeListener = (cb: any) => {
    historyChangeListeners.push(cb);
  };

  const setIncomingRouteParams = (
    routerAction: RouteAction = "push",
    routerDirection: RouteDirection = "forward",
    routerAnimation?: AnimationBuilder,
    tab?: string
  ) => {
    incomingRouteParams = {
      routerAction,
      routerDirection,
      routerAnimation,
      tab,
    };
  };

  const goBack = (routerAnimation?: AnimationBuilder) => {
    setIncomingRouteParams("pop", "back", routerAnimation);
    router.back();
  };

  const goForward = (routerAnimation?: AnimationBuilder) => {
    setIncomingRouteParams("push", "forward", routerAnimation);
    router.forward();
  };

  const getLeavingRouteInfo = () => {
    return locationHistory.current(
      initialHistoryPosition,
      currentHistoryPosition
    );
  };

  return {
    handleNavigate,
    getLeavingRouteInfo,
    handleNavigateBack,
    handleSetCurrentTab,
    getCurrentRouteInfo,
    canGoBack,
    navigate,
    resetTab,
    changeTab,
    registerHistoryChangeListener,
    goBack,
    goForward,
  };
};