@spectrum-web-components/alert-dialog 1.5.1-beta.0 → 1.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +215 -66
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,41 +1,47 @@
|
|
|
1
|
-
##
|
|
1
|
+
## Overview
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`<sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby="">` displays important information that users need to acknowledge. When used directly, the `<sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby="">` element surfaces a `slot` based API for deep customization of the content to be included in the overlay.
|
|
4
4
|
|
|
5
5
|
### Usage
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/@spectrum-web-components/alert-dialog)
|
|
8
8
|
[](https://bundlephobia.com/result?p=@spectrum-web-components/alert-dialog)
|
|
9
9
|
|
|
10
|
-
```
|
|
10
|
+
```bash
|
|
11
11
|
yarn add @spectrum-web-components/alert-dialog
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
-
Import the side effectful registration of `<sp-alert-dialog>` via:
|
|
14
|
+
Import the side effectful registration of `<sp-alert-dialog role="alertdialog" aria-labelledby="xx-heading" aria-describedby="xx-message" role="alertdialog" aria-labelledby="" aria-describedby="">` via:
|
|
15
15
|
|
|
16
|
-
```
|
|
16
|
+
```javascript
|
|
17
17
|
import '@spectrum-web-components/alert-dialog/sp-alert-dialog.js';
|
|
18
18
|
```
|
|
19
19
|
|
|
20
20
|
When looking to leverage the `AlertDialog` base class as a type and/or for extension purposes, do so via:
|
|
21
21
|
|
|
22
|
-
```
|
|
22
|
+
```javascript
|
|
23
23
|
import { AlertDialog } from '@spectrum-web-components/alert-dialog';
|
|
24
24
|
```
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
### Anatomy
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
The alert dialog consists of several key parts:
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
- **Title:** All alert dialogs must have a title, using `slot="heading"`, that uses a few words to convey the outcome of what will happen if a user continues with an action
|
|
31
|
+
- **Content:** Alert dialogs can include a description using the default slot. A description briefly communicates any additional information or context that a user needs to know to continue with an action
|
|
32
|
+
- Action buttons, using `slot="button"`, that allow users to respond
|
|
31
33
|
|
|
32
34
|
```html
|
|
33
|
-
<sp-alert-dialog
|
|
34
|
-
|
|
35
|
-
|
|
35
|
+
<sp-alert-dialog
|
|
36
|
+
role="alertdialog"
|
|
37
|
+
aria-labelledby="example-heading"
|
|
38
|
+
aria-describedby="example-message"
|
|
39
|
+
variant="confirmation"
|
|
40
|
+
>
|
|
41
|
+
<h2 id="example-heading" slot="heading">Important Notice</h2>
|
|
42
|
+
<p id="example-message">This action requires your confirmation.</p>
|
|
36
43
|
<sp-button
|
|
37
44
|
slot="button"
|
|
38
|
-
id="cancelButton"
|
|
39
45
|
variant="secondary"
|
|
40
46
|
treatment="outline"
|
|
41
47
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
@@ -44,58 +50,89 @@ This is the default variant for alert dialogs. Use a confirmation variant for as
|
|
|
44
50
|
</sp-button>
|
|
45
51
|
<sp-button
|
|
46
52
|
slot="button"
|
|
47
|
-
id="confirmButton"
|
|
48
53
|
variant="accent"
|
|
49
54
|
treatment="fill"
|
|
50
55
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
51
56
|
>
|
|
52
|
-
|
|
57
|
+
Confirm
|
|
53
58
|
</sp-button>
|
|
54
59
|
</sp-alert-dialog>
|
|
55
60
|
```
|
|
56
61
|
|
|
57
|
-
|
|
62
|
+
#### Buttons
|
|
58
63
|
|
|
59
|
-
|
|
64
|
+
Use `slot="button"` to render your action button(s) that allow users to respond
|
|
65
|
+
|
|
66
|
+
- An alert dialog must have one primary action button (with `variant="primary"`) with the option to include a secondary action and/or a cancel action.
|
|
67
|
+
- Non-primary action buttons should be `variant="secondary"` and `treatment="outline"`.
|
|
68
|
+
- The three buttons should be rendered in the DOM in the following order:
|
|
69
|
+
- **Cancel action:** Offers an option to go back and cancel the action.
|
|
70
|
+
- **Secondary action:** Offers a secondary action. e.g. "Remind me later"
|
|
71
|
+
- **Primary action:** The first (right-most) button communicates what the button will do if selected, or to acknowledge and dismiss the dialog. Check [variants](#variants) for the correct primary button styling. See also the [Alert Dialog design options](https://spectrum.adobe.com/page/alert-dialog/#Options).
|
|
60
72
|
|
|
61
73
|
```html
|
|
62
|
-
<sp-alert-dialog
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
74
|
+
<sp-alert-dialog
|
|
75
|
+
role="alertdialog"
|
|
76
|
+
aria-labelledby="rate-heading"
|
|
77
|
+
aria-describedby="rate-message"
|
|
78
|
+
variant="information"
|
|
79
|
+
>
|
|
80
|
+
<h2 id="rate-heading" slot="heading">Rate this app</h2>
|
|
81
|
+
<p id="rate-message">
|
|
82
|
+
If you enjoy our app, would you mind taking a moment to rate it?
|
|
83
|
+
</p>
|
|
66
84
|
<sp-button
|
|
67
85
|
slot="button"
|
|
68
|
-
id="cancelButton"
|
|
69
86
|
variant="secondary"
|
|
70
87
|
treatment="outline"
|
|
71
88
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
72
89
|
>
|
|
73
|
-
|
|
90
|
+
No, thanks
|
|
91
|
+
</sp-button>
|
|
92
|
+
<sp-button
|
|
93
|
+
slot="button"
|
|
94
|
+
variant="secondary"
|
|
95
|
+
treatment="outline"
|
|
96
|
+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
97
|
+
>
|
|
98
|
+
Remind me later
|
|
74
99
|
</sp-button>
|
|
75
100
|
<sp-button
|
|
76
101
|
slot="button"
|
|
77
|
-
id="confirmButton"
|
|
78
102
|
variant="primary"
|
|
79
103
|
treatment="outline"
|
|
80
104
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
81
105
|
>
|
|
82
|
-
|
|
106
|
+
Rate now
|
|
83
107
|
</sp-button>
|
|
84
108
|
</sp-alert-dialog>
|
|
85
109
|
```
|
|
86
110
|
|
|
87
|
-
###
|
|
111
|
+
### Options
|
|
88
112
|
|
|
89
|
-
|
|
113
|
+
#### Variants
|
|
114
|
+
|
|
115
|
+
The alert dialog supports `confirmation`, `information`, `warning`, `error`, and `destructive` variants to convey the nature and importance of the message:
|
|
116
|
+
|
|
117
|
+
<sp-tabs selected="confirmation" auto label="Variants">
|
|
118
|
+
<sp-tab value="confirmation">Confirmation</sp-tab>
|
|
119
|
+
<sp-tab-panel value="confirmation">
|
|
120
|
+
|
|
121
|
+
Confirmation is the default variant for alert dialogs. Use a confirmation variant for asking a user to confirm a choice.
|
|
90
122
|
|
|
91
123
|
```html
|
|
92
|
-
<sp-alert-dialog
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
124
|
+
<sp-alert-dialog
|
|
125
|
+
role="alertdialog"
|
|
126
|
+
aria-labelledby="disclaimer-heading"
|
|
127
|
+
aria-describedby="disclaimer-message"
|
|
128
|
+
variant="confirmation"
|
|
129
|
+
>
|
|
130
|
+
<h2 id="disclaimer-heading" slot="heading">Disclaimer</h2>
|
|
131
|
+
<p id="disclaimer-message">
|
|
132
|
+
Smart filters are nondestructive and will preserve your original images.
|
|
133
|
+
</p>
|
|
96
134
|
<sp-button
|
|
97
135
|
slot="button"
|
|
98
|
-
id="cancelButton"
|
|
99
136
|
variant="secondary"
|
|
100
137
|
treatment="outline"
|
|
101
138
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
@@ -104,28 +141,43 @@ Warning alert dialogs communicate important information to users in relation to
|
|
|
104
141
|
</sp-button>
|
|
105
142
|
<sp-button
|
|
106
143
|
slot="button"
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
treatment="outline"
|
|
144
|
+
variant="accent"
|
|
145
|
+
treatment="fill"
|
|
110
146
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
111
147
|
>
|
|
112
|
-
|
|
148
|
+
Enable
|
|
113
149
|
</sp-button>
|
|
114
150
|
</sp-alert-dialog>
|
|
115
151
|
```
|
|
116
152
|
|
|
117
|
-
|
|
153
|
+
</sp-tab-panel>
|
|
154
|
+
<sp-tab value="information">Information</sp-tab>
|
|
155
|
+
<sp-tab-panel value="information">
|
|
118
156
|
|
|
119
|
-
|
|
157
|
+
Information alert dialogs communicate important information that a user needs to acknowledge. Before using this kind of alert dialog, make sure it’s the appropriate communication channel for the message instead of a toast or a more lightweight messaging option.
|
|
120
158
|
|
|
121
159
|
```html
|
|
122
|
-
<sp-alert-dialog
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
160
|
+
<sp-alert-dialog
|
|
161
|
+
role="alertdialog"
|
|
162
|
+
aria-labelledby="information-heading"
|
|
163
|
+
aria-describedby="information-message"
|
|
164
|
+
variant="information"
|
|
165
|
+
>
|
|
166
|
+
<h2 id="information-heading" slot="heading">Connect to wifi</h2>
|
|
167
|
+
<p id="information-message">
|
|
168
|
+
Please connect to wifi to sync your projects or go to Settings to change
|
|
169
|
+
your preferences.
|
|
170
|
+
</p>
|
|
171
|
+
<sp-button
|
|
172
|
+
slot="button"
|
|
173
|
+
variant="secondary"
|
|
174
|
+
treatment="outline"
|
|
175
|
+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
176
|
+
>
|
|
177
|
+
Cancel
|
|
178
|
+
</sp-button>
|
|
126
179
|
<sp-button
|
|
127
180
|
slot="button"
|
|
128
|
-
id="confirmButton"
|
|
129
181
|
variant="primary"
|
|
130
182
|
treatment="outline"
|
|
131
183
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
@@ -135,17 +187,26 @@ Error alert dialogs communicate critical information about an issue that a user
|
|
|
135
187
|
</sp-alert-dialog>
|
|
136
188
|
```
|
|
137
189
|
|
|
138
|
-
|
|
190
|
+
</sp-tab-panel>
|
|
191
|
+
<sp-tab value="warning">Warning</sp-tab>
|
|
192
|
+
<sp-tab-panel value="warning">
|
|
139
193
|
|
|
140
|
-
|
|
194
|
+
Warning alert dialogs communicate important information to users in relation to an issue that needs to be acknowledged, but does not block the user from moving forward.
|
|
141
195
|
|
|
142
196
|
```html
|
|
143
|
-
<sp-alert-dialog
|
|
144
|
-
|
|
145
|
-
|
|
197
|
+
<sp-alert-dialog
|
|
198
|
+
role="alertdialog"
|
|
199
|
+
aria-labelledby="warning-heading"
|
|
200
|
+
aria-describedby="warning-message"
|
|
201
|
+
variant="warning"
|
|
202
|
+
>
|
|
203
|
+
<h2 id="warning-heading" slot="heading">Unverified format</h2>
|
|
204
|
+
<p id="warning-message">
|
|
205
|
+
This format has not been verified and may not be viewable for some
|
|
206
|
+
users. Do you want to continue publishing?
|
|
207
|
+
</p>
|
|
146
208
|
<sp-button
|
|
147
209
|
slot="button"
|
|
148
|
-
id="cancelButton"
|
|
149
210
|
variant="secondary"
|
|
150
211
|
treatment="outline"
|
|
151
212
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
@@ -154,50 +215,138 @@ Destructive alert dialogs are for when a user needs to confirm an action that wi
|
|
|
154
215
|
</sp-button>
|
|
155
216
|
<sp-button
|
|
156
217
|
slot="button"
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
treatment="fill"
|
|
218
|
+
variant="primary"
|
|
219
|
+
treatment="outline"
|
|
160
220
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
161
221
|
>
|
|
162
|
-
|
|
222
|
+
Continue
|
|
163
223
|
</sp-button>
|
|
164
224
|
</sp-alert-dialog>
|
|
165
225
|
```
|
|
166
226
|
|
|
167
|
-
|
|
227
|
+
</sp-tab-panel>
|
|
228
|
+
<sp-tab value="error">Error</sp-tab>
|
|
229
|
+
<sp-tab-panel value="error">
|
|
168
230
|
|
|
169
|
-
|
|
231
|
+
Error alert dialogs communicate critical information about an issue that a user needs to acknowledge.
|
|
170
232
|
|
|
171
233
|
```html
|
|
172
|
-
<sp-alert-dialog
|
|
173
|
-
|
|
174
|
-
|
|
234
|
+
<sp-alert-dialog
|
|
235
|
+
role="alertdialog"
|
|
236
|
+
aria-labelledby="error-heading"
|
|
237
|
+
aria-describedby="error-message"
|
|
238
|
+
variant="error"
|
|
239
|
+
>
|
|
240
|
+
<h2 id="error-heading" slot="heading">Unable to share</h2>
|
|
241
|
+
<p id="error-message">
|
|
242
|
+
An error occurred while sharing your project. Please verify the email
|
|
243
|
+
address and try again.
|
|
244
|
+
</p>
|
|
175
245
|
<sp-button
|
|
176
246
|
slot="button"
|
|
177
|
-
|
|
178
|
-
variant="secondary"
|
|
247
|
+
variant="primary"
|
|
179
248
|
treatment="outline"
|
|
180
249
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
181
250
|
>
|
|
182
|
-
|
|
251
|
+
Continue
|
|
183
252
|
</sp-button>
|
|
253
|
+
</sp-alert-dialog>
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
</sp-tab-panel>
|
|
257
|
+
<sp-tab value="destructive">Destructive</sp-tab>
|
|
258
|
+
<sp-tab-panel value="destructive">
|
|
259
|
+
|
|
260
|
+
Destructive alert dialogs are for when a user needs to confirm an action that will impact their data or experience in a potentially negative way, such as deleting files or contacts.
|
|
261
|
+
|
|
262
|
+
```html
|
|
263
|
+
<sp-alert-dialog
|
|
264
|
+
role="alertdialog"
|
|
265
|
+
aria-labelledby="destructive-heading"
|
|
266
|
+
aria-describedby="destructive-message"
|
|
267
|
+
variant="destructive"
|
|
268
|
+
>
|
|
269
|
+
<h2 id="destructive-heading" slot="heading">Delete 3 documents?</h2>
|
|
270
|
+
<p id="destructive-message">
|
|
271
|
+
Are you sure you want to delete the 3 selected documents?
|
|
272
|
+
</p>
|
|
184
273
|
<sp-button
|
|
185
274
|
slot="button"
|
|
186
|
-
id="cancelButton"
|
|
187
275
|
variant="secondary"
|
|
188
276
|
treatment="outline"
|
|
189
277
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
190
278
|
>
|
|
191
|
-
|
|
279
|
+
Cancel
|
|
192
280
|
</sp-button>
|
|
193
281
|
<sp-button
|
|
194
282
|
slot="button"
|
|
195
|
-
|
|
196
|
-
variant="primary"
|
|
283
|
+
variant="negative"
|
|
197
284
|
treatment="outline"
|
|
198
285
|
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
199
286
|
>
|
|
200
|
-
|
|
287
|
+
Delete
|
|
201
288
|
</sp-button>
|
|
202
289
|
</sp-alert-dialog>
|
|
203
290
|
```
|
|
291
|
+
|
|
292
|
+
</sp-tab-panel>
|
|
293
|
+
</sp-tabs>
|
|
294
|
+
|
|
295
|
+
### Behaviors
|
|
296
|
+
|
|
297
|
+
#### Context
|
|
298
|
+
|
|
299
|
+
An alert dialog should be placed inside a modal overaly:
|
|
300
|
+
|
|
301
|
+
```html
|
|
302
|
+
<sp-button id="trigger">open modal</sp-button>
|
|
303
|
+
<sp-overlay trigger="trigger@click" type="modal">
|
|
304
|
+
<sp-alert-dialog
|
|
305
|
+
role="alertdialog"
|
|
306
|
+
aria-labelledby="modal-heading"
|
|
307
|
+
aria-describedby="modal-message"
|
|
308
|
+
variant="confirmation"
|
|
309
|
+
>
|
|
310
|
+
<h2 id="modal-heading" slot="heading">Important Notice</h2>
|
|
311
|
+
<p id="modal-message">This action requires your confirmation.</p>
|
|
312
|
+
<sp-button
|
|
313
|
+
slot="button"
|
|
314
|
+
variant="secondary"
|
|
315
|
+
treatment="outline"
|
|
316
|
+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
317
|
+
>
|
|
318
|
+
Cancel
|
|
319
|
+
</sp-button>
|
|
320
|
+
<sp-button
|
|
321
|
+
slot="button"
|
|
322
|
+
variant="accent"
|
|
323
|
+
treatment="fill"
|
|
324
|
+
onclick="this.dispatchEvent(new Event('close', { bubbles: true, composed: true }));"
|
|
325
|
+
>
|
|
326
|
+
Confirm
|
|
327
|
+
</sp-button>
|
|
328
|
+
</sp-alert-dialog>
|
|
329
|
+
</sp-overlay>
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### Accessibility
|
|
333
|
+
|
|
334
|
+
#### `<sp-alert-banner>` Element
|
|
335
|
+
|
|
336
|
+
- Use `role="alertdialog"` on the alert dialog
|
|
337
|
+
- Make sure the alert dialog has an `aria-labelledby` attribute that references the title's `id`.
|
|
338
|
+
- Make sure the alert dialog has an `aria-describedby` attribute that references the content's `id`.
|
|
339
|
+
|
|
340
|
+
#### Title
|
|
341
|
+
|
|
342
|
+
- Consider the appropriate variant based on the message's importance and urgency
|
|
343
|
+
- Use concise, meaningful dialog title that clearly states the purpose
|
|
344
|
+
- Use semantic heading elements (`<h2>`) for the dialog title
|
|
345
|
+
|
|
346
|
+
#### Content
|
|
347
|
+
|
|
348
|
+
- Provide clear, concise content that explains the situation and required actions
|
|
349
|
+
|
|
350
|
+
####Buttons
|
|
351
|
+
|
|
352
|
+
- Ensure button labels clearly indicate the action they will perform
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spectrum-web-components/alert-dialog",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.6.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -65,12 +65,12 @@
|
|
|
65
65
|
],
|
|
66
66
|
"dependencies": {
|
|
67
67
|
"@lit-labs/observers": "^2.0.2",
|
|
68
|
-
"@spectrum-web-components/base": "1.
|
|
69
|
-
"@spectrum-web-components/button": "1.
|
|
70
|
-
"@spectrum-web-components/button-group": "1.
|
|
71
|
-
"@spectrum-web-components/divider": "1.
|
|
72
|
-
"@spectrum-web-components/icons-workflow": "1.
|
|
73
|
-
"@spectrum-web-components/shared": "1.
|
|
68
|
+
"@spectrum-web-components/base": "1.6.0",
|
|
69
|
+
"@spectrum-web-components/button": "1.6.0",
|
|
70
|
+
"@spectrum-web-components/button-group": "1.6.0",
|
|
71
|
+
"@spectrum-web-components/divider": "1.6.0",
|
|
72
|
+
"@spectrum-web-components/icons-workflow": "1.6.0",
|
|
73
|
+
"@spectrum-web-components/shared": "1.6.0"
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
76
|
"@spectrum-css/alertdialog": "4.1.0"
|