diff --git a/packages/dialog/README.md b/packages/dialog/README.md index f72988cf8ab..69d473e0e1b 100644 --- a/packages/dialog/README.md +++ b/packages/dialog/README.md @@ -1,4 +1,4 @@ -## Description +## Overview `sp-dialog` displays important information that users need to acknowledge. They appear over the interface and block further interactions. When used directly the `sp-dialog` element surfaces a `slot` based API for deep customization of the content to be included in the overlay. @@ -8,147 +8,43 @@ [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/dialog?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/dialog) [![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/RSDikStPmUPSioVpCsYb/src/index.ts) -``` +```bash yarn add @spectrum-web-components/dialog ``` Import the side effectful registration of `` via: -``` +```ts import '@spectrum-web-components/dialog/sp-dialog.js'; ``` When looking to leverage the `Dialog` base class as a type and/or for extension purposes, do so via: -``` +```ts import { Dialog } from '@spectrum-web-components/dialog'; ``` -## Sizes - - -Small - - -```html demo - -

Disclaimer

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. -
-``` - -
-Medium - - -```html demo - -

Disclaimer

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. -
-``` - -
-Large - - -```html demo - -

Disclaimer

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. -
-``` - -
-
- -## Variants - -### Dismissable - -When supplied with the `dissmissable` attribute an `` element will surface a "close" button afordance that will dispatch a DOM event with the name of `close` when pressed. - -Note: the `dissmissable` attribute will not be followed when `mode="fullscreen"` or `mode="fullscreenTakeover"` are applies in accordance with the Spectrum specification. - -```html - -

Disclaimer

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. -
-``` - -### No Divider +### Anatomy -```html - -

Disclaimer

- Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. -
-``` +The dialog consists of several key parts: -### Hero +- A heading (via `slot="heading"`) +- Content (via default slot) +- Optional hero content (via `slot="hero"`) +- Optional buttons (via `slot="button"`) +- Optional footer content (via `slot="footer"`) +- Optional dismiss button (via `dismissable` attribute) ```html - +

