fix(react-router): dispatch view lifecycle events on non-animated transitions (#31497)

Issue number: resolves #31479

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?

Currently, switching tabs or following a link with
`routerDirection="none"` fires none of the four view lifecycle events,
so a page that loads its data in `useIonViewWillEnter` renders empty.
The non-animated branch of `StackManager.transitionPage()` skips
`routerOutlet.commit()` and swaps the page classes itself to avoid
intermediate paints, and core dispatches all four events from inside
`commit()`, so they never fire. A capturing listener on the
`ion-router-outlet` gets nothing either, so it isn't a problem with the
hooks.

## What is the new behavior?

That branch now dispatches the four events itself, in the same order
core's `transition()` uses. The class swap moved to after all four, so
the leaving page is still on screen for its leave events and the
entering page is revealed only once they've fired. That's what core does
on the animated path, where `beforeTransition` un-hides the leaving page
and `ion-page-hidden` only goes back on after `commit()` resolves, and
it matters because `ion-page-hidden` is `display: none`, so a
`useIonViewDidLeave` handler reading `scrollTop` off the outgoing page
was getting 0.

The two dispatch sites that already existed in this file for
out-of-scope and root navigation now share the same helper.

## Does this introduce a breaking change?

- [ ] Yes
- [X] No

## Other information

The events used to come from core here. This path called
`commit(enteringEl, undefined, { duration: 0 })` until
[12f0d5e](12f0d5e)
dropped it to fix a white flash during tab switches, and with no leaving
element core took its `noAnimation` branch and fired the enter pair, so
the enter half of this is a regression from that commit. Putting the
call back would get the events plus focus and z-index handling from core
for free, but it risks the flash it was removed for, so this dispatches
them directly instead.

The patch on the issue fires the enter events unconditionally. This
gates them on the generation check so a superseded transition doesn't
announce an entry, and it skips the leave events when the leaving page
already has `ion-page-hidden`, because two transitions sharing a leaving
element would otherwise run its `useIonViewDidLeave` teardown twice. The
check is the class rather than `isViewVisible` since a nested outlet
marks its leaving page `visibility: hidden` before we get here and still
needs `ionViewDidLeave` to unmount.

Preview:

- [Tab
lifecycle](https://ionic-framework-git-fix-rr6-lifecycle-non-animated-ionic1.vercel.app/react-router/tab-lifecycle/home)
-
[routerDirection="none"](https://ionic-framework-git-fix-rr6-lifecycle-non-animated-ionic1.vercel.app/react-router/direction-none-back/a)

## Current Dev Build
```
9.0.6-dev.11790615145.1d8c56a2
```

Author: ShaneK

packages/react-router/package-lock.json

@@ -37,6 +37,7 @@
     "dist/"
   ],
   "dependencies": {
+    "@ionic/core": "^9.0.5",
     "@ionic/react": "^9.0.5",
     "tslib": "*"
   },

packages/react-router/package.json

@@ -4,6 +4,12 @@
  * particularly with animations and swipe gestures.
  */
 
+import {
+  LIFECYCLE_DID_ENTER,
+  LIFECYCLE_DID_LEAVE,
+  LIFECYCLE_WILL_ENTER,
+  LIFECYCLE_WILL_LEAVE,
+} from '@ionic/core/components';
 import type { RouteInfo, StackContextState, ViewItem } from '@ionic/react';
 import { IonRoute, RouteManagerContext, StackContext, createDebugLogger, generateId, getConfig } from '@ionic/react';
 import React from 'react';
@@ -89,6 +95,19 @@ const revealIonPageForSwipeBack = (element: HTMLElement | undefined): void => {
   }
 };
 
+type ViewLifecycleEvent =
+  | typeof LIFECYCLE_WILL_ENTER
+  | typeof LIFECYCLE_DID_ENTER
+  | typeof LIFECYCLE_WILL_LEAVE
+  | typeof LIFECYCLE_DID_LEAVE;
+
+/** Dispatches a view lifecycle event the way core's `lifecycle()` does. */
+const dispatchLifecycleEvent = (element: HTMLElement | undefined, eventName: ViewLifecycleEvent): void => {
+  if (element) {
+    element.dispatchEvent(new CustomEvent(eventName, { bubbles: false, cancelable: false }));
+  }
+};
+
 /**
  * A leaf view is "preservable" on browser-back (pop) when its React state
  * should survive a forward-pop round-trip. Non-parameterized leaf paths
@@ -367,12 +386,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
     const allViewsInOutlet = this.context.getViewItemsForOutlet(this.id);
     allViewsInOutlet.forEach((viewItem) => {
       if (viewItem.ionPageElement && isViewVisible(viewItem.ionPageElement)) {
-        viewItem.ionPageElement.dispatchEvent(
-          new CustomEvent('ionViewWillLeave', { bubbles: false, cancelable: false })
-        );
-        viewItem.ionPageElement.dispatchEvent(
-          new CustomEvent('ionViewDidLeave', { bubbles: false, cancelable: false })
-        );
+        dispatchLifecycleEvent(viewItem.ionPageElement, LIFECYCLE_WILL_LEAVE);
+        dispatchLifecycleEvent(viewItem.ionPageElement, LIFECYCLE_DID_LEAVE);
       }
     });
 
@@ -409,12 +424,8 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
         return;
       }
       if (viewItem.ionPageElement && isViewVisible(viewItem.ionPageElement)) {
-        viewItem.ionPageElement.dispatchEvent(
-          new CustomEvent('ionViewWillLeave', { bubbles: false, cancelable: false })
-        );
-        viewItem.ionPageElement.dispatchEvent(
-          new CustomEvent('ionViewDidLeave', { bubbles: false, cancelable: false })
-        );
+        dispatchLifecycleEvent(viewItem.ionPageElement, LIFECYCLE_WILL_LEAVE);
+        dispatchLifecycleEvent(viewItem.ionPageElement, LIFECYCLE_DID_LEAVE);
       }
       this.context.unMountViewItem(viewItem);
     });
@@ -1782,10 +1793,36 @@ export class StackManager extends React.PureComponent<StackManagerProps> {
           // Bail out if the component unmounted during waitForComponentsReady
           if (!this._isMounted) return;
 
+          const isCurrent = myGeneration === this.transitionGeneration;
+          // A page the newest transition is entering is not leaving after all.
+          const isLeaving = isCurrent || leavingEl !== this.transitionEnteringElement;
+          // Already hidden means the leave events have fired. This checks the class rather
+          // than `isViewVisible` because a nested outlet marks its leaving page
+          // `visibility: hidden` before we get here and still needs `ionViewDidLeave`.
+          const announceLeaving = isLeaving && !leavingEl.classList.contains('ion-page-hidden');
+
+          /**
+           * Dispatch the lifecycle events, since we skipped `commit()`. Only the
+           * newest transition fires the entering events, and the class swap follows
+           * all four so the ordering matches core's `transition()`.
+           *
+           * These run after `waitForComponentsReady` because on a first mount the
+           * page has not attached its listeners yet.
+           */
+          if (announceLeaving) {
+            dispatchLifecycleEvent(leavingEl, LIFECYCLE_WILL_LEAVE);
+          }
+          if (isCurrent) {
+            dispatchLifecycleEvent(enteringEl, LIFECYCLE_WILL_ENTER);
+            dispatchLifecycleEvent(enteringEl, LIFECYCLE_DID_ENTER);
+          }
+          if (announceLeaving) {
+            dispatchLifecycleEvent(leavingEl, LIFECYCLE_DID_LEAVE);
+          }
+
           // Swap visibility synchronously - show entering, hide leaving
-          // Skip hiding if a newer transition already made leavingEl the entering view
           enteringEl.classList.remove('ion-page-invisible');
-          if (myGeneration === this.transitionGeneration || leavingEl !== this.transitionEnteringElement) {
+          if (isLeaving) {
             leavingEl.classList.add('ion-page-hidden');
             leavingEl.setAttribute('aria-hidden', 'true');
           }

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

@@ -8,18 +8,28 @@ import {
   IonRouterOutlet,
   IonBackButton,
   IonButtons,
+  useIonViewDidEnter,
+  useIonViewDidLeave,
+  useIonViewWillEnter,
+  useIonViewWillLeave,
 } from '@ionic/react';
 import React from 'react';
 import { Route, Navigate } from 'react-router-dom';
 
 import TestDescription from '../../components/TestDescription';
+import { pushLifecycleEvent } from '../../utils';
 
 /**
  * Tests that IonBackButton works correctly after navigating with
  * routerDirection="none". The back button should use history to
  * determine the previous page, not fall back to defaultHref.
  */
 const PageA: React.FC = () => {
+  useIonViewWillEnter(() => pushLifecycleEvent('a:ionViewWillEnter'));
+  useIonViewDidEnter(() => pushLifecycleEvent('a:ionViewDidEnter'));
+  useIonViewWillLeave(() => pushLifecycleEvent('a:ionViewWillLeave'));
+  useIonViewDidLeave(() => pushLifecycleEvent('a:ionViewDidLeave'));
+
   return (
     <IonPage data-pageid="direction-none-page-a">
       <IonHeader>
@@ -41,6 +51,11 @@ const PageA: React.FC = () => {
 };
 
 const PageB: React.FC = () => {
+  useIonViewWillEnter(() => pushLifecycleEvent('b:ionViewWillEnter'));
+  useIonViewDidEnter(() => pushLifecycleEvent('b:ionViewDidEnter'));
+  useIonViewWillLeave(() => pushLifecycleEvent('b:ionViewWillLeave'));
+  useIonViewDidLeave(() => pushLifecycleEvent('b:ionViewDidLeave'));
+
   return (
     <IonPage data-pageid="direction-none-page-b">
       <IonHeader>

packages/react-router/test/base/src/pages/direction-none-back/DirectionNoneBack.tsx

@@ -21,11 +21,7 @@ import React from 'react';
 import { Route, Navigate } from 'react-router';
 
 import TestDescription from '../../components/TestDescription';
-
-const pushEvent = (event: string) => {
-  (window as any).lifecycleEvents = (window as any).lifecycleEvents || [];
-  (window as any).lifecycleEvents.push(event);
-};
+import { pushLifecycleEvent } from '../../utils';
 
 const TabLifecycle: React.FC = () => {
   return (
@@ -50,10 +46,10 @@ const TabLifecycle: React.FC = () => {
 };
 
 const HomeTab: React.FC = () => {
-  useIonViewWillEnter(() => pushEvent('home:ionViewWillEnter'));
-  useIonViewDidEnter(() => pushEvent('home:ionViewDidEnter'));
-  useIonViewWillLeave(() => pushEvent('home:ionViewWillLeave'));
-  useIonViewDidLeave(() => pushEvent('home:ionViewDidLeave'));
+  useIonViewWillEnter(() => pushLifecycleEvent('home:ionViewWillEnter'));
+  useIonViewDidEnter(() => pushLifecycleEvent('home:ionViewDidEnter'));
+  useIonViewWillLeave(() => pushLifecycleEvent('home:ionViewWillLeave'));
+  useIonViewDidLeave(() => pushLifecycleEvent('home:ionViewDidLeave'));
 
   return (
     <IonPage data-pageid="tab-lifecycle-home">
@@ -73,10 +69,10 @@ const HomeTab: React.FC = () => {
 };
 
 const SettingsTab: React.FC = () => {
-  useIonViewWillEnter(() => pushEvent('settings:ionViewWillEnter'));
-  useIonViewDidEnter(() => pushEvent('settings:ionViewDidEnter'));
-  useIonViewWillLeave(() => pushEvent('settings:ionViewWillLeave'));
-  useIonViewDidLeave(() => pushEvent('settings:ionViewDidLeave'));
+  useIonViewWillEnter(() => pushLifecycleEvent('settings:ionViewWillEnter'));
+  useIonViewDidEnter(() => pushLifecycleEvent('settings:ionViewDidEnter'));
+  useIonViewWillLeave(() => pushLifecycleEvent('settings:ionViewWillLeave'));
+  useIonViewDidLeave(() => pushLifecycleEvent('settings:ionViewDidLeave'));
 
   return (
     <IonPage data-pageid="tab-lifecycle-settings">

packages/react-router/test/base/src/pages/tab-lifecycle/TabLifecycle.tsx

@@ -1,2 +1,3 @@
 export * from './generateId';
+export * from './lifecycleEvents';
 export * from './dev';

packages/react-router/test/base/src/utils/index.ts

@@ -0,0 +1,5 @@
+/** Records a view lifecycle event on `window.lifecycleEvents` for a spec to assert on. */
+export const pushLifecycleEvent = (event: string) => {
+  (window as any).lifecycleEvents = (window as any).lifecycleEvents || [];
+  (window as any).lifecycleEvents.push(event);
+};

packages/react-router/test/base/src/utils/lifecycleEvents.ts

@@ -0,0 +1,44 @@
+import { test, expect, type Page } from '@playwright/test';
+import { ionPageVisible, resetLifecycleEvents, settledLifecycleEvents, withTestingMode } from './utils/test-utils';
+
+/**
+ * A navigation with routerDirection="none" is not animated, but it must still
+ * fire the four view lifecycle events, in the same order an animated one does.
+ */
+test.describe('routerDirection="none" lifecycle events', () => {
+  const expectedEvents = ['a:ionViewWillLeave', 'b:ionViewWillEnter', 'b:ionViewDidEnter', 'a:ionViewDidLeave'];
+
+  const goToPageA = async (page: Page) => {
+    await page.goto(withTestingMode('/direction-none-back/a'));
+    await ionPageVisible(page, 'direction-none-page-a');
+    await resetLifecycleEvents(page);
+  };
+
+  test('should fire enter and leave events on a routerDirection="none" navigation', async ({ page }, testInfo) => {
+    testInfo.annotations.push({
+      type: 'issue',
+      description: 'https://github.com/ionic-team/ionic-framework/issues/31479',
+    });
+
+    await goToPageA(page);
+
+    await page.locator('#go-none').click();
+    await ionPageVisible(page, 'direction-none-page-b');
+
+    expect(await settledLifecycleEvents(page)).toEqual(expectedEvents);
+  });
+
+  /**
+   * The control. A forward navigation keeps its direction, so it takes the
+   * regular transition path, and its event order is the one the test above
+   * has to match.
+   */
+  test('should fire the same events for a forward navigation', async ({ page }) => {
+    await goToPageA(page);
+
+    await page.locator('#go-forward').click();
+    await ionPageVisible(page, 'direction-none-page-b');
+
+    expect(await settledLifecycleEvents(page)).toEqual(expectedEvents);
+  });
+});

packages/react-router/test/base/tests/e2e/playwright/direction-none-lifecycle.spec.ts

@@ -1,5 +1,12 @@
 import { test, expect } from '@playwright/test';
-import { ionPageVisible, ionTabClick, trackPeakMatchCount, withTestingMode } from './utils/test-utils';
+import {
+  ionPageVisible,
+  ionTabClick,
+  resetLifecycleEvents,
+  settledLifecycleEvents,
+  trackPeakMatchCount,
+  withTestingMode,
+} from './utils/test-utils';
 
 test.describe('Tab Lifecycle Events', () => {
   test.beforeEach(async ({ page }) => {
@@ -17,12 +24,12 @@ test.describe('Tab Lifecycle Events', () => {
     await page.goto(withTestingMode('/tab-lifecycle/home'));
     await ionPageVisible(page, 'tab-lifecycle-home');
 
-    await page.evaluate(() => { (window as any).lifecycleEvents = []; });
+    await resetLifecycleEvents(page);
 
     await page.locator('#go-outside').click();
     await ionPageVisible(page, 'tab-lifecycle-outside');
 
-    const events = await page.evaluate(() => (window as any).lifecycleEvents as string[]);
+    const events = await settledLifecycleEvents(page);
     expect(events).toContain('home:ionViewWillLeave');
     expect(events).toContain('home:ionViewDidLeave');
   });
@@ -39,12 +46,12 @@ test.describe('Tab Lifecycle Events', () => {
     await ionTabClick(page, 'Settings');
     await ionPageVisible(page, 'tab-lifecycle-settings');
 
-    await page.evaluate(() => { (window as any).lifecycleEvents = []; });
+    await resetLifecycleEvents(page);
 
     await page.locator('#go-outside-settings').click();
     await ionPageVisible(page, 'tab-lifecycle-outside');
 
-    const events = await page.evaluate(() => (window as any).lifecycleEvents as string[]);
+    const events = await settledLifecycleEvents(page);
     expect(events).toContain('settings:ionViewWillLeave');
     expect(events).toContain('settings:ionViewDidLeave');
   });
@@ -61,16 +68,63 @@ test.describe('Tab Lifecycle Events', () => {
     await page.locator('#go-outside').click();
     await ionPageVisible(page, 'tab-lifecycle-outside');
 
-    await page.evaluate(() => { (window as any).lifecycleEvents = []; });
+    await resetLifecycleEvents(page);
 
     await page.locator('#go-back-to-tabs').click();
     await ionPageVisible(page, 'tab-lifecycle-home');
 
-    const events = await page.evaluate(() => (window as any).lifecycleEvents as string[]);
+    const events = await settledLifecycleEvents(page);
     expect(events).toContain('home:ionViewWillEnter');
     expect(events).toContain('home:ionViewDidEnter');
   });
 
+  test('should fire enter and leave events when switching tabs', async ({ page }, testInfo) => {
+    testInfo.annotations.push({
+      type: 'issue',
+      description: 'https://github.com/ionic-team/ionic-framework/issues/31479',
+    });
+
+    await page.goto(withTestingMode('/tab-lifecycle/home'));
+    await ionPageVisible(page, 'tab-lifecycle-home');
+
+    await resetLifecycleEvents(page);
+
+    await ionTabClick(page, 'Settings');
+    await ionPageVisible(page, 'tab-lifecycle-settings');
+
+    expect(await settledLifecycleEvents(page)).toEqual([
+      'home:ionViewWillLeave',
+      'settings:ionViewWillEnter',
+      'settings:ionViewDidEnter',
+      'home:ionViewDidLeave',
+    ]);
+  });
+
+  test('should fire enter and leave events when switching back to a visited tab', async ({ page }, testInfo) => {
+    testInfo.annotations.push({
+      type: 'issue',
+      description: 'https://github.com/ionic-team/ionic-framework/issues/31479',
+    });
+
+    await page.goto(withTestingMode('/tab-lifecycle/home'));
+    await ionPageVisible(page, 'tab-lifecycle-home');
+
+    await ionTabClick(page, 'Settings');
+    await ionPageVisible(page, 'tab-lifecycle-settings');
+
+    await resetLifecycleEvents(page);
+
+    await ionTabClick(page, 'Home');
+    await ionPageVisible(page, 'tab-lifecycle-home');
+
+    expect(await settledLifecycleEvents(page)).toEqual([
+      'settings:ionViewWillLeave',
+      'home:ionViewWillEnter',
+      'home:ionViewDidEnter',
+      'settings:ionViewDidLeave',
+    ]);
+  });
+
   // A duplicate tab page, even briefly, fails this spec's page assertions on a
   // strict mode violation.
   test('should not duplicate the tab page in the DOM while returning to the tabs', async ({ page }) => {