fix(modal): prevent ion-content collapsing at content-based heights

core/src/components.d.ts

@@ -867,7 +867,7 @@ export namespace Components {
          */
         "getScrollElement": () => Promise<HTMLElement>;
         /**
-          * Recalculate content dimensions. Called by overlays (e.g., popover) when sibling elements like headers or footers have finished rendering and their heights are available, ensuring accurate offset-top calculations.
+          * Recalculates the content dimensions and whether it should size itself to its content. Called by overlays when something they own changes, such as a header finishing its render or `--height` being updated.
          */
         "recalculateDimensions": () => Promise<void>;
         /**

core/src/components/content/content.tsx

@@ -8,13 +8,15 @@ import {
   Listen,
   Method,
   Prop,
+  State,
   Watch,
   forceUpdate,
   h,
   readTask,
 } from '@stencil/core';
 import { componentOnReady, hasLazyBuild, inheritAriaAttributes } from '@utils/helpers';
 import type { Attributes } from '@utils/helpers';
+import { getOverlaySizeType } from '@utils/overlays';
 import { isPlatform } from '@utils/platform';
 import { isRTL } from '@utils/rtl';
 import { createColorClasses, hostContext } from '@utils/theme';
@@ -77,6 +79,11 @@ export class Content implements ComponentInterface {
 
   @Element() el!: HTMLIonContentElement;
 
+  /**
+   * Whether the host is sized to its content.
+   */
+  @State() sizeToContent = false;
+
   /**
    * The color to use from your application's color palette.
    * Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`.
@@ -148,6 +155,7 @@ export class Content implements ComponentInterface {
 
   componentWillLoad() {
     this.inheritedAttributes = inheritAriaAttributes(this.el);
+    this.sizeToContent = this.readSizeToContent();
   }
 
   connectedCallback() {
@@ -190,6 +198,7 @@ export class Content implements ComponentInterface {
 
     // Re-observe on reattach, since componentDidLoad only fires once.
     this.setupFullscreenResizeObserver();
+    this.updateSizeToContent();
   }
 
   componentDidLoad() {
@@ -258,6 +267,17 @@ export class Content implements ComponentInterface {
     this.fullscreenResizeObserver.observe(this.el);
   }
 
+  /**
+   * Picks up an overlay that is no longer sized the way the last render
+   * assumed, re-rendering only when the answer changes. Read in a `readTask`
+   * because resolving the custom property forces a style recalculation.
+   */
+  private updateSizeToContent() {
+    readTask(() => {
+      this.sizeToContent = this.readSizeToContent();
+    });
+  }
+
   private destroyFullscreenResizeObserver() {
     if (this.fullscreenResizeObserver !== undefined) {
       this.fullscreenResizeObserver.disconnect();
@@ -310,6 +330,34 @@ export class Content implements ComponentInterface {
     return forceOverscroll === undefined ? mode === 'ios' && isPlatform('ios') : forceOverscroll;
   }
 
+  /**
+   * Reads whether to size the component to its content height. Forces a style
+   * recalculation, so it belongs in a read task or before the first render.
+   *
+   * This applies inside popovers and modals with a content-based `--height`,
+   * where the overlay does not provide the content with a definite height
+   * to fill.
+   *
+   * Only `--height` is consulted. Styling the wrapper directly, such as
+   * `ion-modal::part(content) { height: fit-content; }`, does not change
+   * `--height` and therefore cannot be observed. `--height` is the only
+   * supported way to opt into content-based sizing.
+   */
+  private readSizeToContent() {
+    if (hostContext('ion-popover', this.el)) {
+      return true;
+    }
+
+    const modal = this.el.closest('ion-modal');
+    if (modal === null) {
+      return false;
+    }
+
+    const height = getComputedStyle(modal).getPropertyValue('--height');
+
+    return getOverlaySizeType(height) === 'content';
+  }
+
   private resize() {
     /**
      * Only force update if the component is rendered in a browser context.
@@ -320,6 +368,13 @@ export class Content implements ComponentInterface {
      * TODO: Remove if STENCIL-834 determines Stencil will account for this.
      */
     if (Build.isBrowser) {
+      /**
+       * A window resize can cross a media query that changes the modal's
+       * `--height`. The content's own offsets are unchanged, so neither branch
+       * below re-renders and the class from the last render would go stale.
+       */
+      this.updateSizeToContent();
+
       if (this.fullscreen) {
         readTask(() => this.readDimensions());
       } else if (this.cTop !== 0 || this.cBottom !== 0) {
@@ -330,14 +385,16 @@ export class Content implements ComponentInterface {
   }
 
   /**
-   * Recalculate content dimensions. Called by overlays (e.g., popover) when
-   * sibling elements like headers or footers have finished rendering and their
-   * heights are available, ensuring accurate offset-top calculations.
+   * Recalculates the content dimensions and whether it should size itself to
+   * its content. Called by overlays when something they own changes, such as
+   * a header finishing its render or `--height` being updated.
+   *
    * @internal
    */
   @Method()
   async recalculateDimensions(): Promise<void> {
     readTask(() => this.readDimensions());
+    this.updateSizeToContent();
   }
 
   private readDimensions() {
@@ -538,7 +595,7 @@ export class Content implements ComponentInterface {
         class={createColorClasses(this.color, {
           [mode]: true,
           'content-fullscreen': this.fullscreen,
-          'content-sizing': hostContext('ion-popover', this.el),
+          'content-sizing': this.sizeToContent,
           overscroll: forceOverscroll,
           [`content-${rtl}`]: true,
         })}

core/src/components/modal/modal.scss

@@ -27,7 +27,12 @@
   --max-width: auto;
   --height: 100%;
   --min-height: auto;
-  --max-height: auto;
+  /**
+   * Clamps a content-sized `--height` (auto, fit-content, ...) to the
+   * overlay, giving the wrapper's flex children something to shrink
+   * toward so `ion-content` scrolls instead of overflowing.
+   */
+  --max-height: 100%;
   --overflow: hidden;
   --border-radius: 0;
   --border-width: 0;
@@ -87,8 +92,16 @@ ion-backdrop {
 /**
  * The wrapper receives programmatic focus for screen readers but should not
  * show a visible focus ring, which is meant only for keyboard navigation.
+ *
+ * A flex layout is required for the wrapper to size itself to its content
+ * when the modal is content-sized (`--height` is auto, fit-content, ...).
+ * This makes it so that the content can scroll when it overflows the wrapper.
  */
 .modal-wrapper {
+  display: flex;
+
+  flex-direction: column;
+
   outline: none;
 }
 

core/src/components/modal/modal.tsx

@@ -56,7 +56,7 @@ import {
   hasCustomModalDimensions,
   type ModalSafeAreaContext,
 } from './safe-area-utils';
-import { setCardStatusBarDark, setCardStatusBarDefault } from './utils';
+import { onModalHeightChange, setCardStatusBarDark, setCardStatusBarDefault } from './utils';
 
 // TODO(FW-2832): types
 
@@ -114,6 +114,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
   private viewTransitionAnimation?: Animation;
   private resizeTimeout?: any;
   private unsubscribeRootSafeAreaTop?: () => void;
+  private unsubscribeHeightChange?: () => void;
   // True from the first safe-area write in `present()` until the enter
   // animation settles. A position-based read in that window is not the rest position.
   private isPresenting = false;
@@ -1502,6 +1503,28 @@ export class Modal implements ComponentInterface, OverlayInterface {
     };
   }
 
+  /**
+   * Keeps the content's sizing in sync with `--height`. The content reads the
+   * property to determine whether it should size itself to its content, and
+   * changes to `--height` on an ancestor or the root can change that behavior
+   * without changing the modal itself.
+   */
+  private watchHeightForContent(): void {
+    /**
+     * A sheet's height comes from its breakpoints, so its content never sizes
+     * itself to `--height`. Watching it would cause the drag to recalculate on
+     * every frame.
+     */
+    if (this.isSheetModal) {
+      return;
+    }
+
+    this.unsubscribeHeightChange?.();
+    this.unsubscribeHeightChange = onModalHeightChange(this.el, () => {
+      this.el.querySelectorAll('ion-content').forEach((contentEl) => contentEl.recalculateDimensions());
+    });
+  }
+
   /**
    * Sets initial safe-area overrides before modal animation.
    * Called in present() before animation starts.
@@ -1520,6 +1543,8 @@ export class Modal implements ComponentInterface, OverlayInterface {
     const safeAreaConfig = getInitialSafeAreaConfig(context);
     applySafeAreaOverrides(this.el, safeAreaConfig);
 
+    this.watchHeightForContent();
+
     // Set the internal offset property with the resolved root safe-area-top value
     if (context.isSheetModal) {
       this.updateSheetOffsetTop();
@@ -1646,6 +1671,9 @@ export class Modal implements ComponentInterface, OverlayInterface {
     this.unsubscribeRootSafeAreaTop?.();
     this.unsubscribeRootSafeAreaTop = undefined;
 
+    this.unsubscribeHeightChange?.();
+    this.unsubscribeHeightChange = undefined;
+
     // Remove internal sheet offset property
     this.el.style.removeProperty('--ion-modal-offset-top');
 

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

@@ -0,0 +1,121 @@
+import { hasCustomModalDimensions } from './safe-area-utils';
+
+/**
+ * The helper resolves `--width` and `--height` through `getComputedStyle`, and
+ * measures the wrapper when the height sizes to the content. A spec
+ * environment reports no custom properties and a zero rect, so each test
+ * states the sizes and the wrapper height it wants.
+ */
+describe('modal: hasCustomModalDimensions', () => {
+  const VIEWPORT_HEIGHT = window.innerHeight;
+
+  let host: HTMLElement;
+  let wrapper: HTMLElement;
+  let hiddenDuringMeasurement: boolean;
+  let originalGetComputedStyle: PropertyDescriptor | undefined;
+  let sizes: Record<string, string>;
+
+  const setSize = (width: string, height: string) => {
+    sizes = { '--width': width, '--height': height };
+  };
+
+  const setWrapperHeight = (height: number) => {
+    wrapper.getBoundingClientRect = () => {
+      hiddenDuringMeasurement = host.classList.contains('overlay-hidden');
+      return { height } as DOMRect;
+    };
+  };
+
+  beforeEach(() => {
+    host = document.createElement('ion-modal');
+    host.classList.add('overlay-hidden');
+    document.body.appendChild(host);
+
+    wrapper = document.createElement('div');
+    wrapper.classList.add('modal-wrapper');
+    host.attachShadow({ mode: 'open' }).appendChild(wrapper);
+
+    hiddenDuringMeasurement = true;
+    setWrapperHeight(0);
+
+    /**
+     * The mock window exposes `getComputedStyle` as a getter, so it has to be
+     * replaced on `globalThis` rather than assigned.
+     */
+    sizes = {};
+    originalGetComputedStyle = Object.getOwnPropertyDescriptor(globalThis, 'getComputedStyle');
+    Object.defineProperty(globalThis, 'getComputedStyle', {
+      value: () => ({ getPropertyValue: (property: string) => sizes[property] ?? '' }),
+      configurable: true,
+      writable: true,
+    });
+  });
+
+  afterEach(() => {
+    if (originalGetComputedStyle) {
+      Object.defineProperty(globalThis, 'getComputedStyle', originalGetComputedStyle);
+    }
+    host.remove();
+  });
+
+  it('should be false when the width spans the viewport', () => {
+    setSize('100%', '300px');
+
+    expect(hasCustomModalDimensions(host)).toBe(false);
+  });
+
+  it('should be false when the height spans the viewport', () => {
+    setSize('300px', '100%');
+
+    expect(hasCustomModalDimensions(host)).toBe(false);
+  });
+
+  it('should be true when both axes are a definite size', () => {
+    setSize('300px', '200px');
+
+    expect(hasCustomModalDimensions(host)).toBe(true);
+  });
+
+  it('should be true when a content sized modal stays clear of the edges', () => {
+    setSize('300px', 'fit-content');
+    setWrapperHeight(244);
+
+    expect(hasCustomModalDimensions(host)).toBe(true);
+  });
+
+  // Overflowing content leaves `--max-height` clamping the modal to the
+  // viewport, where it reaches the top and bottom edges.
+  it('should be false when a content sized modal fills the viewport', () => {
+    setSize('300px', 'fit-content');
+    setWrapperHeight(VIEWPORT_HEIGHT);
+
+    expect(hasCustomModalDimensions(host)).toBe(false);
+  });
+
+  it('should allow a few pixels of tolerance when comparing to the viewport', () => {
+    setSize('300px', 'fit-content');
+    setWrapperHeight(VIEWPORT_HEIGHT - 4);
+
+    expect(hasCustomModalDimensions(host)).toBe(false);
+  });
+
+  it('should measure the wrapper while it is visible and hide it again', () => {
+    setSize('300px', 'fit-content');
+    setWrapperHeight(VIEWPORT_HEIGHT);
+
+    hasCustomModalDimensions(host);
+
+    expect(hiddenDuringMeasurement).toBe(false);
+    expect(host.classList.contains('overlay-hidden')).toBe(true);
+  });
+
+  it('should leave a visible modal visible', () => {
+    host.classList.remove('overlay-hidden');
+    setSize('300px', 'fit-content');
+    setWrapperHeight(244);
+
+    hasCustomModalDimensions(host);
+
+    expect(host.classList.contains('overlay-hidden')).toBe(false);
+  });
+});