fix(react-router): fix swipe-to-go-back view unmounting and cross-outlet navigation

ShaneK · ShaneK · commit 289b12ce7459 · 2025-12-15T12:04:32.000-08:00
diff --git a/packages/react-router/src/ReactRouter/StackManager.tsx b/packages/react-router/src/ReactRouter/StackManager.tsx
@@ -207,9 +207,42 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     }
 
     if (routeInfo.routeAction === 'replace') {
-      return true;
+      // For replace actions, decide whether to unmount the leaving view.
+      // The key question is: are these routes in the same navigation context?
+      const enteringRoutePath = enteringViewItem?.reactElement?.props?.path as string | undefined;
+      const leavingRoutePath = leavingViewItem?.reactElement?.props?.path as string | undefined;
+
+      // Never unmount the root path "/" - it's the main entry point for back navigation
+      if (leavingRoutePath === '/' || leavingRoutePath === '') {
+        return false;
+      }
+
+      if (enteringRoutePath && leavingRoutePath) {
+        // Get parent paths to check if routes share a common parent
+        const getParentPath = (path: string) => {
+          const normalized = path.replace(/\/\*$/, ''); // Remove trailing /*
+          const lastSlash = normalized.lastIndexOf('/');
+          return lastSlash > 0 ? normalized.substring(0, lastSlash) : '/';
+        };
+
+        const enteringParent = getParentPath(enteringRoutePath);
+        const leavingParent = getParentPath(leavingRoutePath);
+
+        // Unmount if:
+        // 1. Routes are siblings (same parent, e.g., /page1 and /page2, or /foo/page1 and /foo/page2)
+        // 2. Entering is a child of leaving (redirect, e.g., /tabs -> /tabs/tab1)
+        const areSiblings = enteringParent === leavingParent && enteringParent !== '/';
+        const isChildRedirect =
+          enteringRoutePath.startsWith(leavingRoutePath) ||
+          (leavingRoutePath.endsWith('/*') && enteringRoutePath.startsWith(leavingRoutePath.slice(0, -2)));
+
+        return areSiblings || isChildRedirect;
+      }
+
+      return false;
     }
 
