fix(modal, popover): respect safe area insets on popovers and modals (#30949)

Issue number: resolves #28411

---------

<!-- 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?
When a modal is displayed on tablet-sized screens (>= 768px × >= 600px),
the `--ion-safe-area-*` CSS variables are explicitly set to 0px. This
was intended for inset modals that don't touch screen edges, but it
breaks safe area handling on newer iPads with Face ID/home indicators,
causing content to overlap with system UI elements.

## What is the new behavior?
Modals now dynamically handle safe-area insets based on their type and
position. This has to be done because modals that don't touch the edges
cannot have a safe area applied (because it will add unnecessary
padding), but modals that do touch the edges need to apply safe area
correctly or the edges will be obstructed by whatever is in the safe
area.

## Does this introduce a breaking change?

- [ ] Yes
- [X] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

[Modals test
page](https://ionic-framework-git-fw-6830-2-ionic1.vercel.app/src/components/modal/test/safe-area/index.html)
[Popovers test
page](https://ionic-framework-git-fw-6830-2-ionic1.vercel.app/src/components/popover/test/safe-area/index.html)

Current dev build:
```
8.7.18-dev.11770674094.18396f54
```

---------

Co-authored-by: ionitron <hi@ionicframework.com>

Author: ShaneK

core/src/components/datetime/test/custom/datetime.e2e.ts-snapshots/datetime-custom-time-button-active-ios-ltr-Mobile-Safari-linux.png

@@ -94,10 +94,6 @@ ion-backdrop {
   :host {
     --width: #{$modal-inset-width};
     --height: #{$modal-inset-height-small};
-    --ion-safe-area-top: 0px;
-    --ion-safe-area-bottom: 0px;
-    --ion-safe-area-right: 0px;
-    --ion-safe-area-left: 0px;
   }
 }
 
@@ -156,9 +152,14 @@ ion-backdrop {
 /**
  * Ensure that the sheet modal does not
  * completely cover the content.
+ *
+ * --ion-modal-offset-top is an internal property set by modal.tsx
+ * with the resolved root safe-area-top pixel value. This decouples
+ * the height calculation from --ion-safe-area-top (which is zeroed
+ * for sheet modals to prevent header double-padding).
  */
 :host(.modal-sheet) {
-  --height: calc(100% - (var(--ion-safe-area-top) + 10px));
+  --height: calc(100% - (var(--ion-modal-offset-top, 0px) + 10px));
 }
 
 :host(.modal-sheet) .modal-wrapper,

core/src/components/datetime/test/custom/datetime.e2e.ts-snapshots/datetime-custom-time-picker-ios-ltr-Mobile-Safari-linux.png

@@ -44,6 +44,14 @@ import type { MoveSheetToBreakpointOptions } from './gestures/sheet';
 import { createSheetGesture } from './gestures/sheet';
 import { createSwipeToCloseGesture, SwipeToCloseDefaults } from './gestures/swipe-to-close';
 import type { ModalBreakpointChangeEventDetail, ModalHandleBehavior } from './modal-interface';
+import {
+  getInitialSafeAreaConfig,
+  getPositionBasedSafeAreaConfig,
+  applySafeAreaOverrides,
+  clearSafeAreaOverrides,
+  getRootSafeAreaTop,
+  type ModalSafeAreaContext,
+} from './safe-area-utils';
 import { setCardStatusBarDark, setCardStatusBarDefault } from './utils';
 
 // TODO(FW-2832): types
@@ -276,14 +284,35 @@ export class Modal implements ComponentInterface, OverlayInterface {
 
   @Listen('resize', { target: 'window' })
   onWindowResize() {
-    // Only handle resize for iOS card modals when no custom animations are provided
-    if (getIonMode(this) !== 'ios' || !this.presentingElement || this.enterAnimation || this.leaveAnimation) {
-      return;
-    }
+    if (!this.presented) return;
 
     clearTimeout(this.resizeTimeout);
     this.resizeTimeout = setTimeout(() => {
-      this.handleViewTransition();
+      const context = this.getSafeAreaContext();
+
+      // iOS card modals: handle portrait/landscape view transitions
+      if (context.isCardModal && !this.enterAnimation && !this.leaveAnimation) {
+        this.handleViewTransition();
+      }
+
+      // Sheet modals: re-compute the internal offset property since safe-area
+      // values may change on device rotation (e.g., portrait notch vs landscape).
+      if (context.isSheetModal) {
+        this.updateSheetOffsetTop();
+      }
+
+      // Regular (non-sheet, non-card) modals: update safe-area overrides
+      // since the viewport may have crossed the centered-dialog breakpoint.
+      if (!context.isSheetModal && !context.isCardModal) {
+        this.updateSafeAreaOverrides();
+
+        // Re-evaluate fullscreen safe-area padding: clear first, then re-apply
+        if (this.wrapperEl) {
+          this.wrapperEl.style.removeProperty('height');
+          this.wrapperEl.style.removeProperty('padding-bottom');
+        }
+        this.applyFullscreenSafeArea();
+      }
     }, 50); // Debounce to avoid excessive calls during active resizing
   }
 
@@ -406,6 +435,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
     this.triggerController.removeClickListener();
     this.cleanupViewTransitionListener();
     this.cleanupParentRemovalObserver();
+    // Also called in dismiss() — intentional dual cleanup covers both
+    // dismiss-then-remove and direct DOM removal without dismiss.
+    this.cleanupSafeAreaOverrides();
   }
 
   componentWillLoad() {
@@ -594,6 +626,13 @@ export class Modal implements ComponentInterface, OverlayInterface {
 
     writeTask(() => this.el.classList.add('show-modal'));
 
+    // Recalculate isSheetModal before safe-area setup because framework
+    // bindings (e.g., Angular) may not have been applied when componentWillLoad ran.
+    this.isSheetModal = this.breakpoints !== undefined && this.initialBreakpoint !== undefined;
+
+    // Set initial safe-area overrides before animation
+    this.setInitialSafeAreaOverrides();
+
     const hasCardModal = presentingElement !== undefined;
 
     /**
@@ -614,6 +653,12 @@ export class Modal implements ComponentInterface, OverlayInterface {
       expandToScroll: this.expandToScroll,
     });
 
+    // Update safe-area based on actual position after animation
+    this.updateSafeAreaOverrides();
+
+    // Apply fullscreen safe-area padding if needed
+    this.applyFullscreenSafeArea();
+
     /* tslint:disable-next-line */
     if (typeof window !== 'undefined') {
       /**
@@ -646,14 +691,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
       window.addEventListener(KEYBOARD_DID_OPEN, this.keyboardOpenCallback);
     }
 
-    /**
-     * Recalculate isSheetModal because framework bindings (e.g., Angular)
-     * may not have been applied when componentWillLoad ran.
-     */
-    const isSheetModal = this.breakpoints !== undefined && this.initialBreakpoint !== undefined;
-    this.isSheetModal = isSheetModal;
-
-    if (isSheetModal) {
+    if (this.isSheetModal) {
       this.initSheetGesture();
     } else if (hasCardModal) {
       this.initSwipeToClose();
@@ -885,6 +923,10 @@ export class Modal implements ComponentInterface, OverlayInterface {
       return false;
     }
 
+    // Cancel any pending resize timeout to prevent stale updates during dismiss
+    clearTimeout(this.resizeTimeout);
+    this.resizeTimeout = undefined;
+
     /**
      * Because the canDismiss check below is async,
      * we need to claim a lock before the check happens,
@@ -956,6 +998,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
       }
       this.cleanupViewTransitionListener();
       this.cleanupParentRemovalObserver();
+      this.cleanupSafeAreaOverrides();
 
       this.cleanupChildRoutePassthrough();
     }
@@ -1166,6 +1209,10 @@ export class Modal implements ComponentInterface, OverlayInterface {
     transitionAnimation.play().then(() => {
       this.viewTransitionAnimation = undefined;
 
+      // Wait for a layout pass after the transition so getBoundingClientRect()
+      // in getPositionBasedSafeAreaConfig() reflects the new dimensions.
+      raf(() => this.updateSafeAreaOverrides());
+
       // After orientation transition, recreate the swipe-to-close gesture
       // with updated animation that reflects the new presenting element state
       this.reinitSwipeToClose();
@@ -1335,6 +1382,130 @@ export class Modal implements ComponentInterface, OverlayInterface {
     this.parentRemovalObserver = undefined;
   }
 
+  /**
+   * Creates the context object for safe-area utilities.
+   */
+  private getSafeAreaContext(): ModalSafeAreaContext {
+    return {
+      isSheetModal: this.isSheetModal,
+      isCardModal: this.presentingElement !== undefined && getIonMode(this) === 'ios',
+      presentingElement: this.presentingElement,
+      breakpoints: this.breakpoints,
+      currentBreakpoint: this.currentBreakpoint,
+    };
+  }
+
+  /**
+   * Sets initial safe-area overrides before modal animation.
+   * Called in present() before animation starts.
+   *
+   * For sheet modals, the SCSS --height formula uses --ion-modal-offset-top
+   * (an internal property) instead of --ion-safe-area-top. We resolve the
+   * root safe-area-top to pixels and set --ion-modal-offset-top, decoupling
+   * the height calculation from --ion-safe-area-top (which is zeroed for
+   * sheets to prevent header content from getting double-offset padding).
+   */
+  private setInitialSafeAreaOverrides(): void {
+    const context = this.getSafeAreaContext();
+    const safeAreaConfig = getInitialSafeAreaConfig(context);
+    applySafeAreaOverrides(this.el, safeAreaConfig);
+
+    // Set the internal offset property with the resolved root safe-area-top value
+    if (context.isSheetModal) {
+      this.updateSheetOffsetTop();
+    }
+  }
+
+  /**
+   * Resolves the current root --ion-safe-area-top value and sets the
+   * internal --ion-modal-offset-top property on the host element.
+   * Called on present and on resize (e.g., device rotation changes safe-area).
+   */
+  private updateSheetOffsetTop(): void {
+    const safeAreaTop = getRootSafeAreaTop();
+    this.el.style.setProperty('--ion-modal-offset-top', `${safeAreaTop}px`);
+  }
+
+  /**
+   * Updates safe-area overrides during dynamic state changes.
+   * Called after animations, during gestures, and on orientation changes.
+   */
+  private updateSafeAreaOverrides(): void {
+    const { wrapperEl, el } = this;
+    const context = this.getSafeAreaContext();
+
+    // Sheet modals: safe-area is fully determined at presentation time
+    // (top is always 0px, height is frozen). Nothing to update.
+    if (context.isSheetModal) return;
+
+    // Card modals have fixed safe-area requirements set by initial prediction.
+    if (context.isCardModal) return;
+
+    // wrapperEl is required for position-based detection below
+    if (!wrapperEl) return;
+
+    // Regular modals: use position-based detection to correctly handle both
+    // fullscreen modals and centered dialogs with custom dimensions.
+    const safeAreaConfig = getPositionBasedSafeAreaConfig(wrapperEl);
+    applySafeAreaOverrides(el, safeAreaConfig);
+  }
+
+  /**
+   * Applies padding-bottom to fullscreen modal wrapper to prevent
+   * content from overlapping system navigation bar.
+   */
+  private applyFullscreenSafeArea(): void {
+    const { wrapperEl, el } = this;
+    if (!wrapperEl) return;
+
+    const context = this.getSafeAreaContext();
+    if (context.isSheetModal || context.isCardModal) return;
+
+    // Check for standard Ionic layout children (ion-content, ion-footer),
+    // searching one level deep for wrapped components (e.g.,
+    // <app-footer><ion-footer>...</ion-footer></app-footer>).
+    // Note: uses a manual loop instead of querySelector(':scope > ...') because
+    // Stencil's mock-doc (used in spec tests) does not support :scope.
+    let hasContent = false;
+    let hasFooter = false;
+    for (const child of Array.from(el.children)) {
+      if (child.tagName === 'ION-CONTENT') hasContent = true;
+      if (child.tagName === 'ION-FOOTER') hasFooter = true;
+      for (const grandchild of Array.from(child.children)) {
+        if (grandchild.tagName === 'ION-CONTENT') hasContent = true;
+        if (grandchild.tagName === 'ION-FOOTER') hasFooter = true;
+      }
+    }
+
+    // Only apply wrapper padding for standard Ionic layouts (has ion-content
+    // but no ion-footer). Custom modals with raw HTML are fully
+    // developer-controlled and should not be modified.
+    if (!hasContent || hasFooter) return;
+
+    // Reduce wrapper height by safe-area and add equivalent padding so the
+    // total visual size stays the same but the flex content area shrinks.
+    // Using height + padding instead of box-sizing: border-box avoids
+    // breaking custom modals that set --border-width (border-box would
+    // include the border inside the height, changing the layout).
+    wrapperEl.style.setProperty('height', 'calc(var(--height) - var(--ion-safe-area-bottom, 0px))');
+    wrapperEl.style.setProperty('padding-bottom', 'var(--ion-safe-area-bottom, 0px)');
+  }
+
+  /**
+   * Clears all safe-area overrides and padding from wrapper.
+   */
+  private cleanupSafeAreaOverrides(): void {
+    clearSafeAreaOverrides(this.el);
+
+    // Remove internal sheet offset property
+    this.el.style.removeProperty('--ion-modal-offset-top');
+
+    if (this.wrapperEl) {
+      this.wrapperEl.style.removeProperty('height');
+      this.wrapperEl.style.removeProperty('padding-bottom');
+    }
+  }
+
   render() {
     const {
       handle,