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

package/src/lightning/toastContainer/toastContainer.html

@@ -0,0 +1,9 @@
+<template>
+    <lightning-focus-trap>
+        <div data-toast-container
+            lwc:dom='manual'
+            class={containerClass}
+            onprivatetoastregister={handleToastRegister}>
+        </div>
+    </lightning-focus-trap>
+</template>

package/src/lightning/toastContainer/toastContainer.js

@@ -0,0 +1,471 @@
+import { api, createElement } from 'lwc';
+import { classSet } from 'lightning/utils';
+import {
+    instanceName,
+    properties,
+    requiredProperties,
+} from 'lightning/overlayUtils';
+import { SHOW_TOAST_EVENT_NAME } from 'lightning/showToastEvent';
+import { normalizeNumber, normalizeString } from 'lightning/utilsPrivate';
+import { createF6Controller } from 'lightning/f6Controller';
+import {
+    getElementWithFocus,
+    returnFocusToElement,
+} from 'lightning/focusUtils';
+import LightningOverlay from 'lightning/overlay';
+
+const CONSOLE_ERROR_MESSAGES = {
+    MISSING_PROPERTY: 'Unable to show toast, missing toast property\'s "{0}"',
+    MISSING_CONFIG: 'Unable to show toast, missing toast config.',
+    MISSING_TOAST: 'Unable to show toast, missing toast class reference.',
+};
+
+const TOAST_POSITION = {
+    TOP_CENTER: 'top-center',
+    TOP_LEFT: 'top-left',
+    TOP_RIGHT: 'top-right',
+    BOTTOM_LEFT: 'bottom-left',
+    BOTTOM_CENTER: 'bottom-center',
+    BOTTOM_RIGHT: 'bottom-right',
+};
+
+const CONTAINER_POSITION = {
+    ABSOLUTE: 'absolute',
+    FIXED: 'fixed',
+};
+
+const DEFAULT_CONTAINER_POSITION = CONTAINER_POSITION.FIXED;
+const DEFAULT_MAX_TOASTS_SHOWN = 3;
+const DEFAULT_TOAST_POSITION = TOAST_POSITION.TOP_CENTER;
+const MAX_NUM_GLOBAL_TOAST_CONTAINER = 1;
+const globalContainer = [];
+
+const getGlobalContainer = () => {
+    return globalContainer[0];
+};
+
+const configure = (toastContainer, config) => {
+    if (!toastContainer) {
+        return;
+    }
+    const { containerPosition, maxToasts, toastPosition } = config;
+    if (maxToasts) {
+        toastContainer.maxToasts = maxToasts;
+    }
+    if (containerPosition) {
+        toastContainer.containerPosition = containerPosition;
+    }
+    if (toastPosition) {
+        toastContainer.toastPosition = toastPosition;
+    }
+};
+
+const CLOSE_EVENT_NAME = 'close';
+
+export default class ToastContainer extends LightningOverlay {
+    static [instanceName] = 'lightning-toast-container';
+    static [properties] = ['containerPosition', 'maxToasts', 'toastPosition'];
+
+    // container position
+    _containerPosition = CONTAINER_POSITION.FIXED;
+    // max number of toasts shown at a time
+    _maxToasts = DEFAULT_MAX_TOASTS_SHOWN;
+    // toast position
+    _toastPosition = TOAST_POSITION.TOP_CENTER;
+    // store the currently displayed toasts
+    _displayToasts = [];
+    // store awaiting toasts and their config
+    _queue = [];
+    // reference to the handler function for ShowToastEvent
+    _showToastHandler;
+
+    /**
+     * css class for focus trap which is used to control toast container position and the toasts' position.
+     * @returns {string} - CSS classes of the toast as a string
+     */
+    get containerClass() {
+        const toastPosition = this._toastPosition.split('-');
+        return classSet(
+            `slds-grid slds-grid_vertical-reverse toast-container ${toastPosition[0]} ${toastPosition[1]}`
+        ).add({
+            'slds-is-fixed':
+                this.containerPosition === CONTAINER_POSITION.FIXED,
+            'slds-is-absolute':
+                this.containerPosition === CONTAINER_POSITION.ABSOLUTE,
+        });
+    }
+
+    /**
+     * toast container position
+     * controls the position of the toast container div related to the containing element
+     * options: 'absolute', 'fixed'
+     * @returns {string}
+     * @default 'fixed'
+     */
+    @api get containerPosition() {
+        return this._containerPosition;
+    }
+
+    set containerPosition(value) {
+        this._containerPosition = normalizeString(value, {
+            fallbackValue: DEFAULT_CONTAINER_POSITION,
+            validValues: [
+                CONTAINER_POSITION.ABSOLUTE,
+                CONTAINER_POSITION.FIXED,
+            ],
+        });
+    }
+
+    /**
+     * this attribute controls the maximum number of toast components shown at a given time
+     * if user enters a zero or negative number, the value will default to 3
+     * @returns {number}
+     * @default 3
+     */
+    @api get maxToasts() {
+        return this._maxToasts;
+    }
+
+    set maxToasts(value) {
+        this._maxToasts = normalizeNumber(value, {
+            fallbackValue: DEFAULT_MAX_TOASTS_SHOWN,
+            minValue: 1,
+        });
+    }
+
+    /**
+     * return the div element which hosts the toast components
+     * @return {HTMLElement}
+     */
+    get root() {
+        return this.template.querySelector('[data-toast-container]');
+    }
+
+    /**
+     * toast position
+     * controls the final position of toast components shown in the toast container
+     * options: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'
+     * @returns {string}
+     * @default 'top-center'
+     */
+    @api get toastPosition() {
+        return this._toastPosition;
+    }
+
+    set toastPosition(value) {
+        this._toastPosition = normalizeString(value, {
+            fallbackValue: DEFAULT_TOAST_POSITION,
+            validValues: [
+                TOAST_POSITION.TOP_LEFT,
+                TOAST_POSITION.TOP_CENTER,
+                TOAST_POSITION.TOP_RIGHT,
+                TOAST_POSITION.BOTTOM_LEFT,
+                TOAST_POSITION.BOTTOM_CENTER,
+                TOAST_POSITION.BOTTOM_RIGHT,
+            ],
+        });
+    }
+
+    /**
+     * override function to "close" the toast container (i.e. remove it from the DOM)
+     */
+    @api close() {
+        // reset before closing the container
+        this.reset();
+        super.close();
+    }
+
+    // private functions
+    connectedCallback() {
+        if (globalContainer.length < MAX_NUM_GLOBAL_TOAST_CONTAINER) {
+            this._showToastHandler = this.handleShowToast.bind(this);
+            document.body.addEventListener(
+                SHOW_TOAST_EVENT_NAME,
+                this._showToastHandler
+            );
+            globalContainer.push(this);
+            this.setAriaHidden();
+            createF6Controller();
+        }
+    }
+
+    disconnectedCallback() {
+        this.close();
+    }
+
+    /**
+     * assign allowed property values to an HTMLElement
+     * @param {array} allowedProperties array of property names which can have value assigned
+     * @param {HTMLElement} element element to assign attribute values
+     * @param {object} config a map of attribute -> value
+     */
+    assignValuesToElement(allowedProperties, element, config) {
+        const elementProperties = allowedProperties || [];
+        Object.entries(config).forEach(([key, value]) => {
+            const keyLower = key.toLowerCase();
+            const match = keyLower.match(/^on(.+)/);
+            if (match) {
+                const eventName = match[1];
+                element.addEventListener(eventName, value);
+            } else {
+                // assign value only to the allowed properties
+                if (elementProperties.indexOf(key) > -1) {
+                    element[key] = value;
+                }
+            }
+        });
+    }
+
+    /**
+     * handler function of show toast event
+     * @param {Event} event ShowToastEvent
+     */
+    handleShowToast(event) {
+        event.stopPropagation();
+        const params = this.validateToastParameters(event);
+        if (!params) {
+            return;
+        }
+        // enqueue the toast and config
+        this._queue.push(params);
+        // show toast if any
+        this.showNextToast();
+    }
+
+    /**
+     * handler function of [toast] close event
+     * @param {HTMLElement} element the closed toast component
+     */
+    handleToastClose(closedToast, event) {
+        let toastIndex = -1;
+        let source;
+
+        // remove the closed toast from the DOM
+        this._displayToasts = this._displayToasts.filter(
+            ({ toastElement, sourceElement }, index) => {
+                if (toastElement === closedToast) {
+                    toastIndex = index;
+                    source = sourceElement;
+                    return false;
+                }
+                return true;
+            }
+        );
+
+        this.root.removeChild(closedToast);
+        // show next toast if any
+        this.showNextToast();
+
+        // if the closed toast does not have focus, do nothing
+        if (!event.detail.isFocused) {
+            return;
+        }
+        // closed toast also is the focused toast, thus move focus to the next toast if any
+        const nextToast =
+            toastIndex > -1 &&
+            toastIndex < this._displayToasts.length &&
+            this._displayToasts[toastIndex].toastElement;
+        if (nextToast && nextToast.isConnected) {
+            nextToast.focus();
+            return;
+        }
+        // no toast to focus, return focus to the source component which triggered the toast which was closed.
+        returnFocusToElement(source);
+    }
+
+    /**
+     * handler function for registering a toast to the container
+     * @param {CustomEvent} event
+     */
+    handleToastRegister(event) {
+        const { target: toastElement, detail } = event;
+        const { unregisterCallback } = detail;
+        const toastCloseHandler = this.handleToastClose.bind(
+            this,
+            toastElement
+        );
+
+        // add the close event listener to the toast element
+        toastElement.addEventListener(CLOSE_EVENT_NAME, toastCloseHandler);
+        unregisterCallback(() => {
+            // remove the close event listener when unregistering the toast from the container
+            toastElement.removeEventListener(
+                CLOSE_EVENT_NAME,
+                toastCloseHandler
+            );
+        });
+    }
+
+    /**
+     * set aria-hidden attribute to true if there is no toasts
+     */
+    setAriaHidden() {
+        const ariaHiddenValueToSet = !this._displayToasts.length;
+        if (this.template.host.ariaHidden !== ariaHiddenValueToSet) {
+            this.template.host.ariaHidden = ariaHiddenValueToSet;
+        }
+    }
+
+    /**
+     * show the next toast component(s) if any
+     */
+    showNextToast() {
+        while (
+            this._queue.length &&
+            this._displayToasts.length < this._maxToasts
+        ) {
+            const { toast, config, sourceElement } = this._queue.shift();
+            // create the toast component
+            const {
+                [instanceName]: toastInstanceName,
+                [properties]: toastProperties,
+            } = toast;
+            const toastElement = createElement(toastInstanceName, {
+                is: toast,
+            });
+
+            this.assignValuesToElement(toastProperties, toastElement, config);
+            this._displayToasts.push({ toastElement, sourceElement });
+            this.root.appendChild(toastElement);
+        }
+        this.setAriaHidden();
+    }
+
+    /**
+     * reset function to be called if the container is no longer used or detached from the DOM
+     */
+    reset() {
+        if (this._showToastHandler) {
+            document.body.removeEventListener(
+                SHOW_TOAST_EVENT_NAME,
+                this._showToastHandler
+            );
+            this._showToastHandler = null;
+        }
+        globalContainer.splice(0, globalContainer.length);
+        this._containerPosition = CONTAINER_POSITION.FIXED;
+        this._maxToasts = DEFAULT_MAX_TOASTS_SHOWN;
+        this._toastPosition = TOAST_POSITION.TOP_CENTER;
+        // remove toasts if any
+        this.root.childNodes.forEach((node) => {
+            this.root.removeChild(node);
+        });
+        this._displayToasts = [];
+        this._queue = [];
+    }
+
+    /**
+     * retrieve toast config constructed in platformShowToastEvent
+     * @param {object} toastAttributes toast config defined by platformShowToastEvent
+     */
+    retrievePlatformShowToastConfig(toastAttributes, detail) {
+        const { title, message, messageData, mode, type } = toastAttributes;
+        const toast = detail.toast || undefined;
+        return {
+            config: {
+                label: title,
+                message,
+                messageLinks: messageData,
+                mode,
+                variant: type,
+            },
+            toast,
+            source: undefined,
+        };
+    }
+
+    /**
+     * retrieve toast config constructed in Toast.show()
+     * @param {*} detail
+     * @returns
+     */
+    retrieveShowToastConfig(detail) {
+        // this toast config is created from Toast.show() i.e. lightningShowToastEvent
+        const config = { ...detail };
+        const toast = detail.toast || undefined;
+        const source = detail.source || undefined;
+        delete config.toast;
+        delete config.source;
+        return { config, toast, source };
+    }
+
+    /**
+     * validate function to check if config, toast, source have the necessary attributes needed
+     */
+    validateToastParameters(event) {
+        const sourceElement = getElementWithFocus();
+        const { toastAttributes, detail } = event;
+        let convertedConfig;
+        // convert the platformShowToastEvent's toast config to the new format consumed by Toast
+        // this handles the case when platformShowToastEvent is dispatched
+        if (toastAttributes && detail) {
+            convertedConfig = this.retrievePlatformShowToastConfig(
+                toastAttributes,
+                detail
+            );
+        } else if (detail) {
+            // this toast config is created from Toast.show() i.e. lightningShowToastEvent
+            convertedConfig = this.retrieveShowToastConfig(detail);
+        }
+
+        if (!convertedConfig) {
+            console.error(CONSOLE_ERROR_MESSAGES.MISSING_CONFIG);
+            return undefined;
+        }
+
+        const { config, toast, source } = convertedConfig;
+        if (!toast) {
+            console.error(
+                'Unable to show toast, missing toast class reference.'
+            );
+            return undefined;
+        }
+        const { [requiredProperties]: toastRequiredProps } = toast;
+        if (toastRequiredProps) {
+            const missingPropertyName = toastRequiredProps.find((property) => {
+                if (
+                    !Object.prototype.hasOwnProperty.call(config, property) ||
+                    !config[property]
+                ) {
+                    return property;
+                }
+                return undefined;
+            });
+            if (missingPropertyName) {
+                console.error(
+                    CONSOLE_ERROR_MESSAGES.MISSING_PROPERTY.replace(
+                        '{0}',
+                        missingPropertyName
+                    )
+                );
+                return undefined;
+            }
+        }
+        return { config, toast, source, sourceElement };
+    }
+
+    /**
+     * create a page level toast container, if it does not exist or return the existing one
+     * @param {object} config map of attributes -> value to set the toast container's public attributes
+     * @returns {ToastContainer} instance of the toast container
+     */
+    static instance(config = {}) {
+        // create a instance if container does not exist
+        if (globalContainer.length < MAX_NUM_GLOBAL_TOAST_CONTAINER) {
+            ToastContainer.open(config);
+            return getGlobalContainer();
+        }
+        let toastContainer = getGlobalContainer();
+        if (!toastContainer.isConnected) {
+            // remove the container if it does not attached to the DOM anymore
+            toastContainer.close();
+            toastContainer = null;
+            // create a new one and returns it
+            ToastContainer.open(config);
+            return getGlobalContainer();
+        }
+        // set container attribute if already exists
+        configure(toastContainer, config);
+        return toastContainer;
+    }
+}

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

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

