lightning-base-components 1.14.6-alpha → 1.15.2-alpha

package/src/lightning/overlay/__docs__/overlay.md

@@ -0,0 +1,90 @@
+# Overlay
+
+> Note: This component is not exposed for use by internal or external developers.
+
+This is as low level in the overlay library as one can get. For this reason the documentation below is aimed at primarily `Lightning*` developers or those creating new overlay types. The overview examples would need much more to be fully accessible.
+
+-   Simple: Contains no wrapping HTML only a host element.
+    -   `<c-custom-overlay>`
+-   Advanced: Contains a wrapping Component. Example: `LightningModal`.
+
+## Creating a Simple Overlay
+
+```js
+import LightningOverlay from 'lightning/overlay';
+import { instanceName } from 'lightning/overlayUtils';
+
+class MyOverlay extends LightningOverlay {
+    static [instanceName] = 'my-overlay';
+
+    @api customProperty = 'Default';
+}
+```
+
+Usage for the `MyOverlay` in a custom app would like like below.
+
+```js
+import { LightningElement } from 'lwc';
+import MyOverlay from 'my/overlay';
+
+class MyApp extends LightningElement {
+    async handleClick() {
+        const result = await MyOverlay.open({
+            customProperty: 'Hello World!';
+        });
+        console.log(result);
+    }
+}
+```
+
+## Creating an Wrapping Component
+
+Other scenarios require wrapping HTML around the overlay component. Most commonly this is used to position an element. A common example is `LightningModal`, but alternatively this can be used for writing a shared `LightningMenu`.
+
+The `LightningMenuBase` component works as a wrapper.
+
+```html
+<template>
+    <ul data-slot lwc:dom="manual"></ul>
+</template>
+```
+
+```js
+
+```
+
+The `LightningMenu` now looks like...
+
+```html
+
+```
+
+```js
+
+```
+
+Usage for the `MyMenu` in a custom app would like like below.
+
+```html
+<template>
+    <button click="{handleClick}">{label}</button>
+</template>
+```
+
+```js
+import { LightningElement, api } from 'lwc';
+import MyMenu from 'my/overlay';
+
+class MyButtonMenu extends LightningElement {
+    @api label = 'Dropdown';
+
+    async handleClick(e) {
+        const result = await MyMenu.open({
+            source: e.target,
+            options: ['Item 1'];
+        });
+        // The selected item
+        console.log(result);
+    }
+}
+```

package/src/lightning/overlay/__examples__/alert/alert.html

@@ -0,0 +1,27 @@
+<template>
+    <lightning-focus-trap>
+        <section role="dialog" tabindex="-1" aria-labelledby="modal-heading-01" aria-modal="true"
+            aria-describedby="modal-content-id-1" class="slds-modal slds-fade-in-open slds-modal_small">
+            <div class="slds-modal__container">
+                <header class="slds-modal__header">
+                    <button class="slds-button slds-button_icon slds-modal__close slds-button_icon-inverse"
+                        title="Close" onclick={handleDismiss}>
+                        <svg class="slds-button__icon slds-button__icon_large" aria-hidden="true">
+                            <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
+                        </svg>
+                        <span class="slds-assistive-text">Close</span>
+                    </button>
+                    <h2 id="modal-heading-01" class="slds-modal__title slds-hyphenate">{header}</h2>
+                </header>
+                <div class="slds-modal__content slds-p-around_medium" id="modal-content-id-1">
+                    <p>{body}</p>
+                </div>
+                <footer class="slds-modal__footer">
+                    <button class="slds-button slds-button_neutral" onclick={handleCancel}>{cancelText}</button>
+                    <button class="slds-button slds-button_brand" onclick={handleOkay}>{okayText}</button>
+                </footer>
+            </div>
+        </section>
+    </lightning-focus-trap>
+    <div class="slds-backdrop slds-backdrop_open"></div>
+</template>

package/src/lightning/overlay/__examples__/alert/alert.js

