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

Issue number: resolves #24631

Co-authored-by: Maria Hutt <[email protected]>
Co-authored-by: Brandy Smith <[email protected]>

Author: 3 people

core/api.txt

@@ -1074,6 +1074,7 @@ ion-modal,prop,backdropDismiss,boolean,true,false,false
 ion-modal,prop,breakpoints,number[] | undefined,undefined,false,false
 ion-modal,prop,canDismiss,((data?: any, role?: string | undefined) => Promise<boolean>) | boolean,true,false,false
 ion-modal,prop,enterAnimation,((baseEl: any, opts?: any) => Animation) | undefined,undefined,false,false
+ion-modal,prop,expandToScroll,boolean,true,false,false
 ion-modal,prop,focusTrap,boolean,true,false,false
 ion-modal,prop,handle,boolean | undefined,undefined,false,false
 ion-modal,prop,handleBehavior,"cycle" | "none" | undefined,'none',false,false

core/src/components.d.ts

@@ -1731,6 +1731,10 @@ export namespace Components {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * Controls whether scrolling or dragging within the sheet modal expands it to a larger breakpoint. This only takes effect when `breakpoints` and `initialBreakpoint` are set.  If `true`, scrolling or dragging anywhere in the modal will first expand it to the next breakpoint. Once fully expanded, scrolling will affect the content. If `false`, scrolling will always affect the content, and the modal will only expand when dragging the header or handle.
+         */
+        "expandToScroll": boolean;
         /**
           * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
          */
@@ -6532,6 +6536,10 @@ declare namespace LocalJSX {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * Controls whether scrolling or dragging within the sheet modal expands it to a larger breakpoint. This only takes effect when `breakpoints` and `initialBreakpoint` are set.  If `true`, scrolling or dragging anywhere in the modal will first expand it to the next breakpoint. Once fully expanded, scrolling will affect the content. If `false`, scrolling will always affect the content, and the modal will only expand when dragging the header or handle.
+         */
+        "expandToScroll"?: boolean;
         /**
           * If `true`, focus will not be allowed to move outside of this overlay. If `false`, focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
          */

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, expandToScroll } = 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.
+  !expandToScroll && 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 (expandToScroll) {
+        // 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, expandToScroll } = 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 (expandToScroll) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * If expandToScroll 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, expandToScroll } = 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.
+  expandToScroll && 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 (expandToScroll) {
+        // 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, expandToScroll } = 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 (expandToScroll) {
+        // Scroll can only be done when the modal is fully expanded.
+        return;
+      }
+
+      /**
+       * If expandToScroll 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, expandToScroll } = 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 = !expandToScroll
+    ? 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) => {