lightning-base-components 1.15.2-alpha → 1.15.3-alpha

package/src/lightning/overlayManager/overlayManager.js

@@ -1,54 +1,404 @@
-// Track order of modals opening
+/* LightningOverlayManager
+ * - provides shared state and methods in order for
+ *   the LWC overlay system to prevent collisions with
+ *   the Aura overlay system (ui:panelManager2, ui:modal, etc)
+ * - works in conjunction with LightningOverlayContainer and the Aura
+ *   based overlay system
+ * - Originally, Aura overlays had z-index values
+ *   incrementing by 1, starting at 9001
+ *   ex: 9001, 9002, 9003, 9004
+ * - After Overlay and Modal updates, Aura overlays are
+ *   only odd z-index values, *starting at 9001*
+ *   ex: 9001, 9003, 9005, 9007
+ * - By default, LWC overlays stay the same value, *starting at 9000*
+ *   relying upon the DOM order to determine which overlay is visible
+ *   ex: 9000, 9000, 9000, 9000
+ * - When Aura AND LWC overlay systems both have active overlays present
+ *   LWC z-index values are even only z-index values
+ *   - incrementing by 1, when the previous highest overlay was an Aura overlay
+ *   - and not incrementing for each additional LWC overlay
+ *   ex 1: 9000 (LWC), 9001 (Aura), 9002 (LWC)
+ *   ex 2: 9001 (Aura), 9003 (Aura), 9004 (LWC), 9004 (LWC), 9005 (Aura)
+ */
+
+// LWC overlay stack constants
+export const LWC_OVERLAY_ENGINE = 'lwc';
+export const LWC_STARTING_ZINDEX = 9000;
+export const LWC_ZINDEX_INCREMENT = 2;
+export const LWC_ZINDEX_OFFSET = 1;
+// Known overlay types with their assigned position type
+// 'fixed' is default if not indicated
+export const LWC_OVERLAY_TYPES = {
+    'lightning-modal': { pos: 'absolute' },
+    'lightning-alert': { pos: 'absolute' },
+    'lightning-confirm': { pos: 'absolute' },
+    'lightning-prompt': { pos: 'absolute' },
+};
+// Aura overlay stack constants
+export const AURA_OVERLAY_ENGINE = 'aura';
+export const AURA_STARTING_ZINDEX = 9001;
+export const AURA_ZINDEX_INCREMENT = 2;
+export const AURA_OVERLAY_TYPES = {
+    'ui:modal': { pos: 'absolute' },
+};
+
 const state = {
+    // track order of overlays opening
+    // [{ overlayEngine: 'lwc', overlayType: 'lightning-modal' },
+    //  { overlayEngine: 'aura', overlayType: 'ui:modal', overlayDetails: { zIndex: 9001, id: '143:0' } }]
     stack: [],
+    // callback comes from LightningOverlayContainer
     callback: null,
-    hasAura: false,
+    // state.stack has mixed case
+    mixedOverlayPresent: false,
+    // aura stack details
+    auraHighestZindex: 9001,
+    // aura overlay is visible on top of stack
+    auraOverlayActive: false,
+    auraModalCount: 0,
+    auraAllOverlayCount: 0,
+    // lwc stack details
+    lwcModalCount: 0,
+    lwcOverlayCount: 0,
+    lwcAllOverlayCount: 0,
 };
 