package/src/lightning/tooltipLibrary/tooltipLibrary.js

@@ -33,6 +33,8 @@ function buildResizeObserver(callback) {
  */
 let CACHED_BUBBLE_ELEMENT;
 
+let activeTooltip;
+
 function getCachedBubbleElement() {
     if (!CACHED_BUBBLE_ELEMENT) {
         CACHED_BUBBLE_ELEMENT = createElement('lightning-primitive-bubble', {
@@ -41,6 +43,7 @@ function getCachedBubbleElement() {
         CACHED_BUBBLE_ELEMENT.contentId = BUBBLE_ID;
         CACHED_BUBBLE_ELEMENT.style.position = 'absolute';
         CACHED_BUBBLE_ELEMENT.style.minWidth = '75px';
+        CACHED_BUBBLE_ELEMENT.disableVisibilityChangeOnLeave = true;
     }
 
     return CACHED_BUBBLE_ELEMENT;
@@ -86,6 +89,7 @@ export class Tooltip {
     _initialized = false;
     _visible = false;
     _isFocusEvent = false;
+    _initialResize = true;
 
     _config = {};
 
@@ -123,6 +127,7 @@ export class Tooltip {
         }
         this.handleDocumentTouch = this.handleDocumentTouch.bind(this);
         this.handleEscape = this.handleEscape.bind(this);
+        this.hide = this.hide.bind(this);
     }
 
     /**
@@ -167,6 +172,7 @@ export class Tooltip {
 
     addInfoListeners() {
         const target = this._target();
+
         if (!this._initialized && target) {
             ['mouseenter', 'focus'].forEach((name) =>
                 target.addEventListener(name, () => this.show())
@@ -181,6 +187,13 @@ export class Tooltip {
     }
 
     hideIfNotSelfCover(event) {
+        /*
+            If the tooltip is already hidden, do not try to hide it. The primitive bubble is shared and we don't want to
+            hide a tooltip that does not belong to this instance.
+        */
+        if (!this._visible) {
+            return;
+        }
         if (event.type === 'mouseleave' && event.clientX && event.clientY) {
             // In any chance, if mouseleave is caused by tooltip itself, it would means
             // tooltip cover the target which mostly caused by dynamic resize of tooltip by CSS or JS.
@@ -209,6 +222,7 @@ export class Tooltip {
 
     addToggleListeners() {
         const target = this._target();
+
         if (!this._initialized && target) {
             target.addEventListener('touchstart', (e) => {
                 e.stopPropagation();
@@ -222,10 +236,11 @@ export class Tooltip {
                     this.hideIfNotSelfCover(event)
                 )
             );
+
             target.addEventListener('keydown', (event) => {
                 if (event.keyCode === 13 && !this._visible) {
                     this.toggle();
-                } else {
+                } else if (this._visible) {
                     this.hide();
                 }
             });
@@ -242,7 +257,29 @@ export class Tooltip {
         if (!this._resizeObserver) {
             this._resizeObserver = buildResizeObserver(() => {
                 if (this._visible && this._autoPosition) {
-                    this.startPositioning();
+                    const tooltip = this._element();
+                    /**
+                     * There are some cases where the tooltip hide event does not trigger. For example,
+                     * if a tab triggers a focus event on element A and then a pointer triggers mouseenter on element B.
+                     * In this case, the content of the cached tooltip does not match the value of this Tooltip object and
+                     * we know that this tooltip should be hidden. See @W-12512833
+                     */
+                    if (activeTooltip !== this) {
+                        this.hide(false);
+                        return;
+                    }
+                    this.startPositioning().then(() => {
+                        /*
+                         * Once positioning is complete, add the listener to react when the mouse leaves the tooltip.
+                         * Cannot be added before, or the tooltip will flicker and hide if the mouse is in the same
+                         * position as the tooltip and the user tabs onto the tooltip. This cannot be managed inside
+                         * the primitive-bubble, or the ResizeObserver will not be reset correctly.
+                         */
+                        if (this._initialResize) {
+                            tooltip.addEventListener('mouseleave', this.hide);
+                            this._initialResize = false;
+                        }
+                    });
                 }
             });
         }
@@ -250,15 +287,29 @@ export class Tooltip {
     }
 
     show(ev) {
-        if (this._disabled) {
+        if (this._disabled || this._visible) {
             return;
         }
+
+        if (activeTooltip && activeTooltip !== this && activeTooltip._visible) {
+            activeTooltip.hide(false);
+        }
+        activeTooltip = this;
+
         this._isFocusEvent = ev && (ev.type === 'focus' ? true : false);
 
         this._visible = true;
+        this._initialResize = true;
         const tooltip = this._element();
-        tooltip.visible = this._visible;
-        tooltip.content = this._value;
+
+        /*
+            When tabbing, populating the tooltip and making it visible too early can lead to bad interactions
+            when the mouse is hovering over a tooltip. W-12559092
+        */
+        if (!this._isFocusEvent) {
+            tooltip.content = this._value;
+            tooltip.visible = this._visible;
+        }
 
         this.startPositioning();
         document.addEventListener('keydown', this.handleEscape);
@@ -266,17 +317,28 @@ export class Tooltip {
         this.resizeObserver.observe(tooltip);
     }
 
-    hide() {
+    /**
+     * Hides the tooltip
+     *
+     * @param {*} hideBubble the primitive bubble is a shared instance, it may not be desirable to hide it
+     * if the current tooltip is no longer using it.
+     */
+    hide(hideBubble = true) {
         this._visible = false;
         const tooltip = this._element();
-        tooltip.visible = this._visible;
+
+        if (hideBubble) {
+            tooltip.visible = this._visible;
+        }
 
         this.stopPositioning();
 
         document.removeEventListener('touchstart', this.handleDocumentTouch);
         document.removeEventListener('keydown', this.handleEscape);
+        tooltip.removeEventListener('mouseleave', this.hide);
 
         this.resizeObserver.unobserve(tooltip);
+        activeTooltip = null;
     }
 
     toggle() {
@@ -323,7 +385,7 @@ export class Tooltip {
         const targetBox = this._target().getBoundingClientRect();
         const padLeft = targetBox.width * 0.5 - NUBBIN_OFFSET;
 
-        this._autoPosition
+        return this._autoPosition
             .start({
                 target: this._target,
                 element: this._element,

package/src/lightning/treeGrid/__docs__/treeGrid.md

@@ -36,8 +36,11 @@ include:
 -   Selecting of rows
 -   Text wrapping and clipping
 
-A checkbox is displayed by default in the first column. The `hide-checkbox-column` attribute
-removes the checkbox.
+This component provides styling for up to 20 nested levels. For tree grids that require more than 20 nested levels,
+build your own component.
+
+A checkbox is displayed by default in the first column. Set the `hide-checkbox-column` attribute
+to `true` to remove the checkbox.
 
 Initialize your tree grid data using the `data`, `columns`, and `key-field` attributes
 and define their values in JavaScript. Note that `key-field` is required.
@@ -46,7 +49,8 @@ This example creates a tree grid with 5 columns, where the
 first column displays a checkbox for row selection. Selecting the checkbox
 enables you to select the entire row of data and triggers the `onrowselection`
 event handler. The `expanded-rows` attribute is optional, and expands nested
-items on a row when provided.
+items on a row when provided. Selecting a row using the checkbox does not select
+the rows nested below it.
 
 The example includes two buttons whose handlers call `lightning-tree-grid` methods
 to collapse all rows and to show which rows are expanded.