fix(react-router): preventing content that's transitioning out from being removed before it's supposed to be, fixing animations

Author: ShaneK

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

@@ -262,9 +262,19 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
       this.outOfScopeUnmountTimeout = undefined;
     }
 
+    // Remove view items from the stack but do NOT apply ion-page-hidden.
+    // ion-page-hidden sets display:none which immediately removes content
+    // from the layout, causing the parent outlet's leaving page to flash
+    // blank during its transition animation (issue #25477).
+    //
+    // Removing from the stack triggers React reconciliation via forceUpdate,
+    // which removes the DOM elements. React batches this re-render after all
+    // componentDidUpdate calls in the current cycle, so the parent outlet's
+    // commit() captures the current DOM state (with content visible) before
+    // React processes the removal. The compositor's cached layer is unaffected
+    // by subsequent DOM changes during the animation.
     const allViewsInOutlet = this.context.getViewItemsForOutlet(this.id);
     allViewsInOutlet.forEach((viewItem) => {
-      hideIonPageElement(viewItem.ionPageElement);
       this.context.unMountViewItem(viewItem);
     });
 
@@ -580,13 +590,15 @@ 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`.
+   * hides the leaving view with inline `visibility:hidden`.
    *
-   * 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.
+   * Skips transitions only for outlets nested inside a parent IonPage's content
+   * area (i.e., an ion-content sits between the outlet and the .ion-page). These
+   * outlets render child pages inside a parent page's scrollable area, and the MD
+   * animation shows both entering and leaving pages simultaneously — causing text
+   * overlap and nested scrollbars. Standard page-level outlets (tabs, routing,
+   * swipe-to-go-back) animate normally even though they sit inside a framework-
+   * managed .ion-page wrapper from the parent outlet's view stack.
    *
    * Uses inline visibility:hidden rather than ion-page-hidden class because
    * core's beforeTransition() removes ion-page-hidden via setPageHidden().
@@ -599,8 +611,22 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     enteringViewItem: ViewItem,
     leavingViewItem: ViewItem | undefined
   ): boolean {
-    const isNestedOutlet = !!this.routerOutletElement?.closest('.ion-page');
-    const shouldSkip = isNestedOutlet && !!leavingViewItem && enteringViewItem !== leavingViewItem;
+    // Only skip for outlets genuinely nested inside a page's content area.
+    // Walk from the outlet up to the nearest .ion-page; if an ion-content
+    // sits in between, the outlet is inside scrollable page content and
+    // animating would cause overlapping pages with duplicate scrollbars.
+    let isInsidePageContent = false;
+    let el: HTMLElement | null = this.routerOutletElement?.parentElement ?? null;
+    while (el) {
+      if (el.classList.contains('ion-page')) break;
+      if (el.tagName === 'ION-CONTENT') {
+        isInsidePageContent = true;
+        break;
+      }
+      el = el.parentElement;
+    }
+
+    const shouldSkip = isInsidePageContent && !!leavingViewItem && enteringViewItem !== leavingViewItem;
 
     if (shouldSkip && leavingViewItem?.ionPageElement) {
       leavingViewItem.ionPageElement.style.setProperty('visibility', 'hidden');

packages/react-router/test/base/tests/e2e/specs/routing.cy.js

@@ -140,6 +140,71 @@ describe('Routing Tests', () => {
     cy.ionPageVisible('tab3-page');
   });
 
+  it('Tab 3 > Other Page, tab page should not flash blank during transition', () => {
+    // Verifies fix for https://github.com/ionic-team/ionic-framework/issues/25477
+    // Tests that navigating from a tab page to a non-tab page does not cause
+    // the tab page content to vanish before the transition animation completes.
+    // Bug: handleOutOfScopeOutlet immediately applied ion-page-hidden (display: none)
+    // to tab views, causing the leaving page to flash blank during the forward transition.
+    cy.visit(`http://localhost:${port}/routing/tabs/tab3?ionic:mode=ios`);
+    cy.ionPageVisible('tab3-page');
+
+    // Set up a MutationObserver BEFORE navigating to detect if ion-page-hidden
+    // (display: none) is ever applied to the tab page during the transition.
+    cy.window().then((win) => {
+      const tabPage = win.document.querySelector('[data-pageid="tab3-page"]');
+      win.__ionPageHiddenApplied = false;
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.target.classList && mutation.target.classList.contains('ion-page-hidden')) {
+            win.__ionPageHiddenApplied = true;
+          }
+        }
+      });
+      observer.observe(tabPage, { attributes: true, attributeFilter: ['class'] });
+      win.__tabPageObserver = observer;
+    });
+
+    // Navigate to non-tab page
+    cy.contains('ion-button', 'Go to Other Page').click();
+    cy.ionPageVisible('other-page');
+
+    // Verify ion-page-hidden was never applied during the transition
+    cy.window().then((win) => {
+      win.__tabPageObserver.disconnect();
+      expect(win.__ionPageHiddenApplied).to.be.false;
+    });
+  });
+
+  it('Home > Other Page, tab page should not flash blank during transition', () => {
+    // Verifies fix for https://github.com/ionic-team/ionic-framework/issues/25477
+    // Same test as above but from the Home tab using routerLink navigation
+    cy.visit(`http://localhost:${port}/routing/tabs/home?ionic:mode=ios`);
+    cy.ionPageVisible('home-page');
+
+    cy.window().then((win) => {
+      const tabPage = win.document.querySelector('[data-pageid="home-page"]');
+      win.__ionPageHiddenApplied = false;
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.target.classList && mutation.target.classList.contains('ion-page-hidden')) {
+            win.__ionPageHiddenApplied = true;
+          }
+        }
+      });
+      observer.observe(tabPage, { attributes: true, attributeFilter: ['class'] });
+      win.__tabPageObserver = observer;
+    });
+
+    cy.contains('ion-item', 'Other Page').click();
+    cy.ionPageVisible('other-page');
+
+    cy.window().then((win) => {
+      win.__tabPageObserver.disconnect();
+      expect(win.__ionPageHiddenApplied).to.be.false;
+    });
+  });
+
   it('/ > Menu > Favorites > Menu > Tabs, should be back on Home', () => {
     // Tests transferring from one outlet to another and back again via menu
     cy.visit(`http://localhost:${port}/routing`);