docs(dialog): updated dialog docs for accessbility

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 `<sp-dialog>` 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
-
-<sp-tabs selected="m" auto label="Size Attribute Options">
-<sp-tab value="s">Small</sp-tab>
-<sp-tab-panel value="s">
-
-```html demo
-<sp-dialog size="s">
-    <h2 slot="heading">Disclaimer</h2>
-    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.
-</sp-dialog>
-```
-
-</sp-tab-panel>
-<sp-tab value="m">Medium</sp-tab>
-<sp-tab-panel value="m">
-
-```html demo
-<sp-dialog size="m">
-    <h2 slot="heading">Disclaimer</h2>
-    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.
-</sp-dialog>
-```
-
-</sp-tab-panel>
-<sp-tab value="l">Large</sp-tab>
-<sp-tab-panel value="l">
-
-```html demo
-<sp-dialog size="l">
-    <h2 slot="heading">Disclaimer</h2>
-    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.
-</sp-dialog>
-```
-
-</sp-tab-panel>
-</sp-tabs>
-
-## Variants
-
-### Dismissable
-
-When supplied with the `dissmissable` attribute an `<sp-dialog>` 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
-<sp-dialog size="m" dismissable>
-    <h2 slot="heading">Disclaimer</h2>
-    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.
-</sp-dialog>
-```
-
-### No Divider
+### Anatomy
 
-```html
-<sp-dialog size="m" dismissable no-divider>
-    <h2 slot="heading">Disclaimer</h2>
-    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.
-</sp-dialog>
-```
+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
-<sp-dialog size="medium" dismissable no-divider>
+<sp-dialog size="s">
     <div
         slot="hero"
         style="background-image: url(https://picsum.photos/1400/260)"
     ></div>
     <h2 slot="heading">Disclaimer</h2>
     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.
+    <div slot="footer">Footer information</div>
+    <sp-button slot="button">Button</sp-button>
 </sp-dialog>
 ```

packages/dialog/dialog-base.md

@@ -1,35 +1,124 @@
-## Description
+## Overview
 
-`sp-dialog-base` accepts slotted dialog content (often an `<sp-dialog>`) 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 `<sp-dialog>`) 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
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/dialog?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/dialog)
 [![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 `<sp-dialog-base>` 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
+<overlay-trigger type="modal">
+    <sp-dialog-base slot="click-content">
+        <sp-dialog>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+            <p>
+                The click events for the "OK" button are bound to the story not
+                to the components in specific.
+            </p>
+            <sp-button
+                variant="secondary"
+                treatment="fill"
+                slot="button"
+                onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
+            >
+                Ok
+            </sp-button>
+            <sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+### Options
+
+#### Sizes
+
+The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, `l`.
+
+<sp-tabs selected="m" auto label="Size attribute options">
+    <sp-tab value="s">Small</sp-tab>
+    <sp-tab-panel value="s">
+
+```html
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay slot="click-content" size="s">
+        <sp-dialog size="s" dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="m">Medium</sp-tab>
+<sp-tab-panel value="m">
+
+```html
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay slot="click-content" size="m">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+<sp-tab value="l">Large</sp-tab>
+<sp-tab-panel value="l">
 
 ```html
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay slot="click-content" size="l">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### Underlay
+
+The `underlay` attribute can be used to add an underlay element between the page content and the dialog.
+
+```html
+</style>
 <overlay-trigger type="modal">
     <sp-dialog-base underlay slot="click-content">
-        <sp-dialog size="s">
+        <sp-dialog>
             <h2 slot="heading">A thing is about to happen</h2>
             <p>Something that might happen a lot is about to happen.</p>
             <p>
@@ -51,6 +140,93 @@ import { DialogBase } from '@spectrum-web-components/dialog';
 </overlay-trigger>
 ```
 
-## Dialog
+#### Dismissable
+
+The `dismissable` attribute can be used to add an underlay element between the page content and the dialog.
+
+```html
+</style>
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay slot="click-content">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+#### Mode
+
+The dialog base supports different display modes:
+
+##### Fullscreen Mode
+
+```html
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay mode="fullscreen" slot="click-content">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+##### Fullscreen Takeover Mode
+
+```html
+<overlay-trigger type="modal">
+    <sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+            <p>
+                The click events for the "OK" button are bound to the story not
+                to the components in specific.
+            </p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+### 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
+<overlay-trigger type="modal" receives-focus="auto">
+    <sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
+        <sp-dialog dismissable>
+            <h2 slot="heading">A thing is about to happen</h2>
+            <p>Something that might happen a lot is about to happen.</p>
+            <p>
+                The click events for the "OK" button are bound to the story not
+                to the components in specific.
+            </p>
+        </sp-dialog>
+    </sp-dialog-base>
+    <sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
+</overlay-trigger>
+```
+
+### 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.