+    // For non-replace actions, only unmount for back navigation (not forward push)
     const isForwardPush = routeInfo.routeAction === 'push' && (routeInfo as any).routeDirection === 'forward';
     if (!isForwardPush && routeInfo.routeDirection !== 'none' && enteringViewItem !== leavingViewItem) {
       return true;
@@ -317,9 +350,6 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     leavingViewItem: ViewItem | undefined,
     shouldUnmountLeavingViewItem: boolean
   ): void {
-    // Ensure the entering view is not hidden from previous navigations
-    showIonPageElement(enteringViewItem.ionPageElement);
-
     // Handle same view item case (e.g., parameterized route changes)
     if (enteringViewItem === leavingViewItem) {
       const routePath = enteringViewItem.reactElement?.props?.path as string | undefined;
@@ -348,34 +378,93 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       leavingViewItem = this.context.findViewItemByPathname(this.props.routeInfo.prevRouteLastPathname, this.id);
     }
 
-    // Skip transition if entering view is visible and leaving view is not
-    if (
-      enteringViewItem.ionPageElement &&
-      isViewVisible(enteringViewItem.ionPageElement) &&
-      leavingViewItem !== undefined &&
-      leavingViewItem.ionPageElement &&
-      !isViewVisible(leavingViewItem.ionPageElement)
-    ) {
-      return;
+    // Ensure the entering view is marked as mounted.
+    // This is critical for views that were previously unmounted (e.g., navigating back to home).
+    // When mount=false, the ViewLifeCycleManager doesn't render the IonPage, so the
+    // ionPageElement reference becomes stale. By setting mount=true, we ensure the view
+    // gets re-rendered and a new IonPage is created.
+    if (!enteringViewItem.mount) {
+      enteringViewItem.mount = true;
     }
 
+    // Check visibility state BEFORE showing the entering view.
+    // This must be done before showIonPageElement to get accurate visibility state.
+    const enteringWasVisible = enteringViewItem.ionPageElement && isViewVisible(enteringViewItem.ionPageElement);
+    const leavingIsHidden =
+      leavingViewItem !== undefined && leavingViewItem.ionPageElement && !isViewVisible(leavingViewItem.ionPageElement);
+
     // Check for duplicate transition
     const currentTransition = {
       enteringId: enteringViewItem.id,
       leavingId: leavingViewItem?.id,
     };
 
-    if (
+    const isDuplicateTransition =
       leavingViewItem &&
       this.lastTransition &&
       this.lastTransition.leavingId &&
       this.lastTransition.enteringId === currentTransition.enteringId &&
-      this.lastTransition.leavingId === currentTransition.leavingId
-    ) {
+      this.lastTransition.leavingId === currentTransition.leavingId;
+
+    // Skip transition if entering view was ALREADY visible and leaving view is not visible.
+    // This indicates the transition has already been performed (e.g., via swipe gesture).
+    // IMPORTANT: Only skip if both ionPageElements are the same as when the transition was last done.
+    // If the leaving view's ionPageElement changed (e.g., component re-rendered with different IonPage),
+    // we should NOT skip because the DOM state is inconsistent.
+    if (enteringWasVisible && leavingIsHidden && isDuplicateTransition) {
+      // For swipe-to-go-back, the transition animation was handled by the gesture.
+      // We still need to set mount=false so React unmounts the leaving view.
+      // Only do this when skipTransition is set (indicating gesture completion).
+      if (
+        this.skipTransition &&
+        shouldUnmountLeavingViewItem &&
+        leavingViewItem &&
+        enteringViewItem !== leavingViewItem
+      ) {
+        leavingViewItem.mount = false;
+        // Call transitionPage with duration 0 to trigger ionViewDidLeave lifecycle
+        // which is needed for ViewLifeCycleManager to remove the view.
+        this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back');
+      }
+      // Clear skipTransition since we're not calling transitionPage which normally clears it
+      this.skipTransition = false;
+      // Must call forceUpdate to trigger re-render after mount state change
+      this.forceUpdate();
+      return;
+    }
+
+    // Ensure the entering view is not hidden from previous navigations
+    // This must happen AFTER the visibility check above
+    showIonPageElement(enteringViewItem.ionPageElement);
+
+    // Skip if this is a duplicate transition (but visibility state didn't match above)
+    // OR if skipTransition is set (swipe gesture already handled the animation)
+    if (isDuplicateTransition || this.skipTransition) {
+      // For swipe-to-go-back, we still need to handle unmounting even if visibility
+      // conditions aren't fully met (animation might still be in progress)
+      if (
+        this.skipTransition &&
+        shouldUnmountLeavingViewItem &&
+        leavingViewItem &&
+        enteringViewItem !== leavingViewItem
+      ) {
+        leavingViewItem.mount = false;
+        // For swipe-to-go-back, we need to call transitionPage with duration 0 to
+        // trigger the ionViewDidLeave lifecycle event. The ViewLifeCycleManager
+        // uses componentCanBeDestroyed callback to remove the view, which is
+        // only called from ionViewDidLeave. Since the gesture animation already
+        // completed before mount=false was set, we need to re-fire the lifecycle.
+        this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back');
+      }
+      // Clear skipTransition since we're not calling transitionPage which normally clears it
+      this.skipTransition = false;
+      // Must call forceUpdate to trigger re-render after mount state change
+      this.forceUpdate();
       return;
     }
 
     this.lastTransition = currentTransition;
+
     this.transitionPage(routeInfo, enteringViewItem, leavingViewItem);
 
     // Handle unmounting the leaving view
@@ -386,14 +475,29 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
   }
 
   /**
-   * Handles the delayed unmount of the leaving view item after a replace action.
+   * Handles the delayed unmount of the leaving view item.
+   * For 'replace' actions: handles container route transitions specially.
+   * For back navigation: explicitly unmounts because the ionViewDidLeave lifecycle
+   * fires DURING transitionPage, but mount=false is set AFTER.
+   *
+   * @param routeInfo Current route information
+   * @param enteringViewItem The view being navigated to
+   * @param leavingViewItem The view being navigated from
    */
   private handleLeavingViewUnmount(routeInfo: RouteInfo, enteringViewItem: ViewItem, leavingViewItem: ViewItem): void {
-    if (routeInfo.routeAction !== 'replace' || !leavingViewItem.ionPageElement) {
+    if (!leavingViewItem.ionPageElement) {
+      return;
+    }
+
+    // For push/pop actions, do NOT unmount - views are cached for navigation history.
+    // Push: Forward navigation caches views for back navigation
+    // Pop: Back navigation should not unmount the entering view's history
+    // Only 'replace' actions should actually unmount views since they replace history.
+    if (routeInfo.routeAction !== 'replace') {
       return;
     }
 
-    // Check if we should skip removal for nested outlet redirects
+    // For replace actions, check if we should skip removal for nested outlet redirects
     const enteringRoutePath = enteringViewItem.reactElement?.props?.path as string | undefined;
     const leavingRoutePath = leavingViewItem.reactElement?.props?.path as string | undefined;
     const isEnteringContainerRoute = enteringRoutePath && enteringRoutePath.endsWith('/*');
@@ -412,6 +516,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     const viewToUnmount = leavingViewItem;
     setTimeout(() => {
       this.context.unMountViewItem(viewToUnmount);
+      // Trigger re-render to remove the view from DOM
+      this.forceUpdate();
     }, VIEW_UNMOUNT_DELAY_MS);
   }
 
@@ -472,6 +578,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
 
         if (shouldUnmountLeavingViewItem && latestLeavingView && latestEnteringView !== latestLeavingView) {
           latestLeavingView.mount = false;
+          // Call handleLeavingViewUnmount to ensure the view is properly removed
+          this.handleLeavingViewUnmount(routeInfo, latestEnteringView, latestLeavingView);
         }
 
         this.forceUpdate();
@@ -615,7 +723,14 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     }
 
     // Handle transition based on ion-page element availability
-    if (enteringViewItem && enteringViewItem.ionPageElement) {
+    // Check if the ionPageElement is still in the document.
+    // If the view was previously unmounted (mount=false), the ViewLifeCycleManager
+    // removes the React component from the tree, which removes the IonPage from the DOM.
+    // The ionPageElement reference becomes stale and we need to wait for a new one.
+    const ionPageIsInDocument =
+      enteringViewItem?.ionPageElement && document.body.contains(enteringViewItem.ionPageElement);
+
+    if (enteringViewItem && ionPageIsInDocument) {
       // Clear waiting state
       if (this.waitingForIonPage) {
         this.waitingForIonPage = false;
@@ -626,8 +741,17 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       }
 
       this.handleReadyEnteringView(routeInfo, enteringViewItem, leavingViewItem, shouldUnmountLeavingViewItem);
-    } else if (enteringViewItem && !enteringViewItem.ionPageElement) {
+    } else if (enteringViewItem && !ionPageIsInDocument) {
       // Wait for ion-page to mount
+      // This handles both: no ionPageElement, or stale ionPageElement (not in document)
+      // Clear stale reference if the element is no longer in the document
+      if (enteringViewItem.ionPageElement && !document.body.contains(enteringViewItem.ionPageElement)) {
+        enteringViewItem.ionPageElement = undefined;
+      }
+      // Ensure the view is marked as mounted so ViewLifeCycleManager renders the IonPage
+      if (!enteringViewItem.mount) {
+        enteringViewItem.mount = true;
+      }
       this.handleWaitingForIonPage(routeInfo, enteringViewItem, leavingViewItem, shouldUnmountLeavingViewItem);
       return;
     } else if (!enteringViewItem && !enteringRoute) {
@@ -659,6 +783,7 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     this.pendingPageTransition = false;
 
     const foundView = this.context.findViewItemByRouteInfo(routeInfo, this.id);
+
     if (foundView) {
       const oldPageElement = foundView.ionPageElement;
 
@@ -746,13 +871,28 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
 
       const { routeInfo } = this.props;
       const swipeBackRouteInfo = this.getSwipeBackRouteInfo();
-      const enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+      // First try to find the view in the current outlet
+      let enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+      // If not found in current outlet, search all outlets (for cross-outlet swipe back)
+      if (!enteringViewItem) {
+        enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, undefined, false);
+      }
+
+      // Check if the ionPageElement is still in the document.
+      // A view might have mount=false but still have its ionPageElement in the DOM
+      // (due to timing differences in unmounting).
+      const ionPageInDocument = Boolean(
+        enteringViewItem?.ionPageElement && document.body.contains(enteringViewItem.ionPageElement)
+      );
 
       const canStartSwipe =
         !!enteringViewItem &&
-        // The root url '/' is treated as the first view item (but is never mounted),
-        // so we do not want to swipe back to the root url.
-        enteringViewItem.mount &&
+        // Check if we can swipe to this view. Either:
+        // 1. The view is mounted (mount=true), OR
+        // 2. The view's ionPageElement is still in the document
+        // The second case handles views that have been marked for unmount but haven't
+        // actually been removed from the DOM yet.
+        (enteringViewItem.mount || ionPageInDocument) &&
         // When on the first page it is possible for findViewItemByRouteInfo to
         // return the exact same view you are currently on.
         // Make sure that we are not swiping back to the same instances of a view.
@@ -764,9 +904,20 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     const onStart = async () => {
       const { routeInfo } = this.props;
       const swipeBackRouteInfo = this.getSwipeBackRouteInfo();
-      const enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+      // First try to find the view in the current outlet, then search all outlets
+      let enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+      if (!enteringViewItem) {
+        enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, undefined, false);
+      }
       const leavingViewItem = this.context.findViewItemByRouteInfo(routeInfo, this.id, false);
 
+      // Ensure the entering view is mounted so React keeps rendering it during the gesture.
+      // This is important when the view was previously marked for unmount but its
+      // ionPageElement is still in the DOM.
+      if (enteringViewItem && !enteringViewItem.mount) {
+        enteringViewItem.mount = true;
+      }
+
       // When the gesture starts, kick off a transition controlled via swipe gesture
       if (enteringViewItem && leavingViewItem) {
         await this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back', true);
@@ -784,7 +935,11 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
         // Swipe gesture was aborted - re-hide the page that was going to enter
         const { routeInfo } = this.props;
         const swipeBackRouteInfo = this.getSwipeBackRouteInfo();
-        const enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+        // First try to find the view in the current outlet, then search all outlets
+        let enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, this.id, false);
+        if (!enteringViewItem) {
+          enteringViewItem = this.context.findViewItemByRouteInfo(swipeBackRouteInfo, undefined, false);
+        }
         const leavingViewItem = this.context.findViewItemByRouteInfo(routeInfo, this.id, false);
 
         // Don't hide if entering and leaving are the same (parameterized route edge case)
