fix(overlays): restore presented state after a DOM move (#31400)

Issue number: resolves #31389

---------

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

Currently, `componentWillUnmount` in `createInlineOverlayComponent`
removes a nested inline overlay host that `CoreDelegate` has teleported
out of its `<template>`. React also runs that hook when it only *hides*
a subtree, so a Suspense fallback, an Offscreen tree, or the StrictMode
cycle deletes an overlay that is still presenting. React did not remove
the host, so React never puts it back. Core emits `ionMount` and then
goes quiet: no `willPresent`, no `didPresent`, and no dismiss lifecycle,
while the React tree still believes the overlay is open. The user sees
nothing at all.

## What is the new behavior?

The wrapper now tells a React hide from a real destroy instead of
treating both as an unmount. The marker `<template>` is the
discriminator, since it stays at the JSX position and leaves the
document only on a real unmount, so the teardown defers a microtask and
runs only if the marker really left. A hide leaves the host exactly
where it is, `present()` and `didDismiss` keep working while the subtree
is hidden, and a destroy that hits while it is already hidden still
cleans up even though React skips the second `componentWillUnmount`
there. This addresses #31223's requirements by making a relocated
portaled host move back into `portalTarget` synchronously, and the
StrictMode cycle still leaves exactly one copy in the DOM.

Separately, the five overlays that release the app root on disconnect
(`modal`, `popover`, `alert`, `action-sheet`, `loading`) now restore it
on reconnect, along with the modal's safe-area overrides and
parent-removal observer, and the button gesture on `alert` and
`action-sheet`. A presented overlay that gets detached and re-inserted
across a task previously came back with the root lock and safe-area
gone.

## Does this introduce a breaking change?

- [ ] Yes
- [X] No

## Other information

This supersedes #31390, which fixes the same issue by recording the
removed host and re-appending it on remount. That works for the reported
case, but it keeps the removal, and the removal costs more than the DOM
node: the disconnect releases the root lock, clears the safe-area
overrides and the sheet's `--ion-modal-offset-top`, destroys the button
gesture, and drops the parent-removal observer. Putting the node back
restores none of that, so the smaller fix needs the core half of this PR
anyway. Not removing it in the first place avoids all of that, and also
covers the portaled overlays, the destroy-while-hidden case, and a
dismiss landing during the hidden window, which #31390 doesn't reach.
Thanks to @ptmkenny for the report, the analysis, and the original
patch, which is where the diagnosis came from.

Note that the core half is defence-in-depth rather than a requirement
for #31389. Once the React wrapper stops removing the host, core no
longer sees a detach and re-attach in the reported flow. It does fix a
real pre-existing bug though, since a presented modal moved by anything
else lost its safe-area, so it's worth keeping.

Preview:
- [Inline modal
(iOS)](https://ionic-framework-git-fix-react-inline-overlay-hide-vs-unmount-ionic1.vercel.app/src/components/modal/test/inline?ionic:mode=ios)
- [Modal safe-area
(iOS)](https://ionic-framework-git-fix-react-inline-overlay-hide-vs-unmount-ionic1.vercel.app/src/components/modal/test/safe-area?ionic:mode=ios)

## Current dev build:
```
9.0.1-dev.11787589191.1e183b55
```

---------

Co-authored-by: ptmkenny <github@ptmkenny.com>

Author: ShaneK

core/src/components/action-sheet/action-sheet.tsx

@@ -14,6 +14,7 @@ import {
   isCancel,
   prepareOverlay,
   present,
+  restoreRootFocusTrapAccessibility,
   safeCall,
   setOverlayId,
 } from '@utils/overlays';
@@ -455,6 +456,15 @@ export class ActionSheet implements ComponentInterface, OverlayInterface {
   connectedCallback() {
     prepareOverlay(this.el);
     this.triggerChanged();
+
+    // `componentDidLoad` only fires once per instance, so a reconnect has to
+    // rebuild the gesture its disconnect destroyed.
+    this.setupButtonActiveGesture();
+
+    // Re-apply the root lock if moved without dismiss() being called
+    if (this.presented) {
+      restoreRootFocusTrapAccessibility(this.el);
+    }
   }
 
   disconnectedCallback() {
@@ -478,26 +488,36 @@ export class ActionSheet implements ComponentInterface, OverlayInterface {
     this.buttonsChanged();
   }
 
-  componentDidLoad() {
-    /**
-     * Only create gesture if:
-     * 1. A gesture does not already exist
-     * 2. App is running in iOS mode
-     * 3. A wrapper ref exists
-     * 4. A group ref exists
-     */
+  /**
+   * Only create gesture if:
+   * 1. A gesture does not already exist
+   * 2. App is running in iOS mode
+   * 3. A wrapper ref exists
+   * 4. A group ref exists
+   * 5. The host is still connected, since a reconnect can schedule this and
+   *    disconnect again before the task runs
+   */
+  private setupButtonActiveGesture() {
     const { groupEl, wrapperEl } = this;
-    if (!this.gesture && getIonMode(this) === 'ios' && wrapperEl && groupEl) {
-      readTask(() => {
-        const isScrollable = groupEl.scrollHeight > groupEl.clientHeight;
-        if (!isScrollable) {
-          this.gesture = createButtonActiveGesture(wrapperEl, (refEl: HTMLElement) =>
-            refEl.classList.contains('action-sheet-button')
-          );
-          this.gesture.enable(true);
-        }
-      });
+    if (getIonMode(this) !== 'ios' || !wrapperEl || !groupEl) {
+      return;
     }
+    readTask(() => {
+      // Bail if a call queued ahead of this one already built the gesture
+      // (a second would orphan the first with its listeners still bound), if
+      // the host disconnected while this task waited, or if the group scrolls.
+      if (this.gesture || !this.el.isConnected || groupEl.scrollHeight > groupEl.clientHeight) {
+        return;
+      }
+      this.gesture = createButtonActiveGesture(wrapperEl, (refEl: HTMLElement) =>
+        refEl.classList.contains('action-sheet-button')
+      );
+      this.gesture.enable(true);
+    });
+  }
+
+  componentDidLoad() {
+    this.setupButtonActiveGesture();
 
     /**
      * If action sheet was rendered with isOpen="true"

core/src/components/action-sheet/test/basic/action-sheet.e2e.ts

@@ -1,5 +1,5 @@
 import { expect } from '@playwright/test';
-import { configs, test } from '@utils/test/playwright';
+import { configs, detachAndReattach, test } from '@utils/test/playwright';
 
 import { ActionSheetFixture } from './fixture';
 
@@ -166,3 +166,56 @@ configs({ directions: ['ltr'] }).forEach(({ title, screenshot, config }) => {
     });
   });
 });
+
+/**
+ * The button gesture only exists in iOS mode, so these run there.
+ */
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ config, title }) => {
+  test.describe(title('action sheet: moved while presented'), () => {
+    test.beforeEach(async ({ page }) => {
+      await page.goto('/src/components/action-sheet/test/basic', config);
+    });
+
+    test('should keep the app root locked', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31389',
+      });
+
+      const ionActionSheetDidPresent = await page.spyOnEvent('ionActionSheetDidPresent');
+
+      await page.click('#basic');
+      await ionActionSheetDidPresent.next();
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+
+      await detachAndReattach(page.locator('ion-action-sheet'));
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+    });
+
+    test('should keep activating buttons on press', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31389',
+      });
+
+      const ionActionSheetDidPresent = await page.spyOnEvent('ionActionSheetDidPresent');
+
+      await page.click('#basic');
+      await ionActionSheetDidPresent.next();
+
+      await detachAndReattach(page.locator('ion-action-sheet'));
+
+      const button = page.locator('ion-action-sheet .action-sheet-button').first();
+      const box = (await button.boundingBox())!;
+
+      await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+      await page.mouse.down();
+
+      await expect(button).toHaveClass(/ion-activated/);
+
+      await page.mouse.up();
+    });
+  });
+});