@@ -0,0 +1,33 @@
+import { api } from 'lwc';
+import LightningOverlay from 'lightning/overlay';
+
+export default class OverlayAlert extends LightningOverlay {
+    @api header = 'Header';
+
+    @api body = 'Body';
+
+    @api okayText = 'Okay';
+
+    @api cancelText = 'Cancel';
+
+    handleOkay() {
+        this.close('okay');
+    }
+
+    handleCancel() {
+        this.close('cancel');
+    }
+
+    handleDismiss() {
+        this.close('dismiss');
+    }
+
+    hasFocus = false;
+    renderedCallback() {
+        if (!this.hasFocus) {
+            const close = this.template.querySelector('header > button');
+            close.focus();
+            this.hasFocus = true;
+        }
+    }
+}

package/src/lightning/overlay/__examples__/basic/basic.css

@@ -0,0 +1,7 @@
+.example {
+    margin: 0.5rem;
+    border-radius: 0.5rem;
+    background: #FFF;
+    box-shadow: 0 1px 0.25rem rgba(0, 0, 0, 0.2);
+    padding: 1rem;
+}

package/src/lightning/overlay/__examples__/basic/basic.html

@@ -0,0 +1,18 @@
+<template>
+    <div class="example">
+        <button onclick={handleConfirmModal}>Open a Confirm Modal</button> 
+        <p>Result: <code>{confirmResult}</code></p>
+    </div>
+    <div class="example">
+        <button onclick={handleConfirmAltModal}>Open a Confirm Modal Alt</button> 
+        <p>Result: <code>{confirmAltResult}</code></p>
+    </div>
+    <div class="example">
+        <button onclick={handleDemoModal}>Open a Demo Modal</button> 
+        <p>Result: <code>{demoResult}</code></p>
+    </div>
+    <div class="example">
+        <button onclick={handlePanel}>Open a Panel</button> 
+        <p>Result: <code>{panelResult}</code></p>
+    </div>
+</template>

package/src/lightning/overlay/__examples__/basic/basic.js

@@ -0,0 +1,61 @@
+import { LightningElement } from 'lwc';
+
+import OverlayAlert from 'overlay/alert';
+import OverlayDemo from 'overlay/demo';
+import OverlayPanel from 'overlay/panel';
+
+export default class OverlayBasic extends LightningElement {
+    confirmResult = 'unset';
+
+    handleConfirmModal() {
+        OverlayAlert.open({
+            header: 'Are you sure?',
+            body: 'Click cancel or okay below to get a string result.',
+        }).then((result) => {
+            this.confirmResult = result;
+        });
+    }
+
+    confirmAltResult = 'unset';
+
+    handleConfirmAltModal() {
+        OverlayAlert.open({
+            header: 'Do you like this demo?',
+            body: '...',
+            okayText: 'Yes',
+            cancelText: 'Also Yes',
+        }).then((result) => {
+            this.confirmAltResult = result;
+        });
+    }
+
+    demoResult = 'unset';
+
+    handleDemoModal() {
+        OverlayDemo.open({
+            header: 'Select an Option',
+            body: 'From the list below select an item',
+            options: [
+                { id: 1, label: 'Option 1' },
+                { id: 2, label: 'Option 2' },
+            ],
+        }).then((result) => {
+            if (result === 0) {
+                this.demoResult = 'dismiss';
+            } else {
+                this.demoResult = result;
+            }
+        });
+    }
+
+    panelResult = 'unset';
+
+    handlePanel() {
+        OverlayPanel.open({
+            header: 'Select an Option',
+            body: 'From the list below select an item',
+        }).then((result) => {
+            this.demoResult = result;
+        });
+    }
+}

package/src/lightning/overlay/__examples__/demo/demo.html

@@ -0,0 +1,29 @@
+<template>
+    <section role="dialog" tabindex="-1" aria-labelledby="modal-heading-01" aria-modal="true"
+        aria-describedby="modal-content-id-1" class="slds-modal slds-fade-in-open">
+        <div class="slds-modal__container">
+            <header class="slds-modal__header">
+                <button class="slds-button slds-button_icon slds-modal__close slds-button_icon-inverse" title="Close" onclick={handleDismiss}>
+                    <svg class="slds-button__icon slds-button__icon_large" aria-hidden="true">
+                        <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
+                    </svg>
+                    <span class="slds-assistive-text">Close</span>
+                </button>
+                <h2 id="modal-heading-01" class="slds-modal__title slds-hyphenate">{header}</h2>
+            </header>
+            <div class="slds-modal__content slds-p-around_medium" id="modal-content-id-1">
+                <p>{body}</p>
+                <ul>
+                    <template for:each={options} for:item="option">
+                        <li key={option.id}>
+                            <button onclick={handleOptionClick} data-id={option.id}>
+                                {option.label}
+                            </button>
+                        </li>
+                    </template>
+                </ul>
+            </div>
+        </div>
+    </section>
+    <div class="slds-backdrop slds-backdrop_open"></div>
+</template>