Disclaimer

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod - tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris - augue neque gravida. Libero volutpat sed ornare arcu. Quisque egestas diam - in arcu cursus euismod quis viverra. Posuere ac ut consequat semper viverra - nam libero justo laoreet. Enim ut tellus elementum sagittis vitae et leo - duis ut. Neque laoreet suspendisse interdum consectetur libero id faucibus - nisl. Diam volutpat commodo sed egestas egestas. Dolor magna eget est lorem - ipsum dolor. Vitae suscipit tellus mauris a diam maecenas sed. Turpis in eu - mi bibendum neque egestas congue. Rhoncus est pellentesque elit ullamcorper - dignissim cras lobortis. + tempor incididunt ut labore et dolore magna aliqua. +
Footer information
+ Button
``` diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 90a32a34d6b..c13d2ac460d 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -1,6 +1,6 @@ -## Description +## Overview -`sp-dialog-base` accepts slotted dialog content (often an ``) and presents that content in a container that is animated into place when toggling the `open` attribute. In concert with the [Overlay API](../overlay) or [Overlay Trigger](../overlay-trigger), the provided dialog content will be displayed over the rest of the page. Leverage the `interaction = modal` and `receivesFocus = 'auto'` settings in the Overlay API to ensure that focus is thrown into the dialog content when opened and that the tab order will be trapped within it while open. +`sp-dialog-base` accepts slotted dialog content (often an ``) and presents that content in a container that is animated into place when toggling the `open` attribute. In concert with the [Overlay API](../overlay) or [Overlay Trigger](../overlay-trigger), the provided dialog content will be displayed over the rest of the page. ### Usage @@ -8,28 +8,117 @@ [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/dialog?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/dialog) [![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/MLYDVWpWhNxJZDW3Ywqq/src/index.ts) -``` +```bash yarn add @spectrum-web-components/dialog ``` Import the side effectful registration of `` via: -``` +```ts import '@spectrum-web-components/dialog/sp-dialog-base.js'; ``` When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via: -``` +```ts import { DialogBase } from '@spectrum-web-components/dialog'; ``` -## Example +### Anatomy + +The dialog base consists of a single default slot that expects an [`sp-dialog` element](./dialog) to be provided. The dialog base manages the presentation and animation of this content. + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+ + Ok + + Don't show me this again +
+
+ Toggle Dialog +
+``` + +### Options + +#### Sizes + +The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, `l`. + + + Small + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
+``` + +
+Medium + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
+``` + +
+Large + ```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
+``` + +
+
+ +#### Underlay + +The `underlay` attribute can be used to add an underlay element between the page content and the dialog. + +```html + - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -51,6 +140,93 @@ import { DialogBase } from '@spectrum-web-components/dialog'; ``` -## Dialog +#### Dismissable + +The `dismissable` attribute can be used to add an underlay element between the page content and the dialog. + +```html + + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
+``` + +#### Mode + +The dialog base supports different display modes: + +##### Fullscreen Mode + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
+``` + +##### Fullscreen Takeover Mode + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+
+
+ Toggle Dialog +
+``` + +### Behaviors + +The dialog base manages several behaviors: + +1. Animation of the dialog content when opening/closing +2. Focus management when the dialog opens +3. Event handling for closing the dialog + +#### Receives focus + +The `receives-focus` attribute can be used to control whether the dialog should receive focus when it is opened. Leverage the `type="modal"` and `receives-focus="auto"` settings in the Overlay API to ensure that focus is thrown into the dialog content when opened and that the tab order will be trapped within it while open. + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+
+
+ Toggle Dialog +
+``` + +### Accessibility + +The dialog base component ensures proper focus management by: + +- Moving focus into the dialog when opened +- Trapping tab order within the dialog while open +- Returning focus to the trigger element when closed -`sp-dialog-base` expects a single slotted child element to play the role of the dialog that it will deliver within your application. When leveraging it as a base class be sure to customize the `dialog` getter to ensure that it acquires the appropriate element for your use case in order to correctly pass focus into your content when the dialog is opened. +See the [Dialog](./dialog) component for more information on the accessibility features of the dialog content. diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index 7aacb05e676..c13d2ac460d 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -1,6 +1,6 @@ -## Description +## Overview -`sp-dialog-wrapper` supplies an attribute based interface for the managed customization of an `sp-dialog` element and the light DOM supplied to it. This is paired it with an `underlay` attribute that opts-in to the use of an `sp-underlay` element between your page content and the `sp-dialog` that opens over it. +`sp-dialog-base` accepts slotted dialog content (often an ``) and presents that content in a container that is animated into place when toggling the `open` attribute. In concert with the [Overlay API](../overlay) or [Overlay Trigger](../overlay-trigger), the provided dialog content will be displayed over the rest of the page. ### Usage @@ -8,118 +8,225 @@ [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/dialog?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/dialog) [![Try it on webcomponents.dev](https://img.shields.io/badge/Try%20it%20on-webcomponents.dev-green?style=for-the-badge)](https://webcomponents.dev/edit/collection/fO75441E1Q5ZlI0e9pgq/MLYDVWpWhNxJZDW3Ywqq/src/index.ts) -``` +```bash yarn add @spectrum-web-components/dialog ``` -Import the side effectful registration of `` via: +Import the side effectful registration of `` via: + +```ts +import '@spectrum-web-components/dialog/sp-dialog-base.js'; +``` + +When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via: + +```ts +import { DialogBase } from '@spectrum-web-components/dialog'; +``` + +### Anatomy + +The dialog base consists of a single default slot that expects an [`sp-dialog` element](./dialog) to be provided. The dialog base manages the presentation and animation of this content. + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+ + Ok + + Don't show me this again +
+
+ Toggle Dialog +
+``` + +### Options + +#### Sizes + +The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, `l`. + + + Small + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
``` -import '@spectrum-web-components/dialog/sp-dialog-wrapper.js'; + +
+Medium + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
``` -When looking to leverage the `DialogWrapper` base class as a type and/or for extension purposes, do so via: +
+Large + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog +
``` -import { DialogWrapper } from '@spectrum-web-components/dialog'; + +
+
+ +#### Underlay + +The `underlay` attribute can be used to add an underlay element between the page content and the dialog. + +```html + + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+ + Ok + + Don't show me this again +
+
+ Toggle Dialog +
``` -## Example +#### Dismissable -### Small +The `dismissable` attribute can be used to add an underlay element between the page content and the dialog. ```html + - - Content of the dialog - + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
Toggle Dialog
``` -### Fullscreen Mode +#### Mode + +The dialog base supports different display modes: + +##### Fullscreen Mode ```html - - Content of the dialog - - - Toggle Dialog - + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+
+
+ Toggle Dialog
``` -### Fullscreen Takeover Mode +##### Fullscreen Takeover Mode ```html - - Content of the dialog - - - Toggle Dialog - + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+
+
+ Toggle Dialog +
+``` + +### Behaviors + +The dialog base manages several behaviors: + +1. Animation of the dialog content when opening/closing +2. Focus management when the dialog opens +3. Event handling for closing the dialog + +#### Receives focus + +The `receives-focus` attribute can be used to control whether the dialog should receive focus when it is opened. Leverage the `type="modal"` and `receives-focus="auto"` settings in the Overlay API to ensure that focus is thrown into the dialog content when opened and that the tab order will be trapped within it while open. + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+

+ The click events for the "OK" button are bound to the story not + to the components in specific. +

+
+
+ Toggle Dialog
``` -## Accessibility +### Accessibility + +The dialog base component ensures proper focus management by: + +- Moving focus into the dialog when opened +- Trapping tab order within the dialog while open +- Returning focus to the trigger element when closed -An `sp-dialog-wrapper` element leverages the `headline` attribute/property to label the dialog content for screen readers. The `headline-visibility` attribute will accept a value of `"none"` to suppress the headline visually. +See the [Dialog](./dialog) component for more information on the accessibility features of the dialog content.