-export const LwcOverlayType = 'lwc';
-export const AuraOverlayType = 'aura';
+/**
+ * triggerLwcContainerCallback is used to callback to the
+ * LightningOverlayContainer when an update to the shared state occurs
+ * This method isn't triggered when:
+ * (A) Only Aura overlays exists so far
+ *  ex: LightningOverlayContainer has not yet been created,
+ *  this is when state.callback gets set initially
+ * (B) No LWC based overlays present
+ *  ex: LightningOverlayContainer has been created, but the existing
+ *  Lightning-based overlays have been removed and only Aura overlays
+ *  remain.  If another LWC overlay is added later, we start using
+ *  the callback again
+ */
+function triggerLwcContainerCallback() {
+    if (state.callback && state.lwcAllOverlayCount > 0) {
+        state.callback(state);
+    }
+}
+
+/**
+ * normalizeOverlayDetails is used create consistent overlay
+ * objects before adding them to state.stack
+ * This public function is used in both LWC and Aura overlay systems
+ * Examples of LWC (even z-index) and Aura (odd z-index) overlay objects
+ * { overlayEngine: 'lwc', overlayType: 'lightning-modal' },
+ * { overlayEngine: 'lwc', overlayType: 'lightning-modal', overlayDetails: { zIndex: 9004 } }
+ * { overlayEngine: 'aura', overlayType: 'ui:modal', overlayDetails: { zIndex: 9001 } }]
+ * @param {string} overlayEngine string representing the engine type: lwc, aura
+ * @param {string} overlayType string representing the type of overlay: lightning-modal, ui:modal
+ * @param {Object} overlayDetails object representing details about overlay, currently zIndex
+ * @return {Object} combined overlay details object
+ */
+export function normalizeOverlayDetails(
+    overlayEngine,
+    overlayType,
+    overlayDetails
+) {
+    let overlayObject = {};
+    const missingRequiredValues = !overlayEngine || !overlayType;
+    const reqdValuesNotCorrectType =
+        (overlayEngine !== LWC_OVERLAY_ENGINE ||
+            overlayEngine !== AURA_OVERLAY_ENGINE) &&
+        typeof overlayType !== 'string';
+    if (missingRequiredValues || reqdValuesNotCorrectType) {
+        return null;
+    }
+    // set required values
+    overlayObject.overlayEngine = overlayEngine;
+    overlayObject.overlayType = overlayType;
+    // set optional values
+    if (overlayDetails) {
+        // acceptable values
+        const { zIndex, id, index } = overlayDetails;
+        let cleanedDetails = {};
+        if (zIndex !== undefined || zIndex !== null) {
+            // ensure that zIndex value is a number before assignment
+            const zIndexNumber = parseInt(zIndex, 10);
+            const isZIndexANumber = !Number.isNaN(zIndexNumber);
+            if (isZIndexANumber) {
+                cleanedDetails.zIndex = zIndexNumber;
+            }
+        }
+        if (id && typeof id === 'string') {
+            cleanedDetails.id = id;
+        }
+        // index is zero based index (can be 0, which is falsy)
+        if (
+            index !== undefined ||
+            (index !== null && typeof index === 'number')
+        ) {
+            cleanedDetails.index = index;
+        }
+        overlayObject.overlayDetails = cleanedDetails;
+    }
+    return overlayObject;
+}
+
+/**
+ * getOverlayStackStats is used to update and reinitialize the Aura and LWC shared
+ * overlay state immediately after overlay additions and removals occur
+ */
+function getOverlayStackStats() {
+    const stats = {
+        // init lwc stats
+        hasLwc: false,
+        lwcOverlays: 0,
+        lwcAllOverlays: 0,
+        lwcModals: 0,
+        // init aura stats
+        hasAura: false,
+        auraModals: 0,
+        auraOverlays: 0,
+        auraAllOverlays: 0,
+        auraOverlayActive: false,
+        auraHighestZIndex: null,
+    };
+    // init one time values
+    const stackLength = state.stack.length;
+
+    state.stack.forEach(
+        ({ overlayEngine, overlayType, overlayDetails }, stackIndex) => {
+            const isLwc = overlayEngine === LWC_OVERLAY_ENGINE;
+            const isAura = overlayEngine === AURA_OVERLAY_ENGINE;
+            // lwc specific details
+            if (isLwc) {
+                if (!stats.hasLwc) {
+                    stats.hasLwc = true;
+                }
+                if (overlayType) {
+                    const isModalType = !!LWC_OVERLAY_TYPES[overlayType];
+                    if (isModalType) {
+                        stats.lwcModals++;
+                    } else {
+                        stats.lwcOverlays++;
+                    }
+                    stats.lwcAllOverlays++;
+                }
+            }
+            // aura specific details
+            if (isAura) {
+                if (!stats.hasAura) {
+                    stats.hasAura = true;
+                }
+                if (overlayType) {
+                    const isModalType = !!AURA_OVERLAY_TYPES[overlayType];
+                    if (isModalType) {
+                        stats.auraModals++;
+                    } else {
+                        stats.auraOverlays++;
+                    }
+                    stats.auraAllOverlays++;
+                }
+                if (overlayDetails && overlayDetails.zIndex) {
+                    const { zIndex } = overlayDetails;
+                    const { auraHighestZIndex } = stats;
+                    const zIndexIsNumber = !isNaN(zIndex);
+                    if (
+                        zIndexIsNumber &&
+                        (!auraHighestZIndex || zIndex > auraHighestZIndex)
+                    ) {
+                        stats.auraHighestZIndex = zIndex;
+                    }
+                }
+                // check if aura overlay is last element in stack
+                // indicates aura is active
+                if (stackLength === stackIndex + 1) {
+                    stats.auraOverlayActive = true;
+                }
+            }
+        }
+    );
+    return stats;
+}
+
+/**
+ * updateStateWithStackStats is used to update and reinitialize the Aura and LWC shared
+ * overlay state immediately after overlay additions and removals occur
+ */
+function updateStateWithStackStats(stats) {
+    if (!stats) {
+        return;
+    }
+
+    // update Aura state with collected stats
+    if (stats.hasAura) {
+        // aura settings
+        state.auraModalCount = stats.auraModals;
+        state.auraOverlayCount = stats.auraOverlays;
+        state.auraAllOverlayCount = stats.auraAllOverlays;
+        state.auraOverlayActive = stats.auraOverlayActive;
+        if (stats.auraHighestZIndex) {
+            state.auraHighestZindex = stats.auraHighestZIndex;
+        }
+        // or reset Aura state
+    } else {
+        initAuraOverlayState();
+    }
 
-function triggerCallback() {
-    // Not triggered in pure LWC environment
-    if (state.callback) {
-        state.callback(state.stack);
+    // update LWC state with collected stats
+    if (stats.hasLwc) {
+        // lwc settings
+        state.lwcModalCount = stats.lwcModalCount;
+        state.lwcOverlayCount = stats.lwcOverlays;
+        state.lwcAllOverlayCount = stats.lwcAllOverlays;
+        // or reset LWC state
+    } else {
+        initLwcOverlayState();
     }
+    // update shared Aura+LWC state
+    state.mixedOverlayPresent = stats.hasLwc && stats.hasAura;
 }
 
 /**
- * Add an overlay to the stack
+ * updateSharedOverlayState is used to trigger updates to shared overlay state
  */
-export function addOverlay(overlayType) {
-    // Prevent unnecessary z-index in pure LWC
-    if (overlayType === AuraOverlayType) {
-        state.hasAura = true;
+function updateSharedOverlayState() {
+    if (state.stack.length === 0) {
+        // don't reset all state, just aura and lwc state individually
+        // in order to avoid removing callback
+        // callback is set only once, when overlayContainer is opened
+        initAuraOverlayState();
+        initLwcOverlayState();
+    } else {
+        const stats = getOverlayStackStats();
+        updateStateWithStackStats(stats);
+    }
+}
+
+function cleanOverlayDetails(details) {
+    let cleanedDetails = {};
+    const detailsKeys = {
+        id: 'string',
+        zIndex: 'number',
+        index: 'number',
+    };
+    if (!details || typeof details !== 'object') {
+        return cleanedDetails;
     }
-    state.stack.push(overlayType);
-    triggerCallback();
+    Object.entries(details).forEach(([key, value]) => {
+        if (detailsKeys[key] && typeof value === detailsKeys[key]) {
+            cleanedDetails[key] = value;
+        }
+    });
+    return cleanedDetails;
 }
 
 /**
- * Remove overlay from the stack
+ * addOverlayToSharedState is used to push an overlay object
+ * into shared overlay state: state.stack
+ * the object should first be processed by normalizeOverlayDetails
+ * This public function is called from LWC and Aura overlay systems
+ * @param {Object} overlayObject object representing details about the overlay to add
  */
-export function removeOverlay() {
-    state.stack.pop();
-    triggerCallback();
+export function addOverlayToSharedState(overlayObject) {
+    let { overlayEngine, overlayType, overlayDetails } = overlayObject;
+    const missingValues = !overlayObject || !overlayEngine || !overlayType;
+    const standardEngines =
+        overlayEngine === LWC_OVERLAY_ENGINE ||
+        overlayEngine === AURA_OVERLAY_ENGINE;
+    // disallow unknown additions
+    if (missingValues || !standardEngines) {
+        return;
+    }
+    overlayDetails = cleanOverlayDetails(overlayDetails);
+
+    // after checks, add overlay object
+    state.stack.push({ overlayEngine, overlayType, overlayDetails });
+    // first update shared overlay state
+    updateSharedOverlayState();
+    // then trigger callback to overlayContainer
+    triggerLwcContainerCallback();
 }
 
 /**
- * LightningOverlayContainer listener
- *
- * Only for LightningContainer usage
+ * removeOverlayFromSharedState is used to remove an overlay object
+ * from shared overlay state: state.stack
+ * This public function is called from LWC and Aura overlay systems
+ * @param {Object} overlayObject object representing details about the overlay to remove
  */
-export function subscribeOverlay(callback) {
+export function removeOverlayFromSharedState(overlayObject) {
+    const stackLength = state.stack.length;
+    const { overlayEngine, overlayDetails } = overlayObject;
+    const missingValues = !overlayObject || !overlayEngine;
+    const standardEngines =
+        overlayEngine === LWC_OVERLAY_ENGINE ||
+        overlayEngine === AURA_OVERLAY_ENGINE;
+    let overlayId = null;
+    let indexToRemove = null;
+    // disallow unknown removals
+    if (stackLength === 0 || missingValues || !standardEngines) {
+        return;
+    }
+
+    if (overlayDetails && overlayDetails.id) {
+        overlayId = overlayDetails.id;
+    }
+    // Use overlay ID to find correct overlay and remove
+    // IDs may be GUID (LBC overlays) or Aura globalId (Aura overlays)
+    if (overlayId) {
+        // loop from end to the front of the stack
+        // determine which item to remove
+        for (let index = stackLength; index--; index >= 0) {
+            const {
+                overlayDetails: { id: oId },
+            } = state.stack[index];
+            if (oId && oId === overlayId) {
+                indexToRemove = index;
+                break;
+            }
+        }
+    }
+
+    if (indexToRemove !== null) {
+        state.stack.splice(indexToRemove, 1);
+        // then update shared overlay state
+        updateSharedOverlayState();
+        // then trigger callback to overlayContainer
+        triggerLwcContainerCallback();
+    }
+}
+
+/**
+ * subscribeOverlay is utilized to set the state.callback function
+ * initially for LightningOverlayContainer (LOC) usage.
+ * NOTE: This function is exported and is supported for use ONLY by LOC
+ * When LOC is initialized, this callback is set, so that later updates to
+ * Aura and LWC overlay state occur, updates to LWC overlay z-index behavior
+ * can be made
+ * @param {boolean} shouldCall value to determine if call should be made
+ * @param {Function} callback function to call when an update occurs
+ */
+export function subscribeOverlay(shouldCall, callback) {
+    // store once for later usage
     state.callback = callback;
-    triggerCallback();
+    if (shouldCall) {
+        triggerLwcContainerCallback();
+    }
+}
+
+/**
+ * initLwcOverlayState resets only LWC overlay state values
+ */
+function initLwcOverlayState() {
+    state.lwcModalCount = 0;
+    state.lwcOverlayCount = 0;
+    state.lwcAllOverlayCount = 0;
 }
 
 /**
- * TEST ONLY! Clear stack and reset hasAura
+ * initAuraOverlayState resets only Aura overlay state values
  */
-export function clearOverlays() {
-    state.stack = [];
-    state.hasAura = false;
+function initAuraOverlayState() {
+    state.auraModalCount = 0;
+    state.auraOverlayCount = 0;
+    state.auraAllOverlayCount = 0;
+    state.auraHighestZindex = AURA_STARTING_ZINDEX;
+    state.auraOverlayActive = false;
+    state.auraOverlayPresent = false;
 }

package/src/lightning/overlayManager/overlayManager.js-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="xmlns=http://soap.sforce.com/2006/04/metadata">
+    <isExposed>true</isExposed>
+    <support>BETA</support>
+</LightningComponentBundle>

package/src/lightning/primitiveCellFactory/primitiveCellFactory.js

@@ -325,17 +325,7 @@ export default class PrivateCellFactory extends PrimitiveDatatableCell {
     }
 
     get dateValue() {
-        // new Date(null) returns new Date(0), which is not expected.
-        // for undefined, '', or any other invalid values, formatted-date-time
-        // just displays ''
-        if (this.value === null) {
-            return '';
-        }
-
-        // this is temporary, formatted-date-time should accept
-        // date time string formats like '2017-03-01 08:45:12Z'
-        // it's accepting only timestamp and Date objects
-        return new Date(this.value);
+        return this.value;
     }
 
     get computedDateLocalDay() {

package/src/lightning/prompt/__docs__/prompt.md

@@ -9,7 +9,7 @@ This example creates a prompt modal with a header, message, and two buttons. If
 ```html
 <!-- c/myApp.html -->
 <template>
-    <lightning-button onclick="{handlePromptClick}" label="Open Prompt Modal">
+    <lightning-button onclick={handlePromptClick} label="Open Prompt Modal">
     </lightning-button>
 </template>
 ```
@@ -64,7 +64,7 @@ Code using `LightningPrompt` can be tested by mocking the `LightningPrompt.open(
 The example below uses a button to open a prompt dialog and sets the result in a template.
 
 ```html
-<button data-button onclick="{handleClick}">Open Prompt</button>
+<button data-button onclick={handleClick}>Open Prompt</button>
 <div data-result>{result}</div>
 ```
 

package/src/lightning/select/select.html

@@ -5,7 +5,7 @@
         </template>
         {label}
     </label>
-    <lightning-helptext content={fieldLevelHelp} if:true={fieldLevelHelp}></lightning-helptext>
+    <lightning-helptext content={fieldLevelHelp} if:true={fieldLevelHelp} alternative-text={helptextAlternativeText}></lightning-helptext>
 
     <div class="slds-form-element__control">
         <div class="slds-select_container">

package/src/lightning/select/select.js

@@ -1,6 +1,7 @@
 import labelRequired from '@salesforce/label/LightningControl.required';
+import labelHelpTextAlternativeText from '@salesforce/label/LightningInput.helptextAlternativeText';
 import { api, LightningElement, track } from 'lwc';
-import { classSet } from 'lightning/utils';
+import { classSet, formatLabel } from 'lightning/utils';
 import {
     classListMutation,
     getRealDOMId,
@@ -18,6 +19,7 @@ import {
 
 const i18n = {
     required: labelRequired,
+    helpTextAlternativeText: labelHelpTextAlternativeText,
 };
 
 export default class LightningSelect extends LightningElement {
@@ -403,4 +405,8 @@ export default class LightningSelect extends LightningElement {
         }
         return this.selectElement.value;
     }
+
+    get helptextAlternativeText() {
+        return formatLabel(i18n.helpTextAlternativeText, this.label);
+    }
 }

package/src/lightning/tabBar/tabBar.html

@@ -6,7 +6,7 @@
         <template for:each={_allTabs} for:item="tab">
             <template if:true={tab.visible}>
                 <li data-tab key={tab.value} class={tab.class} onclick={handleTabClick}
-                    title={tab.title} role="presentation" data-label={tab.label} data-tab-value={tab.value}>
+                    title={tab.title} role="presentation" data-label={tab.label} data-tab-value={tab.value} data-target-selection-name={tab.targetSelectionName}>
                     <a class={tab.linkClass}
                         data-tab-value={tab.value}
                         data-label={tab.label}
@@ -43,6 +43,7 @@
             <li data-overflow class={computedOverflowClass} style={computedOverflowVisibility}>
                 <lightning-button-menu variant="bare"
                     alternative-text={i18n.moreAlternativeText}
+                    data-target-reveals={targetReveals}
                     title={i18n.moreTitle}
                     onselect={handleOverflowSelect}
                     icon-name="utility:chevrondown"
@@ -50,7 +51,7 @@
                     menu-alignment="right">
                     <template for:each={_allTabs} for:item="tab">
                         <template if:false={tab.visible}>
-                            <lightning-menu-item key={tab.value} label={tab.label} value={tab.value}></lightning-menu-item>
+                            <lightning-menu-item key={tab.value} label={tab.label} value={tab.value} data-target-selection-name={tab.targetSelectionName}></lightning-menu-item>
                         </template>
                     </template>
                 </lightning-button-menu>

package/src/lightning/tabBar/tabBar.js

@@ -17,6 +17,7 @@ const i18n = {
 };
 
 const RECOMPUTE_OVERFLOW_THRESHOLD_PX = 30;
+const TARGET_SELECTION_NAME_SUFFIX = 'Tab';
 
 export default class LightningTabBar extends LightningElement {
     @api disableOverflow = false;
@@ -99,6 +100,10 @@ export default class LightningTabBar extends LightningElement {
                 endIconName: tab.endIconName,
                 endIconAlternativeText: tab.endIconAlternativeText,
                 showErrorIndicator: tab.showErrorIndicator,
+                targetSelectionName: tab.value
+                    ? encodeURIComponent(tab.value) +
+                      TARGET_SELECTION_NAME_SUFFIX
+                    : '',
             };
         });
 
@@ -439,4 +444,14 @@ export default class LightningTabBar extends LightningElement {
 
         this._queueSynchronizeA11 = true;
     }
+
+    get targetReveals() {
+        const hiddenTargets = [];
+        this._allTabs.forEach((tab) => {
+            if (!tab.visible && tab.targetSelectionName) {
+                hiddenTargets.push(tab.targetSelectionName);
+            }
+        });
+        return hiddenTargets.join(',');
+    }
 }

package/src/lightning/textarea/textarea.html

@@ -5,7 +5,7 @@
         </template>
         {label}
     </label>
-    <lightning-helptext if:true={fieldLevelHelp} content={fieldLevelHelp}></lightning-helptext>
+    <lightning-helptext if:true={fieldLevelHelp} content={fieldLevelHelp} alternative-text={helptextAlternativeText}></lightning-helptext>
     <div class="slds-form-element__control slds-grow textarea-container">
         <textarea id="input" class="slds-textarea"
             aria-describedby={computedUniqueHelpElementId}

package/src/lightning/textarea/textarea.js

@@ -1,8 +1,9 @@
 /* eslint-disable @lwc/lwc/no-api-reassignments */
 
 import labelRequired from '@salesforce/label/LightningControl.required';
+import labelHelpTextAlternativeText from '@salesforce/label/LightningInput.helptextAlternativeText';
 import { LightningElement, api, track } from 'lwc';
-import { classSet } from 'lightning/utils';
+import { classSet, formatLabel } from 'lightning/utils';
 import {
     normalizeBoolean,
     synchronizeAttrs,
@@ -23,6 +24,7 @@ import { TouchScroller } from 'lightning/touchScrollLibrary';
 
 const i18n = {
     required: labelRequired,
+    helpTextAlternativeText: labelHelpTextAlternativeText,
 };
 
 /**
@@ -483,6 +485,10 @@ export default class LightningTextarea extends LightningElement {
     get computedAriaInvalid() {
         return computeAriaInvalid(this._helpMessage, this.value);
     }
+
+    get helptextAlternativeText() {
+        return formatLabel(i18n.helpTextAlternativeText, this.label);
+    }
 }
 
 LightningTextarea.interopMap = {

package/src/lightning/timepicker/timepicker.html

@@ -6,7 +6,7 @@
             </template>
             {label}
         </label>
-        <lightning-helptext if:true={fieldLevelHelp} content={fieldLevelHelp}></lightning-helptext>
+        <lightning-helptext if:true={fieldLevelHelp} content={fieldLevelHelp} alternative-text={helptextAlternativeText}></lightning-helptext>
     </template>
     <div class="slds-form-element__control">
         <lightning-base-combobox