fix(react-router): use location keys for forward detection and prevent overlap in nested outlets

Author: ShaneK

packages/react-router/src/ReactRouter/IonRouter.tsx

@@ -83,12 +83,20 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
   const viewStack = useRef(new ReactRouterViewStack());
   const incomingRouteParams = useRef<Partial<RouteInfo> | null>(null);
   /**
-   * Tracks URLs (pathname + search) that the user navigated away from via
-   * browser back. When a POP event's destination matches the top of this
-   * stack, it's a browser forward navigation. Cleared on PUSH (new
-   * navigation invalidates forward history, just like in the browser).
+   * Tracks location keys that the user navigated away from via browser back.
+   * When a POP event's destination key matches the top of this stack, it's a
+   * browser forward navigation. Uses React Router's unique location.key
+   * instead of URLs to correctly handle duplicate URLs in history (e.g.,
+   * navigating to /details, then /settings, then /details via routerLink,
+   * then pressing back).
+   * Cleared on PUSH (new navigation invalidates forward history).
    */
   const forwardStack = useRef<string[]>([]);
+  /**
+   * Tracks the current location key so we can push it onto the forward stack
+   * when navigating back. Updated after each history change.
+   */
+  const currentLocationKeyRef = useRef<string>(location.key);
 
   const [routeInfo, setRouteInfo] = useState<RouteInfo>({
     id: generateId('routeInfo'),
@@ -203,7 +211,7 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
           const currentRoute = locationHistory.current.current();
           const isForwardNavigation =
             forwardStack.current.length > 0 &&
-            forwardStack.current[forwardStack.current.length - 1] === location.pathname + location.search;
+            forwardStack.current[forwardStack.current.length - 1] === location.key;
 
           if (isForwardNavigation) {
             forwardStack.current.pop();
@@ -213,8 +221,8 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
               tab: tabToUse,
             };
           } else if (currentRoute && currentRoute.pushedByRoute) {
-            // Back navigation — record current URL for potential forward
-            forwardStack.current.push(currentRoute.pathname + (currentRoute.search || ''));
+            // Back navigation. Record current location key for potential forward
+            forwardStack.current.push(currentLocationKeyRef.current);
             const prevInfo = locationHistory.current.findLastLocation(currentRoute);
             incomingRouteParams.current = { ...prevInfo, routeAction: 'pop', routeDirection: 'back' };
           } else {
@@ -346,6 +354,9 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
       setRouteInfo(routeInfo);
     }
 
+    // Update the current location key after processing the history change.
+    // This ensures the forward stack records the correct key when navigating back.
+    currentLocationKeyRef.current = location.key;
     incomingRouteParams.current = null;
   };
 
