fix(react-router): restore back navigation and swipe over a root splat route

Author: ShaneK

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

@@ -15,7 +15,7 @@ import { analyzeRouteChildren, computeParentPath } from './utils/computeParentPa
 import { derivePathnameToMatch, matchPath } from './utils/pathMatching';
 import { normalizePathnameForComparison } from './utils/pathNormalization';
 import { extractRouteChildren, isNavigateElement } from './utils/routeElements';
-import { isForwardPush, sortViewsBySpecificity } from './utils/viewItemUtils';
+import { isForwardPush, isSwipeRevealed, sortViewsBySpecificity } from './utils/viewItemUtils';
 
 /**
  * Delay in milliseconds before removing a Navigate view item after a redirect.
@@ -510,7 +510,7 @@ export class ReactRouterViewStack extends ViewStacks {
         }
       }
 
-      if (hasSpecificMatch) {
+      if (hasSpecificMatch && !isSwipeRevealed(viewItem)) {
         // A splat can be the outlet's container page rather than a "not found" fallback.
         // Pushed over it is the page underneath, so unmounting it destroys its state and
         // leaves nothing for back to reveal. Hiding it below covers that. A view with no
@@ -636,8 +636,11 @@ export class ReactRouterViewStack extends ViewStacks {
 
         // Persist the mount path for subsequent calls, mirroring StackManager.outletMountPath.
         // Unlike outletParentPaths (cleared when parentPath is undefined), the mount path is
-        // intentionally sticky — it anchors the outlet's scope and is only removed in clear().
-        if (result.outletMountPath && !this.outletMountPaths.has(outletId)) {
+        // intentionally sticky, it anchors the outlet's scope and is only removed in clear().
+        // A root outlet is skipped because it is mounted under nothing, so an inferred path
+        // would scope it to whatever route was active. parentPathnameBase is undefined
+        // exactly when the outlet has no parent matches.
+        if (parentPathnameBase && result.outletMountPath && !this.outletMountPaths.has(outletId)) {
           this.outletMountPaths.set(outletId, result.outletMountPath);
         }
       }

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

@@ -20,7 +20,7 @@ import {
 import { derivePathnameToMatch, matchPath } from './utils/pathMatching';
 import { stripTrailingSlash } from './utils/pathNormalization';
 import { extractRouteChildren, getRoutesChildren, isNavigateElement } from './utils/routeElements';
-import { isForwardPush, isOverMatchingRoute } from './utils/viewItemUtils';
+import { clearSwipeRevealed, isForwardPush, isOverMatchingRoute, markSwipeRevealed } from './utils/viewItemUtils';
 
 /**
  * Delay in milliseconds before unmounting a view after a transition completes.
@@ -119,6 +119,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
   routerOutletElement: HTMLIonRouterOutletElement | undefined;
   prevProps?: StackManagerProps;
   skipTransition: boolean;
+  /** The view item the in-flight swipe gesture revealed, so the same one gets cleared. */
+  private swipeRevealedViewItem?: ViewItem;
 
   stackContextValue: StackContextState = {
     registerIonPage: this.registerIonPage.bind(this),
@@ -220,7 +222,9 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
           hasWildcardRoute,
         });
 
-        if (result.outletMountPath && !this.outletMountPath) {
+        // A root outlet is mounted under nothing, so caching the inferred path would scope
+        // it to whatever route was active and make every other pathname look out of scope.
+        if (!this.isRootOutlet && result.outletMountPath && !this.outletMountPath) {
           this.outletMountPath = result.outletMountPath;
         }
 
@@ -305,6 +309,12 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     return false;
   }
 
+  /** Clears the reveal flag from the view item the gesture marked. */
+  private clearSwipeRevealedView(): void {
+    clearSwipeRevealed(this.swipeRevealedViewItem);
+    this.swipeRevealedViewItem = undefined;
+  }
+
   /**
    * Handles out-of-scope outlet. Returns true if transition should be aborted.
    */
@@ -525,9 +535,7 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
         routeInfo.lastPathname.startsWith(containerBase + '/') || routeInfo.lastPathname === containerBase;
 
       // A root-level "/*" leaves an empty base, so both checks above are true for every
-      // pathname and the shortcut would skip every navigation in this outlet. That only
-      // stops the shortcut misfiring. The root "/*" shape has other problems and is still
-      // not fully working, which framework-react.md covers.
+      // pathname and the shortcut would otherwise skip every navigation in this outlet.
       if (containerBase !== '' && currentInContainer && previousInContainer) {
         const updatedMatch = matchComponent(
           enteringViewItem.reactElement,
@@ -1089,6 +1097,7 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     }
     this.waitingForIonPage = false;
     this.preservedViewItems.clear();
+    this.clearSwipeRevealedView();
 
     // Hide all views in this outlet before clearing.
     // This is critical for nested outlets - when the parent component unmounts,
@@ -1124,6 +1133,11 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       return;
     }
 
+    // A completed swipe keeps its reveal flag past goBack() so the deactivation scan does
+    // not re-hide the page between the gesture ending and the URL settling. Clear it at
+    // the start of the transition for the new pathname.
+    this.clearSwipeRevealedView();
+
     // Find entering and leaving view items
     const viewItems = this.findViewItems(routeInfo);
     let enteringViewItem = viewItems.enteringViewItem;
