@spectrum-web-components/button 1.3.0-testing.0 → 1.3.1-beta.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 +137 -51
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
##
|
|
1
|
+
## Overview
|
|
2
2
|
|
|
3
3
|
An `<sp-button>` represents an action a user can take. sp-buttons can be clicked
|
|
4
|
-
or tapped to perform an action or to navigate to another page.
|
|
4
|
+
or tapped to perform an action or to navigate to another page. Buttons in
|
|
5
5
|
Spectrum have several variations for different uses and multiple levels of
|
|
6
6
|
loudness for various attention-getting needs.
|
|
7
7
|
|
|
@@ -29,9 +29,78 @@ When looking to leverage the `Button`, `ClearButton`, or `CloseButton` base clas
|
|
|
29
29
|
import { Button, ClearButton, CloseButton } from '@spectrum-web-components/button';
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
### Anatomy
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
#### Content
|
|
35
|
+
|
|
36
|
+
`<sp-button>` elements can be provided a visible label,
|
|
37
|
+
a label and an icon, or just an icon.
|
|
38
|
+
|
|
39
|
+
An icon is provided by placing an icon element in the `icon` slot.
|
|
40
|
+
|
|
41
|
+
If the button is `icon-only`, a non-visible label
|
|
42
|
+
can be provided via the `label` attribute on an `<sp-button>`
|
|
43
|
+
or on an `<sp-icon*>` element child to appropriately
|
|
44
|
+
fulfill the accessibility contract of the button.
|
|
45
|
+
|
|
46
|
+
<sp-tabs selected="label" auto label="Labelling a button">
|
|
47
|
+
<sp-tab value="label">Label only</sp-tab>
|
|
48
|
+
<sp-tab-panel value="label">
|
|
49
|
+
|
|
50
|
+
```html demo
|
|
51
|
+
<sp-button variant="primary">Label only</sp-button>
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
</sp-tab-panel>
|
|
55
|
+
<sp-tab value="icon-label">Icon + label</sp-tab>
|
|
56
|
+
<sp-tab-panel value="icon-label">
|
|
57
|
+
|
|
58
|
+
```html demo
|
|
59
|
+
<sp-button variant="primary">
|
|
60
|
+
<sp-icon-help slot="icon"></sp-icon-help>
|
|
61
|
+
Icon + Label
|
|
62
|
+
</sp-button>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
</sp-tab-panel>
|
|
66
|
+
<sp-tab value="svg-label">SVG Icon + label</sp-tab>
|
|
67
|
+
<sp-tab-panel value="svg-label">
|
|
68
|
+
|
|
69
|
+
```html demo
|
|
70
|
+
<sp-button variant="primary">
|
|
71
|
+
<svg
|
|
72
|
+
slot="icon"
|
|
73
|
+
viewBox="0 0 36 36"
|
|
74
|
+
focusable="false"
|
|
75
|
+
aria-hidden="true"
|
|
76
|
+
role="img"
|
|
77
|
+
>
|
|
78
|
+
<path
|
|
79
|
+
d="M16 36a4.407 4.407 0 0 0 4-4h-8a4.407 4.407 0 0 0 4 4zm9.143-24.615c0-3.437-3.206-4.891-7.143-5.268V3a1.079 1.079 0 0 0-1.143-1h-1.714A1.079 1.079 0 0 0 14 3v3.117c-3.937.377-7.143 1.831-7.143 5.268C6.857 26.8 2 26.111 2 28.154V30h28v-1.846C30 26 25.143 26.8 25.143 11.385z"
|
|
80
|
+
></path>
|
|
81
|
+
</svg>
|
|
82
|
+
SVG Icon + Label
|
|
83
|
+
</sp-button>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
</sp-tab-panel>
|
|
87
|
+
<sp-tab value="icon-only">Icon only</sp-tab>
|
|
88
|
+
<sp-tab-panel value="icon-only">
|
|
89
|
+
|
|
90
|
+
```html demo
|
|
91
|
+
<sp-button variant="primary" label="Icon only">
|
|
92
|
+
<sp-icon-help slot="icon"></sp-icon-help>
|
|
93
|
+
</sp-button>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
</sp-tab-panel>
|
|
97
|
+
</sp-tabs>
|
|
98
|
+
|
|
99
|
+
### Options
|
|
100
|
+
|
|
101
|
+
#### Sizes
|
|
102
|
+
|
|
103
|
+
<sp-tabs selected="m" auto label="Size attribute options">
|
|
35
104
|
<sp-tab value="s">Small</sp-tab>
|
|
36
105
|
<sp-tab-panel value="s">
|
|
37
106
|
|
|
@@ -66,42 +135,10 @@ import { Button, ClearButton, CloseButton } from '@spectrum-web-components/butto
|
|
|
66
135
|
</sp-tab-panel>
|
|
67
136
|
</sp-tabs>
|
|
68
137
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
`<sp-button>` elements can be provided a visible label, a label with an icon, or just an icon (a non-visible label can be prived via the `label` attribute on an `<sp-button>` or on an `<sp-icon*>` element child to appropriately fulfill the accessibility contract of the button). An icon is provided by
|
|
72
|
-
placing an icon element to the `icon` slot.
|
|
73
|
-
|
|
74
|
-
```html
|
|
75
|
-
<sp-button-group>
|
|
76
|
-
<sp-button variant="primary">Label only</sp-button>
|
|
77
|
-
<sp-button variant="primary">
|
|
78
|
-
<sp-icon-help slot="icon"></sp-icon-help>
|
|
79
|
-
Icon + Label
|
|
80
|
-
</sp-button>
|
|
81
|
-
<sp-button variant="primary">
|
|
82
|
-
<svg
|
|
83
|
-
slot="icon"
|
|
84
|
-
viewBox="0 0 36 36"
|
|
85
|
-
focusable="false"
|
|
86
|
-
aria-hidden="true"
|
|
87
|
-
role="img"
|
|
88
|
-
>
|
|
89
|
-
<path
|
|
90
|
-
d="M16 36a4.407 4.407 0 0 0 4-4h-8a4.407 4.407 0 0 0 4 4zm9.143-24.615c0-3.437-3.206-4.891-7.143-5.268V3a1.079 1.079 0 0 0-1.143-1h-1.714A1.079 1.079 0 0 0 14 3v3.117c-3.937.377-7.143 1.831-7.143 5.268C6.857 26.8 2 26.111 2 28.154V30h28v-1.846C30 26 25.143 26.8 25.143 11.385z"
|
|
91
|
-
></path>
|
|
92
|
-
</svg>
|
|
93
|
-
SVG Icon + Label
|
|
94
|
-
</sp-button>
|
|
95
|
-
<sp-button variant="primary" label="Icon only" icon-only>
|
|
96
|
-
<sp-icon-help slot="icon"></sp-icon-help>
|
|
97
|
-
</sp-button>
|
|
98
|
-
</sp-button-group>
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
## Variants
|
|
138
|
+
#### Variants
|
|
102
139
|
|
|
103
140
|
There are many button variants to choose from in Spectrum. The `variant`
|
|
104
|
-
attribute defaults to `accent
|
|
141
|
+
attribute defaults to `accent`, but also accepts the following value: `accent`, `primary`, `secondary`, `negative`, `white`, and `black`. They display as follows:
|
|
105
142
|
|
|
106
143
|
<sp-tabs selected="accent" auto label="Variant Attribute Options">
|
|
107
144
|
<sp-tab value="accent">Accent</sp-tab>
|
|
@@ -208,7 +245,7 @@ attribute defaults to `accent` but also accepts the following value: `accent`, `
|
|
|
208
245
|
</sp-tab-panel>
|
|
209
246
|
</sp-tabs>
|
|
210
247
|
|
|
211
|
-
|
|
248
|
+
#### Treatment
|
|
212
249
|
|
|
213
250
|
The `treatment` attribute accepts `fill` and `outline` as values, and defaults to `fill`. These display as follows:
|
|
214
251
|
|
|
@@ -293,11 +330,11 @@ The `treatment` attribute accepts `fill` and `outline` as values, and defaults t
|
|
|
293
330
|
</sp-tab-panel>
|
|
294
331
|
</sp-tabs>
|
|
295
332
|
|
|
296
|
-
|
|
333
|
+
### States
|
|
297
334
|
|
|
298
335
|
In addition to the variant, `<sp-button>` elements support two different visual states, disabled and pending, which can be applied by adding the attribute `disabled` or `pending` respectively. All `<sp-button>` variants support these states.
|
|
299
336
|
|
|
300
|
-
|
|
337
|
+
#### Disabled
|
|
301
338
|
|
|
302
339
|
While disabled, `<sp-button>` elements will not respond to click events and will appear faded.
|
|
303
340
|
|
|
@@ -308,13 +345,12 @@ While disabled, `<sp-button>` elements will not respond to click events and will
|
|
|
308
345
|
</sp-button-group>
|
|
309
346
|
```
|
|
310
347
|
|
|
311
|
-
|
|
348
|
+
#### Pending
|
|
312
349
|
|
|
313
|
-
While in pending state, `<sp-button>` elements will not respond to click events and will appear faded with an
|
|
314
|
-
`<sp-button>`
|
|
350
|
+
While in pending state, `<sp-button>` elements will not respond to click events and will appear faded with an indeterminate `<sp-progress-circle>`.
|
|
351
|
+
The `<sp-button>` element's label and icon will be hidden while in pending state.
|
|
315
352
|
|
|
316
|
-
Note:
|
|
317
|
-
You can override the delay by adding custom css var `--pending-delay` to your css.
|
|
353
|
+
Note: The pending state of the `<sp-button>` element is applied after a 1s delay to avoid flashing the pending state for quick actions. You can override the delay by adding custom css var `--pending-delay` to your css.
|
|
318
354
|
|
|
319
355
|
```html
|
|
320
356
|
<sp-button-group>
|
|
@@ -323,10 +359,12 @@ You can override the delay by adding custom css var `--pending-delay` to your cs
|
|
|
323
359
|
</sp-button-group>
|
|
324
360
|
```
|
|
325
361
|
|
|
326
|
-
|
|
362
|
+
### Behaviors
|
|
363
|
+
|
|
364
|
+
#### Handling events
|
|
327
365
|
|
|
328
366
|
Events handlers for clicks and other user actions can be registered on a
|
|
329
|
-
`<sp-button>` as on a standard HTML `<button>` element.
|
|
367
|
+
`<sp-button>` as one would on a standard HTML `<button>` element.
|
|
330
368
|
|
|
331
369
|
```html
|
|
332
370
|
<sp-button onclick="spAlert(this, '<sp-button> clicked!')">Click me</sp-button>
|
|
@@ -334,7 +372,7 @@ Events handlers for clicks and other user actions can be registered on a
|
|
|
334
372
|
|
|
335
373
|
In addition to handling events like a native `<button>` HTML element, one can also use a `<sp-button>` in place of the `<a>` HTML element by using the `href` and optional `target` attribute.
|
|
336
374
|
|
|
337
|
-
```html
|
|
375
|
+
```html demo
|
|
338
376
|
<sp-button
|
|
339
377
|
href="https://github.com/adobe/spectrum-web-components"
|
|
340
378
|
target="_blank"
|
|
@@ -343,12 +381,60 @@ In addition to handling events like a native `<button>` HTML element, one can al
|
|
|
343
381
|
</sp-button>
|
|
344
382
|
```
|
|
345
383
|
|
|
346
|
-
|
|
384
|
+
#### Autofocus
|
|
347
385
|
|
|
348
|
-
The `autofocus` attribute sets focus
|
|
386
|
+
The `autofocus` attribute sets focus on the `<sp-button>` when the component
|
|
349
387
|
mounts. This is useful for setting focus to a specific sp-button when a
|
|
350
388
|
popover or dialog opens.
|
|
351
389
|
|
|
352
390
|
```html
|
|
353
391
|
<sp-button autofocus>Confirm</sp-button>
|
|
354
392
|
```
|
|
393
|
+
|
|
394
|
+
### Accessibility
|
|
395
|
+
|
|
396
|
+
#### Include a label
|
|
397
|
+
|
|
398
|
+
A button is required to have either a visible text label or a `label` attribute on either the `<sp-button>` itself
|
|
399
|
+
or on an `<sp-icon*>` element child.
|
|
400
|
+
|
|
401
|
+
#### Don't override color
|
|
402
|
+
|
|
403
|
+
Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible.
|
|
404
|
+
|
|
405
|
+
#### Don't mix href and non-href buttons in a set of buttons
|
|
406
|
+
|
|
407
|
+
A screen reader user will not encounter href buttons when navigating by buttons or form controls. While they can both be used in the same page problems could occur if mixing the types in close proximity to each other.
|
|
408
|
+
|
|
409
|
+
#### Use static black or static white to contrast with backgrounds and images
|
|
410
|
+
|
|
411
|
+
To ensure maximum contrast with the background, use static black for light backgrounds and images, and static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast.
|
|
412
|
+
|
|
413
|
+
<sp-tabs selected="black" auto label="Static variants for contrast">
|
|
414
|
+
<sp-tab value="black">Static black on light background</sp-tab>
|
|
415
|
+
<sp-tab-panel value="black">
|
|
416
|
+
|
|
417
|
+
```html demo
|
|
418
|
+
<div style="background-color: #ccffee; padding: 20px">
|
|
419
|
+
<sp-button static="black">Click me</sp-button>
|
|
420
|
+
<sp-button static="black" treatment="outline">Click me</sp-button>
|
|
421
|
+
</div>
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
</sp-tab-panel>
|
|
425
|
+
<sp-tab value="white">Static white on dark background</sp-tab>
|
|
426
|
+
<sp-tab-panel value="white">
|
|
427
|
+
|
|
428
|
+
```html demo
|
|
429
|
+
<div style="background-color: #220033; padding: 20px">
|
|
430
|
+
<sp-button static="white">Click me</sp-button>
|
|
431
|
+
<sp-button static="white" treatment="outline">Click me</sp-button>
|
|
432
|
+
</div>
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
</sp-tab-panel>
|
|
436
|
+
</sp-tabs>
|
|
437
|
+
|
|
438
|
+
#### Clearly state the action
|
|
439
|
+
|
|
440
|
+
Make sure that a button’s label clearly states the outcome of the action. Use the same word or phrase as found elsewhere in the experience.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spectrum-web-components/button",
|
|
3
|
-
"version": "1.3.
|
|
3
|
+
"version": "1.3.1-beta.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -83,14 +83,14 @@
|
|
|
83
83
|
"lit-html"
|
|
84
84
|
],
|
|
85
85
|
"dependencies": {
|
|
86
|
-
"@spectrum-web-components/base": "
|
|
87
|
-
"@spectrum-web-components/clear-button": "
|
|
88
|
-
"@spectrum-web-components/close-button": "
|
|
89
|
-
"@spectrum-web-components/icon": "
|
|
90
|
-
"@spectrum-web-components/icons-ui": "
|
|
91
|
-
"@spectrum-web-components/progress-circle": "
|
|
92
|
-
"@spectrum-web-components/reactive-controllers": "
|
|
93
|
-
"@spectrum-web-components/shared": "
|
|
86
|
+
"@spectrum-web-components/base": "1.3.1-beta.0",
|
|
87
|
+
"@spectrum-web-components/clear-button": "1.3.1-beta.0",
|
|
88
|
+
"@spectrum-web-components/close-button": "1.3.1-beta.0",
|
|
89
|
+
"@spectrum-web-components/icon": "1.3.1-beta.0",
|
|
90
|
+
"@spectrum-web-components/icons-ui": "1.3.1-beta.0",
|
|
91
|
+
"@spectrum-web-components/progress-circle": "1.3.1-beta.0",
|
|
92
|
+
"@spectrum-web-components/reactive-controllers": "1.3.1-beta.0",
|
|
93
|
+
"@spectrum-web-components/shared": "1.3.1-beta.0"
|
|
94
94
|
},
|
|
95
95
|
"devDependencies": {
|
|
96
96
|
"@spectrum-css/button": "14.1.1"
|