lightning-base-components 1.16.3-alpha → 1.16.4-alpha

package/src/lightning/modal/__examples__disabled/footless/footless.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/modal/__examples__disabled/footless/footless.html

@@ -0,0 +1,9 @@
+<template>
+    <div class="example">
+        <button
+            onclick={handleDemoModal}
+            aria-haspopup="modal"
+        >Open the Footless Modal</button> 
+        <p>Result: <code>{demoResult}</code></p>
+    </div>
+</template>

package/src/lightning/modal/__examples__disabled/footless/footless.js

@@ -0,0 +1,19 @@
+import { LightningElement } from 'lwc';
+import ModalDemoFootless from 'modal/demofootless';
+
+export default class ModalFootless extends LightningElement {
+    demoResult = 'unset';
+
+    handleDemoModal() {
+        ModalDemoFootless.open({
+            // LightningModal
+            size: 'small',
+        }).then((result) => {
+            if (result === null) {
+                this.demoResult = 'dismiss';
+            } else {
+                this.demoResult = result;
+            }
+        });
+    }
+}

package/src/lightning/modal/__examples__disabled/headless/headless.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/modal/__examples__disabled/headless/headless.html

@@ -0,0 +1,9 @@
+<template>
+    <div class="example">
+        <button
+            onclick={handleDemoModal}
+            aria-haspopup="modal"
+        >Open the Headless Modal</button> 
+        <p>Result: <code>{demoResult}</code></p>
+    </div>
+</template>

package/src/lightning/modal/__examples__disabled/headless/headless.js

@@ -0,0 +1,27 @@
+import { LightningElement } from 'lwc';
+import ModalDemoHeadless from 'modal/demoheadless';
+
+export default class ModalAllChildren extends LightningElement {
+    demoResult = 'unset';
+
+    handleDemoModal() {
+        ModalDemoHeadless.open({
+            // LightningModal
+            size: 'small',
+            label: 'Modal Header',
+            // ModalDemo
+            body: 'Select an option:',
+            options: [
+                { id: 1, variant: 'neutral', label: 'Option 1' },
+                { id: 2, variant: 'neutral', label: 'Option 2' },
+                { id: 3, variant: 'brand', label: 'Main Option' },
+            ],
+        }).then((result) => {
+            if (result === null) {
+                this.demoResult = 'dismiss';
+            } else {
+                this.demoResult = result;
+            }
+        });
+    }
+}

package/src/lightning/modal/modal.html

@@ -0,0 +1,3 @@
+<template>
+    <!-- LightningModalBase -->
+</template>

package/src/lightning/modal/modal.js

@@ -0,0 +1,93 @@
+import { api } from 'lwc';
+import LightningOverlay from 'lightning/overlay';
+import { parent, instanceName, secure } from 'lightning/overlayUtils';
+import LightningModalBase from 'lightning/modalBase';
+import { normalizeBoolean } from 'lightning/utilsPrivate';
+
+/**
+ * Extend this component to create a message modal overlayed on the current app window.
+ */
+export default class LightningModal extends LightningOverlay {
+    static [parent] = LightningModalBase;
+    static [instanceName] = 'lightning-modal';
+
+    // private tracked state
+    _disableClose = false;
+
+    // public api
+    /**
+     * How much of the viewport width the modal uses. Supported values are small, medium, or large.
+     * @type {string}
+     * @default medium
+     */
+    @api size = 'medium';
+
+    /**
+     * Sets the modal's title and assistive device label.
+     * @type {string}
+     * @required true
+     * @default false
+     */
+    @api label = '';
+
+    /**
+     * Sets the modal's accessible description.
+     * @type {boolean}
+     * @default false
+     */
+    @api description = '';
+
+    /**
+     * Prevents closing the modal by normal means like the ESC key, the close button, or `.close()`.
+     * @type {boolean}
+     * @default false
+     */
+    @api
+    get disableClose() {
+        return this._disableClose;
+    }
+
+    set disableClose(value) {
+        const currentDisableClose = this._disableClose;
+        this._disableClose = normalizeBoolean(value);
+        // if there is a change, dispatch private event for modalBase
+        if (currentDisableClose !== this._disableClose) {
+            this.dispatchEvent(
+                new CustomEvent('privatedisableclosebutton', {
+                    detail: {
+                        disableClose: this._disableClose,
+                        [secure]: true,
+                    },
+                    bubbles: true,
+                })
+            );
+        }
+    }
+
+    @api
+    close(result) {
+        // Prevent close() private event until disableClose removed
+        if (!this.disableClose) {
+            const promise = new Promise((resolve) => {
+                this.dispatchEvent(
+                    new CustomEvent('privateclose', {
+                        detail: {
+                            resolve,
+                            [secure]: true,
+                        },
+                        bubbles: true,
+                    })
+                );
+            });
+            super.close(result, promise);
+        } else {
+            // Intentionally console error when devs have not disabled elements
+            // when disableClose has been set true
+            let errorMsg =
+                'LightningModal - Any interactions (buttons, processes, etc) that call modal.close() should be ';
+            errorMsg += '(a) disabled, while disableClose api set true, and ';
+            errorMsg += '(b) re-enabled, when disableClose set false';
+            console.error(errorMsg);
+        }
+    }
+}

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

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