package/src/lightning/overlay/__examples__/demo/demo.js

@@ -0,0 +1,40 @@
+import { api } from 'lwc';
+
+import LightningOverlay from 'lightning/overlay';
+import OverlayAlert from 'overlay/alert';
+
+export default class OverlayDemo extends LightningOverlay {
+    @api header = 'Header';
+
+    @api body = 'Body';
+
+    @api options = [];
+
+    handleOptionClick(e) {
+        const { target } = e;
+        const id = parseInt(target.dataset.id, 10);
+        const option = this.options.find((x) => x.id === id);
+        OverlayAlert.open({
+            header: 'Are you sure?',
+            body: `You selected "${option.label}".`,
+            okayText: `Yes, ${option.label}`,
+        }).then((result) => {
+            if (result === 'okay') {
+                this.close(parseInt(target.dataset.id, 10));
+            }
+        });
+    }
+
+    handleDismiss() {
+        this.close(0);
+    }
+
+    hasFocus = false;
+    renderedCallback() {
+        if (!this.hasFocus) {
+            const close = this.template.querySelector('header > button');
+            close.focus();
+            this.hasFocus = true;
+        }
+    }
+}

package/src/lightning/overlay/__examples__/panel/panel.html

@@ -0,0 +1,17 @@
+<template>
+    <lightning-focus-trap>
+        <div class="slds-panel slds-size_medium slds-panel_docked slds-panel_docked-left slds-is-open" aria-hidden="false">
+            <div class="slds-panel__header">
+                <h2 class="slds-panel__header-title slds-text-heading_small slds-truncate" title="Panel Header">{header}</h2>
+                <button class="slds-button slds-button_icon slds-button_icon-small slds-panel__close" title="Collapse Panel Header" onclick={handleDismiss}>
+                <svg class="slds-button__icon" aria-hidden="true">
+                    <use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#close"></use>
+                </svg>
+                <span class="slds-assistive-text">Collapse Panel Header</span>
+                </button>
+            </div>
+            <div class="slds-panel__body">{body}</div>
+        </div>
+    </lightning-focus-trap>
+    <!-- <div class="slds-backdrop slds-backdrop_open"></div>-->
+</template>

package/src/lightning/overlay/__examples__/panel/panel.js

@@ -0,0 +1,21 @@
+import { api } from 'lwc';
+import LightningOverlay from 'lightning/overlay';
+
+export default class OverlayPanel extends LightningOverlay {
+    @api header = 'Header';
+
+    @api body = 'Body';
+
+    handleDismiss() {
+        this.close('dismiss');
+    }
+
+    hasFocus = false;
+    renderedCallback() {
+        if (!this.hasFocus) {
+            const close = this.template.querySelector('div > button');
+            close.focus();
+            this.hasFocus = true;
+        }
+    }
+}

package/src/lightning/overlay/overlay.html

@@ -0,0 +1,3 @@
+<template>
+    <!-- This template is overridden when the class is extended. -->
+</template>

package/src/lightning/overlay/overlay.js

@@ -0,0 +1,45 @@
+import { LightningElement, createElement, api } from 'lwc';
+import { instanceName } from 'lightning/overlayUtils';
+import OverlayContainer from 'lightning/overlayContainer';
+
+const ROOT = 'body';
+const OVERLAY_CONTAINER = 'lightning-overlay-container';
+
+function container() {
+    // eslint-disable-next-line @lwc/lwc/no-document-query
+    let element = document.querySelector(`${ROOT} > ${OVERLAY_CONTAINER}`);
+    if (!element) {
+        element = createElement(OVERLAY_CONTAINER, { is: OverlayContainer });
+        document.body.appendChild(element);
+    }
+    return element;
+}
+
+/**
+ * Extend this component for open/close apis.
+ */
+export default class LightningOverlay extends LightningElement {
+    /**
+     * Easier to debug when dynamically created.
+     */
+    static [instanceName] = 'lightning-overlay';
+
+    /**
+     * Open a modal instance
+     *
+     * @param {Object} apis Set apis directly on the modal instance
+     */
+    static open(apis) {
+        return container().push(this, apis);
+    }
+
+    /**
+     * The close api is public for testing only.
+     *
+     * @param {any} result Returned in the promise.
+     */
+    @api
+    close(result, promise) {
+        container().pop(this.template.host, result, promise);
+    }
+}

