lightning-base-components 1.16.3-alpha → 1.16.5-alpha

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>

package/src/lightning/modalFooter/modalFooter.js

@@ -0,0 +1,161 @@
+import { LightningElement } from 'lwc';
+import { classSet } from 'lightning/utils';
+import { findAllTabbableElements, filterTooltips } from 'lightning/focusUtils';
+
+// SLDS Modal Footer classes
+const footerClass = 'slds-modal__footer';
+const hideClass = 'slds-hide';
+// selectors
+const footerSelector = `.${footerClass}`;
+const footerSlotSelector = '[data-footer-slot]';
+
+/**
+ * The modal footer component to display footer content in lightning modal.
+ * */
+export default class LightningModalFooter extends LightningElement {
+    // tracked private state
+    initialRender = true;
+    initialSlotRender = true;
+    hideFooter = false;
+    unregisterCallback = null;
+
+    /**
+     * 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();
+        this.hideFooter = !this.isDefaultSlotPopulated;
+    }
+
+    /**
+     * Gets the CSS classes applicable to the modal footer element.
+     * Hidden classes are set when the footer is hidden
+     * @returns {string} CSS class applied to modal footer
+     * @private
+     */
+    get footerCssClasses() {
+        const classes = classSet(footerClass);
+        classes.add({
+            [hideClass]: this.hideFooter,
+        });
+        return classes.toString();
+    }
+
+    /**
+     * Get the height of outer wrapper of modal footer
+     * @returns {number} represents a height value in pixels
+     * @private
+     */
+    get footerHeight() {
+        const divElem = this.template.querySelector(footerSelector);
+        const footerRect = divElem ? divElem.getBoundingClientRect() : {};
+        const { height } = footerRect;
+        return height || 0;
+    }
+
+    /**
+     * Get an element reference to the modal footer's slot element
+     * @returns {(HTMLElement|null)}
+     * @private
+     */
+    get defaultSlotElement() {
+        return this.template.querySelector(footerSlotSelector);
+    }
+
+    /**
+     * 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 true;
+    }
+
+    /**
+     * Get first tabbable element within modalFooter's slot, if exists
+     * This is passed to parent in order to possibly be used for autoFocus
+     * @returns {(HTMLElement|null)}
+     * @private
+     */
+    get firstTabbableElement() {
+        let firstElem = null;
+        if (this.isDefaultSlotPopulated) {
+            const filteredElements = filterTooltips(
+                findAllTabbableElements(this.defaultSlotElement)
+            );
+            if (filteredElements.length > 0) {
+                firstElem = filteredElements[0];
+            }
+        }
+        return firstElem;
+    }
+
+    /**
+     * Register modalFooter with modal parent, including callbacks to
+     * unregister the modal footer
+     * this will get called multiple times over component lifecycle
+     * @type {CustomEvent}
+     * @private
+     */
+    registerWithParent() {
+        const evtRegister = new CustomEvent('privatemodalfooterregister', {
+            bubbles: true,
+            composed: true,
+            detail: {
+                footerHeight: this.footerHeight,
+                defaultSlotIsPopulated: this.isDefaultSlotPopulated,
+                defaultSlotHasRendered: !this.initialSlotRender,
+                firstTabbableElemRef: this.firstTabbableElement,
+                unRegisterCallback: (unregisterCallback) => {
+                    this.unregisterCallback = unregisterCallback;
+                },
+            },
+        });
+        this.dispatchEvent(evtRegister);
+    }
+
+    /**
+     * When modal footer is being created, initialize
+     * private tracked modal footer state
+     * This is need because modal footer can be added back to
+     * the DOM, after being removed, and need to re-initialize state values
+     * @private
+     */
+    initState() {
+        this.initialRender = true;
+        this.initialSlotRender = true;
+        this.hideFooter = false;
+        this.unregisterCallback = null;
+    }
+
+    connectedCallback() {
+        // handle case where modalFooter is added/removed/added to DOM
+        // so registerWithParent gets called
+        this.initState();
+    }
+
+    disconnectedCallback() {
+        if (this.unregisterCallback) {
+            this.unregisterCallback();
+        }
+    }
+
+    renderedCallback() {
+        if (this.initialRender) {
+            this.registerWithParent();
+            this.initialRender = false;
+        }
+        this.hideFooter = !this.isDefaultSlotPopulated;
+    }
+}

package/src/lightning/modalFooter/modalFooter.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/modalHeader/__docs__/modalHeader.md

@@ -0,0 +1,64 @@
+The `lightning-modal-header` component displays header text in a panel at the top of a modal dialog.
+Use of a header is optional, but when you provide a header you must specify the header text with the `label` attribute. 
+
+If you don't use the `lightning-modal-header` component, you must set a label
+in the modal you create by extending `LightningModal`. A label is required for accessibility.
+
+The modal components render in the order they appear in the template. Place the `lightning-modal-header` 
+component before the `lightning-modal-body` component in the template.
+
+`lightning-modal-header` supports optional tagline text, which displays in smaller text below the heading. Enclose the
+tagline text directly in the `lightning-modal-header` component, no HTML tag or attribute is needed. You can include links with `<a>`
+tags, which are the only HTML elements permitted. If the header text is too long to fit on one line, it wraps in the modal header. 
+
+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">
+        Tagline can be descriptive content with <a href="https://www.example.com">links</a> and can wrap to multiple lines.
+    </lightning-modal-header>
+    <lightning-modal-body>
+        <!-- modal content specified in LightningModal component -->
+    </lightning-modal-body>
+</template>
+```
+#### Component Styling
+
+`lightning-modal-header` 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-header label="My Modal" class="my-modal-header">
+   
+</lightning-modal-header>
+```
+
+Use SLDS styling hooks to customize the component's styles. Several `--sds-c-modal-header-*` and `--sds-c-modal-heading-*` hooks 
+enable you to customize the header. 
+
+For example, specify the background color on the button using the `sds-c-modal-header-color-background` custom property.
+
+```css
+.my-modal-header {
+    --sds-c-modal-header-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
+
+When you use `lightning-modal-header` in your modal, the rendered modal provides an `aria-labelledby` attribute set to the ID of the header element.
+If you don't use `lightning-modal-header`, the accessible label is provided using `aria-label` set to the label you provide in the modal.
+
+When the modal opens, focus goes to the first interactive element in the modal. If the header includes a link in tagline text, the link
+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/modalHeader/modalHeader.html

@@ -0,0 +1,16 @@
+ <template>
+    <div class="slds-modal__header">
+        <template if:true={label}>
+            <h1
+                id="modal-label"
+                class="slds-modal__title slds-hyphenate"
+                tabindex="-1"
+                data-label
+            >{label}</h1>
+        </template>
+        <slot
+            data-default-slot
+            onslotchange={handleDefaultSlotChange}
+        ></slot>
+    </div>
+</template>