core/src/components/alert/alert.tsx

@@ -17,6 +17,7 @@ import {
   isCancel,
   prepareOverlay,
   present,
+  restoreRootFocusTrapAccessibility,
   safeCall,
   setOverlayId,
 } from '@utils/overlays';
@@ -363,10 +364,16 @@ export class Alert implements ComponentInterface, OverlayInterface {
     this.triggerChanged();
     /**
      * If the alert was previously connected and is being reattached, the
-     * ResizeObserver was disconnected. componentDidLoad only fires once per
-     * instance, so re-establish the observer here on reconnect.
+     * `ResizeObserver` and the button gesture were torn down. `componentDidLoad`
+     * only fires once per instance, so re-establish both here on reconnect.
      */
     this.setupButtonGroupResizeObserver();
+    this.setupButtonActiveGesture();
+
+    // Re-apply the root lock if moved without dismiss() being called
+    if (this.presented) {
+      restoreRootFocusTrapAccessibility(this.el);
+    }
   }
 
   componentWillLoad() {
@@ -394,20 +401,23 @@ export class Alert implements ComponentInterface, OverlayInterface {
     this.buttonGroupResizeObserver = undefined;
   }
 
-  componentDidLoad() {
-    /**
-     * Only create gesture if:
-     * 1. A gesture does not already exist
-     * 2. App is running in iOS mode
-     * 3. A wrapper ref exists
-     */
+  /**
+   * Only create gesture if:
+   * 1. A gesture does not already exist
+   * 2. App is running in iOS mode
+   * 3. A wrapper ref exists
+   */
+  private setupButtonActiveGesture() {
     if (!this.gesture && getIonMode(this) === 'ios' && this.wrapperEl) {
       this.gesture = createButtonActiveGesture(this.wrapperEl, (refEl: HTMLElement) =>
         refEl.classList.contains('alert-button')
       );
       this.gesture.enable(true);
     }
+  }
 
+  componentDidLoad() {
+    this.setupButtonActiveGesture();
     this.setupButtonGroupResizeObserver();
 
     /**

core/src/components/alert/test/basic/alert.e2e.ts

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import type { Locator } from '@playwright/test';
 import type { E2EPage } from '@utils/test/playwright';
-import { configs, test } from '@utils/test/playwright';
+import { configs, detachAndReattach, test } from '@utils/test/playwright';
 
 configs({ directions: ['ltr'] }).forEach(({ config, screenshot, title }) => {
   test.describe(title('alert: basic'), () => {
@@ -203,3 +203,56 @@ class AlertFixture {
     await expect(this.alert).toHaveScreenshot(screenshotFn(`alert-${modifier}`));
   }
 }
+
+/**
+ * The button gesture only exists in iOS mode, so these run there.
+ */
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ config, title }) => {
+  test.describe(title('alert: moved while presented'), () => {
+    test.beforeEach(async ({ page }) => {
+      await page.goto('/src/components/alert/test/basic', config);
+    });
+
+    test('should keep the app root locked', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31389',
+      });
+
+      const ionAlertDidPresent = await page.spyOnEvent('ionAlertDidPresent');
+
+      await page.click('#basic');
+      await ionAlertDidPresent.next();
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+
+      await detachAndReattach(page.locator('ion-alert'));
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+    });
+
+    test('should keep activating buttons on press', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31389',
+      });
+
+      const ionAlertDidPresent = await page.spyOnEvent('ionAlertDidPresent');
+
+      await page.click('#multipleButtons');
+      await ionAlertDidPresent.next();
+
+      await detachAndReattach(page.locator('ion-alert'));
+
+      const button = page.locator('ion-alert .alert-button').first();
+      const box = (await button.boundingBox())!;
+
+      await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+      await page.mouse.down();
+
+      await expect(button).toHaveClass(/ion-activated/);
+
+      await page.mouse.up();
+    });
+  });
+});