package/src/lightning/overlayContainer/overlayContainer.html

@@ -0,0 +1,3 @@
+<template>
+    <div lwc:dom="manual"></div>
+</template>

package/src/lightning/overlayContainer/overlayContainer.js

@@ -0,0 +1,138 @@
+import { LightningElement, api, createElement } from 'lwc';
+import { parent, instanceName } from 'lightning/overlayUtils';
+import {
+    addOverlay,
+    LwcOverlayType,
+    subscribeOverlay,
+} from 'lightning/overlayManager';
+
+export default class LightningOverlayContainer extends LightningElement {
+    // [{ element, parentElement, resolve }, ...]
+    stack = [];
+
+    get root() {
+        return this.template.querySelector('div');
+    }
+
+    /**
+     * Generate a new modal with params and return promise.
+     *
+     * @param {LightningModal} scope LightningOverlay extended class
+     * @param {Object} apis key value pair of apis to assign
+     */
+    @api
+    push(scope, apis) {
+        apis = apis || {};
+
+        if (typeof apis !== 'object') {
+            throw new Error('Invalid .open() or .open({}) argument.');
+        }
+        const { [instanceName]: overlayInstanceName, [parent]: overlayParent } =
+            scope;
+        const element = createElement(overlayInstanceName, { is: scope });
+
+        Object.entries(apis).forEach(([key, value]) => {
+            const keyLower = key.toLowerCase();
+            const match = keyLower.match(/^on(.+)/);
+            if (match) {
+                const eventName = match[1];
+                element.addEventListener(eventName, value);
+            } else {
+                element[key] = value;
+            }
+        });
+
+        let promise = null;
+        if (overlayParent) {
+            // Ex: extends LightningModal with wrapping LightningModalBase
+            const parentElement = createElement(overlayParent[instanceName], {
+                is: overlayParent,
+            });
+            this.root.appendChild(parentElement);
+            parentElement.defaultSlot.appendChild(element);
+            promise = new Promise((resolve) => {
+                this.stack.push({ resolve, element, parentElement });
+            });
+        } else {
+            this.root.appendChild(element);
+            promise = new Promise((resolve) => {
+                this.stack.push({ resolve, element });
+            });
+        }
+        // Aura Compatability
+        addOverlay(LwcOverlayType);
+        return promise;
+    }
+
+    /**
+     * Remove the last added popover.
+     */
+    @api
+    pop(ele, result, promise) {
+        // element = `extends LightningOverlay`
+        // parentElement = Ex: LightningModalBase
+        const { element, parentElement, resolve } = this.stack.find(
+            ({ element: e }) => e === ele
+        );
+        // Resolve immediately
+        resolve(result);
+        // Animate out. Ex: LightningModal slide up animation
+        if (promise) {
+            promise.then(() => {
+                this.removeOverlay(element, parentElement);
+            });
+        } else {
+            this.removeOverlay(element, parentElement);
+        }
+        // Remove from stack
+        this.stack = this.stack.filter(({ element: e }) => e !== ele);
+    }
+
+    /**
+     * Remove overlay (with IE11 support)
+     *
+     * @param {LightningModal} element Required
+     * @param {LightningElement} parentElement Optional
+     */
+    removeOverlay(element, parentElement) {
+        if (parentElement && parentElement.remove) {
+            parentElement.remove();
+        } else if (parentElement) {
+            parentElement.parentNode.removeChild(parentElement);
+        } else if (element.remove) {
+            element.remove();
+        } else {
+            element.parentNode.removeChild(element);
+        }
+    }
+
+    connectedCallback() {
+        // Notified anytime a overlay is added/removed
+        // zIndex assumes aura modals stack every other
+        subscribeOverlay((stack) => {
+            // LWC Overlays are always on odd zIndexes, aura even
+            let zIndex = 9001;
+            let modalCount = 0;
+
+            stack.forEach((overlayType) => {
+                if (overlayType === LwcOverlayType) {
+                    const overlay = this.root.childNodes[modalCount];
+                    if (overlay) {
+                        overlay.style.zIndex = zIndex;
+                        // ToDo: Refactor for LightningPanel
+                        overlay.style.position = 'absolute';
+                    }
+                    modalCount += 1;
+                } else {
+                    zIndex += 2;
+                }
+            });
+        });
+    }
+
+    // After this is fixed jest tests do not need clearOverlays()
+    // https://github.com/salesforce/lwc/issues/1102
+    // disconnectedCallback() {
+    //     clearOverlays();
+    // }
+}

