fix(modal): decouple sheet height from safe-area and update on resize

Author: ShaneK

core/src/components/modal/modal.scss

@@ -152,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/modal/modal.tsx

@@ -49,6 +49,7 @@ import {
   getPositionBasedSafeAreaConfig,
   applySafeAreaOverrides,
   clearSafeAreaOverrides,
+  getRootSafeAreaTop,
   type ModalSafeAreaContext,
 } from './safe-area-utils';
 import { setCardStatusBarDark, setCardStatusBarDefault } from './utils';
@@ -283,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
   }
 
@@ -770,8 +792,6 @@ export class Modal implements ComponentInterface, OverlayInterface {
         if (this.currentBreakpoint !== breakpoint) {
           this.currentBreakpoint = breakpoint;
           this.ionBreakpointDidChange.emit({ breakpoint });
-          // Update safe-area overrides based on new position
-          this.updateSafeAreaOverrides();
         }
       }
     );
@@ -903,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,
@@ -1374,11 +1398,32 @@ export class Modal implements ComponentInterface, OverlayInterface {
   /**
    * 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`);
   }
 
   /**
@@ -1389,19 +1434,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
     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;
-    }
+    // 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;
@@ -1454,6 +1489,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
   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');

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

@@ -1,4 +1,5 @@
 import { win } from '@utils/browser';
+import { raf } from '@utils/helpers';
 
 type SafeAreaValue = '0px' | 'inherit';
 
@@ -37,6 +38,12 @@ const MODAL_INSET_MIN_WIDTH = 768;
 const MODAL_INSET_MIN_HEIGHT = 600;
 const EDGE_THRESHOLD = 5;
 
+/**
+ * Cache for resolved root safe-area-top value, invalidated once per frame.
+ */
+let cachedRootSafeAreaTop: number | null = null;
+let cacheInvalidationScheduled = false;
+
 /**
  * Determines if the current viewport meets the CSS media query conditions
  * that cause regular modals to render as centered dialogs instead of fullscreen.
@@ -48,6 +55,44 @@ const isCenteredDialogViewport = (): boolean => {
     .matches;
 };
 
+/**
+ * Resolves the current root --ion-safe-area-top value to pixels.
+ * Uses a temporary element because getComputedStyle on :root returns
+ * the declared value of custom properties (e.g. "env(safe-area-inset-top)")
+ * rather than a resolved number.
+ *
+ * Results are cached for the current frame to avoid repeated reflows.
+ */
+export const getRootSafeAreaTop = (): number => {
+  if (cachedRootSafeAreaTop !== null) {
+    return cachedRootSafeAreaTop;
+  }
+
+  const doc = win?.document;
+  if (!doc?.body) {
+    return 0;
+  }
+
+  const el = doc.createElement('div');
+  el.style.cssText =
+    'position:fixed;visibility:hidden;pointer-events:none;top:0;left:0;' +
+    'padding-top:var(--ion-safe-area-top,0px);';
+  doc.body.appendChild(el);
+  const value = parseFloat(getComputedStyle(el).paddingTop) || 0;
+  el.remove();
+
+  cachedRootSafeAreaTop = value;
+  if (!cacheInvalidationScheduled) {
+    cacheInvalidationScheduled = true;
+    raf(() => {
+      cachedRootSafeAreaTop = null;
+      cacheInvalidationScheduled = false;
+    });
+  }
+
+  return value;
+};
+
 /**
  * Returns the initial safe-area configuration based on modal type.
  * This is called before animation starts and uses configuration-based prediction.
@@ -58,10 +103,14 @@ const isCenteredDialogViewport = (): boolean => {
 export const getInitialSafeAreaConfig = (context: ModalSafeAreaContext): SafeAreaConfig => {
   const { isSheetModal, isCardModal } = context;
 
-  // Sheet modals use bottom safe-area, and top safe-area only when fully expanded
+  // Sheet modals always zero top safe-area. The sheet height offset from the
+  // top edge is handled by --ion-modal-offset-top (set in modal.tsx) using
+  // the resolved root value, so --ion-safe-area-top is never needed for
+  // height calculation. Keeping it at 0px prevents header content from
+  // getting double-offset padding.
   if (isSheetModal) {
     return {
-      top: context.currentBreakpoint === 1 ? 'inherit' : '0px',
+      top: '0px',
       bottom: 'inherit',
       left: '0px',
       right: '0px',

core/src/components/modal/test/safe-area/modal.e2e.ts

@@ -8,6 +8,12 @@ import { configs, test, Viewports } from '@utils/test/playwright';
  * Safe-area handling is position-based and not affected by text direction.
  * Testing only LTR to avoid redundant test runs.
  */
+
+/**
+ * The test page (index.html) sets these root safe-area values.
+ * Keep in sync with the :root block in test/safe-area/index.html.
+ */
+const TEST_SAFE_AREA_TOP = '47px';
 configs({ modes: ['ios', 'md'], directions: ['ltr'] }).forEach(({ title, config }) => {
   test.describe(title('modal: safe-area handling'), () => {
     test.beforeEach(async ({ page }) => {
@@ -123,7 +129,7 @@ configs({ modes: ['ios', 'md'], directions: ['ltr'] }).forEach(({ title, config
       expect(height).toBe('calc(var(--height) - var(--ion-safe-area-bottom, 0px))');
     });
 
-    test('sheet modal at breakpoint 1 should inherit top safe-area', async ({ page }, testInfo) => {
+    test('sheet modal at breakpoint 1 should keep top safe-area zeroed', async ({ page }, testInfo) => {
       testInfo.annotations.push({
         type: 'issue',
         description: 'https://github.com/ionic-team/ionic-framework/issues/30900',
@@ -149,11 +155,71 @@ configs({ modes: ['ios', 'md'], directions: ['ltr'] }).forEach(({ title, config
       });
       await ionBreakpointDidChange.next();
 
-      // At breakpoint 1, top safe-area should be inherited
+      // At breakpoint 1, top safe-area should still be 0px because the
+      // sheet height is frozen with the resolved root value. This prevents
+      // header content from getting double-offset padding.
       safeAreaTop = await modal.evaluate((el: HTMLIonModalElement) => {
         return el.style.getPropertyValue('--ion-safe-area-top');
       });
+      expect(safeAreaTop).toBe('0px');
+    });
+
+    test('sheet modal should have --ion-modal-offset-top set with resolved safe-area value', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/30900',
+      });
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+
+      await page.click('#sheet-modal');
+      await ionModalDidPresent.next();
+
+      const modal = page.locator('ion-modal');
+
+      // The internal --ion-modal-offset-top property should be set to the
+      // resolved root --ion-safe-area-top value. The SCSS --height formula
+      // uses this instead of --ion-safe-area-top directly.
+      const offsetTop = await modal.evaluate((el: HTMLIonModalElement) => {
+        return el.style.getPropertyValue('--ion-modal-offset-top');
+      });
+      expect(offsetTop).toBe(TEST_SAFE_AREA_TOP);
+    });
+
+    test('fullscreen modal safe-area should update on resize from phone to tablet', async ({ page }, testInfo) => {
+      testInfo.annotations.push({
+        type: 'issue',
+        description: 'https://github.com/ionic-team/ionic-framework/issues/30900',
+      });
+
+      const ionModalDidPresent = await page.spyOnEvent('ionModalDidPresent');
+
+      await page.click('#fullscreen-modal');
+      await ionModalDidPresent.next();
+
+      const modal = page.locator('ion-modal');
+
+      // On phone viewport, modal should inherit safe-area
+      let safeAreaTop = await modal.evaluate((el: HTMLIonModalElement) => {
+        return el.style.getPropertyValue('--ion-safe-area-top');
+      });
       expect(safeAreaTop).toBe('inherit');
+
+      // Resize to tablet viewport (centered dialog breakpoint)
+      await page.setViewportSize(Viewports.tablet.portrait);
+
+      // Poll until the debounced resize handler updates safe-area overrides
+      await expect.poll(async () => {
+        return modal.evaluate((el: HTMLIonModalElement) =>
+          el.style.getPropertyValue('--ion-safe-area-top')
+        );
+      }).toBe('0px');
+
+      const safeAreaBottom = await modal.evaluate((el: HTMLIonModalElement) => {
+        return el.style.getPropertyValue('--ion-safe-area-bottom');
+      });
+
+      expect(safeAreaBottom).toBe('0px');
     });
 
     test('centered dialog should have all safe-area values zeroed on tablet', async ({ page }, testInfo) => {