core/src/components/loading/loading.tsx

@@ -12,6 +12,7 @@ import {
   eventMethod,
   prepareOverlay,
   present,
+  restoreRootFocusTrapAccessibility,
   setOverlayId,
 } from '@utils/overlays';
 import { sanitizeDOMString } from '@utils/sanitization';
@@ -208,6 +209,11 @@ export class Loading implements ComponentInterface, OverlayInterface {
   connectedCallback() {
     prepareOverlay(this.el);
     this.triggerChanged();
+
+    // Re-apply the root lock if moved without dismiss() being called
+    if (this.presented) {
+      restoreRootFocusTrapAccessibility(this.el);
+    }
   }
 
   componentWillLoad() {

core/src/components/loading/test/basic/loading.e2e.ts

@@ -1,6 +1,6 @@
 import { expect } from '@playwright/test';
 import type { E2EPage, ScreenshotFn } from '@utils/test/playwright';
-import { configs, test } from '@utils/test/playwright';
+import { configs, detachAndReattach, test } from '@utils/test/playwright';
 
 const runVisualTest = async (page: E2EPage, selector: string, screenshot: ScreenshotFn, screenshotModifier: string) => {
   const ionLoadingDidPresent = await page.spyOnEvent('ionLoadingDidPresent');
@@ -100,3 +100,30 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, screenshot, c
     });
   });
 });
+
+/**
+ * This behavior does not vary across modes/directions.
+ */
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ config, title }) => {
+  test.describe(title('loading: moved while presented'), () => {
+    test('should keep the app root locked', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/31389',
+      });
+
+      await page.goto('/src/components/loading/test/basic', config);
+      const ionLoadingDidPresent = await page.spyOnEvent('ionLoadingDidPresent');
+
+      // This one carries no duration, so it can't auto-dismiss mid-move.
+      await page.click('#backdrop-loading');
+      await ionLoadingDidPresent.next();
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+
+      await detachAndReattach(page.locator('ion-loading'));
+
+      await expect(page.locator('body')).toHaveClass(/backdrop-no-scroll/);
+    });
+  });
+});