package/src/lightning/overlayManager/overlayManager.js

@@ -0,0 +1,54 @@
+// Track order of modals opening
+const state = {
+    stack: [],
+    callback: null,
+    hasAura: false,
+};
+
+export const LwcOverlayType = 'lwc';
+export const AuraOverlayType = 'aura';
+
+function triggerCallback() {
+    // Not triggered in pure LWC environment
+    if (state.callback) {
+        state.callback(state.stack);
+    }
+}
+
+/**
+ * Add an overlay to the stack
+ */
+export function addOverlay(overlayType) {
+    // Prevent unnecessary z-index in pure LWC
+    if (overlayType === AuraOverlayType) {
+        state.hasAura = true;
+    }
+    state.stack.push(overlayType);
+    triggerCallback();
+}
+
+/**
+ * Remove overlay from the stack
+ */
+export function removeOverlay() {
+    state.stack.pop();
+    triggerCallback();
+}
+
+/**
+ * LightningOverlayContainer listener
+ *
+ * Only for LightningContainer usage
+ */
+export function subscribeOverlay(callback) {
+    state.callback = callback;
+    triggerCallback();
+}
+
+/**
+ * TEST ONLY! Clear stack and reset hasAura
+ */
+export function clearOverlays() {
+    state.stack = [];
+    state.hasAura = false;
+}

package/src/lightning/overlayUtils/overlayUtils.js

@@ -0,0 +1,17 @@
+/**
+ * Optional static parent definition on extended LightningOverlay
+ * Ex: static [parent] = CustomOverlayBase;
+ */
+export const parent = Symbol('parent');
+
+/**
+ * Optional static instanceName for CustomOverlayBase;
+ * Ex: static [instanceName] = 'custom-overlay';
+ * This makes it easier to debug in the dom.
+ */
+export const instanceName = Symbol('instanceName');
+
+/**
+ * Secure access to events
+ */
+export const secure = Symbol('secure event');

package/src/lightning/picklist/picklist.js

@@ -31,6 +31,7 @@ export default class LightningPicklist extends LightningElement {
     @api placeholder;
     @api variant;
     @api autocomplete = 'off';
+    @api suppressNoneOption;
 
     set fieldLevelHelp(value) {
         this._fieldLevelHelp = value;
@@ -86,6 +87,7 @@ export default class LightningPicklist extends LightningElement {
         // reset the flag that hides the required indicator when we have no options
         this._requiredButDisabled = false;
     }
+
     @api
     get required() {
         return this._required;
@@ -293,7 +295,10 @@ export default class LightningPicklist extends LightningElement {
         // We could have set required=false if the picklist had no options, see updateDisabledState and updateRequiredState
         const isRequiredPicklist = this.required || this._requiredButDisabled;
 
-        if (isRequiredPicklist && numberOfOptions === 1) {
+        if (
+            this.suppressNoneOption ||
+            (isRequiredPicklist && numberOfOptions === 1)
+        ) {
             return false;
         }
 

package/src/lightning/progressBar/progressBar.html

@@ -4,7 +4,8 @@
          aria-valuemax="100"
          aria-valuenow={percentValue}
          aria-busy={ariaBusy}
-         role="progressbar">
+         role="progressbar" 
+         aria-label={computeAriaLabel}>
         <span class="slds-progress-bar__value" style={computedStyle}>
             <span class="slds-assistive-text">{assistiveText}</span>
         </span>