diff --git a/packages/dialog/README.md b/packages/dialog/README.md index f72988cf8ab..072ee61d86c 100644 --- a/packages/dialog/README.md +++ b/packages/dialog/README.md @@ -1,30 +1,59 @@ -## 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. +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) [![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 +118,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 +140,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 +158,73 @@ 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. + +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 + + + +

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 + +#### Include a heading + +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 90a32a34d6b..77c950a034a 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. +`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. ### Usage @@ -8,28 +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/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 `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 - +

A thing is about to happen

Something that might happen a lot is about to happen.

@@ -51,6 +73,232 @@ import { DialogBase } from '@spectrum-web-components/dialog'; ``` -## Dialog +### Options + +#### Underlay + +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 + +``` + + + + +### 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 + +#### 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 + +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 7aacb05e676..89396ef3d5d 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-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. ### Usage @@ -8,25 +8,127 @@ [![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-wrapper.js'; ``` -When looking to leverage the `DialogWrapper` base class as a type and/or for extension purposes, do so via: +### Anatomy + +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. + +The dialog wrapper consists of several key parts: + +- 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 + + Toggle Dialog + +``` + +### Options + +#### Sizes + +The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, `l`. + + + Small + + +```html + + + Content of the dialog + + Toggle Dialog + +``` + + +Medium + +```html + + + Content of the dialog + + Toggle Dialog + ``` -import { DialogWrapper } from '@spectrum-web-components/dialog'; + + +Large + + +```html + + + Content of the dialog + + Toggle Dialog + ``` -## Example + + + +#### Underlay + +The `underlay` attribute can be used to add an underlay element between the page content and the dialog. -### Small + + With underlay + ```html @@ -44,82 +146,157 @@ import { DialogWrapper } from '@spectrum-web-components/dialog'; ``` -### Fullscreen Mode + +Without underlay + ```html + 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 + + - Toggle Dialog - + Content of the dialog + + Toggle Dialog ``` -### Fullscreen Takeover Mode + + + +#### Mode + +The dialog wrapper supports different display modes: + + + Fullscreen + ```html Content of the dialog - Toggle Dialog + +``` + + +Fullscreen Takeover + + +```html + + - Toggle Dialog - + Content of the dialog + + Toggle Dialog ``` -## Accessibility + + + +### 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. + +#### Manage focus + +The dialog wrapper component ensures proper focus management by: -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. +- 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 + + + Content of the dialog + + Toggle Dialog + +``` 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 diff --git a/projects/documentation/scripts/build-search-index.js b/projects/documentation/scripts/build-search-index.js index 61f3d381b97..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: 10 }); + 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) {