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

package/src/lightning/mediaUtils/__docs__/mediaUtils.md

@@ -0,0 +1,87 @@
+The `mediaUtils` library contains utility functions that can be used by an LWC developer to process media files. The following functions are contained in the `mediaUtils` library:
+
+## processImage
+
+You can use `processImage` function to resize and compress image files. To use this function, simply import it in your LWC first:
+```
+import { processImage } from 'lightning/mediaUtils';
+```
+
+You can then call this function by passing in an input image and a set of options to be used to process the input image, as further described below. It will return a promise that will resolve to a `Blob` object containing the output image data.
+
+#### Parameters
+
+* `input`: Defines the input image, which can either be a `File` or `Blob` object
+* `options`: An object that defines the options to be used when processing the input image. It is an optional parameter containing a number of flags. If this parameter or any of its flags are omitted, default values will be used as further described below.
+    * `resizeMode`: A string that determines how the image will be resized. It can contain one of the below values
+        * `fill`: This is default. The image will be resized to fill the target dimension. If necessary, the image will be stretched or squished to fit.
+        * `contain`: The image keeps its aspect ratio but will be resized to fit within the target dimension.
+        * `none`: The image will not be resized and will retain its original dimension.
+    * `resizeStrategy`: A string that determines how to resize the image. If `resizeMode` is set to `none` this flag will be ignored.
+        * `reduce`: Only resize if the image is larger than the target size (smaller images won't be resized).
+        * `enlarge`: Only resize if the image is smaller than the target size (larger images won't be resized).
+        * `always`: This is default. Always resize the image to the target size regardless of the original image dimensions.
+    * `targetWidth`: The target width when resizing an image. If omitted, defaults to the original image width. If `resizeMode` is set to `none` this flag will be ignored.
+    * `targetHeight`: The target height when resizing an image. If omitted, defaults to the original image height. If `resizeMode` is set to `none` this flag will be ignored.
+    * `compressionQuality`: A number between 0-1 that determines the compression quality. If omitted then the browser/webview picks a default value as it sees fit. Note that this parameter will be considered as a suggested compression quality, however the browser/webview may choose to override this value if it deems it necessary. For example if the value is larger than 1 or if it is considered to be too small by the browser/webview, then it will override the value to something that it deems more appropriate.
+    * `imageSmoothingEnabled`: A boolean that determines whether scaled images are smoothed or not. Defaults to `true`.
+    * `preserveTransparency`: A boolean that determines whether the transparency info of the input image (if any) should be preserved or not. Defaults to `true`. If the input image is a GIF/PNG and this flag is set to `true` the output image will be a PNG. For all other cases the output will be a JPEG.
+    * `backgroundColor`: A string that defines a CSS color as described [here](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Defaults to `white`. When `preserveTransparency` is set to `false`, the output image will have its background set to this color before the input image is resized and drawn on top.
+
+#### Example
+
+As an example, consider the scenario where you would like to upload files to a Salesforce org using a [`lightning-input`](bundle/lightning-input/documentation) component. In your HTML code, you may have:
+```
+.
+.
+.
+<lightning-input
+    type="file"
+    label="Select Files to Upload"
+    accept="image/*"
+    multiple
+    onchange={handleFilesSelected}>
+</lightning-input>
+.
+.
+.
+```
+
+In your Javascript file, you can now use `processImage` from `mediaUtils`, for example to reduce image sizes and hence reduce the bandwidth used to upload the images, as illustrated below:
+```
+import { processImage } from 'lightning/mediaUtils';
+.
+.
+.
+async handleFilesSelected(event) {
+    try {
+        // Using the below options we resize images to a maximum of 2048x2048 pixels
+        // while containing their aspect ratio. By setting 'resizeStrategy' to 'reduce'
+        // we ensure that only images that have either width or height larger than
+        // 2048 pixels will be resized. Moreover, we've chosen not to preserve transparency
+        // in the input images and instead convert transparent pixels to white. Lastly,
+        // the images will be compressed with a 75% compression quality to reduce their byte size.
+        let options = {
+            resizeMode: 'contain',
+            resizeStrategy: 'reduce',
+            targetWidth: 2048,
+            targetHeight: 2048,
+            compressionQuality: 0.75,
+            imageSmoothingEnabled: true,
+            preserveTransparency: false,
+            backgroundColor: 'white'
+        };
+
+        for (const file of event.target.files) {
+            let blob = await processImage(file, options);
+            // here we can upload the data contained in the blob that is returned by processImage
+        }
+    } 
+    catch (error) {
+        console.error("ERROR: ", error)
+    }
+}
+.
+.
+.
+```

package/src/lightning/mediaUtils/mediaUtils.js

@@ -0,0 +1,321 @@
+/**
+ * Given an input image (as a file handle or a blob) this method will resize
+ * and compress the image according to the specified options, and return a Blob
+ * object containing the resulting image data.
+ *
+ * @param {(File|Blob)} input the input image
+ * @param {Object} [options] the options to be used when processing the image.
+ *        It is an optional parameter containing a number of flags. If this
+ *        parameter or any of its flags are omitted, default values will be
+ *        used as described below.
+ *
+ *        resizeMode: A string that determines how the image will be resized.
+ *           fill: This is default. The image will be resized to fill the target dimension.
+ *                 If necessary, the image will be stretched or squished to fit.
+ *           contain: The image keeps its aspect ratio but will be resized to fit within the target dimension.
+ *           none: The image will not be resized and will retain its original dimension.
+ *
+ *        resizeStrategy: A string that determines how to resize the image. If resizeMode is set to 'none' this flag will be ignored.
+ *           reduce: Only resize if the image is larger than the target size (smaller images won't be resized)
+ *           enlarge: Only resize if the image is smaller than the target size (larger images won't be resized)
+ *           always: This is default. Always resize the image to the target size regardless of the original image dimensions.
+ *
+ *        targetWidth: The target width when resizing an image. If omitted, defaults to the original image width.
+ *                  If resizeMode is set to 'none' this flag will be ignored.
+ *
+ *        targetHeight: The target height when resizing an image. If omitted, defaults to the original image height.
+ *                  If resizeMode is set to 'none' this flag will be ignored.
+ *
+ *        compressionQuality: A number between 0-1 that determines the compression quality. If omitted then the browser/webview  picks
+ *                            a default value as it sees fit. Note that this parameter will be considered as a suggested/desired
+ *                            compression quality however the browser/webview may choose to override this value if it deems it necessary.
+ *                            For example if the value is larger than 1 or if it is considered to be too small by the browser/webview,
+ *                            then it will override the value to something that it deems more appropriate.
+ *
+ *        imageSmoothingEnabled: A boolean that determines whether scaled images are smoothed or not. Defaults to true.
+ *
+ *        preserveTransparency: A boolean that determines whether the transparency info of the input image (if any) should
+ *                              be preserved or not. Defaults to true. If the input image is a GIF/PNG and this flag is set to true
+ *                              the output image will be a PNG. For all other cases the output will be a JPEG.
+ *
+ *        backgroundColor: A string that defines a CSS color as described here: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+ *                         Defaults to white. When preserveTransparency is set to false, the output image will have its background set to
+ *                         this color before the input image is resized and drawn on top.
+ *
+ * @returns {Promise} a promise that resolves to a Blob object containing the output image data.
+ */
+export function processImage(input, options = null) {
+    return readInputData(input)
+        .then((dataURL) => loadInputDataIntoImage(dataURL))
+        .then((image) => resizeAndCompressImage(image, input.type, options));
+}
+
+function readInputData(input) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onloadend = (event) => {
+            resolve(event.target.result);
+        };
+
+        reader.onerror = () => {
+            reject(new Error('Unable to read the input data.'));
+        };
+
+        try {
+            reader.readAsDataURL(input);
+        } catch (err) {
+            reject(new Error('Unable to read the input data.'));
+        }
+    });
+}
+
+function loadInputDataIntoImage(dataUrl) {
+    return new Promise((resolve, reject) => {
+        let image = new Image();
+
+        image.onload = function () {
+            resolve(image);
+        };
+
+        image.onerror = function () {
+            reject(new Error('Unable to load the input as an image.'));
+        };
+
+        image.src = dataUrl;
+    });
+}
+
+function getResizeMode(defaultValue, options) {
+    let resizeMode = defaultValue;
+    if (options && options.resizeMode) {
+        resizeMode = `${options.resizeMode}`.toLowerCase().trim();
+    }
+
+    if (
+        resizeMode === 'fill' ||
+        resizeMode === 'contain' ||
+        resizeMode === 'none'
+    ) {
+        return resizeMode;
+    }
+
+    throw new Error('Invalid parameter value for resizeMode.');
+}
+
+function getResizeStrategy(defaultValue, options) {
+    let resizeStrategy = defaultValue;
+    if (options && options.resizeStrategy) {
+        resizeStrategy = `${options.resizeStrategy}`.toLowerCase().trim();
+    }
+
+    if (
+        resizeStrategy === 'reduce' ||
+        resizeStrategy === 'enlarge' ||
+        resizeStrategy === 'always'
+    ) {
+        return resizeStrategy;
+    }
+
+    throw new Error('Invalid parameter value for resizeStrategy.');
+}
+
+function getTargetWidth(defaultValue, options) {
+    let targetWidth = defaultValue;
+
+    if (options && options.targetWidth) {
+        targetWidth = parseFloat(options.targetWidth);
+        if (isNaN(targetWidth)) {
+            throw new Error('Invalid parameter value for targetWidth.');
+        }
+    }
+
+    return Math.round(targetWidth);
+}
+
+function getTargetHeight(defaultValue, options) {
+    let targetHeight = defaultValue;
+
+    if (options && options.targetHeight) {
+        targetHeight = parseFloat(options.targetHeight);
+        if (isNaN(targetHeight)) {
+            throw new Error('Invalid parameter value for targetHeight.');
+        }
+    }
+
+    return Math.round(targetHeight);
+}
+
+function getCompressionQuality(defaultValue, options) {
+    let compressionQuality = defaultValue;
+
+    if (options && options.compressionQuality) {
+        compressionQuality = parseFloat(options.compressionQuality);
+        if (isNaN(compressionQuality)) {
+            throw new Error('Invalid parameter value for compressionQuality.');
+        }
+    }
+
+    return compressionQuality;
+}
+
+function getPreserveTransparency(defaultValue, options) {
+    if (
+        options &&
+        options.preserveTransparency !== undefined &&
+        options.preserveTransparency !== null
+    ) {
+        let strVal = `${options.preserveTransparency}`.toLowerCase().trim();
+
+        if (strVal === `true`) {
+            return true;
+        } else if (strVal === `false`) {
+            return false;
+        }
+
+        throw new Error('Invalid parameter value for preserveTransparency.');
+    }
+
+    return defaultValue;
+}
+
+function getImageSmoothingEnabled(defaultValue, options) {
+    if (
+        options &&
+        options.imageSmoothingEnabled !== undefined &&
+        options.imageSmoothingEnabled !== null
+    ) {
+        let strVal = `${options.imageSmoothingEnabled}`.toLowerCase().trim();
+
+        if (strVal === `true`) {
+            return true;
+        } else if (strVal === `false`) {
+            return false;
+        }
+
+        throw new Error('Invalid parameter value for imageSmoothingEnabled.');
+    }
+
+    return defaultValue;
+}
+
+function getBackgroundColor(defaultValue, options) {
+    if (options && options.backgroundColor) {
+        let strVal = `${options.backgroundColor}`;
+        if (CSS.supports('color', strVal)) {
+            return strVal;
+        }
+
+        throw new Error('Invalid parameter value for backgroundColor.');
+    }
+
+    return defaultValue;
+}
+
+function computeFinalDimensions(
+    originalWidth,
+    originalHeight,
+    targetWidth,
+    targetHeight,
+    resizeMode,
+    resizeStrategy
+) {
+    let finalWidth = originalWidth;
+    let finalHeight = originalHeight;
+
+    // first check to see if we even need to resize at all
+    if (
+        resizeMode !== 'none' &&
+        (resizeStrategy === 'always' ||
+            (resizeStrategy === 'reduce' &&
+                (originalWidth > targetWidth ||
+                    originalHeight > targetHeight)) ||
+            (resizeStrategy === 'enlarge' &&
+                (originalWidth < targetWidth || originalHeight < targetHeight)))
+    ) {
+        // if resizing is needed then compute the final size
+        if (resizeMode === 'fill') {
+            finalWidth = targetWidth;
+            finalHeight = targetHeight;
+        } else if (resizeMode === 'contain') {
+            let ratio = Math.min(
+                targetWidth / originalWidth,
+                targetHeight / originalHeight
+            );
+            finalWidth = Math.round(originalWidth * ratio);
+            finalHeight = Math.round(originalHeight * ratio);
+        }
+    }
+
+    return { finalWidth, finalHeight };
+}
+
+function resizeAndCompressImage(image, mimeType, options) {
+    return new Promise((resolve, reject) => {
+        let resizeMode;
+        let resizeStrategy;
+        let targetWidth;
+        let targetHeight;
+        let compressionQuality;
+        let imageSmoothingEnabled;
+        let preserveTransparency;
+        let backgroundColor;
+
+        // parse the options
+        try {
+            resizeMode = getResizeMode('fill', options);
+            resizeStrategy = getResizeStrategy('always', options);
+            targetWidth = getTargetWidth(image.width, options);
+            targetHeight = getTargetHeight(image.height, options);
+            compressionQuality = getCompressionQuality(null, options);
+            imageSmoothingEnabled = getImageSmoothingEnabled(true, options);
+            preserveTransparency = getPreserveTransparency(true, options);
+            backgroundColor = getBackgroundColor('white', options);
+        } catch (error) {
+            reject(error);
+            return;
+        }
+
+        let { finalWidth, finalHeight } = computeFinalDimensions(
+            image.width,
+            image.height,
+            targetWidth,
+            targetHeight,
+            resizeMode,
+            resizeStrategy
+        );
+
+        // Render the image into a canvas at the calculated final size
+        let canvas = document.createElement('canvas');
+        canvas.width = finalWidth;
+        canvas.height = finalHeight;
+        canvas.imageSmoothingEnabled = imageSmoothingEnabled;
+
+        let ctx = canvas.getContext('2d');
+
+        if (!preserveTransparency) {
+            ctx.fillStyle = backgroundColor;
+            ctx.fillRect(0, 0, finalWidth, finalHeight);
+        }
+
+        ctx.drawImage(image, 0, 0, finalWidth, finalHeight);
+
+        let targetType = 'image/jpeg';
+        if (
+            preserveTransparency &&
+            (mimeType === 'image/gif' || mimeType === 'image/png')
+        ) {
+            targetType = 'image/png';
+        }
+
+        let resultFunc = function (blob) {
+            resolve(blob);
+        };
+
+        // Compress at the specified compression quality and return the final result
+        if (compressionQuality) {
+            canvas.toBlob(resultFunc, targetType, compressionQuality);
+        } else {
+            canvas.toBlob(resultFunc, targetType);
+        }
+    });
+}

