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

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.

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

@@ -0,0 +1,414 @@
+A `lightningModal` component overlays a message modal on top of the current app window. A modal interrupts a user’s workflow and draws attention to the message. 
+
+`LightningModal` implements the SLDS [modals](https://www.lightningdesignsystem.com/components/modals/) blueprint.
+
+Create a modal component in response to a user action, such as clicking a button or link. The modal blocks interaction with everything else on the page until the user acts upon or dismisses the modal.
+
+Unlike other components, this component doesn't use a `lightning-modal` tag or extend `LightningElement`. There is no `lightning-modal` component. Instead, you create a modal by extending `LightningModal` and using these helper `lightning-modal-*` components to provide a header, footer and the body of the modal. 
+- `lightning-modal-body`
+- `lightning-modal-header`
+- `lightning-modal-footer`
+
+To create a modal component, import `LightningModal` from `lightning/modal`. The component has access to the normal LWC resources as well as the special container, helper components, methods, and events of the `lightning/modal` module.
+
+In this example, the `content` property passes data to the modal from the component that invokes it. 
+
+```js
+/* c/myModal.js */
+
+import { api } from 'lwc';
+import LightningModal from 'lightning/modal';
+
+export default class MyModal extends LightningModal {
+    @api content;
+
+    handleOkay() {
+        this.close('okay');
+    }
+}
+```
+
+The modal’s HTML template uses helper `lightning-modal-*` components to provide a header, footer, and the body of the modal. In this example, the content for the modal body comes from the `content` property we defined in the modal's JavaScript file. 
+
+```html
+<!-- c/myModal.html -->
+
+<template>
+    <lightning-modal-header label="My Modal Heading"></lightning-modal-header>
+    <lightning-modal-body> Content: {content} </lightning-modal-body>
+    <lightning-modal-footer>
+        <lightning-button label="OK" onclick={handleOkay}></lightning-button>
+    </lightning-modal-footer>
+</template>
+```
+
+The `lightning-modal-body` component is required for the modal template. 
+
+The `lightning-modal-header` and `lightning-modal-footer` components are optional, but recommended. The `lightning-modal-*` components render in the order they appear in the template. Place the `lightning-modal-body` component after `lightning-modal-header` and before the `lightning-modal-footer` component. 
+
+#### Open a Modal Instance
+
+`LightningModal` provides an `.open()` method which opens a modal and returns a promise that asynchronously resolves with the result of the user’s interaction with the modal.
+
+Each invocation of a modal component’s `.open()` method creates a unique instance of the modal. You can think of a modal as a self-contained application that starts from scratch when it opens. It displays the content you pass in through the `.open()` method or that you set within the modal's HTML template. 
+
+When you close a modal, the modal instance is destroyed, not hidden. On close, the modal must save the user’s input data or pass it to the invoking component as the promise result. Otherwise, the data is lost when the modal instance is closed. 
+
+The `.open()` method lets you assign values to the modal's properties. `LightningModal` provides these properties. 
+
+* `label` - Required. Sets the modal's title and assistive device label. If the modal has a header, set `label` in the `lightning-modal-header` component. If the modal doesn't have a header, set the `label` property when opening the modal.
+
+* `size` - Determines how much of the viewport width the modal uses. Supported values are `small`, `medium`, and `large`, which you can set when you open the modal. Default value is `medium`. The length of the modal is determined by the amount of content.
+
+* `description` - Sets the modal's accessible description. It uses the `aria-description` attribute where supported, or falls back to `aria-describedby`. If you set a custom description value, include the label name at the beginning of your description, because some screen readers only read the description, and not the label.
+
+* `disableClose` - Prevents closing the modal by normal means like the ESC key, the close button, or `.close()`. For example, you could briefly set `disableClose` to true while a completed form is saving, so the user doesn't dismiss the modal early. See [**Use the `disableClose` Attribute**](#use-the-disableclose-attribute).
+
+In this example, the app opens the `myModal` component. It invokes the `.open()` method in a `handleClick()` function bound to the app button’s `onclick` attribute, and uses `async` and `await` keywords to handle the promise returned by `.open()`. This example overrides the `size` value by setting it to `large` and sets the modal’s user-defined property `content`.
+
+```js
+/* c/myApp.js */
+
+import { LightningElement } from 'lwc';
+import MyModal from 'c/myModal';
+
+export default class MyApp extends LightningElement {
+    async handleClick() {
+        const result = await MyModal.open({
+            // `label` is not included here in this example.
+            // it is set on lightning-modal-header instead
+            size: 'large',
+            description: 'Accessible description of modal\'s purpose',
+            content: 'Passed into content api',
+        });
+        // if modal closed with X button, promise returns result = 'undefined'
+        // if modal closed with OK button, promise returns result = 'okay'
+        console.log(result);
+    }
+}
+```
+The HTML template for this app contains a button that opens the modal and displays the result returned when the modal closes.
+
+```html
+<!-- c/myApp.html -->
+
+<template>
+    <lightning-button
+        onclick={handleClick}
+        aria-haspopup="modal"
+        label="Open My Modal">
+    </lightning-button> 
+    <p>Result: {result}</p>
+</template>
+```
+
+You can also use `.open()` to pass data from your invoking component into the modal with custom properties decorated with `@api`. These properties can be any type, such as a string or an object that’s an array of key/value pairs to be assigned to the new modal instance. 
+
+For example, this app component sets an `options` property to a set of key/value pairs in `MyModal.open()`. The promise is handled using an arrow function that logs the result to the console.
+
+```js
+/* c/myApp.js */
+
+import { LightningElement } from "lwc";
+import MyModal from "c/myModal";
+
+export default class MyPage extends LightningElement {
+  handleOpenClick() {
+    MyModal.open({
+      // maps to developer-created `@api options`
+      options: [
+        { id: 1, label: 'Option 1' },
+        { id: 2, label: 'Option 2' },
+      ]
+    }).then((result) => {
+        console.log(result);
+    });
+  }
+}
+```
+The modal dialog can then use this property. In this case, the modal creates buttons whose labels are provided in the `options` array.
+
+```js
+/* c/myModal.js */
+
+import { api } from 'lwc';
+import LightningModal from 'lightning/modal';
+
+export default class MyModal extends LightningModal {
+  // Data is passed to api properties via .open({ options: [] })
+  @api options = [];
+}
+```
+
+```html
+<!-- c/myModal.html -->
+
+<template>
+    <lightning-modal-header label="My Modal Heading"></lightning-modal-header>
+    <lightning-modal-body>
+        Let's make some buttons!
+        <template for:each={options} for:item="option">
+            <lightning-button
+              onclick={handleOptionClick}
+              data-id={option.id}
+              key={option.id}
+            >
+                {option.label}
+            </lightning-button>
+        </template>   
+    </lightning-modal-body>
+</template>
+```
+
+#### Close a Modal Instance
+
+Use `this.close(result)` to close the modal, where `result` is anything you want to return from the modal. The `.close()` operation is asynchronous to display a brief fade out animation before the modal is destroyed. The `result` data can’t be modified after the close operation begins. 
+
+You can also close the modal with the default close button, the X at the top right corner. Closing a modal like this is the same as calling `this.close()` with an `undefined` result, so any data input is lost.
+
+This example shows the handler for some buttons inside a modal. When the user clicks the button, `this.close(id)` returns the option that they chose and the modal closes.
+
+```js
+/* c/myModal.js */
+
+import { api } from 'lwc';
+import LightningModal from 'lightning/modal';
+
+export default class MyModal extends LightningModal {
+  // Data is passed to apis via .open({ options: [] })
+  @api options = [];
+
+  handleOptionClick(e) {
+    const { target } = e;
+    const { id } = target.dataset;
+    // this.close() triggers closing the modal
+    // the value of `id` is passed as the result
+    this.close(id);
+  }
+}
+```
+
+```html
+<!-- c/myModal.html -->
+
+<template>
+  <template for:each={options} for:item="option">
+    <lightning-button
+      onclick={handleOptionClick}
+      data-id={option.id}
+      key={option.id}
+    >
+      {option.label}
+    </lightning-button>
+  </template>
+</template>
+```
+
+#### Use the `disableClose` Attribute
+
+`disableClose` temporarily turns off the ability to dismiss the modal by normal means like the ESC key, the close button, or `this.close()`. For example, you could briefly set `disableClose` to `true` while a completed form is saving, so the user doesn't dismiss the modal early.
+
+Preventing a modal's close should be a temporary state. Use `disableClose` for less than 5 seconds. Accessibility is affected if you trap keyboard focus inappropriately. See [No Keyboard Trap](https://www.w3.org/TR/UNDERSTANDING-WCAG20/keyboard-operation-trapping.html) for more information.
+
+When the process using `disableClose` finishes successfully, dismiss the modal. If the process using `disableClose` fails, re-enable the ability to dismiss the modal with `disableClose = false`, or give feedback to help the user resolve the issue.
+
+While `disableClose` is `true`, disable any processes or UI buttons that might call `Modal.close()`.
+
+This example shows how to use `disableClose`. It's not a fully functional example, but could be used in a complex modal component.
+
+```js
+/* c/myModalForm.js */
+/* This is intended as a mock example, not as fully functional code */
+/* NOTE: observe values set:
+   this.disableClose (in JS),
+   and this.saveInProcess (in JS and HTML)
+*/
+import { api } from 'lwc';
+import LightningModal from 'lightning/modal';
+
+export default class MyModalForm extends LightningModal {
+  // formData is utilized for saving current form values
+  formData = {};
+  failureType = null;
+  saveStatus = {};
+  saveInProcess = false;
+
+  handleCloseClick() {
+    this.close('canceled');
+  }
+
+  closeModal() {
+    // immediately exits, so no need to trigger
+    // this.disableClose = false OR
+    // this.saveInProcess = false;
+    // modal is destroyed, and focus moves
+    // back to originally clicked item that
+    // generated the modal
+    this.close('success');
+  }
+
+  mitigateSaveFailure() {
+    // depending on how easily the failure can be resolved
+    // you may need to immediately set disableClose = false
+    if (this.failureType === 'recoverable') {
+      // no need to call this.disableClose = false
+      // or this.saveInProgress = false yet
+      tryToFixFailure();
+    } else {
+      // can't resolve the error
+      // need to allow users to exit modal
+      this.disableClose = false;
+      this.saveInProcess = false;
+      // mock function to indicate modal state
+      // while still allowing user to exit
+      // preventing keyboard trap
+      reportUnresolvableError();
+    }
+  }
+
+  async saveData() {
+    // switches disabled state on buttons
+    this.saveInProcess = true;
+    const saveStatus = await sendData(this.formData);
+    return (saveStatus && saveStatus.success)
+      ? closeModal()
+      : mitigateSaveFailure();
+  }
+
+  async handleSaveClick() {
+    if (isValid(this.formData)) {
+      // begin saving data, temporarily disable
+      // LightningModal's close button
+      // Be sure to reenable the close button, by setting
+      // this.disableClose = false, IF further interaction
+      // is desired before the modal closes
+      this.disableClose = true;
+      await saveData();
+    } else {
+      // function that display form errors based on data
+      showFormErrors(this.formData);
+    }
+  }
+}
+```
+
+```html
+<!-- c/myModalForm.html -->
+
+<template>
+    <lightning-modal-header
+      label="My Modal Heading"
+    ></lightning-modal-header>
+    <lightning-modal-body>
+      <!-- form here -->
+    </lightning-modal-body>
+    <lightning-modal-footer>
+      <button
+        disabled={saveInProcess}
+        onclick={handleCloseClick}
+        aria-label="Cancel and close"
+      >Cancel</button>
+      <button
+        disabled={saveInProcess}
+        onclick={handleSaveClick}
+      >Save</button>
+    </lightning-modal-footer>
+</template>
+```
+
+#### Modal Events
+
+A modal can only fire events captured by the component that opened it, not the modal itself. Normal techniques can't catch events that fire from the modal, because the events bubble up to a top root element outside of the component that opened the modal.
+
+To capture modal events, attach them in the `.open()` method invoked by the component that opens the modal. 
+
+For example, here's a custom `select` event dispatched from `MyModal`.
+
+```js
+/* c/myModal.js */
+dispatchSelectEvent(e) {
+  // e.target might represent an input with an id and value
+  const { id, value } = e.target;
+  const selectEvent = new CustomEvent('select', {
+    detail: { id, value }
+  });
+  this.dispatchEvent(selectEvent);
+}
+```
+
+The `open()` method in `myApp` defines the `onselect` event handler. This example uses `onselect` to proxy events that we want to pass through.
+
+```js
+/* c/myApp.js */
+
+// ...
+// Process the select event from within the modal
+handleSelectEvent(detail) {
+  const { id, value } = detail;
+  console.log(`select event fired elem with id ${id} and value: ${value}`);
+}
+
+// ...
+// Trigger visibility of the modal
+handleOpenModal() {
+  MyModal.open({
+    label: 'Modal Title',
+    size: 'large',
+    description: 'Modal Title with brief description',
+    // event triggered when new CustomEvent('select', {detail: {}});
+    // occurs *from within* LightningModal.
+    // see dispatchSelectEvent() in c/myModal.js above
+    onselect: (e) => {
+      // stop further propagation of the event
+      e.stopPropagation();
+      // hand off to separate function to process
+      // result of the event (see above in this example)
+      this.handleSelectEvent(e.detail);
+      // or proxy to be handled above by dispatching
+      // another custom event to pass on the event
+      // this.dispatchEvent(e);
+    }
+  });
+}
+```
+
+See [Create and Dispatch Events](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/events_create_dispatch) in the LWC Dev Guide for more information about events.
+
+#### Styling Variants
+
+The `lightning-modal-header` and `lightning-modal-footer` child components are optional, and you can choose to not include one or the other in your modal. 
+
+The headerless variant of `LightningModal` has these additional requirements.
+- Must set a descriptive modal title with the `label` property using `Modal.open({ label })` or you’ll get a console error.
+-  The `label` property is required for all variants of `LightningModal`. Assistive devices read the `label` value, even though the headerless modal variant doesn't display the label. 
+-  Because this variant doesn't use `lightning-modal-header`, you have to manually create an `<h1>` heading in `lightning-modal-body`. Provide accessible structure by starting with heading level `<h1>` and using levels up to `<h6>` appropriately. For more information, see [Semantic Structure, Headings on WebAim.org](https://webaim.org/techniques/semanticstructure/#headings).
+
+The `LightningModal` component also supports the SLDS [Directional variant](https://www.lightningdesignsystem.com/components/modals/#Directional) modal blueprint pattern.
+
+To achieve the directional button layout, place the buttons in a `div` with the `slds-modal__footer_directional` class. 
+
+```html
+<!-- c/modalDirectional.html -->
+
+<template>
+    <lightning-modal-body> Content: {content} </lightning-modal-body>
+    <lightning-modal-footer>
+        <div class=“slds-modal__footer_directional”>
+            <lightning-button label="NO" onclick={handleNo}></lightning-button>
+            <lightning-button label="OK" onclick={handleOkay}></lightning-button>
+        </div>
+    </lightning-modal-footer>
+</template>
+```
+
+#### Styling Hooks
+
+The `lightning-modal-*` helper components support [style hooks](https://www.lightningdesignsystem.com/components/modals/#Styling-Hooks-Overview). The styling hooks for the template that invokes the helper components doesn't carry over to them, so you must style each helper component individually. 
+
+Customizing the styling on the white modal frame and background, close button, or gray backdrop isn't supported.
+
+#### Accessibility
+
+The `lightning-modal-header` component renders the `label` value in an `<h1>` element. If your modal uses the header, begin any additional heading levels in the modal with `<h2>` for accessibility. Provide accessible structure by using heading levels up to `<h6>` appropriately. For more information, see [Semantic Structure, Headings on WebAim.org](https://webaim.org/techniques/semanticstructure/#headings).
+
+To include tagline text or link content for the header section, add it between the `<lightning-modal-header>` tags. 

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

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

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

@@ -0,0 +1,25 @@
+import { LightningElement } from 'lwc';
+import ModalDemoAll from 'modal/demoall';
+
+export default class ModalAll extends LightningElement {
+    demoResult = 'unset';
+
+    handleDemoModal() {
+        ModalDemoAll.open({
+            // LightningModal
+            size: 'small',
+            // ModalDemo
+            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/__examples__disabled/allform/allform.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/allform/allform.html

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