feat(modal): add expandToScroll property to allow scrolling at all breakpoints

core/api.txt

@@ -1085,6 +1085,7 @@ ion-modal,prop,keyboardClose,boolean,true,false,false
 ion-modal,prop,leaveAnimation,((baseEl: any, opts?: any) => Animation) | undefined,undefined,false,false
 ion-modal,prop,mode,"ios" | "md",undefined,false,false
 ion-modal,prop,presentingElement,HTMLElement | undefined,undefined,false,false
+ion-modal,prop,scrollAtEdge,boolean,true,false,false
 ion-modal,prop,showBackdrop,boolean,true,false,false
 ion-modal,prop,trigger,string | undefined,undefined,false,false
 ion-modal,method,dismiss,dismiss(data?: any, role?: string) => Promise<boolean>

core/src/components.d.ts

@@ -1793,6 +1793,10 @@ export namespace Components {
           * The element that presented the modal. This is used for card presentation effects and for stacking multiple modals on top of each other. Only applies in iOS mode.
          */
         "presentingElement"?: HTMLElement;
+        /**
+          * Determines whether or not the sheet modal will only scroll when fully expanded.  If the value is `true`, the modal will only scroll when fully expanded. If the value is `false`, the modal will scroll at any breakpoint.
+         */
+        "scrollAtEdge": boolean;
         /**
           * Move a sheet style modal to a specific breakpoint. The breakpoint value must be a value defined in your `breakpoints` array.
          */
@@ -6618,6 +6622,10 @@ declare namespace LocalJSX {
           * The element that presented the modal. This is used for card presentation effects and for stacking multiple modals on top of each other. Only applies in iOS mode.
          */
         "presentingElement"?: HTMLElement;
+        /**
+          * Determines whether or not the sheet modal will only scroll when fully expanded.  If the value is `true`, the modal will only scroll when fully expanded. If the value is `false`, the modal will scroll at any breakpoint.
+         */
+        "scrollAtEdge"?: boolean;
         /**
           * If `true`, a backdrop will be displayed behind the modal. This property controls whether or not the backdrop darkens the screen when the modal is presented. It does not control whether or not the backdrop is active or present in the DOM.
          */

core/src/components/modal/animations/ios.enter.ts

@@ -17,27 +17,78 @@ const createEnterAnimation = () => {
 
   const wrapperAnimation = createAnimation().fromTo('transform', 'translateY(100vh)', 'translateY(0vh)');
 
-  return { backdropAnimation, wrapperAnimation };
+  return { backdropAnimation, wrapperAnimation, contentAnimation: undefined };
 };
 
 /**
  * iOS Modal Enter Animation for the Card presentation style
  */
 export const iosEnterAnimation = (baseEl: HTMLElement, opts: ModalAnimationOptions): Animation => {
-  const { presentingEl, currentBreakpoint } = opts;
+  const { presentingEl, currentBreakpoint, scrollAtEdge } = opts;
   const root = getElementRoot(baseEl);
-  const { wrapperAnimation, backdropAnimation } =
+  const { wrapperAnimation, backdropAnimation, contentAnimation } =
     currentBreakpoint !== undefined ? createSheetEnterAnimation(opts) : createEnterAnimation();
 
   backdropAnimation.addElement(root.querySelector('ion-backdrop')!);
 
   wrapperAnimation.addElement(root.querySelectorAll('.modal-wrapper, .modal-shadow')!).beforeStyles({ opacity: 1 });
 
+  // The content animation is only added if scrolling is enabled for
+  // all the breakpoints.
+  !scrollAtEdge && contentAnimation?.addElement(baseEl.querySelector('.ion-page')!);
+
   const baseAnimation = createAnimation('entering-base')
     .addElement(baseEl)
     .easing('cubic-bezier(0.32,0.72,0,1)')
     .duration(500)
-    .addAnimation(wrapperAnimation);
+    .addAnimation([wrapperAnimation])
+    .beforeAddWrite(() => {
+      if (scrollAtEdge) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * There are some browsers that causes flickering when
+       * dragging the content when scroll is enabled at every
+       * breakpoint. This is due to the wrapper element being
+       * transformed off the screen and having a snap animation.
+       *
+       * A workaround is to clone the footer element and append
+       * it outside of the wrapper element. This way, the footer
+       * is still visible and the drag can be done without
+       * flickering. The original footer is hidden until the modal
+       * is dismissed. This maintains the animation of the footer
+       * when the modal is dismissed.
+       *
+       * The workaround needs to be done before the animation starts
+       * so there are no flickering issues.
+       */
+      const ionFooter = baseEl.querySelector('ion-footer');
+      /**
+       * This check is needed to prevent more than one footer
+       * from being appended to the shadow root.
+       * Otherwise, iOS and MD enter animations would append
+       * the footer twice.
+       */
+      const ionFooterAlreadyAppended = baseEl.shadowRoot!.querySelector('ion-footer');
+      if (ionFooter && !ionFooterAlreadyAppended) {
+        const footerHeight = ionFooter.clientHeight;
+        const clonedFooter = ionFooter.cloneNode(true) as HTMLIonFooterElement;
+
+        baseEl.shadowRoot!.appendChild(clonedFooter);
+        ionFooter.style.setProperty('display', 'none');
+        ionFooter.setAttribute('aria-hidden', 'true');
+
+        // Padding is added to prevent some content from being hidden.
+        const page = baseEl.querySelector('.ion-page') as HTMLElement;
+        page.style.setProperty('padding-bottom', `${footerHeight}px`);
+      }
+    });
+
+  if (contentAnimation) {
+    baseAnimation.addAnimation(contentAnimation);
+  }
 
   if (presentingEl) {
     const isMobile = window.innerWidth < 768;

core/src/components/modal/animations/ios.leave.ts

@@ -19,7 +19,7 @@ const createLeaveAnimation = () => {
  * iOS Modal Leave Animation
  */
 export const iosLeaveAnimation = (baseEl: HTMLElement, opts: ModalAnimationOptions, duration = 500): Animation => {
-  const { presentingEl, currentBreakpoint } = opts;
+  const { presentingEl, currentBreakpoint, scrollAtEdge } = opts;
   const root = getElementRoot(baseEl);
   const { wrapperAnimation, backdropAnimation } =
     currentBreakpoint !== undefined ? createSheetLeaveAnimation(opts) : createLeaveAnimation();
@@ -32,7 +32,33 @@ export const iosLeaveAnimation = (baseEl: HTMLElement, opts: ModalAnimationOptio
     .addElement(baseEl)
     .easing('cubic-bezier(0.32,0.72,0,1)')
     .duration(duration)
-    .addAnimation(wrapperAnimation);
+    .addAnimation(wrapperAnimation)
+    .beforeAddWrite(() => {
+      if (scrollAtEdge) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * If scrollAtEdge is disabled, we need to swap
+       * the visibility to the original, so the footer
+       *  dismisses with the modal and doesn't stay
+       *  until the modal is removed from the DOM.
+       */
+      const ionFooter = baseEl.querySelector('ion-footer');
+      if (ionFooter) {
+        const clonedFooter = baseEl.shadowRoot!.querySelector('ion-footer')!;
+
+        ionFooter.style.removeProperty('display');
+        ionFooter.removeAttribute('aria-hidden');
+
+        clonedFooter.style.setProperty('display', 'none');
+        clonedFooter.setAttribute('aria-hidden', 'true');
+
+        const page = baseEl.querySelector('.ion-page') as HTMLElement;
+        page.style.removeProperty('padding-bottom');
+      }
+    });
 
   if (presentingEl) {
     const isMobile = window.innerWidth < 768;

core/src/components/modal/animations/md.enter.ts

@@ -19,25 +19,78 @@ const createEnterAnimation = () => {
     { offset: 1, opacity: 1, transform: `translateY(0px)` },
   ]);
 
-  return { backdropAnimation, wrapperAnimation };
+  return { backdropAnimation, wrapperAnimation, contentAnimation: undefined };
 };
 
 /**
  * Md Modal Enter Animation
  */
 export const mdEnterAnimation = (baseEl: HTMLElement, opts: ModalAnimationOptions): Animation => {
-  const { currentBreakpoint } = opts;
+  const { currentBreakpoint, scrollAtEdge } = opts;
   const root = getElementRoot(baseEl);
-  const { wrapperAnimation, backdropAnimation } =
+  const { wrapperAnimation, backdropAnimation, contentAnimation } =
     currentBreakpoint !== undefined ? createSheetEnterAnimation(opts) : createEnterAnimation();
 
   backdropAnimation.addElement(root.querySelector('ion-backdrop')!);
 
   wrapperAnimation.addElement(root.querySelector('.modal-wrapper')!);
 
-  return createAnimation()
+  // The content animation is only added if scrolling is enabled for
+  // all the breakpoints.
+  scrollAtEdge && contentAnimation?.addElement(baseEl.querySelector('.ion-page')!);
+
+  const baseAnimation = createAnimation()
     .addElement(baseEl)
     .easing('cubic-bezier(0.36,0.66,0.04,1)')
     .duration(280)
-    .addAnimation([backdropAnimation, wrapperAnimation]);
+    .addAnimation([backdropAnimation, wrapperAnimation])
+    .beforeAddWrite(() => {
+      if (scrollAtEdge) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * There are some browsers that causes flickering when
+       * dragging the content when scroll is enabled at every
+       * breakpoint. This is due to the wrapper element being
+       * transformed off the screen and having a snap animation.
+       *
+       * A workaround is to clone the footer element and append
+       * it outside of the wrapper element. This way, the footer
+       * is still visible and the drag can be done without
+       * flickering. The original footer is hidden until the modal
+       * is dismissed. This maintains the animation of the footer
+       * when the modal is dismissed.
+       *
+       * The workaround needs to be done before the animation starts
+       * so there are no flickering issues.
+       */
+      const ionFooter = baseEl.querySelector('ion-footer');
+      /**
+       * This check is needed to prevent more than one footer
+       * from being appended to the shadow root.
+       * Otherwise, iOS and MD enter animations would append
+       * the footer twice.
+       */
+      const ionFooterAlreadyAppended = baseEl.shadowRoot!.querySelector('ion-footer');
+      if (ionFooter && !ionFooterAlreadyAppended) {
+        const footerHeight = ionFooter.clientHeight;
+        const clonedFooter = ionFooter.cloneNode(true) as HTMLIonFooterElement;
+
+        baseEl.shadowRoot!.appendChild(clonedFooter);
+        ionFooter.style.setProperty('display', 'none');
+        ionFooter.setAttribute('aria-hidden', 'true');
+
+        // Padding is added to prevent some content from being hidden.
+        const page = baseEl.querySelector('.ion-page') as HTMLElement;
+        page.style.setProperty('padding-bottom', `${footerHeight}px`);
+      }
+    });
+
+  if (contentAnimation) {
+    baseAnimation.addAnimation(contentAnimation);
+  }
+
+  return baseAnimation;
 };

core/src/components/modal/animations/md.leave.ts

@@ -21,16 +21,44 @@ const createLeaveAnimation = () => {
  * Md Modal Leave Animation
  */
 export const mdLeaveAnimation = (baseEl: HTMLElement, opts: ModalAnimationOptions): Animation => {
-  const { currentBreakpoint } = opts;
+  const { currentBreakpoint, scrollAtEdge } = opts;
   const root = getElementRoot(baseEl);
   const { wrapperAnimation, backdropAnimation } =
     currentBreakpoint !== undefined ? createSheetLeaveAnimation(opts) : createLeaveAnimation();
 
   backdropAnimation.addElement(root.querySelector('ion-backdrop')!);
   wrapperAnimation.addElement(root.querySelector('.modal-wrapper')!);
 
-  return createAnimation()
+  const baseAnimation = createAnimation()
     .easing('cubic-bezier(0.47,0,0.745,0.715)')
     .duration(200)
-    .addAnimation([backdropAnimation, wrapperAnimation]);
+    .addAnimation([backdropAnimation, wrapperAnimation])
+    .beforeAddWrite(() => {
+      if (scrollAtEdge) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * If scrollAtEdge is disabled, we need to swap
+       * the visibility to the original, so the footer
+       *  dismisses with the modal and doesn't stay
+       *  until the modal is removed from the DOM.
+       */
+      const ionFooter = baseEl.querySelector('ion-footer');
+      if (ionFooter) {
+        const clonedFooter = baseEl.shadowRoot!.querySelector('ion-footer')!;
+
+        ionFooter.style.removeProperty('display');
+        ionFooter.removeAttribute('aria-hidden');
+
+        clonedFooter.style.setProperty('display', 'none');
+        clonedFooter.setAttribute('aria-hidden', 'true');
+
+        const page = baseEl.querySelector('.ion-page') as HTMLElement;
+        page.style.removeProperty('padding-bottom');
+      }
+    });
+
+  return baseAnimation;
 };

core/src/components/modal/animations/sheet.ts

@@ -4,7 +4,7 @@ import type { ModalAnimationOptions } from '../modal-interface';
 import { getBackdropValueForSheet } from '../utils';
 
 export const createSheetEnterAnimation = (opts: ModalAnimationOptions) => {
-  const { currentBreakpoint, backdropBreakpoint } = opts;
+  const { currentBreakpoint, backdropBreakpoint, scrollAtEdge } = opts;
 
   /**
    * If the backdropBreakpoint is undefined, then the backdrop
@@ -29,7 +29,17 @@ export const createSheetEnterAnimation = (opts: ModalAnimationOptions) => {
     { offset: 1, opacity: 1, transform: `translateY(${100 - currentBreakpoint! * 100}%)` },
   ]);
 
-  return { wrapperAnimation, backdropAnimation };
+  /**
+   * This allows the content to be scrollable at any breakpoint.
+   */
+  const contentAnimation = !scrollAtEdge
+    ? createAnimation('contentAnimation').keyframes([
+        { offset: 0, opacity: 1, maxHeight: `${(1 - currentBreakpoint!) * 100}%` },
+        { offset: 1, opacity: 1, maxHeight: `${currentBreakpoint! * 100}%` },
+      ])
+    : undefined;
+
+  return { wrapperAnimation, backdropAnimation, contentAnimation };
 };
 
 export const createSheetLeaveAnimation = (opts: ModalAnimationOptions) => {