package/src/lightning/modalBody/__docs__/modalBody.md

@@ -0,0 +1,61 @@
+The `lightning-modal-body` component renders the content of a modal.
+
+The modal components render in the order they appear in the template. Place the `lightning-modal-body` 
+component after `lightning-modal-header` and before `lightning-modal-footer` components, if you're providing them. 
+
+This sample code shows the expected order of the modal components. The modal content is
+created in a separate component extended from `LightningModal`. See 
+[Lightning Web Components Developer Guide](docs/component-library/documentation/en/lwc/)
+
+```html
+<!-- my/modalDialog.html -->
+<template>
+    <lightning-modal-header label="My Modal Heading">
+        Tagline content with <a href="https://salesforce.com">Salesforce.com link</a>
+    </lightning-modal-header>
+    <lightning-modal-body>
+        <!-- modal content specified in LightningModal component -->
+        { content }
+        <!-- alternatively, add content here directly -->
+    </lightning-modal-body>
+    <lightning-modal-footer>
+        Footer Content
+    </lightning-modal-footer>
+</template>
+```
+
+You can nest content in `lightning-modal-body` or 
+`lightning-modal-body` automatically scrolls the modal's content when necessary. 
+The modal's maximum height is calculated to prevent the content from exceeding the screen height,
+and scroll bars are automatically added.
+#### Component Styling
+
+`lightning-modal-body` implements the [modals](https://www.lightningdesignsystem.com/components/modals/) blueprint in the Salesforce Lightning Design System (SLDS).
+
+To apply custom styling, use the `:host` selector or define a custom class using the `class` attribute.
+
+```html
+<lightning-modal-body class="my-modal-body">
+   
+</lightning-modal-body>
+```
+
+Use SLDS styling hooks to customize the component's styles. The `--sds-c-modal-content-*` hooks 
+enable you to customize the background color and text color of the modal body. 
+
+For example, specify the background color on the modal using the `sds-c-modal-content-color-background` custom property.
+
+```css
+.my-modal-body {
+    --sds-c-modal-content-color-background: LightBlue;
+}
+```
+
+See the modal blueprint's [Styling Hooks Overview](https://www.lightningdesignsystem.com/components/modals/#Styling-Hooks-Overview) for a list of CSS custom properties.
+
+For more information, see [Style Components Using Lightning Design System Styling Hooks](docs/component-library/documentation/lwc/lwc.create_components_css_custom_properties) in the Lightning Web Components Developer Guide.
+
+#### Accessibility
+
+See [Lightning Web Components Developer Guide](docs/component-library/documentation/en/lwc/) for more information about accessibility in modals.
+

package/src/lightning/modalBody/modalBody.html

@@ -0,0 +1,13 @@
+<template>
+    <div
+        id="modal-content"
+        class={modalBodyCssClasses}
+        data-content-container
+        onprivatescrollablecontainer={handleScrollableContainerRepositionEvent}
+    >
+        <slot
+            data-default-slot
+            onslotchange={handleDefaultSlotChange}
+        ></slot>
+    </div>
+</template>

package/src/lightning/modalBody/modalBody.js

@@ -0,0 +1,203 @@
+import { LightningElement } from 'lwc';
+import { classSet } from 'lightning/utils';
+import { getRealDOMId } from 'lightning/utilsPrivate';
+import { findAllTabbableElements, filterTooltips } from 'lightning/focusUtils';
+
+/**
+ * The modal body component to display main content area in lightning modal.
+ * */
+export default class LightningModalBody extends LightningElement {
+    // private tracked state
+    initialRender = true;
+    initialSlotRender = true;
+    unregisterCallback = null;
+    headerPresent = false;
+    footerPresent = false;
+
+    /**
+     * Handle the default slot change event
+     * Always register with parent every slot change
+     * @private
+     */
+    handleDefaultSlotChange() {
+        // Set this once so that parent can know slot has rendered
+        if (this.initialSlotRender) {
+            this.initialSlotRender = false;
+        }
+        this.registerWithParent();
+    }
+
+    /**
+     * Handle the 'privatescrollablecontainer from positionLibrary.js
+     * This repositions elements with overlays that use positionLibrary
+     * like helptext, combobox, etc
+     * @private
+     */
+    handleScrollableContainerRepositionEvent(event) {
+        const { callback: repositionCallback } = event.detail;
+        repositionCallback(event.composedPath());
+        event.stopPropagation();
+    }
+
+    /**
+     * Gets the CSS classes applicable to the modal body element.
+     * Hidden classes included for sibling components
+     * @return {string} CSS class applied to modal body
+     * @private
+     */
+    get modalBodyCssClasses() {
+        const classes = classSet('slds-modal__content slds-p-around_medium');
+        classes.add({
+            'slds-modal__content_headless': !this.headerPresent,
+            'slds-modal__content_footless': !this.footerPresent,
+        });
+        return classes.toString();
+    }
+
+    /**
+     * Get a reference to the modal body content area wrapper div element
+     * @returns {(HTMLElement|null)} Outer wrapper for modal body
+     * @private
+     */
+    get contentElem() {
+        return this.template.querySelector('[data-content-container]');
+    }
+
+    /**
+     * Get the main content div element assigned ID value
+     * @type {(string|null)}
+     * @private
+     */
+    get modalContentId() {
+        return getRealDOMId(this.contentElem);
+    }
+
+    /**
+     * Get the default slot element for modal body component
+     * @returns {(HTMLElement|null)}
+     * @private
+     */
+    get defaultSlotElement() {
+        return this.template.querySelector('[data-default-slot]');
+    }
+
+    /**
+     * Determine whether the default slot is populated
+     * @returns {boolean}
+     * @private
+     */
+    get isDefaultSlotPopulated() {
+        const slotElement = this.defaultSlotElement;
+        if (slotElement && slotElement.assignedNodes) {
+            return slotElement.assignedNodes().length > 0;
+        }
+        return false;
+    }
+
+    /**
+     * Get first tabbable element within modalBody, if exists
+     * This is passed to parent in order to autoFocus
+     * @return {(HTMLElement|null)}
+     * @private
+     */
+    get firstTabbableElement() {
+        let firstElem = null;
+        if (this.isDefaultSlotPopulated) {
+            const tabbableElements = findAllTabbableElements(
+                this.defaultSlotElement
+            );
+            const filteredElements = filterTooltips(tabbableElements);
+            if (filteredElements.length > 0) {
+                firstElem = filteredElements[0];
+            }
+        }
+        return firstElem;
+    }
+
+    /**
+     * 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
+     * @private
+     */
+    handleUpdateHeight({ headerHeight, footerHeight, backdropHeight }) {
+        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);
+            this.headerPresent = headerHeight !== 0;
+            this.footerPresent = footerHeight !== 0;
+        }
+    }
+
+    /**
+     * Register modalBody with modal parent, including callbacks to
+     * unregister the modal body, and update the modal body height
+     * this will get called multiple times over component lifecycle
+     * @type {CustomEvent}
+     * @private
+     */
+    registerWithParent() {
+        const evtRegister = new CustomEvent('privatemodalbodyregister', {
+            bubbles: true,
+            composed: true,
+            detail: {
+                bodyId: this.modalContentId,
+                bodyIsPopulated: this.isDefaultSlotPopulated,
+                defaultSlotHasRendered: !this.initialSlotRender,
+                updateBodyCallback: this.handleUpdateHeight.bind(this),
+                unRegisterCallback: (unregisterCallback) => {
+                    this.unregisterCallback = unregisterCallback;
+                },
+                firstTabbableElemRef: this.firstTabbableElement,
+            },
+        });
+        this.dispatchEvent(evtRegister);
+    }
+
+    /**
+     * When modal body is being created, initialize
+     * private tracked modal body state
+     * @private
+     */
+    initState() {
+        this.initialRender = true;
+        this.initialSlotRender = true;
+        this.unregisterCallback = null;
+        this.headerPresent = false;
+        this.footerPresent = false;
+    }
+
+    connectedCallback() {
+        // handle case where modalBody is added/removed/re-added to DOM
+        this.initState();
+    }
+
+    disconnectedCallback() {
+        if (this.unregisterCallback) {
+            this.unregisterCallback();
+        }
+    }
+
+    renderedCallback() {
+        if (this.initialRender) {
+            this.registerWithParent();
+            this.initialRender = false;
+        }
+    }
+}

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

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

