lightning-base-components 1.17.2-alpha → 1.17.5-alpha

package/src/lightning/modalBase/modalBase.js

@@ -18,6 +18,11 @@ import closeButtonAltText from '@salesforce/label/LightningModalBase.cancelandcl
 import disableCloseBtnMessage from '@salesforce/label/LightningModalBase.waitstate';
 
 const DEBOUNCE_RESIZE = 300;
+const SMALL_SCREEN_SIZE = 767;
+const SIZE_SMALL = 'small';
+const SIZE_MEDIUM = 'medium';
+const SIZE_LARGE = 'large';
+const SIZE_FULL = 'full';
 
 export default class LightningModalBase extends LightningElement {
     // this is visible in DOM, changed from 'lightning-modal-base'
@@ -26,12 +31,15 @@ export default class LightningModalBase extends LightningElement {
     // private tracked state
     initialRender = true;
     autoFocusCompletedOnce = false;
-    windowResizeEventsBound = false;
     timeoutId = 0;
     disableCloseButton = false;
     sectionAriaBusy = null;
     closeButtonAltText = closeButtonAltText;
     disableCloseBtnMessage = disableCloseBtnMessage;
+    isModalClosing = false;
+    // screen size private tracked state
+    isSmallScreenSize = null;
+
     // modalHeader, child
     headerRegistered = false;
     headerHeight = 0;
@@ -51,6 +59,11 @@ export default class LightningModalBase extends LightningElement {
     baseUpdateBodyCallback = null;
     bodyResizeScheduled = false;
     bodyTabElemRef = null;
+    // eventing state utilized when modalBody present
+    windowResizeEventBound = false;
+    windowOrientationEventBound = false;
+    portraitMatchMedia = null;
+    screenOrientationChangeHandler = null;
 
     // modalFooter, child
     footerRegistered = false;
@@ -70,7 +83,6 @@ export default class LightningModalBase extends LightningElement {
     // modal features
     isModalOpen = false;
     isModalTransitioningIn = false;
-    _size = 'medium';
     // modal background elements
     savedInertElements = [];
     // before modal opened, element previously focused
@@ -103,12 +115,12 @@ export default class LightningModalBase extends LightningElement {
 
     /**
      * Get the current modal size, calculated as a percentage of the viewport.
-     * Valid values are small, medium, and large. The default is medium.
+     * Valid values are small, medium, large, and full. The default is medium.
      * @type {string}
      * @default medium
      */
     get size() {
-        const sizeDefault = 'medium';
+        const sizeDefault = SIZE_MEDIUM;
         const modal = this.modal;
         if (!modal) {
             return sizeDefault;
@@ -116,7 +128,7 @@ export default class LightningModalBase extends LightningElement {
         // get the size value from <lightning-modal>
         return normalizeString(modal.size, {
             fallbackValue: sizeDefault,
-            validValues: ['small', 'medium', 'large'],
+            validValues: [SIZE_FULL, SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE],
         });
     }
 
@@ -252,13 +264,16 @@ export default class LightningModalBase extends LightningElement {
      * @returns {number}
      * @private
      */
-    get backdropHeight() {
+    get backdropDimensions() {
         const backdropElem = this.modalBackdrop;
         const backdropRect = backdropElem
             ? backdropElem.getBoundingClientRect()
             : {};
-        const { height } = backdropRect;
-        return height || 0;
+        const { height, width } = backdropRect;
+        return {
+            height: height || 0,
+            width: width || 0,
+        };
     }
 
     /**
@@ -287,9 +302,10 @@ export default class LightningModalBase extends LightningElement {
         }
         // don't add animation related css classes in this group
         classes.add({
-            'slds-modal_medium': sizeClass === 'medium',
-            'slds-modal_large': sizeClass === 'large',
-            'slds-modal_small': sizeClass === 'small',
+            'slds-modal_full': sizeClass === SIZE_FULL,
+            'slds-modal_medium': sizeClass === SIZE_MEDIUM,
+            'slds-modal_large': sizeClass === SIZE_LARGE,
+            'slds-modal_small': sizeClass === SIZE_SMALL,
         });
         return classes.toString();
     }
@@ -316,6 +332,20 @@ export default class LightningModalBase extends LightningElement {
         return classes.toString();
     }
 
+    /**
+     * Compute the correct lightning-button-icon variant to use
+     * for the size="full" behaviors, based upon the screen size
+     * threshold.  Important to maintain existing close button behavior
+     * when size 'small', 'medium' and 'large' close button variant
+     * when 'isSmallScreenSize = true' for a11y purposes
+     * @private
+     */
+    get computedCloseButtonVariant() {
+        return this.isSmallScreenSize && this.size === SIZE_FULL
+            ? 'bare'
+            : 'bare-inverse';
+    }
+
     /**
      * Saves the current active focused element on modal creation
      * in order to be able to set focus back to that previous element
@@ -492,8 +522,11 @@ export default class LightningModalBase extends LightningElement {
                     [ARIA.LABEL]: label,
                 });
             } else {
-                // in headless variant, must have label value set
-                this.unsetAriaLabelAndError();
+                // in headless variant, must have label value set, unless the modal
+                // is actively closing
+                if (!this.isModalClosing) {
+                    this.unsetAriaLabelAndError();
+                }
             }
         }
     }
@@ -530,6 +563,10 @@ export default class LightningModalBase extends LightningElement {
             console.error('Invalid access to privateclose event');
             return;
         }
+
+        // set isModalClosing boolean, to prevent intentional error
+        // when checking for presence of api 'label' value
+        this.isModalClosing = true;
         if (hasAnimation()) {
             /// triggers the disappearance of the foreground modal elements
             this.modalWrapper.classList.remove('slds-fade-in-open');
@@ -542,6 +579,17 @@ export default class LightningModalBase extends LightningElement {
             // skip animation, resolve immediately
             e.detail.resolve();
         }
+        // disconnectedCallback doesn't get called on .close()
+        // unregistering child components
+        if (this.headerRegistered && this.unregisterHeader) {
+            this.unregisterHeader();
+        }
+        if (this.bodyRegistered && this.unregisterBody) {
+            this.unregisterBody();
+        }
+        if (this.footerRegistered && this.unregisterFooter) {
+            this.unregisterFooter();
+        }
         this.closeModal();
     }
 
@@ -678,7 +726,7 @@ export default class LightningModalBase extends LightningElement {
         // FUTURE TODO mechanism to support aria-describedby
         // aria-describedby is optional, without a good reproducible pattern
         this.initBodyState();
-        this.detachBodyResizeEvents();
+        this.removeWindowResizeEventListener();
     }
 
     /**
@@ -707,11 +755,14 @@ export default class LightningModalBase extends LightningElement {
         });
         // cover case if modalBody is removed, then added back
         // required to correctly set the CSS classes on modalBody
-        this.updateBodyHeight();
+        this.updateModalBodyHeight();
 
         // ModalBody can register 2+ times when initially rendering
-        if (!this.windowResizeEventsBound) {
-            this.bindBodyResizeEvents();
+        if (!this.windowResizeEventBound) {
+            this.addWindowResizeEventListener();
+        }
+        if (!this.windowOrientationEventBound) {
+            this.addOrientationChangeListener();
         }
     }
 
@@ -738,6 +789,7 @@ export default class LightningModalBase extends LightningElement {
         this.baseUpdateBodyCallback = null;
         this.bodyResizeScheduled = false;
         this.bodyTabElemRef = null;
+        this.removeModalEventListeners();
     }
 
     /**
@@ -781,7 +833,7 @@ export default class LightningModalBase extends LightningElement {
         });
         // update modalBody max-height values
         if (this.bodyRegistered) {
-            this.updateBodyHeight();
+            this.updateModalBodyHeight();
         }
     }
 
@@ -847,7 +899,7 @@ export default class LightningModalBase extends LightningElement {
         });
         // update modalBody max-height values
         if (this.bodyRegistered) {
-            this.updateBodyHeight();
+            this.updateModalBodyHeight();
         }
     }
 
@@ -884,7 +936,7 @@ export default class LightningModalBase extends LightningElement {
      */
     get modalResizing() {
         if (!this._resizing) {
-            this._resizing = this.scheduleResize.bind(this);
+            this._resizing = this.scheduleWindowResizeEvent.bind(this);
         }
         return this._resizing;
     }
@@ -896,13 +948,16 @@ export default class LightningModalBase extends LightningElement {
      * the window.onresize event fires
      * @private
      */
-    updateBodyHeight() {
+    updateModalBodyHeight() {
         clearTimeout(this.timeoutId);
         this.timeoutId = 0;
         const { bodyResizeScheduled, bodyRegistered, baseUpdateBodyCallback } =
             this;
 
         if (bodyRegistered && !bodyResizeScheduled) {
+            // check, and update isSmallScreenSize before
+            // callback to modalBody
+            this.setIsSmallScreenSize();
             // eslint-disable-next-line @lwc/lwc/no-async-operation
             requestAnimationFrame(() => {
                 this.bodyResizeScheduled = false;
@@ -910,7 +965,11 @@ export default class LightningModalBase extends LightningElement {
                     const values = {
                         footerHeight: this.footerHeight || 0,
                         headerHeight: this.headerHeight || 0,
-                        backdropHeight: this.backdropHeight,
+                        // backdrop values can be used as proxies for screen width / height
+                        backdropHeight: this.backdropDimensions.height,
+                        backdropWidth: this.backdropDimensions.width,
+                        sizeSetFull: this.size === SIZE_FULL,
+                        isSmallScreenSize: this.isSmallScreenSize,
                     };
                     baseUpdateBodyCallback(values);
                 }
@@ -924,11 +983,11 @@ export default class LightningModalBase extends LightningElement {
      * from being fired every time window.onresize event fires
      * @private
      */
-    scheduleResize() {
+    scheduleWindowResizeEvent() {
         if (this.timeoutId === 0) {
             // eslint-disable-next-line @lwc/lwc/no-async-operation
             this.timeoutId = setTimeout(() => {
-                this.updateBodyHeight();
+                this.updateModalBodyHeight();
             }, DEBOUNCE_RESIZE);
         }
     }
@@ -937,18 +996,20 @@ export default class LightningModalBase extends LightningElement {
      * Event handler for window.onresize event
      * @private
      */
-    handleWindowResize = () => {
-        this.scheduleResize();
+    handleWindowResizeEvent = () => {
+        this.scheduleWindowResizeEvent();
     };
 
     /**
-     * Bind window.onresize event listener when modalBody is present
+     * Add window 'resize' event listener when modalBody is present
+     * this only gets used by modalBody, so only gets wired up when
+     * registerBody function called
      * @private
      */
-    bindBodyResizeEvents() {
-        if (window && !this.windowResizeEventsBound) {
-            window.addEventListener('resize', this.handleWindowResize);
-            this.windowResizeEventsBound = true;
+    addWindowResizeEventListener() {
+        if (window && !this.windowResizeEventBound) {
+            window.addEventListener('resize', this.handleWindowResizeEvent);
+            this.windowResizeEventBound = true;
         }
     }
 
@@ -956,26 +1017,87 @@ export default class LightningModalBase extends LightningElement {
      * Detach window.onresize event listener when modalBody is removed
      * @private
      */
-    detachBodyResizeEvents() {
-        if (window) {
-            window.removeEventListener('resize', this.handleWindowResize);
+    removeWindowResizeEventListener() {
+        if (window && this.windowResizeEventBound) {
+            window.removeEventListener('resize', this.handleWindowResizeEvent);
             clearTimeout(this.timeoutId);
             this.timeoutId = 0;
-            this.windowResizeEventsBound = false;
+            this.windowResizeEventBound = false;
+        }
+    }
+
+    /**
+     * Remove screen orientation 'change' listener
+     * @private
+     */
+    removeOrientationChangeListener() {
+        // TODO START HERE, check for this.windowOrientationEventBound === true
+        if (this.portraitMatchMedia) {
+            this.portraitMatchMedia.removeEventListener(
+                'change',
+                this.screenOrientationChangeHandler
+            );
+            this.portraitMatchMedia = null;
+            this.windowOrientationEventBound = false;
+        }
+        if (this.screenOrientationChangeHandler) {
+            this.screenOrientationChangeHandler = null;
+        }
+    }
+
+    /**
+     * Add screen orientation 'change' listener.
+     * orientation changes: 'portrait' -> 'landscape' -> 'portrait'
+     */
+    addOrientationChangeListener() {
+        this.portraitMatchMedia = window.matchMedia('(orientation: portrait)');
+        this.screenOrientationChangeHandler =
+            this.handleWindowResizeEvent.bind(this);
+        if (typeof this.portraitMatchMedia === 'function') {
+            this.portraitMatchMedia.addEventListener(
+                'change',
+                this.screenOrientationChangeHandler
+            );
+            this.windowOrientationEventBound = true;
         }
     }
 
+    /**
+     * determine if the current screen is less than SMALL_SCREEN_SIZE
+     * for Modal, screen size detection is simplified to what's required
+     * for the size="full" feature addition, which is a single breakpoint
+     * either (a) at or below 767 pixels (small = full screen modal behavior),
+     * or (b) at or above 768 (large = default modal behavior)
+     * @private
+     */
+    setIsSmallScreenSize() {
+        const docElem = (document && document.documentElement) || null;
+        const browserWidth = docElem ? docElem.clientWidth : window.innerWidth;
+        const isSmallScreenSize = browserWidth <= SMALL_SCREEN_SIZE;
+        if (isSmallScreenSize !== this.isSmallScreenSize) {
+            this.isSmallScreenSize = isSmallScreenSize;
+        }
+    }
+
+    removeModalEventListeners() {
+        this.removeWindowResizeEventListener();
+        this.removeOrientationChangeListener();
+    }
+
     /**
      * When modal is being created, initialize
-     * private tracked modal state
+     * private tracked modal base/default state
+     * this is a collection of state variables
+     * that are not including modalHeader, modalBody,
+     * modalFooter
      * @private
      */
-    initState() {
+    initBaseState() {
         // setting initialRender true handles the case where modal
         // is added / removed/added back to DOM
         this.initialRender = true;
         this.autoFocusCompletedOnce = false;
-        this.windowResizeEventsBound = false;
+        this.windowResizeEventBound = false;
         this.timeoutId = 0;
         this.disableCloseButton = false;
         this.modalLabel = null;
@@ -983,24 +1105,37 @@ export default class LightningModalBase extends LightningElement {
         this.modalDescribedBy = null;
         this.showAriaLiveMessage = false;
         this.ariaLiveMessage = '';
-        this._size = 'medium';
         this.savedInertElements = [];
         this.savedActiveElement = null;
         this.isModalOpen = false;
         this.isModalTransitioningIn = false;
+        this.isModalClosing = false;
+        // browser screen size
+        this.isSmallScreenSize = null;
     }
 
-    connectedCallback() {
-        this.initState();
+    /**
+     * Reset all modal state
+     * @private
+     */
+    initModalState() {
+        this.initBaseState();
         this.initHeaderState();
         this.initBodyState();
         this.initFooterState();
     }
 
+    connectedCallback() {
+        this.initModalState();
+        // check for screen size right away
+        // not adding event listeners here,
+        // as 'resize' and 'orientation' events
+        // are utilized by modalBody, see registerBody()
+        this.setIsSmallScreenSize();
+    }
+
     disconnectedCallback() {
-        if (this.windowResizeEventsBound) {
-            this.detachBodyResizeEvents();
-        }
+        this.removeModalEventListeners();
         this.closeModal();
     }
 
@@ -1021,6 +1156,6 @@ export default class LightningModalBase extends LightningElement {
                 this.focusFirstElement();
             }
         }
-        this.updateBodyHeight();
+        this.updateModalBodyHeight();
     }
 }

package/src/lightning/modalBody/modalBody.js

@@ -114,34 +114,149 @@ export default class LightningModalBody extends LightningElement {
         return firstElem;
     }
 
+    /**
+     * Determine how much usuable screen height the modal has available
+     * @param {object} values passed from modalBase to modalBody
+     * representing height and width values of header, footer, and body
+     * @return {object} values, after adding of modalUsableHeight
+     * @private
+     */
+    calculateModalUsableHeight(values) {
+        const { backdropHeight, paddingTop, paddingBottom } = values;
+        const modalUsableHeight = backdropHeight - paddingTop - paddingBottom;
+        values.modalUsableHeight = modalUsableHeight;
+        return values;
+    }
+
+    /**
+     * Determine how much usuable height modalBody has available
+     * @param {object} values passed from modalBase to modalBody
+     * representing height and width values of header, footer, and body
+     * @return {number} calculation of modal body usable height
+     * @private
+     */
+    calculateModalBodyUsableHeight({
+        modalUsableHeight,
+        headerHeight,
+        footerHeight,
+    }) {
+        return modalUsableHeight - headerHeight - footerHeight;
+    }
+
+    /**
+     * Based on initial values, calculate min/max height style values
+     * to set on modalBody for correct display of content, and scrollability
+     * @param {object} values passed from modalBase to modalBody,
+     * @param {boolean} shouldUseFullHeight boolean to determine if full
+     * height of screen should be used
+     * representing height and width values of header, footer, and body
+     * @return {object} values, after adding of modalUsableHeight
+     * @private
+     */
+    updateModalBodyHeightValues(values, shouldUseFullHeight) {
+        const { modalBodyMinHeight } = values;
+        // first have to calculate the correct values
+        const updatedValues = this.calculateModalUsableHeight(values);
+        const modalBodyUsableHeight =
+            this.calculateModalBodyUsableHeight(updatedValues);
+        // update values with calculated values
+        values.modalBodyUsableHeight = modalBodyUsableHeight;
+        values.maxModalBodyHeightStyle = `${modalBodyUsableHeight}px`;
+        // need to adjust minHeight, to force modal to use full height
+        // of user screen
+        values.minModalBodyHeightStyle = shouldUseFullHeight
+            ? `${modalBodyUsableHeight}px`
+            : `${modalBodyMinHeight}px`;
+        return values;
+    }
+
+    /**
+     * Set modal body height style values after calculating the correcting values to assign
+     * @param {object} values Provided height, width values from handleUpdateHeight
+     * @private
+     */
+    setModalBodyHeight(values, shouldUseFullHeight) {
+        const { maxModalBodyHeightStyle, minModalBodyHeightStyle } =
+            this.updateModalBodyHeightValues(values, shouldUseFullHeight);
+        const divElem = this.contentElem;
+        const styles = {
+            maxHeight: maxModalBodyHeightStyle,
+            minHeight: minModalBodyHeightStyle,
+        };
+        // set the max and min height value on modal body wrapper div
+        Object.assign(divElem.style, styles);
+    }
+
+    /**
+     * Update values based on whether size="full" behavior should be full screen (small)
+     * or less than full screen (large)
+     * @param {Boolean} shouldUseFullHeight Whether full height of screen should be used
+     * @param {object} values Provided height, width values from handleUpdateHeight
+     * @returns {object} updatedValues based on full screen or default strategy used
+     * @private
+     */
+    updateValues(shouldUseFullHeight, values) {
+        const { headerHeight, footerHeight, backdropHeight } = values;
+        const MODAL_BODY_MIN_HEIGHT = 80;
+        // Full screen size constants
+        // positioning values of body and footer are effected
+        // by modalHeader presence (headless)
+        const PAD_TOP_FULL = 48;
+        const PAD_BOTTOM_FULL = 1;
+        // default screen behavior (original modal behavior)
+        const PAD_TOP_DEFAULT = 48;
+        const PAD_BOTTOM_DEFAULT = 80;
+        // use of Math.floor for some values returning half pixel values
+        // for example headerHeight = 505.5px
+        const updatedValues = {
+            headerHeight: Math.floor(headerHeight),
+            footerHeight: Math.floor(footerHeight),
+            backdropHeight: Math.floor(backdropHeight),
+            paddingTop: shouldUseFullHeight ? PAD_TOP_FULL : PAD_TOP_DEFAULT,
+            paddingBottom: shouldUseFullHeight
+                ? PAD_BOTTOM_FULL
+                : PAD_BOTTOM_DEFAULT,
+            modalBodyMinHeight: MODAL_BODY_MIN_HEIGHT,
+            // these last four values must first be calculated
+            // the first two values get set on modal body
+            minModalBodyHeightStyle: null,
+            maxModalBodyHeightStyle: null,
+            modalBodyUsableHeight: null,
+            modalUsableHeight: null,
+        };
+        return updatedValues;
+    }
     /**
      * Set the max-height style inline on modalBody to prevent vertical height
      * of overall modal to overflow
      * This function is passed to the parent modal as a callback
      * and will be called on first modal load, and then on window resize events
      * as long as modalBody is present
-     * @param {Object} values Representing headerHeight, footerHeight, backdropHeight
-     * @returns {object} Representing headerHeight, footerHeight, backdropHeight
+     * To support size="full" behavior (full screen modal), this flow has been updated
+     * to first determine which strategy to use, update values, then set values on modalBody
+     * @param {Object} values Representing headerHeight, footerHeight, backdropHeight,
+     * sizeSetFull, and isSmallScreenSize
      * @private
      */
-    handleUpdateHeight({ headerHeight, footerHeight, backdropHeight }) {
+    handleUpdateModalBodyHeight(values) {
         if (!this.initialRender) {
-            const paddingTop = 48; // 3rem
-            const paddingBottom = 80; // 5rem
-            const modalBodyMinHeight = 80;
-            const modalUsableHeight =
-                backdropHeight - paddingTop - paddingBottom;
-            const modalBodyUsableHeight =
-                modalUsableHeight - headerHeight - footerHeight;
-            const divElem = this.contentElem;
-            const styles = {
-                maxHeight: `${modalBodyUsableHeight}px`,
-                minHeight: `${modalBodyMinHeight}px`,
-            };
-            // set the max and min height value on modal body wrapper div
-            Object.assign(divElem.style, styles);
+            const {
+                sizeSetFull,
+                isSmallScreenSize,
+                headerHeight,
+                footerHeight,
+            } = values;
+            // update modalBody state, tracks header and footer presence
             this.headerPresent = headerHeight !== 0;
             this.footerPresent = footerHeight !== 0;
+            // now determine behavior: full screen or default
+            const shouldUseFullHeight = sizeSetFull && isSmallScreenSize;
+            const updatedValues = this.updateValues(
+                shouldUseFullHeight,
+                values
+            );
+            // set updated values based on behavior
+            this.setModalBodyHeight(updatedValues, shouldUseFullHeight);
         }
     }
 
@@ -160,7 +275,7 @@ export default class LightningModalBody extends LightningElement {
                 bodyId: this.modalContentId,
                 bodyIsPopulated: this.isDefaultSlotPopulated,
                 defaultSlotHasRendered: !this.initialSlotRender,
-                updateBodyCallback: this.handleUpdateHeight.bind(this),
+                updateBodyCallback: this.handleUpdateModalBodyHeight.bind(this),
                 unRegisterCallback: (unregisterCallback) => {
                     this.unregisterCallback = unregisterCallback;
                 },