From 96ee3ce44e29c1f596950f0391543640e0e4b323 Mon Sep 17 00:00:00 2001
From: Patrick Kenny <github@ptmkenny.com>
Date: Fri, 21 Aug 2026 01:15:11 +0900
Subject: [PATCH 1/3] fix(react): re-attach nested inline overlay after a
 Suspense hide

---
 .../createInlineOverlayComponent.spec.tsx     | 66 +++++++++++++++++++
 .../createInlineOverlayComponent.tsx          | 29 +++++++-
 2 files changed, 93 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx b/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
index e2cb8176af8..6e256d2d20f 100644
--- a/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
+++ b/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
@@ -131,6 +131,72 @@ describe('createInlineOverlayComponent: unmount cleanup', () => {
     expect(document.querySelector('ion-popover')).toBeNull();
   });
 
+  it('restores a relocated nested overlay when a Suspense boundary hides and reveals it', async () => {
+    /**
+     * React runs `componentWillUnmount` when it *hides* a subtree as well as
+     * when it destroys one: a Suspense boundary falling back after mount runs
+     * it, then runs `componentDidMount` again on the same instance when the
+     * boundary reveals its content. A host removed while hidden has to come
+     * back, since React only re-inserts nodes it removed itself. Otherwise an
+     * overlay that was mid-`present()` is gone for good, with no dismiss
+     * lifecycle ever firing.
+     */
+    let resolveSuspender!: () => void;
+    let hasResolved = false;
+    const suspenderPromise = new Promise<void>((resolve) => {
+      resolveSuspender = () => {
+        hasResolved = true;
+        resolve();
+      };
+    });
+
+    const Suspender = () => {
+      if (!hasResolved) {
+        throw suspenderPromise;
+      }
+      return null;
+    };
+
+    let suspend!: () => void;
+    const Boundary = () => {
+      const [isSuspended, setIsSuspended] = React.useState(false);
+      suspend = () => setIsSuspended(true);
+
+      return (
+        <React.Suspense fallback={<div>loading</div>}>
+          <IonModal keepContentsMounted={true}>
+            <IonPopover />
+          </IonModal>
+          {isSuspended ? <Suspender /> : null}
+        </React.Suspense>
+      );
+    };
+
+    render(<Boundary />);
+
+    const popover = document.body.querySelector('ion-popover') as HTMLElement;
+
+    // CoreDelegate teleports the host out of its `<template>` as `present()`
+    // starts, before the events that flip `isOpen` have fired.
+    teleport(popover);
+    const teleportDestination = popover.parentElement as HTMLElement;
+
+    // A sibling suspends, so React hides the boundary's content: the overlay
+    // wrapper gets componentWillUnmount without actually being unmounted.
+    act(() => {
+      suspend();
+    });
+
+    // The boundary reveals its content again on the same instances.
+    await act(async () => {
+      resolveSuspender();
+      await suspenderPromise;
+    });
+
+    expect(popover.isConnected).toBe(true);
+    expect(popover.parentElement).toBe(teleportDestination);
+  });
+
   it('removes an open, relocated nested overlay on unmount', () => {
     const { unmount } = render(
       <IonModal keepContentsMounted={true}>
diff --git a/packages/react/src/components/createInlineOverlayComponent.tsx b/packages/react/src/components/createInlineOverlayComponent.tsx
index 0fc5fe204ab..4e0a88f63af 100644
--- a/packages/react/src/components/createInlineOverlayComponent.tsx
+++ b/packages/react/src/components/createInlineOverlayComponent.tsx
@@ -57,6 +57,12 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
     stableMergedRefs: React.RefCallback<HTMLElement>;
     portalTarget: HTMLElement | null;
     isUnmounted = false;
+    /**
+     * A relocated nested host removed in `componentWillUnmount`, together with
+     * the parent it was removed from, so `componentDidMount` can put it back
+     * when React was only hiding this subtree rather than destroying it.
+     */
+    removedHost: { node: HTMLElement; parent: HTMLElement } | null = null;
 
     constructor(props: InternalProps) {
       super(props);
@@ -87,6 +93,21 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
       // componentWillUnmount.
       this.isUnmounted = false;
 
+      /**
+       * React also calls `componentWillUnmount` when it *hides* a subtree
+       * rather than destroying it - a Suspense boundary falling back, an
+       * Offscreen tree, or the StrictMode dev cycle - and calls
+       * `componentDidMount` again on the same instance when it reveals it.
+       * Put back a nested host removed there: the overlay can still be
+       * mid-`present()`, and React never re-inserts a node it did not remove
+       * itself, so the presenting overlay would be lost for good.
+       */
+      const { removedHost } = this;
+      this.removedHost = null;
+      if (removedHost && !removedHost.node.isConnected && removedHost.parent.isConnected) {
+        removedHost.parent.appendChild(removedHost.node);
+      }
+
       this.componentDidUpdate(this.props);
 
       this.ref.current?.addEventListener('ionMount', this.handleIonMount);
@@ -149,9 +170,13 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
            * Nested overlays render inline inside a `<template>`. If the host
            * has been moved out of that template, React's unmount won't reach
            * it, so remove it directly. A host still in its template is left
-           * for React to remove.
+           * for React to remove. The removal is recorded so `componentDidMount`
+           * can undo it if this turns out to be a hide rather than a real
+           * unmount.
            */
-          if (!(node.parentElement instanceof HTMLTemplateElement)) {
+          const parent = node.parentElement;
+          if (parent && !(parent instanceof HTMLTemplateElement)) {
+            this.removedHost = { node, parent };
             node.remove();
           }
         } else if (this.portalTarget && node.parentNode !== this.portalTarget) {

From b8f454b4943978058153bb6e44ffc5d7fa4b45b9 Mon Sep 17 00:00:00 2001
From: Patrick Kenny <github@ptmkenny.com>
Date: Fri, 21 Aug 2026 11:07:47 +0900
Subject: [PATCH 2/3] fix for appendChild loses position, more tests

---
 .../createInlineOverlayComponent.spec.tsx     | 334 +++++++++++++++---
 .../createInlineOverlayComponent.tsx          |  44 ++-
 .../overlay-components/ModalSuspense.tsx      | 107 ++++++
 .../overlay-components/OverlayComponents.tsx  |   6 +
 .../overlay-components/IonModalSuspense.cy.ts |  51 +++
 5 files changed, 472 insertions(+), 70 deletions(-)
 create mode 100644 packages/react/test/base/src/pages/overlay-components/ModalSuspense.tsx
 create mode 100644 packages/react/test/base/tests/e2e/specs/overlay-components/IonModalSuspense.cy.ts

diff --git a/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx b/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
index 6e256d2d20f..6c12aa60d5b 100644
--- a/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
+++ b/packages/react/src/components/__tests__/createInlineOverlayComponent.spec.tsx
@@ -30,14 +30,97 @@ const IonPopover = createInlineOverlayComponent<any, any>('ion-popover', undefin
 
 /**
  * Simulate what CoreDelegate does when an overlay presents: it teleports the
- * host element out of its portal parent into another in-document container
- * (the running app uses ion-app; here we use any sibling).
+ * host element out of its portal parent into another in-document container.
+ * The running app uses the single `ion-app` for every overlay, so one shared
+ * destination is created lazily and reused - overlays that present in
+ * sequence end up as siblings there, in presentation order.
  */
 const teleport = (el: HTMLElement) => {
-  const dest = document.createElement('div');
-  dest.id = 'teleport-destination';
-  document.body.appendChild(dest);
+  let dest = document.getElementById('teleport-destination');
+  if (!dest) {
+    dest = document.createElement('div');
+    dest.id = 'teleport-destination';
+    document.body.appendChild(dest);
+  }
   dest.appendChild(el);
+  return dest;
+};
+
+/**
+ * A component that suspends until `resolve` is called, plus the helpers to
+ * drive it. Rendering `<Suspender />` inside a boundary hides that boundary's
+ * content - React runs `componentWillUnmount` on everything in it without
+ * actually unmounting - and `reveal()` brings the same instances back with
+ * `componentDidMount`.
+ */
+const createSuspender = () => {
+  let resolveSuspender!: () => void;
+  let hasResolved = false;
+  const suspenderPromise = new Promise<void>((resolve) => {
+    resolveSuspender = () => {
+      hasResolved = true;
+      resolve();
+    };
+  });
+
+  return {
+    Suspender: () => {
+      if (!hasResolved) {
+        throw suspenderPromise;
+      }
+      return null;
+    },
+    reveal: async () => {
+      await act(async () => {
+        resolveSuspender();
+        await suspenderPromise;
+      });
+    },
+  };
+};
+
+/**
+ * The ids of `#teleport-destination`'s children, in document order. Document
+ * order is what core's `getPresentedOverlay` reads to decide which overlay
+ * Escape, hardware back and the focus trap act on, so a restore that changes
+ * it changes which overlay the user is talking to.
+ */
+const teleportedOrder = () =>
+  Array.from(document.getElementById('teleport-destination')?.children ?? []).map((el) => el.id);
+
+/**
+ * Render `children` inside a Suspense boundary alongside a sibling that can be
+ * made to suspend on demand. `hide()` suspends that sibling, which is what the
+ * reported bug hits: the overlay itself renders fine, something else in the
+ * boundary does not, and React hides the whole boundary - running
+ * `componentWillUnmount` on the overlay wrapper without unmounting it.
+ */
+const renderWithBoundary = (children: React.ReactNode) => {
+  const { Suspender, reveal } = createSuspender();
+
+  let suspend!: () => void;
+  const Boundary = () => {
+    const [isSuspended, setIsSuspended] = React.useState(false);
+    suspend = () => setIsSuspended(true);
+
+    return (
+      <React.Suspense fallback={<div>loading</div>}>
+        {children}
+        {isSuspended ? <Suspender /> : null}
+      </React.Suspense>
+    );
+  };
+
+  const result = render(<Boundary />);
+
+  return {
+    ...result,
+    hide: () =>
+      act(() => {
+        suspend();
+      }),
+    reveal,
+  };
 };
 
 afterEach(() => {
@@ -131,6 +214,30 @@ describe('createInlineOverlayComponent: unmount cleanup', () => {
     expect(document.querySelector('ion-popover')).toBeNull();
   });
 
+  it('removes an open, relocated nested overlay on unmount', () => {
+    const { unmount } = render(
+      <IonModal keepContentsMounted={true}>
+        <IonPopover />
+      </IonModal>
+    );
+
+    const popover = document.body.querySelector('ion-popover') as HTMLElement;
+
+    // Drive the nested popover open the way core does, then teleport it out of
+    // its `<template>`. This exercises the `node.remove()` branch followed by
+    // the `isOpen` teardown block on an already-detached node.
+    act(() => {
+      popover.dispatchEvent(new CustomEvent('willPresent'));
+    });
+    teleport(popover);
+
+    expect(() => unmount()).not.toThrow();
+
+    expect(document.querySelector('ion-popover')).toBeNull();
+  });
+});
+
+describe('createInlineOverlayComponent: hidden subtree restore', () => {
   it('restores a relocated nested overlay when a Suspense boundary hides and reveals it', async () => {
     /**
      * React runs `componentWillUnmount` when it *hides* a subtree as well as
@@ -141,81 +248,198 @@ describe('createInlineOverlayComponent: unmount cleanup', () => {
      * overlay that was mid-`present()` is gone for good, with no dismiss
      * lifecycle ever firing.
      */
-    let resolveSuspender!: () => void;
-    let hasResolved = false;
-    const suspenderPromise = new Promise<void>((resolve) => {
-      resolveSuspender = () => {
-        hasResolved = true;
-        resolve();
-      };
-    });
-
-    const Suspender = () => {
-      if (!hasResolved) {
-        throw suspenderPromise;
-      }
-      return null;
-    };
-
-    let suspend!: () => void;
-    const Boundary = () => {
-      const [isSuspended, setIsSuspended] = React.useState(false);
-      suspend = () => setIsSuspended(true);
-
-      return (
-        <React.Suspense fallback={<div>loading</div>}>
-          <IonModal keepContentsMounted={true}>
-            <IonPopover />
-          </IonModal>
-          {isSuspended ? <Suspender /> : null}
-        </React.Suspense>
-      );
-    };
-
-    render(<Boundary />);
+    const { hide, reveal } = renderWithBoundary(
+      <IonModal keepContentsMounted={true}>
+        <IonPopover />
+      </IonModal>
+    );
 
     const popover = document.body.querySelector('ion-popover') as HTMLElement;
 
     // CoreDelegate teleports the host out of its `<template>` as `present()`
     // starts, before the events that flip `isOpen` have fired.
-    teleport(popover);
-    const teleportDestination = popover.parentElement as HTMLElement;
+    const teleportDestination = teleport(popover);
 
     // A sibling suspends, so React hides the boundary's content: the overlay
     // wrapper gets componentWillUnmount without actually being unmounted.
-    act(() => {
-      suspend();
-    });
+    hide();
 
     // The boundary reveals its content again on the same instances.
-    await act(async () => {
-      resolveSuspender();
-      await suspenderPromise;
-    });
+    await reveal();
 
     expect(popover.isConnected).toBe(true);
     expect(popover.parentElement).toBe(teleportDestination);
   });
 
-  it('removes an open, relocated nested overlay on unmount', () => {
-    const { unmount } = render(
+  it('restores a hidden nested overlay to its original position in the container', async () => {
+    /**
+     * Restoring the host is not enough on its own: core's `getPresentedOverlay`
+     * takes the *last* match in document order, so Escape, hardware back and
+     * the focus trap all follow the overlay that sits last in `ion-app`.
+     * Anything appended there while the subtree was hidden - a Suspense
+     * fallback showing an `ion-loading` is the obvious one - has to stay after
+     * the overlay that was already presented, so the restore has to remember
+     * the position, not just the parent.
+     */
+    const { hide, reveal } = renderWithBoundary(
       <IonModal keepContentsMounted={true}>
-        <IonPopover />
+        <IonPopover id="nested-popover" />
       </IonModal>
     );
 
     const popover = document.body.querySelector('ion-popover') as HTMLElement;
+    const teleportDestination = teleport(popover);
 
-    // Drive the nested popover open the way core does, then teleport it out of
-    // its `<template>`. This exercises the `node.remove()` branch followed by
-    // the `isOpen` teardown block on an already-detached node.
+    hide();
+
+    // Something else presents into the same container while the subtree is
+    // hidden. The restored overlay must not jump behind it.
+    const laterOverlay = document.createElement('ion-loading');
+    laterOverlay.id = 'later-overlay';
+    teleportDestination.appendChild(laterOverlay);
+
+    await reveal();
+
+    expect(teleportedOrder()).toEqual(['nested-popover', 'later-overlay']);
+  });
+
+  it('keeps the stacking order of two nested overlays across a hide', async () => {
+    /**
+     * React tears a subtree down parent-first and builds it back up
+     * child-first, so two nested overlays restored by appending come back in
+     * the opposite order. In `ion-app` that hands Escape and the focus trap to
+     * the wrong overlay: the menu would dismiss while the submenu opened on
+     * top of it stays up.
+     */
+    const { hide, reveal } = renderWithBoundary(
+      <IonModal keepContentsMounted={true}>
+        <IonPopover id="menu-popover" keepContentsMounted={true}>
+          <IonPopover id="submenu-popover" />
+        </IonPopover>
+      </IonModal>
+    );
+
+    const menu = document.querySelector('#menu-popover') as HTMLElement;
+    const submenu = document.querySelector('#submenu-popover') as HTMLElement;
+
+    // Presented in order, so the submenu sits after the menu in the container.
+    teleport(menu);
+    teleport(submenu);
+    expect(teleportedOrder()).toEqual(['menu-popover', 'submenu-popover']);
+
+    hide();
+    await reveal();
+
+    expect(teleportedOrder()).toEqual(['menu-popover', 'submenu-popover']);
+  });
+
+  it('presents and dismisses a nested overlay after the reveal', async () => {
+    /**
+     * A reconnected node is not the same thing as a working overlay. The
+     * present/dismiss lifecycle has to reach the app again: the contents mount
+     * on `willPresent`, non-React `on*` props are re-bound, and `didDismiss`
+     * still unmounts the contents.
+     */
+    const onWillPresent = jest.fn();
+    const onDidPresent = jest.fn();
+    const onDidDismiss = jest.fn();
+
+    const { hide, reveal } = renderWithBoundary(
+      <IonModal keepContentsMounted={true}>
+        <IonPopover onWillPresent={onWillPresent} onIonPopoverDidPresent={onDidPresent} onDidDismiss={onDidDismiss}>
+          <span data-testid="popover-content">content</span>
+        </IonPopover>
+      </IonModal>
+    );
+
+    const popover = document.body.querySelector('ion-popover') as HTMLElement;
+    teleport(popover);
+
+    hide();
+    await reveal();
+
+    // The overlay presents: contents mount and both present handlers fire.
     act(() => {
       popover.dispatchEvent(new CustomEvent('willPresent'));
+      popover.dispatchEvent(new CustomEvent('ionPopoverDidPresent'));
     });
-    teleport(popover);
 
-    expect(() => unmount()).not.toThrow();
+    expect(onWillPresent).toHaveBeenCalledTimes(1);
+    expect(onDidPresent).toHaveBeenCalledTimes(1);
+    expect(document.querySelector('[data-testid="popover-content"]')).toBeTruthy();
 
-    expect(document.querySelector('ion-popover')).toBeNull();
+    // And it dismisses: the handler reaches the app and the contents unmount.
+    act(() => {
+      popover.dispatchEvent(new CustomEvent('didDismiss'));
+    });
+
+    expect(onDidDismiss).toHaveBeenCalledTimes(1);
+    expect(document.querySelector('[data-testid="popover-content"]')).toBeNull();
+  });
+
+  it('restores a nested overlay whose own contents suspended while presenting', async () => {
+    /**
+     * The reported flow. Core emits `ionMount` from the middle of `present()`,
+     * which is what first mounts the overlay's children, so a suspension in
+     * those children always lands while `present()` is in flight and the host
+     * has just been teleported out of its `<template>`.
+     */
+    const { Suspender, reveal } = createSuspender();
+    const onDidPresent = jest.fn();
+
+    render(
+      <React.Suspense fallback={<div>loading</div>}>
+        <IonModal keepContentsMounted={true}>
+          <IonPopover id="nested-popover" onIonPopoverDidPresent={onDidPresent}>
+            <Suspender />
+          </IonPopover>
+        </IonModal>
+      </React.Suspense>
+    );
+
+    const popover = document.querySelector('#nested-popover') as HTMLElement;
+    const teleportDestination = teleport(popover);
+
+    // `present()`: the host is already teleported when `ionMount` mounts the
+    // contents, and the contents suspend as they render.
+    act(() => {
+      popover.dispatchEvent(new CustomEvent('ionMount'));
+    });
+
+    await reveal();
+
+    expect(popover.isConnected).toBe(true);
+    expect(popover.parentElement).toBe(teleportDestination);
+
+    // `present()` runs to completion against the restored host.
+    act(() => {
+      popover.dispatchEvent(new CustomEvent('ionPopoverDidPresent'));
+    });
+
+    expect(onDidPresent).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not orphan a relocated nested overlay across a StrictMode mount/unmount cycle', () => {
+    /**
+     * The nested branch removes its host outright where the portaled branch
+     * only moves it, so the StrictMode dev cycle has to be covered on both.
+     * The discarded first mount must not leave an orphan behind, and the
+     * surviving instance must still have its host.
+     */
+    mockComponentOnReady = (el, cb) => {
+      teleport(el);
+      cb();
+    };
+
+    render(
+      <React.StrictMode>
+        <IonModal keepContentsMounted={true}>
+          <IonPopover id="nested-popover" />
+        </IonModal>
+      </React.StrictMode>
+    );
+
+    expect(document.querySelectorAll('ion-popover')).toHaveLength(1);
+    expect(document.querySelector('ion-popover')?.isConnected).toBe(true);
   });
 });
diff --git a/packages/react/src/components/createInlineOverlayComponent.tsx b/packages/react/src/components/createInlineOverlayComponent.tsx
index 4e0a88f63af..03ae1e7b535 100644
--- a/packages/react/src/components/createInlineOverlayComponent.tsx
+++ b/packages/react/src/components/createInlineOverlayComponent.tsx
@@ -59,10 +59,11 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
     isUnmounted = false;
     /**
      * A relocated nested host removed in `componentWillUnmount`, together with
-     * the parent it was removed from, so `componentDidMount` can put it back
-     * when React was only hiding this subtree rather than destroying it.
+     * the comment left in its place, so `componentDidMount` can put it back
+     * where it was when React was only hiding this subtree rather than
+     * destroying it.
      */
-    removedHost: { node: HTMLElement; parent: HTMLElement } | null = null;
+    removedHost: { node: HTMLElement; anchor: Comment } | null = null;
 
     constructor(props: InternalProps) {
       super(props);
@@ -95,17 +96,20 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
 
       /**
        * React also calls `componentWillUnmount` when it *hides* a subtree
-       * rather than destroying it - a Suspense boundary falling back, an
-       * Offscreen tree, or the StrictMode dev cycle - and calls
-       * `componentDidMount` again on the same instance when it reveals it.
-       * Put back a nested host removed there: the overlay can still be
-       * mid-`present()`, and React never re-inserts a node it did not remove
-       * itself, so the presenting overlay would be lost for good.
+       * rather than destroying it, and mounts the same instance again on the
+       * reveal. Put back a nested host removed there, at the position it was
+       * removed from: core reads document order to decide which overlay is on
+       * top. See createInlineOverlayComponent.spec.tsx for the full flow.
        */
       const { removedHost } = this;
       this.removedHost = null;
-      if (removedHost && !removedHost.node.isConnected && removedHost.parent.isConnected) {
-        removedHost.parent.appendChild(removedHost.node);
+      if (removedHost) {
+        const { node, anchor } = removedHost;
+        if (!node.isConnected && anchor.isConnected) {
+          anchor.replaceWith(node);
+        } else {
+          anchor.remove();
+        }
       }
 
       this.componentDidUpdate(this.props);
@@ -170,13 +174,17 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
            * Nested overlays render inline inside a `<template>`. If the host
            * has been moved out of that template, React's unmount won't reach
            * it, so remove it directly. A host still in its template is left
-           * for React to remove. The removal is recorded so `componentDidMount`
-           * can undo it if this turns out to be a hide rather than a real
-           * unmount.
+           * for React to remove.
+           *
+           * A comment takes the host's place, the way CoreDelegate marks a
+           * teleport, so `componentDidMount` can put the host back in the same
+           * spot if this turns out to be a hide rather than a real unmount.
            */
           const parent = node.parentElement;
           if (parent && !(parent instanceof HTMLTemplateElement)) {
-            this.removedHost = { node, parent };
+            const anchor = document.createComment(RESTORE_ANCHOR);
+            parent.insertBefore(anchor, node);
+            this.removedHost = { node, anchor };
             node.remove();
           }
         } else if (this.portalTarget && node.parentNode !== this.portalTarget) {
@@ -343,3 +351,9 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
 };
 
 const DELEGATE_HOST = 'ion-delegate-host';
+
+/**
+ * Marks where a nested overlay host was removed from, so it can be restored to
+ * the same position if React was only hiding the subtree.
+ */
+const RESTORE_ANCHOR = 'ionic hidden overlay';
diff --git a/packages/react/test/base/src/pages/overlay-components/ModalSuspense.tsx b/packages/react/test/base/src/pages/overlay-components/ModalSuspense.tsx
new file mode 100644
index 00000000000..6b9886202bc
--- /dev/null
+++ b/packages/react/test/base/src/pages/overlay-components/ModalSuspense.tsx
@@ -0,0 +1,107 @@
+import React, { Suspense, lazy, useState } from 'react';
+import {
+  IonButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonModal,
+  IonPage,
+  IonTitle,
+  IonToolbar,
+} from '@ionic/react';
+
+const NestedModalContents: React.FC = () => (
+  <IonContent className="ion-padding">
+    <p id="nested-modal-contents">Nested modal contents</p>
+  </IonContent>
+);
+
+/**
+ * The nested modal's contents, resolved after a delay so that their first
+ * render suspends.
+ *
+ * Core emits `ionMount` from the middle of `present()`, and that is what first
+ * mounts an inline overlay's children, so a suspension in those children always
+ * lands while the nested modal is presenting and its host has just been
+ * teleported out of its `<template>` into `ion-app`.
+ */
+const LazyNestedModalContents = lazy(
+  () =>
+    new Promise<{ default: React.ComponentType }>((resolve) => {
+      setTimeout(() => resolve({ default: NestedModalContents }), 500);
+    })
+);
+
+const ModalSuspense: React.FC = () => {
+  const [isOuterOpen, setIsOuterOpen] = useState(false);
+  const [isNestedOpen, setIsNestedOpen] = useState(false);
+  const [nestedDismissCount, setNestedDismissCount] = useState(0);
+
+  return (
+    <IonPage>
+      <IonContent className="ion-padding">
+        <IonButton id="open-suspense-outer-modal" onClick={() => setIsOuterOpen(true)}>
+          Open Outer Modal
+        </IonButton>
+        <div>
+          Nested dismiss count: <span id="nested-modal-dismiss-count">{nestedDismissCount}</span>
+        </div>
+
+        <IonModal
+          id="suspense-outer-modal"
+          isOpen={isOuterOpen}
+          onDidDismiss={() => setIsOuterOpen(false)}
+        >
+          <IonHeader>
+            <IonToolbar>
+              <IonTitle>Outer Modal</IonTitle>
+              <IonButtons slot="end">
+                <IonButton id="close-suspense-outer-modal" onClick={() => setIsOuterOpen(false)}>
+                  Close
+                </IonButton>
+              </IonButtons>
+            </IonToolbar>
+          </IonHeader>
+          <IonContent className="ion-padding">
+            <IonButton id="open-suspense-nested-modal" onClick={() => setIsNestedOpen(true)}>
+              Open Nested Modal
+            </IonButton>
+
+            {/*
+             * The boundary encloses the nested overlay itself, so hiding it
+             * runs `componentWillUnmount` on the nested modal's wrapper while
+             * the overlay is presenting.
+             */}
+            <Suspense fallback={<div id="suspense-fallback">Loading nested modal contents</div>}>
+              <IonModal
+                id="suspense-nested-modal"
+                isOpen={isNestedOpen}
+                onDidDismiss={() => {
+                  setIsNestedOpen(false);
+                  setNestedDismissCount((count) => count + 1);
+                }}
+              >
+                <IonHeader>
+                  <IonToolbar>
+                    <IonTitle>Nested Modal</IonTitle>
+                    <IonButtons slot="end">
+                      <IonButton
+                        id="close-suspense-nested-modal"
+                        onClick={() => setIsNestedOpen(false)}
+                      >
+                        Close
+                      </IonButton>
+                    </IonButtons>
+                  </IonToolbar>
+                </IonHeader>
+                <LazyNestedModalContents />
+              </IonModal>
+            </Suspense>
+          </IonContent>
+        </IonModal>
+      </IonContent>
+    </IonPage>
+  );
+};
+
+export default ModalSuspense;
diff --git a/packages/react/test/base/src/pages/overlay-components/OverlayComponents.tsx b/packages/react/test/base/src/pages/overlay-components/OverlayComponents.tsx
index cb7ceb4ac4b..cd978d2e543 100644
--- a/packages/react/test/base/src/pages/overlay-components/OverlayComponents.tsx
+++ b/packages/react/test/base/src/pages/overlay-components/OverlayComponents.tsx
@@ -15,6 +15,7 @@ import LoadingComponent from './LoadingComponent';
 import ModalComponent from './ModalComponent';
 import ModalFocusTrap from './ModalFocusTrap';
 import ModalSheetChildRoute from './ModalSheetChildRoute';
+import ModalSuspense from './ModalSuspense';
 import ModalTeleport from './ModalTeleport';
 import PopoverComponent from './PopoverComponent';
 import ToastComponent from './ToastComponent';
@@ -32,6 +33,7 @@ const OverlayHooks: React.FC<OverlayHooksProps> = () => {
         <Route path="modal-basic" element={<ModalComponent />} />
         <Route path="modal-focus-trap" element={<ModalFocusTrap />} />
         <Route path="modal-sheet-child-route/*" element={<ModalSheetChildRoute />} />
+        <Route path="modal-suspense" element={<ModalSuspense />} />
         <Route path="modal-teleport" element={<ModalTeleport />} />
         <Route path="popover" element={<PopoverComponent />} />
         <Route path="toast" element={<ToastComponent />} />
@@ -57,6 +59,10 @@ const OverlayHooks: React.FC<OverlayHooksProps> = () => {
           <IonIcon icon={star} />
           <IonLabel>Modal Focus</IonLabel>
         </IonTabButton>
+        <IonTabButton tab="modalSuspense" href="/overlay-components/modal-suspense">
+          <IonIcon icon={star} />
+          <IonLabel>Modal Suspense</IonLabel>
+        </IonTabButton>
         <IonTabButton tab="modalTeleport" href="/overlay-components/modal-teleport">
           <IonIcon icon={star} />
           <IonLabel>Modal Teleport</IonLabel>
diff --git a/packages/react/test/base/tests/e2e/specs/overlay-components/IonModalSuspense.cy.ts b/packages/react/test/base/tests/e2e/specs/overlay-components/IonModalSuspense.cy.ts
new file mode 100644
index 00000000000..79a6790961c
--- /dev/null
+++ b/packages/react/test/base/tests/e2e/specs/overlay-components/IonModalSuspense.cy.ts
@@ -0,0 +1,51 @@
+describe('IonModal: nested overlay hidden by a Suspense boundary', () => {
+  beforeEach(() => {
+    cy.visit('/overlay-components/modal-suspense');
+
+    cy.get('#open-suspense-outer-modal').click();
+    cy.get('#suspense-outer-modal').should('be.visible');
+  });
+
+  it('should present the nested modal after its contents suspend', () => {
+    cy.get('#open-suspense-nested-modal').click();
+
+    // The nested modal's contents suspend as `present()` mounts them, which
+    // hides the boundary and runs `componentWillUnmount` on the wrapper.
+    cy.get('#suspense-fallback').should('exist');
+
+    // The reveal has to bring the presenting overlay back.
+    cy.get('#suspense-nested-modal').should('be.visible');
+    cy.get('#nested-modal-contents').should('be.visible');
+  });
+
+  it('should dismiss the nested modal after the reveal', () => {
+    cy.get('#open-suspense-nested-modal').click();
+    cy.get('#nested-modal-contents').should('be.visible');
+
+    cy.get('#close-suspense-nested-modal').click();
+
+    // The dismiss lifecycle still reaches the app.
+    cy.get('#suspense-nested-modal').should('not.be.visible');
+    cy.get('#nested-modal-dismiss-count').should('have.text', '1');
+    cy.get('#suspense-outer-modal').should('be.visible');
+  });
+
+  it('should keep the nested modal on top after the reveal', () => {
+    cy.get('#open-suspense-nested-modal').click();
+    cy.get('#nested-modal-contents').should('be.visible');
+
+    /**
+     * `getPresentedOverlay` takes the last match in document order, so the
+     * overlay restored after the reveal has to keep its place in `ion-app`.
+     * If it moves, Escape, hardware back and the focus trap start acting on
+     * the outer modal instead.
+     */
+    cy.get('ion-app ion-modal').last().should('have.id', 'suspense-nested-modal');
+
+    cy.get('body').type('{esc}');
+
+    cy.get('#suspense-nested-modal').should('not.be.visible');
+    cy.get('#nested-modal-dismiss-count').should('have.text', '1');
+    cy.get('#suspense-outer-modal').should('be.visible');
+  });
+});

From b8878b3b1dc6279b5c06972ff691aa8d64e9dce8 Mon Sep 17 00:00:00 2001
From: Patrick Kenny <github@ptmkenny.com>
Date: Fri, 21 Aug 2026 02:56:38 +0000
Subject: [PATCH 3/3] trim the duplicated hide/reveal explanation

---
 .../createInlineOverlayComponent.tsx          | 26 ++++++-------------
 1 file changed, 8 insertions(+), 18 deletions(-)

diff --git a/packages/react/src/components/createInlineOverlayComponent.tsx b/packages/react/src/components/createInlineOverlayComponent.tsx
index 03ae1e7b535..016fcab2b3a 100644
--- a/packages/react/src/components/createInlineOverlayComponent.tsx
+++ b/packages/react/src/components/createInlineOverlayComponent.tsx
@@ -57,12 +57,8 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
     stableMergedRefs: React.RefCallback<HTMLElement>;
     portalTarget: HTMLElement | null;
     isUnmounted = false;
-    /**
-     * A relocated nested host removed in `componentWillUnmount`, together with
-     * the comment left in its place, so `componentDidMount` can put it back
-     * where it was when React was only hiding this subtree rather than
-     * destroying it.
-     */
+    // A nested host removed in `componentWillUnmount`, with the comment left in
+    // its place, so `componentDidMount` can put it back where it was.
     removedHost: { node: HTMLElement; anchor: Comment } | null = null;
 
     constructor(props: InternalProps) {
@@ -94,13 +90,10 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
       // componentWillUnmount.
       this.isUnmounted = false;
 
-      /**
-       * React also calls `componentWillUnmount` when it *hides* a subtree
-       * rather than destroying it, and mounts the same instance again on the
-       * reveal. Put back a nested host removed there, at the position it was
-       * removed from: core reads document order to decide which overlay is on
-       * top. See createInlineOverlayComponent.spec.tsx for the full flow.
-       */
+      // React runs `componentWillUnmount` when it only hides a subtree and
+      // mounts the same instance again on the reveal, so a host removed there
+      // goes back at the position it came from - document order decides which
+      // overlay is on top. The spec covers the flow.
       const { removedHost } = this;
       this.removedHost = null;
       if (removedHost) {
@@ -174,11 +167,8 @@ export const createInlineOverlayComponent = <PropType, ElementType>(
            * Nested overlays render inline inside a `<template>`. If the host
            * has been moved out of that template, React's unmount won't reach
            * it, so remove it directly. A host still in its template is left
-           * for React to remove.
-           *
-           * A comment takes the host's place, the way CoreDelegate marks a
-           * teleport, so `componentDidMount` can put the host back in the same
-           * spot if this turns out to be a hide rather than a real unmount.
+           * for React to remove. A comment marks the spot, the way CoreDelegate
+           * marks a teleport, so a reveal can put the host back where it was.
            */
           const parent = node.parentElement;
           if (parent && !(parent instanceof HTMLTemplateElement)) {