package/src/lightning/modalFooter/__docs__/modalFooter.md

@@ -0,0 +1,72 @@
+The `lightning-modal-footer` component creates a footer at the bottom of a modal dialog. 
+Use of a footer is optional.
+
+The modal components render in the order they appear in the template.
+Place the `lightning-modal-footer` component after the `lightning-modal-body` component.
+
+This sample code shows the expected order of the modal components. The modal content is
+created in a separate component extended from `LightningModal`. See 
+[Lightning Web Components Developer Guide](docs/component-library/documentation/en/lwc/)
+
+This sample's `lightning-modal-footer` includes two `lightning-button` components, 
+but you can also use `<button>` elements.
+
+```html
+<!-- my/modalDialog.html -->
+<template>
+    <lightning-modal-header label="My Modal">
+    </lightning-modal-header>
+    <lightning-modal-body>
+        <!-- modal content specified in LightningModal component -->
+    </lightning-modal-body>
+    <lightning-modal-footer>
+        <lightning-button
+            class="slds-button"
+            variant="neutral"
+            label="Cancel"
+            onclick={handleDismiss}
+        ></lightning-button>                
+        <lightning-button
+            class="slds-button slds-m-left_x-small"
+            variant="brand"
+            label="Save"
+        ></lightning-button>
+    </lightning-modal-footer>
+</template>
+```
+#### Component Styling
+
+`lightning-modal-footer` implements the [modals](https://www.lightningdesignsystem.com/components/modals/) blueprint in the Salesforce Lightning Design System (SLDS).
+
+To apply custom styling, use the `:host` selector or define a custom class using the `class` attribute.
+
+```html
+<lightning-modal-footer class="my-modal-footer">
+   
+</lightning-modal-footer>
+```
+
+Use SLDS styling hooks to customize the component's styles. Several `--sds-c-modal-footer-*` hooks 
+enable you to customize the footer spacing, background color, and text color. 
+
+For example, specify the background color on the footer using the `sds-c-modal-footer-color-background` custom property.
+
+```css
+.my-modal-footer {
+    --sds-c-modal-footer-color-background: LightGray;
+}
+```
+
+See the modal blueprint's [Styling Hooks Overview](https://www.lightningdesignsystem.com/components/modals/#Styling-Hooks-Overview) for a list of CSS custom properties.
+
+For more information, see [Style Components Using Lightning Design System Styling Hooks](docs/component-library/documentation/lwc/lwc.create_components_css_custom_properties) in the Lightning Web Components Developer Guide.
+
+#### Accessibility
+
+If you add buttons to the footer, you can use the accessibility attributes described in [`lightning-button`](bundle/lightning-button/documentation).
+
+When the modal opens, focus goes to the first interactive element in the modal. If there are no links in the header or any interactive elements
+in the modal body, the first footer button gets initial focus. 
+
+See [Lightning Web Components Developer Guide](docs/component-library/documentation/en/lwc/) for more information about accessibility in modals.
+

package/src/lightning/modalFooter/modalFooter.html

@@ -0,0 +1,8 @@
+<template>
+    <div class={footerCssClasses}>
+        <slot
+            data-footer-slot
+            onslotchange={handleDefaultSlotChange}
+        ></slot>
+    </div>
+</template>