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

Issue number: resolves #24631 Co-authored-by: Maria Hutt <13530427+thetaPC@users.noreply.github.com> Co-authored-by: Brandy Smith <brandyscarney@users.noreply.github.com>

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) => {