package/src/lightning/mediaUtils/mediaUtils.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>0.0</minApiVersion>
+    <support>BETA</support>
+</LightningComponentBundle>

package/src/lightning/modal/__docs__/migration.md

@@ -0,0 +1,158 @@
+# Migrating from Other Modal Solutions to LightningModal
+
+This document is about migrating existing modal implementations.
+
+## **Creating a new LWC-based modal implementation?**
+* Starting in release 236, when utilizing LWC or Aura code, your team should use `LightningModal` 
+* Dive into the details here by [Creating a Modal Component](modal.md#creating-a-modal-component)
+* Or, take a look at some of our [Modal Code Examples](modal.md#modal-code-examples).
+
+## Why `LightningModal`?
+
+`LightningModal` provides a full-featured, modern, accessible modal solution intended for on and off the Salesforce platform (see [intended timeline](#intended-timeline-for-modal-solutions)) _that will **replace all** previous Lightning modal solutions_. Whether you are starting a completely new modal implementation, or have an existing modal implementation using a prior Aura or LWC modal solution, `LightningModal` is your Salesforce modal migration path *forward*.
+
+**Why migrate to `LightningModal`?** The `LightningModal` component has fewer limitations, is actively supported for use both on the Salesforce platform (starting in 236) and off Salesforce platform (likely, starting in 238), has SLDS blueprints and accessibility best practices built in, is performant, provides a scroll bar when your modal content is taller than the screen height, and is well-tested. Using `LightningModal` gives your team more time to implement your app's unique features instead of recreating modal functionality.
+
+### Intended Timeline for Modal Solutions:
+1. `LightningModal`:
+    * Availability:
+        * for new Salesforce internal projects in release 236 via `lwc-components-lightning` package
+        * for new Salesforce internal _and_ planned for external projects in release 238 via `lightning-base-components` (npmjs.com) package
+    * Ongoing Support:
+        * starting in release 236 for Salesforce internal teams
+1. `lightning-dialog`:
+    * Availability:
+        * from 230, for all new modal projects, _within documented limited use cases_ (**not recommended in one.app**)
+        * **recommend** transitioning new Salesforce internal modal work to `LightningModal` starting in release 236
+    * Ongoing Support:
+        * for LWC modal projects, through end of 236, _within documented limited use cases_
+        * planned review for deprecation starting in 238
+1. `ui:createPanel`:
+    * Availability:
+        * for Aura modal projects through end of 236
+        * **recommend** transitioning new Salesforce internal modal work to `LightningModal` starting in release 236
+    * Ongoing Support:
+        * through the end of release 236
+        * planned review for deprecation starting in 238
+
+## Migrating Existing Modal Implementations
+
+In this section, we’ll discuss migrating your existing modal implementation to `LightningModal` by showing the implementation differences in markup and APIs.
+
+* **Migrating from custom modal implementations** using [SLDS modal blueprints](https://www.lightningdesignsystem.com/components/modals/)
+* **Migrating from Aura** **`ui:createPanel`**
+* **Migrating from** [**`lightning-dialog`**](https://git.soma.salesforce.com/aura/lightning-global/tree/master/ui-lightning-components/src/main/modules/lightning/dialog) (Salesforce internal only)
+
+## Key Points For Modal Code Migration
+
+* **There isn't a `<lightning-modal>` tag!**  Instead, you extend `LightningModal`, and call `.open()` and `.close()` on your modal implementation.  You'll never use the `<lightning-modal>` tag within your code.
+* **In most implementations, you’ll have, at minimum, two components**:
+    1. your `CustomModal` modal component which defines behavior and is wrapped in the modal window
+    1. your application component that imports your `CustomModal` component and calls `.open({})` to open your modal
+* **You don’t need to set the base SLDS modal CSS classes, or manage the accessibility of the modal itself.** Each of the modal helper components have the SLDS styling classes and accessibility built in. However, you're responsible for making sure your modal’s content has accessibility covered!
+* **Currently, auto-focus on the first interactive element is performed automatically** once at the beginning of modal creation.
+* **You only work directly with helper components named `lightning-modal-*`**. `LightningModal` is actually a collection of supporting components that create the underlying LWC-based modal features and functionality. When you extend `LightningModal`, you can use the modal content helper components like `lightning-modal-header` (optional), `lightning-modal-body`, and `lightning-modal-footer` (optional) to set up the content of the modal, and call `.open()` in the `onclick` event handler of your app page's button or link.
+* **We’ve provided a few `LightningModal` code examples for use in our LWR-based `playground.html` file, or our deprecated `demo/app` code playground to get you started.** Each of these examples is based on an SLDS blueprint pattern, and can be found in the '`modal/__examples__`' folder. Review the [Modal Code Examples](modal.md#modal-code-examples) section.
+
+## Migrating From a Custom Built Modal
+
+If you have an existing LWC custom modal that implements the HTML and CSS from the [SLDS modal blueprint](https://www.lightningdesignsystem.com/components/modals/) and custom JavaScript behavior, you likely have your own custom api attributes and methods. We recommend the following:
+
+* Start by looking at our [Modal Code Examples](modal.md#modal-code-examples) for comparison to your own implementation
+    * Each of these code examples can be viewed within the `modal/__examples__` folder
+    * Each can be previewed within our repo by editing the `playground.html` file (by running `yarn start`) or the deprecated `demo/app` and (running `yarn app:start`) utilizing the corresponding tag:
+        * `<modal-all>`
+        * `<modal-headless>`
+        * `<modal-footless>`
+    * Wrap the desired example tag within a `<template></template>` tag
+    * For modal blueprints and variants, review the [Modal and supported variants](modal.md#modal-and-supported-variants) section.
+* `LightningModal` provides three helper components for header, body content, and footer sections. The `lightning-modal-body` is the only required component.
+* You don’t need to worry about setting any of the base SLDS modal CSS classes. These are set for you. If you’d like to further style your modal, review the modal [Style Hooks](modal.md#style-hooks) section 
+* Review our `LightningModal` documentation:
+    * [Creating a Modal Component](modal.md#creating-a-modal-component)
+    * [Opening a Modal Instance](modal.md#opening-a-modal-instance)
+    * [About Modal Instances](modal.md#about-modal-instances)
+    * [Using the open() method](modal.md#using-the-open-method)
+    * [Using the close() method](modal.md#using-the-close-method)
+    * [Modal Code Examples](modal.md#modal-code-examples)
+
+## Migrating From Aura Modals
+
+If you are ready to move an existing modal implementation from Aura-based `ui:createPanel`, `ui:createModal`, or `ui:modal`, here are some key differences:
+
+### Implementation differences
+
+This section covers implementation differences between Aura modal solutions and `LightningModal`.
+
+* When setting up the config before opening the modal, either pass your content via custom written `@api` (see [Using the open() method](modal.md#using-the-open-method)), or set it statically within your template (see the [Base Modal](modal.md#base-modal) HTML template example)
+* If you don't want a header and title section, simply remove `lightning-modal-header`. You must then pass the required `label` value (for the accessible modal title) when opening the modal, for example `Modal.open({label: ‘Descriptive Modal Header’})`. See our [Headless Variant](modal.md#headless-variant) documentation, and [Modal Code Examples](modal.md#modal-code-examples). Same goes for the footer section, if you don’t want a footer, don't use `lightning-modal-footer`. Only `lightning-modal-body` is required.
+* **For specific events and event listeners availability** within `createPanel` or `createModal`, for example, `onBeforeShow`, `onAfterShow`, `onCreate` or `onDestroy`, see our section on [About Modal Events](modal.md#about-modal-events).  
+    * **Recommend:** create these as [custom events](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/events_create_dispatch)
+* **If you want to get element reference,** for example, `linkElement.querySelector(‘[data-my-link]’)` within the content you’ve set within your modal, utilize data attributes.  For this example, `<a href=“#” data-my-link>`, rather than relying on ID references, since these dynamically change in LWC).  
+    * **Recommend:** See the note within the [ARIA attributes](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_components_accessibility_attributes) section.
+* If you need to style aspects of your modal, you can apply CSS styles directly to your markup within the helper components. 
+    * **Recommend:** See the example under [Directional Variant](modal.md#directional-variant) section.
+* If you need to support a modal with a [directional variant](https://www.lightningdesignsystem.com/components/modals/#Directional), please review our [Directional Variant](modal.md#directional-variant) documentation.
+
+### API differences
+
+This section covers `@api` or attribute differences between Aura modal solutions and `LightningModal`.
+
+#### Supported APIs
+See [ui:modal](https://git.soma.salesforce.com/aura/aura/tree/master/aura-components/src/main/components/ui/modal)
+
+* `title` attribute has been changed to the `label` attribute 
+    * You set the `label` attribute on the `lightning-modal-header` helper component or in the case of a headless modal, when you open the modal, you would set the `label` attribute when opening the modal.  For example: `Modal.open({ label: ‘Modal Descriptive Title’ })`
+* `**LightningModal**` currently has only four official attributes A
+    * `size` - to set the width of the modal
+    * `label` - to set the modal heading
+    * `description` - to set the modal's `aria-description` or `aria-describedby` property
+    * `disableClose` - a boolean value to toggle usability of the Close button
+    * **Modal enables you to pass in your own `@api`** to interact and wire-up your own desired functionality within the modal (interactive elements like buttons, inputs, etc) by setting key value pairs on `.open({ options: [], buttons: [] })`, for example
+    * **Modal enables setting event listeners** that may be listened to by the base LWC component (that opens the modal) by passing custom events into your LightningModal implementation by setting keys startin with `on` `.open({ onselect: () => { /* do stuff */ } })`, setting the corresponding listener on the outer templates markup, and firing the custom event `select` from within the modal.  See [modal.md](modal.md#about-modal-events) for examples
+
+#### Unsupported API
+See [ui:modal](https://git.soma.salesforce.com/aura/aura/tree/master/aura-components/src/main/components/ui/modal)
+
+* **Animation related:** `animation`, `closeAnimation`, `useTransition`
+    * **recommend:** remove for now, future support may be available
+* **Close button related:** `closeAction`**,** `showCloseButton`, `closeButton`, `closeDialogLabel`
+    * **notes:** no recommendations, these properties cannot be altered currently
+* **Setting CSS Classes related:** `class,` `modalClass`, `headerClass`, `bodyClass`, `footerClass`
+    * **recommend:** apply your required styles within the modal component. See the [Directional Variant](modal.md#directional-variant) section for an example.
+* **Accessibility related:** trapFocus, ariaLabelleBy, ariaDescribedBy
+    * **notes:** the first two properties are managed for you, ariaDescribedBy feature will be added later
+* **autoFocus** - **note:** this is currently happens automatically at open time
+* **icon** - **note:** no current ability set an icon
+* **titleDisplay** - note: not supported
+    * **Recommend:** If you don’t want a header section or title in the modal, set a descriptive label attribute value for accessibility, and don’t add the `lightning-modal-header` component.
+
+## Migrating From `lightning-dialog`
+
+If you need to move an existing `lightning-dialog` implementation, you’ll need to consider these changes: 
+
+### Implementation Differences
+
+This section covers implementation differences between `lightning-dialog` and `LightningModal`.
+
+* `lightning-dialog` and `LightningModal` are fairly similar in terms of their template code implementation, with the exception that the different sections within the `LightningModal` have separate helper components.
+* `lightning-dialog` is inline with your application limiting the z-index to the context where it is placed. `LightningModal` is created outside and above all elements with a managed z-index to not conflict with other overlays.
+* You implement `lightning-dialog` via its tag in your markup. There is no equivalent `lightning-modal`, instead you extend `LightningModal`. For example:
+    * import **LightningModal** from 'lightning/modal';
+    * export default class **MyModal _extends_ LightningModal** { /* your code */ }
+* `LightningModal` makes use of extending `LightningOverlay` which provides `.open()` and `.close()` methods, whereas `lightning-dialog` worked from LWC declarative implementation without extends.  See our sample [Modal Code Examples](modal.md#modal-code-examples) documentation.
+* Custom events - `LightningModal` only provides a `privateclose` event.  `<lightning-dialog>` provided events `cancel` or `close` events.
+
+### API and Method Differences
+
+This section covers api or attribute and method differences between `lightning-dialog` and `LightningModal`.
+
+* The API to indicate the modal's title or heading is renamed from `header` to `label`
+    * From: `<lightning-dialog header=“Descriptive Modal Heading”>`
+    * To:
+        1. `<lightning-modal-header label=“Descriptive Modal Heading”>` for modal with header section
+        1. Or, `MyModal.open({ label: ‘Descriptive Modal Heading’ })` for headless modal
+* The method to show the modal is renamed
+    * From: `.showModal()`
+    * To: `.open()`
+    * `.open()` is inherited when you extend LightningModal.