fix(overlays): refine safe-area handling for modals and popovers

Author: ShaneK

core/src/components/modal/modal.tsx

@@ -413,6 +413,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() {
@@ -601,6 +604,10 @@ 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();
 
@@ -662,14 +669,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();
@@ -1185,8 +1185,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
     transitionAnimation.play().then(() => {
       this.viewTransitionAnimation = undefined;
 
-      // Update safe-area overrides for new orientation
-      this.updateSafeAreaOverrides();
+      // 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
@@ -1361,11 +1362,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
    * Creates the context object for safe-area utilities.
    */
   private getSafeAreaContext(): ModalSafeAreaContext {
-    const mode = getIonMode(this);
     return {
       isSheetModal: this.isSheetModal,
-      isCardModal: this.presentingElement !== undefined && mode === 'ios',
-      mode,
+      isCardModal: this.presentingElement !== undefined && getIonMode(this) === 'ios',
       presentingElement: this.presentingElement,
       breakpoints: this.breakpoints,
       currentBreakpoint: this.currentBreakpoint,
@@ -1378,8 +1377,8 @@ export class Modal implements ComponentInterface, OverlayInterface {
    */
   private setInitialSafeAreaOverrides(): void {
     const context = this.getSafeAreaContext();
-    const config = getInitialSafeAreaConfig(context);
-    applySafeAreaOverrides(this.el, config);
+    const safeAreaConfig = getInitialSafeAreaConfig(context);
+    applySafeAreaOverrides(this.el, safeAreaConfig);
   }
 
   /**
@@ -1388,12 +1387,32 @@ export class Modal implements ComponentInterface, OverlayInterface {
    */
   private updateSafeAreaOverrides(): void {
     const { wrapperEl, el } = this;
+    const context = this.getSafeAreaContext();
+
+    // Sheet modals: the wrapper extends beyond the viewport and is translated
+    // via breakpoint gestures, making getBoundingClientRect unreliable for
+    // edge detection. Instead, use breakpoint value to determine top safe-area.
+    if (context.isSheetModal) {
+      const needsTopSafeArea = context.currentBreakpoint === 1;
+      applySafeAreaOverrides(el, {
+        top: needsTopSafeArea ? 'inherit' : '0px',
+        bottom: 'inherit',
+        left: '0px',
+        right: '0px',
+      });
+      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;
 
-    // Always use position-based detection to correctly handle both
-    // fullscreen modals and centered dialogs with custom dimensions
-    const config = getPositionBasedSafeAreaConfig(wrapperEl);
-    applySafeAreaOverrides(el, config);
+    // 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);
   }
 
   /**
@@ -1407,12 +1426,31 @@ export class Modal implements ComponentInterface, OverlayInterface {
     const context = this.getSafeAreaContext();
     if (context.isSheetModal || context.isCardModal) return;
 
-    // Check if footer exists
-    const footer = el.querySelector('ion-footer');
-    if (footer) 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>).
+    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;
+      }
+    }
 
-    // Add padding to wrapper to prevent content overlap
-    wrapperEl.style.setProperty('box-sizing', 'border-box');
+    // 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)');
   }
 
@@ -1423,7 +1461,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
     clearSafeAreaOverrides(this.el);
 
     if (this.wrapperEl) {
-      this.wrapperEl.style.removeProperty('box-sizing');
+      this.wrapperEl.style.removeProperty('height');
       this.wrapperEl.style.removeProperty('padding-bottom');
     }
   }

core/src/components/modal/safe-area-utils.ts

@@ -17,20 +17,32 @@ export interface SafeAreaConfig {
 export interface ModalSafeAreaContext {
   isSheetModal: boolean;
   isCardModal: boolean;
-  mode: 'ios' | 'md';
   presentingElement?: HTMLElement;
   breakpoints?: number[];
   currentBreakpoint?: number;
 }
 
-const TABLET_WIDTH = 768;
+/**
+ * These thresholds match the SCSS media query breakpoints in modal.vars.scss
+ * that trigger the centered dialog layout (non-fullscreen modal).
+ *
+ * SCSS defines two height breakpoints: $modal-inset-min-height-small (600px)
+ * and $modal-inset-min-height-large (768px). We use the smaller one because
+ * that's the threshold where the modal transitions from fullscreen to centered
+ * dialog — the larger breakpoint only increases the dialog's height.
+ */
+const MODAL_INSET_MIN_WIDTH = 768;
+const MODAL_INSET_MIN_HEIGHT = 600;
 const EDGE_THRESHOLD = 5;
 
 /**
- * Determines if the current viewport is tablet-sized (>= 768px width).
+ * Determines if the current viewport meets the CSS media query conditions
+ * that cause regular modals to render as centered dialogs instead of fullscreen.
+ * Matches: @media (min-width: 768px) and (min-height: 600px)
  */
-export const isTabletViewport = (): boolean => {
-  return win ? win.innerWidth >= TABLET_WIDTH : false;
+const isCenteredDialogViewport = (): boolean => {
+  if (!win) return false;
+  return win.matchMedia(`(min-width: ${MODAL_INSET_MIN_WIDTH}px) and (min-height: ${MODAL_INSET_MIN_HEIGHT}px)`).matches;
 };
 
 /**
@@ -41,20 +53,21 @@ export const isTabletViewport = (): boolean => {
  * @returns SafeAreaConfig with initial safe-area values
  */
 export const getInitialSafeAreaConfig = (context: ModalSafeAreaContext): SafeAreaConfig => {
-  const { isSheetModal, isCardModal, mode } = context;
+  const { isSheetModal, isCardModal } = context;
 
-  // Sheet modals always use bottom safe-area only
+  // Sheet modals use bottom safe-area, and top safe-area only when fully expanded
   if (isSheetModal) {
     return {
-      top: '0px',
+      top: context.currentBreakpoint === 1 ? 'inherit' : '0px',
       bottom: 'inherit',
       left: '0px',
       right: '0px',
     };
   }
 
-  // Card modals (iOS only) need safe-area for height calculation
-  if (isCardModal && mode === 'ios') {
+  // Card modals need safe-area for height calculation.
+  // Note: isCardModal is already gated on mode === 'ios' by the caller.
+  if (isCardModal) {
     return {
       top: 'inherit',
       bottom: 'inherit',
@@ -63,7 +76,19 @@ export const getInitialSafeAreaConfig = (context: ModalSafeAreaContext): SafeAre
     };
   }
 
-  // Fullscreen and centered dialogs - inherit all, let position detection decide
+  // On viewports that meet the centered dialog media query breakpoints,
+  // regular modals render as centered dialogs (not fullscreen), so they
+  // don't touch any screen edges and don't need safe-area insets.
+  if (isCenteredDialogViewport()) {
+    return {
+      top: '0px',
+      bottom: '0px',
+      left: '0px',
+      right: '0px',
+    };
+  }
+
+  // Fullscreen modals on phone - inherit all safe areas
   return {
     top: 'inherit',
     bottom: 'inherit',
@@ -76,25 +101,16 @@ export const getInitialSafeAreaConfig = (context: ModalSafeAreaContext): SafeAre
  * Returns safe-area configuration based on actual modal position.
  * Detects which edges the modal overlaps with and only applies safe-area to those edges.
  *
+ * Note: On Android edge-to-edge (API 36+), getBoundingClientRect() may report
+ * inconsistent values. Sheet and card modals avoid this by using configuration-based
+ * prediction instead. Regular modals use coordinate detection which works reliably
+ * on web and iOS; Android edge-to-edge may need a configuration-based fallback
+ * once a reliable detection mechanism is available.
+ *
  * @param wrapperEl - The modal wrapper element to measure
- * @param skipCoordinateDetection - If true, skips coordinate detection and returns inherit for all
  * @returns SafeAreaConfig based on position
  */
-export const getPositionBasedSafeAreaConfig = (
-  wrapperEl: HTMLElement,
-  skipCoordinateDetection = false
-): SafeAreaConfig => {
-  // Skip coordinate detection for Android edge-to-edge compatibility
-  // or when explicitly requested
-  if (skipCoordinateDetection) {
-    return {
-      top: 'inherit',
-      bottom: 'inherit',
-      left: 'inherit',
-      right: 'inherit',
-    };
-  }
-
+export const getPositionBasedSafeAreaConfig = (wrapperEl: HTMLElement): SafeAreaConfig => {
   const rect = wrapperEl.getBoundingClientRect();
   const vh = win?.innerHeight ?? 0;
   const vw = win?.innerWidth ?? 0;