@@ -1435,6 +1449,10 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     };
 
     const onStart = async () => {
+      // Core only calls onEnd when a progress animation exists, so with animations off a
+      // previous gesture can leave its mark behind. Drop any stale one before marking.
+      this.clearSwipeRevealedView();
+
       const { routeInfo } = this.props;
       const swipeBackRouteInfo = this.getSwipeBackRouteInfo();
       const enteringViewItem = this.findEnteringViewForSwipe(swipeBackRouteInfo);
@@ -1465,6 +1483,12 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
 
       // When the gesture starts, kick off a transition controlled via swipe gesture
       if (enteringViewItem && leavingViewItem) {
+        // Without a leaving view there is no progress animation, and core only calls
+        // swipeHandler.onEnd when one exists, so nothing would clear the mark until the
+        // next transition.
+        markSwipeRevealed(enteringViewItem);
+        this.swipeRevealedViewItem = enteringViewItem;
+
         await this.transitionPage(routeInfo, enteringViewItem, leavingViewItem, 'back', true);
       }
 
@@ -1492,6 +1516,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
         const enteringViewItem = this.findEnteringViewForSwipe(swipeBackRouteInfo);
         const leavingViewItem = this.context.findViewItemByRouteInfo(routeInfo, this.id, false);
 
+        this.clearSwipeRevealedView();
+
         // Don't hide if entering and leaving are the same (parameterized route edge case)
         if (enteringViewItem !== leavingViewItem && enteringViewItem?.ionPageElement !== undefined) {
           hideIonPageElement(enteringViewItem.ionPageElement);

packages/react-router/src/ReactRouter/utils/viewItemUtils.ts

@@ -55,6 +55,30 @@ export const isOverMatchingRoute = (route: { path?: string; index?: boolean }):
 export const isForwardPush = (routeInfo: Pick<RouteInfo, 'routeAction' | 'routeDirection'>): boolean =>
   routeInfo.routeAction === 'push' && routeInfo.routeDirection === 'forward';
 
+const swipeRevealed = new WeakSet<ViewItem>();
+
+/**
+ * Marks the page a swipe-back gesture has revealed. For the length of the drag that page
+ * is on screen while a more specific sibling still matches the current pathname, and the
+ * deactivation scan in `renderViewItem` would otherwise re-hide it on the next render and
+ * leave the user dragging a blank page.
+ */
+export const markSwipeRevealed = (viewItem: ViewItem | undefined): void => {
+  if (viewItem) {
+    swipeRevealed.add(viewItem);
+  }
+};
+
+/** Drops the mark once the gesture ends, so the view is hidden normally again. */
+export const clearSwipeRevealed = (viewItem: ViewItem | undefined): void => {
+  if (viewItem) {
+    swipeRevealed.delete(viewItem);
+  }
+};
+
+/** True while a swipe-back gesture is showing this view. */
+export const isSwipeRevealed = (viewItem: ViewItem): boolean => swipeRevealed.has(viewItem);
+
 /**
  * Sorts view items by route specificity (most specific first).
  *

packages/react-router/test/base/tests/e2e/playwright/splat-sibling.spec.ts

@@ -50,17 +50,14 @@ test.describe('splat route with a more specific sibling', () => {
     await expect(page.locator('[data-testid="count"]')).toHaveText('3');
   });
 
-  /*
-    Swipe-to-go-back over a splat container. Animations must be on, so the gesture reveals
-    the page underneath rather than a commit doing it.
-
-    The gesture starts, but the entering page goes back to display:none with
-    ion-page-hidden re-applied, so the drag shows nothing and the navigation never
-    commits. Neither the renderViewItem deactivation scan nor the splat's stored
-    routeData.match is the cause, both were tried. No follow-up ticket yet, so there is no
-    annotation on this one, and it is not issue 31477.
-  */
-  test.fixme('reveals the splat page while swiping back', async ({ page }) => {
+  // Animations stay on here, so the gesture reveals the page underneath rather than a
+  // commit doing it.
+  test('reveals the splat page while swiping back', async ({ page }, testInfo) => {
+    testInfo.annotations.push({
+      type: 'issue',
+      description: 'https://github.com/ionic-team/ionic-framework/issues/31477',
+    });
+
     await page.goto('/splat-sibling?ionic:mode=ios');
     await ionPageVisible(page, 'splat-sibling-home');
 
@@ -69,6 +66,11 @@ test.describe('splat route with a more specific sibling', () => {
 
     await page.locator('[data-testid="open-detail"]').click();
     await ionPageVisible(page, 'splat-sibling-detail');
+    // ionPageHidden resolves early here, because the deactivation scan applies
+    // ion-page-hidden at render time rather than on commit, so wait out the push
+    // transition before starting the gesture.
+    await ionPageHidden(page, 'splat-sibling-home');
+    await page.waitForTimeout(600);
 
     await ionSwipeToGoBack(page, true, 'ion-router-outlet#splat-sibling-outlet');