Merge branch 'feature-8.5' into ROU-11551

Author: brandyscarney

core/api.txt

@@ -403,6 +403,7 @@ ion-checkbox,prop,justify,"end" | "space-between" | "start" | undefined,undefine
 ion-checkbox,prop,labelPlacement,"end" | "fixed" | "stacked" | "start",'start',false,false
 ion-checkbox,prop,mode,"ios" | "md",undefined,false,false
 ion-checkbox,prop,name,string,this.inputId,false,false
+ion-checkbox,prop,required,boolean,false,false,false
 ion-checkbox,prop,value,any,'on',false,false
 ion-checkbox,event,ionBlur,void,true
 ion-checkbox,event,ionChange,CheckboxChangeEventDetail<any>,true
@@ -1074,6 +1075,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
@@ -1633,6 +1635,7 @@ ion-select,prop,multiple,boolean,false,false,false
 ion-select,prop,name,string,this.inputId,false,false
 ion-select,prop,okText,string,'OK',false,false
 ion-select,prop,placeholder,string | undefined,undefined,false,false
+ion-select,prop,required,boolean,false,false,false
 ion-select,prop,selectedText,null | string | undefined,undefined,false,false
 ion-select,prop,shape,"round" | undefined,undefined,false,false
 ion-select,prop,toggleIcon,string | undefined,undefined,false,false
@@ -1949,6 +1952,7 @@ ion-toggle,prop,justify,"end" | "space-between" | "start" | undefined,undefined,
 ion-toggle,prop,labelPlacement,"end" | "fixed" | "stacked" | "start",'start',false,false
 ion-toggle,prop,mode,"ios" | "md",undefined,false,false
 ion-toggle,prop,name,string,this.inputId,false,false
+ion-toggle,prop,required,boolean,false,false,false
 ion-toggle,prop,value,null | string | undefined,'on',false,false
 ion-toggle,event,ionBlur,void,true
 ion-toggle,event,ionChange,ToggleChangeEventDetail<any>,true

core/src/components.d.ts

@@ -643,6 +643,10 @@ export namespace Components {
           * The name of the control, which is submitted with the form data.
          */
         "name": string;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required": boolean;
         "setFocus": () => Promise<void>;
         /**
           * The value of the checkbox does not mean if it's checked or not, use the `checked` property for that.  The value of a checkbox is analogous to the value of an `<input type="checkbox">`, it's only used when the checkbox participates in a native `<form>`.
@@ -1731,6 +1735,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.
          */
@@ -2816,6 +2824,10 @@ export namespace Components {
           * The text to display when the select is empty.
          */
         "placeholder"?: string;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required": boolean;
         /**
           * The text to display instead of the selected option's value.
          */
@@ -3288,6 +3300,10 @@ export namespace Components {
           * The name of the control, which is submitted with the form data.
          */
         "name": string;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required": boolean;
         /**
           * The value of the toggle does not mean if it's checked or not, use the `checked` property for that.  The value of a toggle is analogous to the value of a `<input type="checkbox">`, it's only used when the toggle participates in a native `<form>`.
          */
@@ -5443,6 +5459,10 @@ declare namespace LocalJSX {
           * Emitted when the checkbox has focus.
          */
         "onIonFocus"?: (event: IonCheckboxCustomEvent<void>) => void;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required"?: boolean;
         /**
           * The value of the checkbox does not mean if it's checked or not, use the `checked` property for that.  The value of a checkbox is analogous to the value of an `<input type="checkbox">`, it's only used when the checkbox participates in a native `<form>`.
          */
@@ -6540,6 +6560,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.
          */
@@ -7656,6 +7680,10 @@ declare namespace LocalJSX {
           * The text to display when the select is empty.
          */
         "placeholder"?: string;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required"?: boolean;
         /**
           * The text to display instead of the selected option's value.
          */
@@ -8171,6 +8199,10 @@ declare namespace LocalJSX {
           * Emitted when the toggle has focus.
          */
         "onIonFocus"?: (event: IonToggleCustomEvent<void>) => void;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required"?: boolean;
         /**
           * The value of the toggle does not mean if it's checked or not, use the `checked` property for that.  The value of a toggle is analogous to the value of a `<input type="checkbox">`, it's only used when the toggle participates in a native `<form>`.
          */

core/src/components/checkbox/checkbox.tsx

@@ -98,6 +98,13 @@ export class Checkbox implements ComponentInterface {
    */
   @Prop() alignment?: 'start' | 'center';
 
+  /**
+   * If true, screen readers will announce it as a required field. This property
+   * works only for accessibility purposes, it will not prevent the form from
+   * submitting if the value is invalid.
+   */
+  @Prop() required = false;
+
   /**
    * Emitted when the checked property has changed as a result of a user action such as a click.
    *
@@ -182,6 +189,7 @@ export class Checkbox implements ComponentInterface {
       name,
       value,
       alignment,
+      required,
     } = this;
     const mode = getIonMode(this);
     const path = getSVGPath(mode, indeterminate);
@@ -218,6 +226,7 @@ export class Checkbox implements ComponentInterface {
             onFocus={() => this.onFocus()}
             onBlur={() => this.onBlur()}
             ref={(focusEl) => (this.focusEl = focusEl)}
+            required={required}
             {...inheritedAttributes}
           />
           <div

core/src/components/checkbox/test/checkbox.spec.ts

@@ -54,3 +54,33 @@ describe('ion-checkbox: indeterminate', () => {
     expect(checkbox.getAttribute('aria-checked')).toBe('mixed');
   });
 });
+
+describe('ion-checkbox: required', () => {
+  it('should have a required attribute in inner input when true', async () => {
+    const page = await newSpecPage({
+      components: [Checkbox],
+      html: `
+        <ion-checkbox required="true">Checkbox</ion-checkbox>
+      `,
+    });
+
+    const checkbox = page.body.querySelector('ion-checkbox')!;
+    const nativeInput = checkbox.shadowRoot?.querySelector('input[type=checkbox]')!;
+
+    expect(nativeInput.hasAttribute('required')).toBeTruthy();
+  });
+
+  it('should not have a required attribute in inner input when false', async () => {
+    const page = await newSpecPage({
+      components: [Checkbox],
+      html: `
+        <ion-checkbox required="false">Checkbox</ion-checkbox>
+      `,
+    });
+
+    const checkbox = page.body.querySelector('ion-checkbox')!;
+    const nativeInput = checkbox.shadowRoot?.querySelector('input[type=checkbox]')!;
+
+    expect(nativeInput.hasAttribute('required')).toBeFalsy();
+  });
+});

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;
 };