Skip to content

Commit 062ea44

Browse files
nikkimknikkimk
authored
docs(dialog): testing dialo-wrapper for test fails
1 parent 5bc2cbf commit 062ea44

File tree

1 file changed

+192
-85
lines changed

1 file changed

+192
-85
lines changed

‎packages/dialog/dialog-wrapper.md

+192-85
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,232 @@
1-
## Description
1+
## Overview
22

3-
`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.
3+
`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.
44

55
### Usage
66

77
[![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)
88
[![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)
99
[![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)
1010

11-
```
11+
```bash
1212
yarn add @spectrum-web-components/dialog
1313
```
1414

15-
Import the side effectful registration of `<sp-dialog-wrapper>` via:
15+
Import the side effectful registration of `<sp-dialog-base>` via:
16+
17+
```ts
18+
import '@spectrum-web-components/dialog/sp-dialog-base.js';
19+
```
20+
21+
When looking to leverage the `DialogBase` base class as a type and/or for extension purposes, do so via:
22+
23+
```ts
24+
import { DialogBase } from '@spectrum-web-components/dialog';
25+
```
26+
27+
### Anatomy
28+
29+
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.
30+
31+
```html
32+
<overlay-trigger type="modal">
33+
<sp-dialog-base slot="click-content">
34+
<sp-dialog>
35+
<h2 slot="heading">A thing is about to happen</h2>
36+
<p>Something that might happen a lot is about to happen.</p>
37+
<p>
38+
The click events for the "OK" button are bound to the story not
39+
to the components in specific.
40+
</p>
41+
<sp-button
42+
variant="secondary"
43+
treatment="fill"
44+
slot="button"
45+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
46+
>
47+
Ok
48+
</sp-button>
49+
<sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
50+
</sp-dialog>
51+
</sp-dialog-base>
52+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
53+
</overlay-trigger>
54+
```
55+
56+
### Options
57+
58+
#### Sizes
59+
60+
The dialog wrapper supports different sizes via the `size` attribute: `s`, `m`, `l`.
61+
62+
<sp-tabs selected="m" auto label="Size attribute options">
63+
<sp-tab value="s">Small</sp-tab>
64+
<sp-tab-panel value="s">
1665

66+
```html
67+
<overlay-trigger type="modal">
68+
<sp-dialog-base underlay slot="click-content" size="s">
69+
<sp-dialog size="s" dismissable>
70+
<h2 slot="heading">A thing is about to happen</h2>
71+
<p>Something that might happen a lot is about to happen.</p>
72+
</sp-dialog>
73+
</sp-dialog-base>
74+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
75+
</overlay-trigger>
1776
```
18-
import '@spectrum-web-components/dialog/sp-dialog-wrapper.js';
77+
78+
</sp-tab-panel>
79+
<sp-tab value="m">Medium</sp-tab>
80+
<sp-tab-panel value="m">
81+
82+
```html
83+
<overlay-trigger type="modal">
84+
<sp-dialog-base underlay slot="click-content" size="m">
85+
<sp-dialog dismissable>
86+
<h2 slot="heading">A thing is about to happen</h2>
87+
<p>Something that might happen a lot is about to happen.</p>
88+
</sp-dialog>
89+
</sp-dialog-base>
90+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
91+
</overlay-trigger>
1992
```
2093

21-
When looking to leverage the `DialogWrapper` base class as a type and/or for extension purposes, do so via:
94+
</sp-tab-panel>
95+
<sp-tab value="l">Large</sp-tab>
96+
<sp-tab-panel value="l">
2297

98+
```html
99+
<overlay-trigger type="modal">
100+
<sp-dialog-base underlay slot="click-content" size="l">
101+
<sp-dialog dismissable>
102+
<h2 slot="heading">A thing is about to happen</h2>
103+
<p>Something that might happen a lot is about to happen.</p>
104+
</sp-dialog>
105+
</sp-dialog-base>
106+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
107+
</overlay-trigger>
23108
```
24-
import { DialogWrapper } from '@spectrum-web-components/dialog';
109+
110+
</sp-tab-panel>
111+
</sp-tabs>
112+
113+
#### Underlay
114+
115+
The `underlay` attribute can be used to add an underlay element between the page content and the dialog.
116+
117+
```html
118+
</style>
119+
<overlay-trigger type="modal">
120+
<sp-dialog-base underlay slot="click-content">
121+
<sp-dialog>
122+
<h2 slot="heading">A thing is about to happen</h2>
123+
<p>Something that might happen a lot is about to happen.</p>
124+
<p>
125+
The click events for the "OK" button are bound to the story not
126+
to the components in specific.
127+
</p>
128+
<sp-button
129+
variant="secondary"
130+
treatment="fill"
131+
slot="button"
132+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
133+
>
134+
Ok
135+
</sp-button>
136+
<sp-checkbox slot="footer">Don't show me this again</sp-checkbox>
137+
</sp-dialog>
138+
</sp-dialog-base>
139+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
140+
</overlay-trigger>
25141
```
26142

27-
## Example
143+
#### Dismissable
28144

29-
### Small
145+
The `dismissable` attribute can be used to add an underlay element between the page content and the dialog.
30146

31147
```html
148+
</style>
32149
<overlay-trigger type="modal">
33-
<sp-dialog-wrapper
34-
slot="click-content"
35-
headline="Dialog title"
36-
dismissable
37-
dismiss-label="Close"
38-
underlay
39-
footer="Content for footer"
40-
>
41-
Content of the dialog
42-
</sp-dialog-wrapper>
150+
<sp-dialog-base underlay slot="click-content">
151+
<sp-dialog dismissable>
152+
<h2 slot="heading">A thing is about to happen</h2>
153+
<p>Something that might happen a lot is about to happen.</p>
154+
</sp-dialog>
155+
</sp-dialog-base>
43156
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
44157
</overlay-trigger>
45158
```
46159

47-
### Fullscreen Mode
160+
#### Mode
161+
162+
The dialog base supports different display modes:
163+
164+
##### Fullscreen Mode
48165

49166
```html
50167
<overlay-trigger type="modal">
51-
<sp-dialog-wrapper
52-
slot="click-content"
53-
headline="Dialog title"
54-
mode="fullscreen"
55-
confirm-label="Keep Both"
56-
secondary-label="Replace"
57-
cancel-label="Cancel"
58-
footer="Content for footer"
59-
>
60-
Content of the dialog
61-
</sp-dialog-wrapper>
62-
<sp-button
63-
slot="trigger"
64-
variant="primary"
65-
onClick="
66-
const overlayTrigger = this.parentElement;
67-
const dialogWrapper = overlayTrigger.clickContent;
68-
function handleEvent({type}) {
69-
spAlert(this, `<sp-dialog-wrapper> '${type}' event handled.`);
70-
dialogWrapper.open = false;
71-
dialogWrapper.removeEventListener('confirm', handleEvent);
72-
dialogWrapper.removeEventListener('secondary', handleEvent);
73-
dialogWrapper.removeEventListener('cancel', handleEvent);
74-
}
75-
dialogWrapper.addEventListener('confirm', handleEvent);
76-
dialogWrapper.addEventListener('secondary', handleEvent);
77-
dialogWrapper.addEventListener('cancel', handleEvent);
78-
"
79-
>
80-
Toggle Dialog
81-
</sp-button>
168+
<sp-dialog-base underlay mode="fullscreen" slot="click-content">
169+
<sp-dialog dismissable>
170+
<h2 slot="heading">A thing is about to happen</h2>
171+
<p>Something that might happen a lot is about to happen.</p>
172+
</sp-dialog>
173+
</sp-dialog-base>
174+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
82175
</overlay-trigger>
83176
```
84177

85-
### Fullscreen Takeover Mode
178+
##### Fullscreen Takeover Mode
86179

87180
```html
88181
<overlay-trigger type="modal">
89-
<sp-dialog-wrapper
90-
slot="click-content"
91-
headline="Dialog title"
92-
mode="fullscreenTakeover"
93-
confirm-label="Keep Both"
94-
secondary-label="Replace"
95-
cancel-label="Cancel"
96-
footer="Content for footer"
97-
>
98-
Content of the dialog
99-
</sp-dialog-wrapper>
100-
<sp-button
101-
slot="trigger"
102-
variant="primary"
103-
onClick="
104-
const overlayTrigger = this.parentElement;
105-
const dialogWrapper = overlayTrigger.clickContent;
106-
function handleEvent({type}) {
107-
spAlert(this, `<sp-dialog-wrapper> '${type}' event handled.`);
108-
dialogWrapper.open = false;
109-
dialogWrapper.removeEventListener('confirm', handleEvent);
110-
dialogWrapper.removeEventListener('secondary', handleEvent);
111-
dialogWrapper.removeEventListener('cancel', handleEvent);
112-
}
113-
dialogWrapper.addEventListener('confirm', handleEvent);
114-
dialogWrapper.addEventListener('secondary', handleEvent);
115-
dialogWrapper.addEventListener('cancel', handleEvent);
116-
"
117-
>
118-
Toggle Dialog
119-
</sp-button>
182+
<sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
183+
<sp-dialog dismissable>
184+
<h2 slot="heading">A thing is about to happen</h2>
185+
<p>Something that might happen a lot is about to happen.</p>
186+
<p>
187+
The click events for the "OK" button are bound to the story not
188+
to the components in specific.
189+
</p>
190+
</sp-dialog>
191+
</sp-dialog-base>
192+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
193+
</overlay-trigger>
194+
```
195+
196+
### Behaviors
197+
198+
The dialog base manages several behaviors:
199+
200+
1. Animation of the dialog content when opening/closing
201+
2. Focus management when the dialog opens
202+
3. Event handling for closing the dialog
203+
204+
#### Receives focus
205+
206+
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.
207+
208+
```html
209+
<overlay-trigger type="modal" receives-focus="auto">
210+
<sp-dialog-base underlay mode="fullscreenTakeover" slot="click-content">
211+
<sp-dialog dismissable>
212+
<h2 slot="heading">A thing is about to happen</h2>
213+
<p>Something that might happen a lot is about to happen.</p>
214+
<p>
215+
The click events for the "OK" button are bound to the story not
216+
to the components in specific.
217+
</p>
218+
</sp-dialog>
219+
</sp-dialog-base>
220+
<sp-button slot="trigger" variant="primary">Toggle Dialog</sp-button>
120221
</overlay-trigger>
121222
```
122223

123-
## Accessibility
224+
### Accessibility
225+
226+
The dialog base component ensures proper focus management by:
227+
228+
- Moving focus into the dialog when opened
229+
- Trapping tab order within the dialog while open
230+
- Returning focus to the trigger element when closed
124231

125-
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.
232+
See the [Dialog](./dialog) component for more information on the accessibility features of the dialog content.

0 commit comments

Comments
 (0)