@@ -481,8 +492,8 @@ export const IonRouter = ({ children, registerHistoryListener }: PropsWithChildr
         const condition1 = routeInfo.lastPathname === routeInfo.pushedByRoute;
         const condition2 = prevInfo.pathname === routeInfo.pushedByRoute && routeInfo.tab === '' && prevInfo.tab === '';
         if (condition1 || condition2) {
-          // Record current URL so browser forward is detectable
-          forwardStack.current.push(routeInfo.pathname + (routeInfo.search || ''));
+          // Record the current location key so browser forward is detectable
+          forwardStack.current.push(currentLocationKeyRef.current);
           navigate(-1);
         } else {
           /**

packages/react-router/src/ReactRouter/StackManager.tsx

@@ -33,7 +33,7 @@ interface StackManagerProps {
 }
 
 const isViewVisible = (el: HTMLElement) =>
-  !el.classList.contains('ion-page-invisible') && !el.classList.contains('ion-page-hidden');
+  !el.classList.contains('ion-page-invisible') && !el.classList.contains('ion-page-hidden') && el.style.display !== 'none';
 
 const hideIonPageElement = (element: HTMLElement | undefined): void => {
   if (element) {
@@ -44,6 +44,7 @@ const hideIonPageElement = (element: HTMLElement | undefined): void => {
 
 const showIonPageElement = (element: HTMLElement | undefined): void => {
   if (element) {
+    element.style.removeProperty('display');
     element.classList.remove('ion-page-hidden');
     element.removeAttribute('aria-hidden');
   }
@@ -322,8 +323,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
 
         const enteringEl = enteringViewItem.ionPageElement;
         if (enteringEl) {
-          enteringEl.classList.remove('ion-page-hidden', 'ion-page-invisible');
-          enteringEl.removeAttribute('aria-hidden');
+          showIonPageElement(enteringEl);
+          enteringEl.classList.remove('ion-page-invisible');
         }
 
         this.forceUpdate();
@@ -417,7 +418,9 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
 
     this.lastTransition = currentTransition;
 
-    this.transitionPage(routeInfo, enteringViewItem, leavingViewItem);
+    const shouldSkipAnimation = this.applySkipAnimationIfNeeded(enteringViewItem, leavingViewItem);
+
+    this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, undefined, false, shouldSkipAnimation);
 
     if (shouldUnmountLeavingViewItem && leavingViewItem && enteringViewItem !== leavingViewItem) {
       leavingViewItem.mount = false;
@@ -547,6 +550,36 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     }
   }
 
+  /**
+   * Determines whether to skip the transition animation and, if so, immediately
+   * hides the leaving view with inline `display:none`.
+   *
+   * Skips transitions in outlets nested inside a parent IonPage. These outlets
+   * render pages inside a parent page's content area. The MD animation shows
+   * both entering and leaving pages simultaneously, causing text overlap and
+   * nested scrollbars (each page has its own IonContent). Top-level outlets
+   * are unaffected and animate normally.
+   *
+   * Uses inline display:none rather than ion-page-hidden class because core's
+   * beforeTransition() removes ion-page-hidden via setPageHidden().
+   * Inline display:none survives that removal, keeping the page hidden
+   * until React unmounts it after ionViewDidLeave fires.
+   */
+  private applySkipAnimationIfNeeded(
+    enteringViewItem: ViewItem,
+    leavingViewItem: ViewItem | undefined
+  ): boolean {
+    const isNestedOutlet = !!this.routerOutletElement?.closest('.ion-page');
+    const shouldSkip = isNestedOutlet && !!leavingViewItem && enteringViewItem !== leavingViewItem;
+
+    if (shouldSkip && leavingViewItem?.ionPageElement) {
+      leavingViewItem.ionPageElement.style.setProperty('display', 'none');
+      leavingViewItem.ionPageElement.setAttribute('aria-hidden', 'true');
+    }
+
+    return shouldSkip;
+  }
+
   /**
    * Handles entering view with no ion-page element yet (waiting for render).
    */
@@ -609,7 +642,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       const latestLeavingView = this.context.findLeavingViewItemByRouteInfo(routeInfo, this.id) ?? leavingViewItem;
 
       if (latestEnteringView?.ionPageElement) {
-        this.transitionPage(routeInfo, latestEnteringView, latestLeavingView ?? undefined);
+        const shouldSkipAnimation = this.applySkipAnimationIfNeeded(latestEnteringView, latestLeavingView ?? undefined);
+        this.transitionPage(routeInfo, latestEnteringView, latestLeavingView ?? undefined, undefined, false, shouldSkipAnimation);
 
         if (shouldUnmountLeavingViewItem && latestLeavingView && latestEnteringView !== latestLeavingView) {
           latestLeavingView.mount = false;
@@ -863,6 +897,17 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
         return;
       }
 
+      /**
+       * Don't let a nested element (e.g., ion-router-outlet with ionPage prop)
+       * override an existing IonPage registration when the existing element is
+       * an ancestor of the new one. This ensures ionPageElement always points
+       * to the outermost IonPage, which is needed to properly hide the entire
+       * page during back navigation (not just the inner outlet).
+       */
+      if (oldPageElement && oldPageElement !== page && oldPageElement.isConnected && oldPageElement.contains(page)) {
+        return;
+      }
+
       foundView.ionPageElement = page;
       foundView.ionRoute = true;
 
@@ -1008,13 +1053,18 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
    * @param progressAnimation Indicates if the transition is part of a
    * gesture controlled animation (e.g., swipe to go back).
    * Defaults to `false`.
+   * @param skipAnimation When true, forces `duration: 0` so the page
+   * swap is instant (no visible animation). Used for ionPage outlets
+   * and back navigations that unmount the leaving view to prevent
+   * overlapping content during the transition. Defaults to `false`.
    */
   async transitionPage(
     routeInfo: RouteInfo,
     enteringViewItem: ViewItem,
     leavingViewItem?: ViewItem,
     direction?: 'forward' | 'back',
-    progressAnimation = false
+    progressAnimation = false,
+    skipAnimation = false
   ) {
     const runCommit = async (enteringEl: HTMLElement, leavingEl?: HTMLElement) => {
       const skipTransition = this.skipTransition;
@@ -1055,7 +1105,7 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       }
 
       await routerOutlet.commit(enteringEl, leavingEl, {
-        duration: skipTransition || directionToUse === undefined ? 0 : undefined,
+        duration: skipTransition || skipAnimation || directionToUse === undefined ? 0 : undefined,
         direction: directionToUse,
         showGoBack: !!routeInfo.pushedByRoute,
         progressAnimation,