From abe5d0db523312548a2bb18d7ba1479bd14acde9 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Tue, 29 Apr 2025 09:57:54 -0400 Subject: [PATCH 01/11] docs(dialog): updated dialog docs for accessbility --- packages/dialog/README.md | 126 ++++++++++---- packages/dialog/dialog-base.md | 194 ++++++++++++++++++++- packages/dialog/dialog-wrapper.md | 277 +++++++++++++++++++++--------- 3 files changed, 474 insertions(+), 123 deletions(-) diff --git a/packages/dialog/README.md b/packages/dialog/README.md index f72988cf8ab..ca6b4e5c33d 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,23 +8,50 @@ [![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 +### Anatomy + +The dialog consists of several key parts: + +- 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. +
Footer information
+ Button + +``` + +### Options + +#### Sizes Small @@ -89,16 +116,14 @@ import { Dialog } from '@spectrum-web-components/dialog'; -## Variants - -### Dismissable +#### 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 @@ -113,10 +138,10 @@ Note: the `dissmissable` attribute will not be followed when `mode="fullscreen"` ``` -### No Divider +#### No Divider ```html - +

Disclaimer

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Auctor augue mauris @@ -131,24 +156,67 @@ Note: the `dissmissable` attribute will not be followed when `mode="fullscreen"` ``` -### Hero +### Behaviors + +Use the dialog with an overlay to create a dialog that appears over the current page. The dialog 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 ```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. - +Overlay Trigger + + + +

Overlay 1

+ 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. + + + + + Overlay Trigger 2 + + +

Overlay 2

+ 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. + + I understand + + + + ``` + +#### 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 + + +

Dialog Heading

+ 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. + + +``` + +### Accessibility + +The dialog 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 + +For more information on accessibility features, see the [Dialog Base](./dialog-base) component. 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. From 04852efe4bff56040f339a9b7abb0c0027ef1630 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 30 Apr 2025 16:19:12 -0400 Subject: [PATCH 02/11] docs: updated search index to boost title --- projects/documentation/scripts/build-search-index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/documentation/scripts/build-search-index.js b/projects/documentation/scripts/build-search-index.js index 61f3d381b97..3df6b56e8a2 100644 --- a/projects/documentation/scripts/build-search-index.js +++ b/projects/documentation/scripts/build-search-index.js @@ -164,7 +164,7 @@ async function main() { // Configure the index fields this.ref('metadata'); // Boost title field for higher relevance when matching titles - this.field('title', { boost: 10 }); + this.field('title', { boost: 100 }); this.field('body'); this.field('category'); From c409ff1d101843b007dad02ca477b99602e8ff93 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Wed, 30 Apr 2025 16:29:57 -0400 Subject: [PATCH 03/11] docs: updated search index --- projects/documentation/scripts/build-search-index.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/documentation/scripts/build-search-index.js b/projects/documentation/scripts/build-search-index.js index 3df6b56e8a2..b8bdea2363e 100644 --- a/projects/documentation/scripts/build-search-index.js +++ b/projects/documentation/scripts/build-search-index.js @@ -164,9 +164,9 @@ async function main() { // Configure the index fields this.ref('metadata'); // Boost title field for higher relevance when matching titles - this.field('title', { boost: 100 }); + this.field('title', { boost: 50 }); this.field('body'); - this.field('category'); + this.field('category', { boost: 10 }); // Add all documents to the index for (const document of documents) { From 51e479a62fd6b9793cb8ca1f835f54c3e1a6ac52 Mon Sep 17 00:00:00 2001 From: Casey Eickhoff <48574582+caseyisonit@users.noreply.github.com> Date: Wed, 30 Apr 2025 16:56:30 -0600 Subject: [PATCH 04/11] add popover to receives focus example --- packages/dialog/README.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/packages/dialog/README.md b/packages/dialog/README.md index ca6b4e5c33d..d480934dae0 100644 --- a/packages/dialog/README.md +++ b/packages/dialog/README.md @@ -202,12 +202,14 @@ The `receives-focus` attribute can be used to control whether the dialog should ```html Overlay Trigger - -

Dialog Heading

- 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. - + + +

Dialog Heading

+ 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. + + ``` From 4b4d0589b9f0b9ebb3d24f483748b5b3a57ca45e Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Thu, 1 May 2025 09:43:00 -0400 Subject: [PATCH 05/11] docs(dialog): added tabs instead of level 5 headings --- packages/dialog/dialog-base.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index c13d2ac460d..8894ce9f4ad 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -161,7 +161,9 @@ The `dismissable` attribute can be used to add an underlay element between the p The dialog base supports different display modes: -##### Fullscreen Mode + + Fullscreen Mode + ```html @@ -175,7 +177,9 @@ The dialog base supports different display modes: ``` -##### Fullscreen Takeover Mode + +Fullscreen Takeover Mode + ```html @@ -193,6 +197,9 @@ The dialog base supports different display modes: ``` + + + ### Behaviors The dialog base manages several behaviors: From f9e382be40cbf5d826d5a35ca559a2892f53c6fe Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 13:56:37 -0400 Subject: [PATCH 06/11] docs(dialog): added distinction between dialog base and dialog wrapper --- packages/dialog/dialog-base.md | 210 ++++-------------------------- packages/dialog/dialog-wrapper.md | 56 +++++--- 2 files changed, 63 insertions(+), 203 deletions(-) diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 8894ce9f4ad..92725427226 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -1,6 +1,20 @@ ## 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. +`DialogBase` is a foundational class that handles the core functionality of displaying and managing dialog content in an overlay. This base class provides the foundation for more specific dialog implementations like [`sp-dialog`](./dialog) and [`sp-dialog-wrapper`](./dialog-wrapper), handling the core functionality while allowing those implementations to focus on their specific features. + +Use `sp-dialog-wrapper`, or `DialogBase` when: + +- You need to present important information that requires user acknowledgment +- You're building a modal interface that blocks interaction with the page +- You need a structured container with features like backdrop/underlay +- Your content is complex and requires formal layout with headings, content sections, and actions + +Use [`sp-popover`](./popover) when: + +- You need a lightweight, contextual container that's positioned relative to a trigger element +- You want to display simple content like menus, tooltips, or additional options +- You're building a non-modal interface where users can still interact with the page +- You need an element with an arrow/tip pointing to the trigger ### Usage @@ -24,181 +38,33 @@ When looking to leverage the `DialogBase` base class as a type and/or for extens 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 - -``` - - -Medium - - -```html - - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

- - - Toggle Dialog - -``` +Extend the dialog base to create a new component that uses the same base functionality but with additional features. See [`DialogWrapper.ts`](https://github.com/adobe/spectrum-web-components/blob/main/packages/dialog/src/DialogWrapper.ts) for an example component that extends the dialog base. - -Large - - -```html - - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

- - - Toggle Dialog - +```ts +export class MyCustomDialog extends DialogBase { + public static override get styles(): CSSResultArray { + return [...super.styles]; + } + + protected override renderDialog(): TemplateResult { + ... + } +} ``` - - +### Options #### 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 - -``` - #### 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 - -``` - - - +The dialog base supports different display modes: `fullscreen` and `fullscreenTakeover`. ### Behaviors @@ -208,26 +74,6 @@ The dialog base manages several behaviors: 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: diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index c13d2ac460d..a03afd19b8c 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -1,6 +1,20 @@ ## 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. +`sp-dialog-wrapper` 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. + +Use `sp-dialog-wrapper` when: + +- You need to present important information that requires user acknowledgment +- You're building a modal interface that blocks interaction with the page +- You need a structured container with features like backdrop/underlay +- Your content is complex and requires formal layout with headings, content sections, and actions + +Use [`sp-popover`](./popover) when: + +- You need a lightweight, contextual container that's positioned relative to a trigger element +- You want to display simple content like menus, tooltips, or additional options +- You're building a non-modal interface where users can still interact with the page +- You need an element with an arrow/tip pointing to the trigger ### Usage @@ -12,10 +26,10 @@ 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'; +import '@spectrum-web-components/dialog/sp-dialog-wrapper.js'; ``` When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via: @@ -30,7 +44,7 @@ The dialog base consists of a single default slot that expects an [`sp-dialog` e ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -48,7 +62,7 @@ The dialog base consists of a single default slot that expects an [`sp-dialog` e Don't show me this again - + Toggle Dialog ``` @@ -65,12 +79,12 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

 - + Toggle Dialog ``` @@ -81,12 +95,12 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

 - + Toggle Dialog ``` @@ -97,12 +111,12 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

 - + Toggle Dialog ``` @@ -117,7 +131,7 @@ The `underlay` attribute can be used to add an underlay element between the page ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -135,7 +149,7 @@ The `underlay` attribute can be used to add an underlay element between the page Don't show me this again - + Toggle Dialog ``` @@ -147,12 +161,12 @@ The `dismissable` attribute can be used to add an underlay element between the p ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

 - + Toggle Dialog ``` @@ -165,12 +179,12 @@ The dialog base supports different display modes: ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

 - + Toggle Dialog ``` @@ -179,7 +193,7 @@ The dialog base supports different display modes: ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -188,7 +202,7 @@ The dialog base supports different display modes: to the components in specific.

- + Toggle Dialog ``` @@ -207,7 +221,7 @@ The `receives-focus` attribute can be used to control whether the dialog should ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -216,7 +230,7 @@ The `receives-focus` attribute can be used to control whether the dialog should to the components in specific.

- + Toggle Dialog ``` From be881722730929c41d0137d49c64f217ce5d5b67 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 13:58:08 -0400 Subject: [PATCH 07/11] docs: added more guidelines in documentation standards --- projects/documentation/content/guides/adding-component.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/projects/documentation/content/guides/adding-component.md b/projects/documentation/content/guides/adding-component.md index 4ad63666d96..65d9b61acc1 100644 --- a/projects/documentation/content/guides/adding-component.md +++ b/projects/documentation/content/guides/adding-component.md @@ -388,11 +388,16 @@ for an example. Each component's `packages/_componentname_/README.md`. These files must meet our standards below: - Heading structure must communicate the organization of the docs page. See W3C WAI's Tutorial on [Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/). -- Main headings (level 2 and 3) should be consistent from component to component. See W3C WAI's [Understanding SC 3.2: Predictable](https://www.w3.org/WAI/WCAG21/Understanding/predictable.html) and the [Documentation structure](#documentatio-structuren) section below. +- Main headings (level 2 and 3) should be consistent from component to component. See W3C WAI's [Understanding SC 3.2: Predictable](https://www.w3.org/WAI/WCAG21/Understanding/predictable.html) and the [Documentation structure](#documentation-structure) section below. +- Consider using `` for related sections/examples, such as tabs for each of the sizes, states, types, or variants. +- Consider using an `` to make content like keyboard actions easiert to read. +- Use the `` tag to semantically indicate keyboard input and make keyboard actions easier to read. +- Use the plain language to make the docs easier to understand. - All examples code must be accessible. - The example code must show the component with enough context to demonstrate how to use it with other elements in an accessible way. See how the examples in [`packages/help-text/README.md`](https://github.com/adobe/spectrum-web-components/blob/main/packages/help-text/README.md) show the component used with field elements. - The "Accessibility" section contains tips on how to use the component accessibly. See the Accessibility section of [`packages/picker/README.md`](https://github.com/adobe/spectrum-web-components/blob/main/packages/menu/README.md). - The "Accessibility" section contains notes on any accessibility considerations that affect the component's development. See the notes on cross-root ARIA in Accessibility section of [`packages/help-text/README.md`](https://github.com/adobe/spectrum-web-components/blob/main/packages/help-text/README.md). +- Check out the [Spectrum Design System documentation](https://spectrum.adobe.com/) to ensure our documentation is uses consistent langauge and component recommendations. #### Documentation structure From e35e5bb4a54a2798d4a28f6988e11faa023bde6a Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 15:34:36 -0400 Subject: [PATCH 08/11] docs(dialog): updated docs based on feedback --- packages/dialog/README.md | 8 +- packages/dialog/dialog-base.md | 72 +++++-- packages/dialog/dialog-wrapper.md | 316 +++++++++++++++++++++--------- 3 files changed, 288 insertions(+), 108 deletions(-) diff --git a/packages/dialog/README.md b/packages/dialog/README.md index d480934dae0..a1cbb33a2b8 100644 --- a/packages/dialog/README.md +++ b/packages/dialog/README.md @@ -2,6 +2,8 @@ `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. +Note: the `sp-dialog` element is a component that is used to create a dialog layout. For modal and popover behavior, it should be used within a component that manages the overlay state. + ### 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) @@ -205,9 +207,9 @@ The `receives-focus` attribute can be used to control whether the dialog should

Dialog Heading

- 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. + 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. diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 92725427226..0b177d52a19 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -2,14 +2,14 @@ `DialogBase` is a foundational class that handles the core functionality of displaying and managing dialog content in an overlay. This base class provides the foundation for more specific dialog implementations like [`sp-dialog`](./dialog) and [`sp-dialog-wrapper`](./dialog-wrapper), handling the core functionality while allowing those implementations to focus on their specific features. -Use `sp-dialog-wrapper`, or `DialogBase` when: +Use `DialogBase` when: - You need to present important information that requires user acknowledgment - You're building a modal interface that blocks interaction with the page - You need a structured container with features like backdrop/underlay - Your content is complex and requires formal layout with headings, content sections, and actions -Use [`sp-popover`](./popover) when: +Use an [`sp-popover`](./popover) when: - You need a lightweight, contextual container that's positioned relative to a trigger element - You want to display simple content like menus, tooltips, or additional options @@ -38,18 +38,33 @@ When looking to leverage the `DialogBase` base class as a type and/or for extens import { DialogBase } from '@spectrum-web-components/dialog'; ``` -Extend the dialog base to create a new component that uses the same base functionality but with additional features. See [`DialogWrapper.ts`](https://github.com/adobe/spectrum-web-components/blob/main/packages/dialog/src/DialogWrapper.ts) for an example component that extends the dialog base. - -```ts -export class MyCustomDialog extends DialogBase { - public static override get styles(): CSSResultArray { - return [...super.styles]; - } - - protected override renderDialog(): TemplateResult { - ... - } -} +### Anatomy + +The `sp-dialog-base` element is a wrapper that provides animation and positioning for the dialog 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 @@ -74,6 +89,35 @@ The dialog base manages several behaviors: 2. Focus management when the dialog opens 3. Event handling for closing the dialog +### Extending `DialogBase` + +Extend the dialog base to create a new component that uses the same base functionality but with additional features. + +`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 [`DialogWrapper.ts`](https://github.com/adobe/spectrum-web-components/blob/main/packages/dialog/src/DialogWrapper.ts) for an example component that extends the dialog base. + +```ts +import { DialogBase } from '@spectrum-web-components/dialog'; + +export class MyCustomDialogWrapper extends DialogBase { + public static override get styles(): CSSResultArray { + return [...super.styles]; + + protected override renderDialog(): TemplateResult { + return html` + + + + `; + } + + protected override get dialog(): Dialog { + return this.shadowRoot.querySelector('my-custom-dialog') as Dialog; + } +} +``` + ### Accessibility The dialog base component ensures proper focus management by: diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index a03afd19b8c..0eaa431df06 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -1,13 +1,13 @@ ## Overview -`sp-dialog-wrapper` 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. +`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`](./underlay) element between your page content and the [`sp-dialog`](./dialog) that opens over it. Use `sp-dialog-wrapper` when: - You need to present important information that requires user acknowledgment - You're building a modal interface that blocks interaction with the page - You need a structured container with features like backdrop/underlay -- Your content is complex and requires formal layout with headings, content sections, and actions +- Your content is requires formal layout with headings, content sections, and actions Use [`sp-popover`](./popover) when: @@ -32,36 +32,100 @@ Import the side effectful registration of `` via: import '@spectrum-web-components/dialog/sp-dialog-wrapper.js'; ``` -When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via: +### Anatomy -```ts -import { DialogBase } from '@spectrum-web-components/dialog'; +The dialog wrapper is a high-level component that combines the [`sp-dialog-base`](./dialog-base) functionality and the [`sp-dialog`](./dialog) layout and stylingwith an attribute-based API. + +```html + + + Content of the dialog + + Toggle Dialog + ``` -### Anatomy +#### Hero -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. +The hero content is displayed above the dialog content. Use the `hero` attribute to provide the hero 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 - + + Content of the dialog + + Toggle Dialog + +``` + +#### Headline + +The headline content is displayed as the dialog title. Use the `headline` attribute to provide the headline content. + +```html + + + Content of the dialog + + Toggle Dialog + +``` + +#### Footer + +The footer content is displayed as below the dialog content. Use the `footer` attribute to provide the footer content. + +```html + + + Content of the dialog + + Toggle Dialog + +``` + +#### Buttons + +The dialog wrapper supports different buttons via the `confirm-label`, `cancel-label`, `secondary-label`, `dismiss-label` attributes. + +```html + + + Content of the dialog Toggle Dialog @@ -79,11 +143,16 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

- + + Content of the dialog Toggle Dialog @@ -95,11 +164,16 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

- + + Content of the dialog Toggle Dialog @@ -111,11 +185,16 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, ```html - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

- + + Content of the dialog Toggle Dialog @@ -128,62 +207,110 @@ The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, The `underlay` attribute can be used to add an underlay element between the page content and the dialog. + + With underlay + + +```html + + + Content of the dialog + + Toggle Dialog + +``` + + +Without underlay + + ```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 - + + Content of the dialog Toggle Dialog ``` + + + #### Dismissable The `dismissable` attribute can be used to add an underlay element between the page content and the dialog. + + Dismissable + + +```html + + + Content of the dialog + + Toggle Dialog + +``` + + +Not dismissable + + ```html - - - -

A thing is about to happen

-

Something that might happen a lot is about to happen.

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

A thing is about to happen

-

Something that might happen a lot is about to happen.

- + + Content of the dialog Toggle Dialog @@ -193,15 +320,15 @@ The dialog base supports different display modes: ```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. -

- + + Content of the dialog Toggle Dialog @@ -209,7 +336,7 @@ The dialog base supports different display modes: ### Behaviors -The dialog base manages several behaviors: +The dialog wrapper manages several behaviors: 1. Animation of the dialog content when opening/closing 2. Focus management when the dialog opens @@ -221,15 +348,16 @@ The `receives-focus` attribute can be used to control whether the dialog should ```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. -

- + + Content of the dialog Toggle Dialog @@ -237,7 +365,13 @@ The `receives-focus` attribute can be used to control whether the dialog should ### Accessibility -The dialog base component ensures proper focus management by: +#### Include a headline + +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. + +#### Focus management + +The dialog wrapper component ensures proper focus management by: - Moving focus into the dialog when opened - Trapping tab order within the dialog while open From 14b61d060d96dbf96e55b8067552970466723cf1 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 15:57:33 -0400 Subject: [PATCH 09/11] docs(dialog): updated docs based on feedback --- packages/dialog/dialog-base.md | 147 +++++++++++++++++++++++++++++- packages/dialog/dialog-wrapper.md | 101 ++------------------ 2 files changed, 156 insertions(+), 92 deletions(-) diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 0b177d52a19..34e825f925a 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -45,7 +45,7 @@ The `sp-dialog-base` element is a wrapper that provides animation and positionin ```html - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -73,14 +73,159 @@ The `sp-dialog-base` element is a wrapper that provides animation and positionin The `underlay` attribute can be used to add an underlay element between the page content and the dialog. + + With underlay + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + Ok + + + + Toggle Dialog + +``` + + +Without underlay + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

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

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + + Toggle Dialog + +``` + + +Not dismissable + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + Ok + + + + Toggle Dialog + +``` + + + + #### Mode The dialog base supports different display modes: `fullscreen` and `fullscreenTakeover`. + + Fullscreen + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + Ok + + + + Toggle Dialog + +``` + + +Fullscreen Takeover + + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + Ok + + + + Toggle Dialog + +``` + + + + ### Behaviors The dialog base manages several behaviors: diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index 0eaa431df06..0f55856bb87 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -2,20 +2,6 @@ `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`](./underlay) element between your page content and the [`sp-dialog`](./dialog) that opens over it. -Use `sp-dialog-wrapper` when: - -- You need to present important information that requires user acknowledgment -- You're building a modal interface that blocks interaction with the page -- You need a structured container with features like backdrop/underlay -- Your content is requires formal layout with headings, content sections, and actions - -Use [`sp-popover`](./popover) when: - -- You need a lightweight, contextual container that's positioned relative to a trigger element -- You want to display simple content like menus, tooltips, or additional options -- You're building a non-modal interface where users can still interact with the page -- You need an element with an arrow/tip pointing to the trigger - ### 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) @@ -36,94 +22,27 @@ import '@spectrum-web-components/dialog/sp-dialog-wrapper.js'; The dialog wrapper is a high-level component that combines the [`sp-dialog-base`](./dialog-base) functionality and the [`sp-dialog`](./dialog) layout and stylingwith an attribute-based API. -```html - - - Content of the dialog - - Toggle Dialog - -``` - -#### Hero - -The hero content is displayed above the dialog content. Use the `hero` attribute to provide the hero content. - -```html - - - Content of the dialog - - Toggle Dialog - -``` - -#### Headline +The dialog wrapper consists of several key parts: -The headline content is displayed as the dialog title. Use the `headline` attribute to provide the headline content. - -```html - - - Content of the dialog - - Toggle Dialog - -``` - -#### Footer - -The footer content is displayed as below the dialog content. Use the `footer` attribute to provide the footer content. - -```html - - - Content of the dialog - - Toggle Dialog - -``` - -#### Buttons - -The dialog wrapper supports different buttons via the `confirm-label`, `cancel-label`, `secondary-label`, `dismiss-label` attributes. +- A headline used as the dialog title (via the `headline` attribute) +- Content (via default slot) +- Optional hero content (via the `hero` attribute) +- Optional footer content (via the `footer` attribute) +- Optional underlay (via the `underlay` attribute) +- Optional buttons (via the `confirm-label`, `cancel-label`, and `secondary-label` attributes) +- Optional dismiss button (via the `dismissable` attribute and the `dismiss-label` attribute) ```html Content of the dialog From d97dacc8cebf3baf17620ebea808f24fc9421ab9 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 16:16:20 -0400 Subject: [PATCH 10/11] docs(dialog): updated docs based on feedback --- packages/dialog/README.md | 16 ++++--- packages/dialog/dialog-base.md | 76 +++++++++++++++++++++---------- packages/dialog/dialog-wrapper.md | 42 ++++++++--------- 3 files changed, 82 insertions(+), 52 deletions(-) diff --git a/packages/dialog/README.md b/packages/dialog/README.md index a1cbb33a2b8..072ee61d86c 100644 --- a/packages/dialog/README.md +++ b/packages/dialog/README.md @@ -201,6 +201,14 @@ Use the dialog with an overlay to create a dialog that appears over the current 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. +The `receives-focus` attribute on `overlay-trigger` has three possible values: + +- `auto` (default): Focus will automatically move to the first focusable element in the dialog +- `true`: Forces focus to move to the overlay content +- `false`: Prevents focus from moving to the overlay + +For accessible dialogs, always use `receives-focus="auto"` or `receives-focus="true"` to ensure keyboard users can interact with the dialog content. + ```html Overlay Trigger @@ -217,10 +225,6 @@ The `receives-focus` attribute can be used to control whether the dialog should ### Accessibility -The dialog 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 +#### Include a heading -For more information on accessibility features, see the [Dialog Base](./dialog-base) component. +The `heading` slot is of the `sp-dialog` dialog element is used to label the dialog content for screen readers. diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 34e825f925a..1705a082d44 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -2,20 +2,6 @@ `DialogBase` is a foundational class that handles the core functionality of displaying and managing dialog content in an overlay. This base class provides the foundation for more specific dialog implementations like [`sp-dialog`](./dialog) and [`sp-dialog-wrapper`](./dialog-wrapper), handling the core functionality while allowing those implementations to focus on their specific features. -Use `DialogBase` when: - -- You need to present important information that requires user acknowledgment -- You're building a modal interface that blocks interaction with the page -- You need a structured container with features like backdrop/underlay -- Your content is complex and requires formal layout with headings, content sections, and actions - -Use an [`sp-popover`](./popover) when: - -- You need a lightweight, contextual container that's positioned relative to a trigger element -- You want to display simple content like menus, tooltips, or additional options -- You're building a non-modal interface where users can still interact with the page -- You need an element with an arrow/tip pointing to the trigger - ### 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) @@ -42,6 +28,26 @@ import { DialogBase } from '@spectrum-web-components/dialog'; The `sp-dialog-base` element is a wrapper that provides animation and positioning for the dialog content. +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 + +Use `DialogBase` when: + +- You need to present important information that requires user acknowledgment +- You're building a modal interface that blocks interaction with the page +- You need a structured container with features like backdrop/underlay +- Your content is complex and requires formal layout with headings, content sections, and actions + +Use an [`sp-popover`](./popover) when: + +- You need a lightweight, contextual container that's positioned relative to a trigger element +- You want to display simple content like menus, tooltips, or additional options +- You're building a non-modal interface where users can still interact with the page +- You need an element with an arrow/tip pointing to the trigger + ```html @@ -226,14 +232,6 @@ The dialog base supports different display modes: `fullscreen` and `fullscreenTa -### 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 - ### Extending `DialogBase` Extend the dialog base to create a new component that uses the same base functionality but with additional features. @@ -265,10 +263,42 @@ export class MyCustomDialogWrapper extends DialogBase { ### Accessibility +#### Include a heading + +The `heading` slot is of the `sp-dialog` dialog element is used to label the dialog content for screen readers. + +#### Manage focus + 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 -See the [Dialog](./dialog) component for more information on the accessibility features of the dialog content. +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. + +The `receives-focus` attribute on `overlay-trigger` has three possible values: + +- `auto` (default): Focus will automatically move to the first focusable element in the dialog +- `true`: Forces focus to move to the overlay content +- `false`: Prevents focus from moving to the overlay + +```html + + + +

A thing is about to happen

+

Something that might happen a lot is about to happen.

+ + Ok + + + + Toggle Dialog + +``` diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index 0f55856bb87..a990bc18139 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -253,20 +253,32 @@ The dialog wrapper supports different display modes: ``` -### Behaviors +### Accessibility -The dialog wrapper manages several behaviors: +#### Include a headline -1. Animation of the dialog content when opening/closing -2. Focus management when the dialog opens -3. Event handling for closing the dialog +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. -#### Receives focus +#### Manage focus + +The dialog wrapper 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 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. +The `receives-focus` attribute on `overlay-trigger` has three possible values: + +- `auto` (default): Focus will automatically move to the first focusable element in the dialog +- `true`: Forces focus to move to the overlay content +- `false`: Prevents focus from moving to the overlay + +For accessible dialogs, always use `receives-focus="auto"` or `receives-focus="true"` to ensure keyboard users can interact with the dialog content. + ```html - + Toggle Dialog ``` - -### Accessibility - -#### Include a headline - -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. - -#### Focus management - -The dialog wrapper 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 - -See the [Dialog](./dialog) component for more information on the accessibility features of the dialog content. From f248c074a40c244bd7a3bdf0dbd67711148a9254 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 5 May 2025 16:19:57 -0400 Subject: [PATCH 11/11] docs(dialog): updated docs based on feedback --- packages/dialog/dialog-base.md | 2 +- packages/dialog/dialog-wrapper.md | 11 +++++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/packages/dialog/dialog-base.md b/packages/dialog/dialog-base.md index 1705a082d44..77c950a034a 100644 --- a/packages/dialog/dialog-base.md +++ b/packages/dialog/dialog-base.md @@ -181,7 +181,7 @@ The `dismissable` attribute can be used to add an underlay element between the p The dialog base supports different display modes: `fullscreen` and `fullscreenTakeover`. - + Fullscreen diff --git a/packages/dialog/dialog-wrapper.md b/packages/dialog/dialog-wrapper.md index a990bc18139..89396ef3d5d 100644 --- a/packages/dialog/dialog-wrapper.md +++ b/packages/dialog/dialog-wrapper.md @@ -217,7 +217,9 @@ The `dismissable` attribute can be used to add an underlay element between the p The dialog wrapper supports different display modes: -##### Fullscreen Mode + + Fullscreen + ```html @@ -235,7 +237,9 @@ The dialog wrapper supports different display modes: ``` -##### Fullscreen Takeover Mode + +Fullscreen Takeover + ```html @@ -253,6 +257,9 @@ The dialog wrapper supports different display modes: ``` + + + ### Accessibility #### Include a headline