@spectrum-web-components/radio 1.3.0 → 1.4.0-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 +156 -72
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
|
-
##
|
|
1
|
+
## Overview
|
|
2
2
|
|
|
3
3
|
`<sp-radio>` and `<sp-radio-group>` allow users to select a single option from a list of mutually exclusive options. All possible options are exposed up front for users to compare.
|
|
4
4
|
|
|
5
|
-
`<sp-radio-group>` holds a list of `<sp-radio>` elements, and is responsible for deselecting radio buttons when a new one is selected, which in turn makes it responsible for keeping track of which one is selected. `<sp-radio>` is responsible for handling user interactions and for visually reflecting if it is the one that is checked or not.
|
|
6
|
-
|
|
7
5
|
### Usage
|
|
8
6
|
|
|
9
7
|
[](https://www.npmjs.com/package/@spectrum-web-components/radio)
|
|
@@ -30,14 +28,139 @@ import {
|
|
|
30
28
|
} from '@spectrum-web-components/radio';
|
|
31
29
|
```
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
### Anatomy
|
|
32
|
+
|
|
33
|
+
`<sp-radio-group>` holds a list of `<sp-radio>` elements, and is responsible for deselecting radio buttons when a new one is selected, which in turn makes it responsible for keeping track of which one is selected. `<sp-radio>` is responsible for handling user interactions and for visually reflecting if it is the one that is checked or not.
|
|
34
|
+
|
|
35
|
+
```html
|
|
36
|
+
<sp-radio-group label="Choose an option" name="anatomy">
|
|
37
|
+
<sp-radio value="first">Option 1</sp-radio>
|
|
38
|
+
<sp-radio value="second">Option 2</sp-radio>
|
|
39
|
+
<sp-radio value="third">Option 3</sp-radio>
|
|
40
|
+
<sp-radio value="fourth">Option 4</sp-radio>
|
|
41
|
+
</sp-radio-group>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
#### Label
|
|
45
|
+
|
|
46
|
+
The `<sp-radio>` elements are labelled with text in their default slot.
|
|
47
|
+
|
|
48
|
+
The `<sp-radio-group>` element can be labeled with the `label` property or with an <`sp-field-label>` element:
|
|
49
|
+
|
|
50
|
+
<sp-tabs selected="property" auto label="Label Anatomy">
|
|
51
|
+
<sp-tab value="property">`label` property</sp-tab>
|
|
52
|
+
<sp-tab-panel value="self">
|
|
53
|
+
|
|
54
|
+
```html
|
|
55
|
+
<sp-radio-group label="Choose an option" name="anatomy">
|
|
56
|
+
<sp-radio value="first">Option 1</sp-radio>
|
|
57
|
+
<sp-radio value="second">Option 2</sp-radio>
|
|
58
|
+
<sp-radio value="third">Option 3</sp-radio>
|
|
59
|
+
<sp-radio value="fourth">Option 4</sp-radio>
|
|
60
|
+
</sp-radio-group>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
</sp-tab-panel>
|
|
64
|
+
<sp-tab value="sp-field-label">Using a field bale</sp-tab>
|
|
65
|
+
<sp-tab-panel value="above">
|
|
66
|
+
|
|
67
|
+
```html
|
|
68
|
+
<sp-field-label for="options">Choose an option</sp-field-label>
|
|
69
|
+
<sp-radio-group id="options" name="anatomy">
|
|
70
|
+
<sp-radio value="first">Option 1</sp-radio>
|
|
71
|
+
<sp-radio value="second">Option 2</sp-radio>
|
|
72
|
+
<sp-radio value="third">Option 3</sp-radio>
|
|
73
|
+
<sp-radio value="fourth">Option 4</sp-radio>
|
|
74
|
+
</sp-radio-group>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
</sp-tab-panel>
|
|
78
|
+
<sp-tab value="sp-field-label">Using a field bale</sp-tab>
|
|
79
|
+
<sp-tab-panel value="above">
|
|
80
|
+
|
|
81
|
+
```html
|
|
82
|
+
<sp-field-label for="options">Choose an option</sp-field-label>
|
|
83
|
+
<sp-radio-group id="options" name="anatomy">
|
|
84
|
+
<sp-radio value="first">Option 1</sp-radio>
|
|
85
|
+
<sp-radio value="second">Option 2</sp-radio>
|
|
86
|
+
<sp-radio value="third">Option 3</sp-radio>
|
|
87
|
+
<sp-radio value="fourth">Option 4</sp-radio>
|
|
88
|
+
</sp-radio-group>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
</sp-tab-panel>
|
|
92
|
+
</sp-tabs>
|
|
93
|
+
|
|
94
|
+
#### Help Text
|
|
95
|
+
|
|
96
|
+
Help text can be accessibly associated with an `<sp-radio-group>` element by using the `help-text` or `negative-help-text` slots. When using the `negative-help-text` slot, `<sp-radio-group>` will self manage the presence of this content based on the value of the `invalid` property on your `<sp-radio-group>` element. Content within the `help-text` slot will be show by default. When your `<sp-radio-group>` should receive help text based on state outside of the complexity of `invalid` or not, manage the content addressed to the `help-text` from above to ensure that it displays the right messaging and possesses the right `variant`.
|
|
97
|
+
|
|
98
|
+
Read more about using [help text](../help-text).
|
|
99
|
+
|
|
100
|
+
<sp-tabs selected="self" auto label="Help text usage in radio groups">
|
|
101
|
+
<sp-tab value="self">Self managed</sp-tab>
|
|
102
|
+
<sp-tab-panel value="self">
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<sp-field-label for="self">
|
|
106
|
+
What is your favorite ice cream flavor?
|
|
107
|
+
</sp-field-label>
|
|
108
|
+
<sp-radio-group
|
|
109
|
+
id="self"
|
|
110
|
+
onchange="
|
|
111
|
+
this.invalid = this.selected === 'fourth';
|
|
112
|
+
"
|
|
113
|
+
>
|
|
114
|
+
<sp-radio value="first">Vanilla</sp-radio>
|
|
115
|
+
<sp-radio value="second">Chocolate</sp-radio>
|
|
116
|
+
<sp-radio value="third">Strawberry</sp-radio>
|
|
117
|
+
<sp-radio value="fourth">I don't like ice cream</sp-radio>
|
|
118
|
+
<sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
|
|
119
|
+
<sp-help-text slot="negative-help-text" icon>
|
|
120
|
+
You can't not like ice cream.
|
|
121
|
+
</sp-help-text>
|
|
122
|
+
</sp-radio-group>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
</sp-tab-panel>
|
|
126
|
+
<sp-tab value="above">Managed from above</sp-tab>
|
|
127
|
+
<sp-tab-panel value="above">
|
|
128
|
+
|
|
129
|
+
```html
|
|
130
|
+
<sp-field-label for="managed">
|
|
131
|
+
What is your favorite ice cream flavor?
|
|
132
|
+
</sp-field-label>
|
|
133
|
+
<sp-radio-group
|
|
134
|
+
id="managed"
|
|
135
|
+
onchange="
|
|
136
|
+
const helpText = this.querySelector(`[slot='help-text']`);
|
|
137
|
+
const isInvalid = this.selected === 'fourth';
|
|
138
|
+
helpText.icon = isInvalid;
|
|
139
|
+
helpText.textContent = isInvalid ? 'You can\'t not like ice cream.' : 'Everyone likes ice cream.';
|
|
140
|
+
helpText.variant = isInvalid ? 'negative' : 'neutral';
|
|
141
|
+
"
|
|
142
|
+
>
|
|
143
|
+
<sp-radio value="first">Vanilla</sp-radio>
|
|
144
|
+
<sp-radio value="second">Chocolate</sp-radio>
|
|
145
|
+
<sp-radio value="third">Strawberry</sp-radio>
|
|
146
|
+
<sp-radio value="fourth">I don't like ice cream</sp-radio>
|
|
147
|
+
<sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
|
|
148
|
+
</sp-radio-group>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
</sp-tab-panel>
|
|
152
|
+
</sp-tabs>
|
|
153
|
+
|
|
154
|
+
### Options
|
|
155
|
+
|
|
156
|
+
#### Sizes
|
|
34
157
|
|
|
35
158
|
<sp-tabs selected="m" auto label="Size Attribute Options">
|
|
36
159
|
<sp-tab value="s">Small</sp-tab>
|
|
37
160
|
<sp-tab-panel value="s">
|
|
38
161
|
|
|
39
162
|
```html
|
|
40
|
-
<sp-radio-group label="Small" selected="first" name="
|
|
163
|
+
<sp-radio-group label="Small" selected="first" name="small">
|
|
41
164
|
<sp-radio value="first" size="s">Option 1</sp-radio>
|
|
42
165
|
<sp-radio value="second" size="s">Option 2</sp-radio>
|
|
43
166
|
<sp-radio value="third" size="s">Option 3</sp-radio>
|
|
@@ -50,7 +173,7 @@ import {
|
|
|
50
173
|
<sp-tab-panel value="m">
|
|
51
174
|
|
|
52
175
|
```html
|
|
53
|
-
<sp-radio-group label="Medium" selected="first" name="
|
|
176
|
+
<sp-radio-group label="Medium" selected="first" name="medium">
|
|
54
177
|
<sp-radio value="first" size="m">Option 1</sp-radio>
|
|
55
178
|
<sp-radio value="second" size="m">Option 2</sp-radio>
|
|
56
179
|
<sp-radio value="third" size="m">Option 3</sp-radio>
|
|
@@ -63,7 +186,7 @@ import {
|
|
|
63
186
|
<sp-tab-panel value="l">
|
|
64
187
|
|
|
65
188
|
```html
|
|
66
|
-
<sp-radio-group label="Large" selected="first" name="
|
|
189
|
+
<sp-radio-group label="Large" selected="first" name="large">
|
|
67
190
|
<sp-radio value="first" size="l">Option 1</sp-radio>
|
|
68
191
|
<sp-radio value="second" size="l">Option 2</sp-radio>
|
|
69
192
|
<sp-radio value="third" size="l">Option 3</sp-radio>
|
|
@@ -76,7 +199,7 @@ import {
|
|
|
76
199
|
<sp-tab-panel value="xl">
|
|
77
200
|
|
|
78
201
|
```html
|
|
79
|
-
<sp-radio-group label="Extra large" selected="first" name="
|
|
202
|
+
<sp-radio-group label="Extra large" selected="first" name="extra-large">
|
|
80
203
|
<sp-radio value="first" size="xl">Option 1</sp-radio>
|
|
81
204
|
<sp-radio value="second" size="xl">Option 2</sp-radio>
|
|
82
205
|
<sp-radio value="third" size="xl">Option 3</sp-radio>
|
|
@@ -87,13 +210,17 @@ import {
|
|
|
87
210
|
</sp-tab-panel>
|
|
88
211
|
</sp-tabs>
|
|
89
212
|
|
|
90
|
-
|
|
213
|
+
#### Styles
|
|
91
214
|
|
|
92
215
|
Standard radio buttons are the default style for radio buttons. They are optimal for application panels where all visual elements are monochrome in order to direct focus to the content.
|
|
93
216
|
|
|
94
|
-
|
|
217
|
+
**Emphasized** radio buttons are a secondary style for radio buttons. The blue color provides a visual prominence that is optimal for forms, settings, etc. where the radio buttons need to be noticed.
|
|
218
|
+
|
|
219
|
+
<sp-tabs selected="standard" auto label="Style Options">
|
|
220
|
+
<sp-tab value="standard">Standard</sp-tab>
|
|
221
|
+
<sp-tab-panel value="standard">
|
|
95
222
|
|
|
96
|
-
```html
|
|
223
|
+
```html
|
|
97
224
|
<div style="display: flex; justify-content: space-between;">
|
|
98
225
|
<div style="display: flex; flex-direction: column;">
|
|
99
226
|
<sp-field-label for="example-1" size="l">
|
|
@@ -130,13 +257,11 @@ Invalid selections in radio groups are identified using the `negative-help-text`
|
|
|
130
257
|
</div>
|
|
131
258
|
```
|
|
132
259
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
Invalid selections in radio groups are identified using the `negative-help-text` slot. Read more about using [help text](#help-text) below.
|
|
260
|
+
</sp-tab-panel>
|
|
261
|
+
<sp-tab value="emphasized">Emphasized</sp-tab>
|
|
262
|
+
<sp-tab-panel value="emphasized">
|
|
138
263
|
|
|
139
|
-
```html
|
|
264
|
+
```html
|
|
140
265
|
<div style="display: flex; justify-content: space-between;">
|
|
141
266
|
<div style="display: flex; flex-direction: column;">
|
|
142
267
|
<sp-field-label for="example-a" size="l">
|
|
@@ -173,7 +298,12 @@ Invalid selections in radio groups are identified using the `negative-help-text`
|
|
|
173
298
|
</div>
|
|
174
299
|
```
|
|
175
300
|
|
|
176
|
-
|
|
301
|
+
</sp-tab-panel>
|
|
302
|
+
</sp-tabs>
|
|
303
|
+
|
|
304
|
+
### Behaviors
|
|
305
|
+
|
|
306
|
+
#### Handling events
|
|
177
307
|
|
|
178
308
|
Event handlers for clicks and other user actions can be registered on an `<sp-radio>` similar to a standard `<input type="radio">` element.
|
|
179
309
|
|
|
@@ -183,64 +313,18 @@ Event handlers for clicks and other user actions can be registered on an `<sp-ra
|
|
|
183
313
|
</sp-radio>
|
|
184
314
|
```
|
|
185
315
|
|
|
186
|
-
|
|
316
|
+
### Accessibility
|
|
187
317
|
|
|
188
|
-
|
|
318
|
+
Tabbing into a group of radio buttons places the focus on the first radio button selected. If none of the radio buttons are selected, the focus is set on the first one in the group. Space selects the radio button in focus (if not already selected). Using the arrow keys moves focus and selection to the previous or next radio button in the group (last becomes first, and first becomes last). The new radio button in focus gets selected even if the previous one was not.
|
|
189
319
|
|
|
190
|
-
|
|
191
|
-
<sp-tab value="self">Self managed</sp-tab>
|
|
192
|
-
<sp-tab-panel value="self">
|
|
320
|
+
#### Provide a label
|
|
193
321
|
|
|
194
|
-
|
|
195
|
-
<sp-field-label for="self">
|
|
196
|
-
What is your favorite ice cream flavor?
|
|
197
|
-
</sp-field-label>
|
|
198
|
-
<sp-radio-group
|
|
199
|
-
id="self"
|
|
200
|
-
onchange="
|
|
201
|
-
this.invalid = this.selected === 'fourth';
|
|
202
|
-
"
|
|
203
|
-
>
|
|
204
|
-
<sp-radio value="first">Vanilla</sp-radio>
|
|
205
|
-
<sp-radio value="second">Chocolate</sp-radio>
|
|
206
|
-
<sp-radio value="third">Strawberry</sp-radio>
|
|
207
|
-
<sp-radio value="fourth">I don't like ice cream</sp-radio>
|
|
208
|
-
<sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
|
|
209
|
-
<sp-help-text slot="negative-help-text" icon>
|
|
210
|
-
You can't not like ice cream.
|
|
211
|
-
</sp-help-text>
|
|
212
|
-
</sp-radio-group>
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
</sp-tab-panel>
|
|
216
|
-
<sp-tab value="above">Managed from above</sp-tab>
|
|
217
|
-
<sp-tab-panel value="above">
|
|
322
|
+
Radio groups and radio items should always have labels.
|
|
218
323
|
|
|
219
|
-
|
|
220
|
-
<sp-field-label for="managed">
|
|
221
|
-
What is your favorite ice cream flavor?
|
|
222
|
-
</sp-field-label>
|
|
223
|
-
<sp-radio-group
|
|
224
|
-
id="managed"
|
|
225
|
-
onchange="
|
|
226
|
-
const helpText = this.querySelector(`[slot='help-text']`);
|
|
227
|
-
const isInvalid = this.selected === 'fourth';
|
|
228
|
-
helpText.icon = isInvalid;
|
|
229
|
-
helpText.textContent = isInvalid ? 'You can\'t not like ice cream.' : 'Everyone likes ice cream.';
|
|
230
|
-
helpText.variant = isInvalid ? 'negative' : 'neutral';
|
|
231
|
-
"
|
|
232
|
-
>
|
|
233
|
-
<sp-radio value="first">Vanilla</sp-radio>
|
|
234
|
-
<sp-radio value="second">Chocolate</sp-radio>
|
|
235
|
-
<sp-radio value="third">Strawberry</sp-radio>
|
|
236
|
-
<sp-radio value="fourth">I don't like ice cream</sp-radio>
|
|
237
|
-
<sp-help-text slot="help-text">Everyone likes ice cream.</sp-help-text>
|
|
238
|
-
</sp-radio-group>
|
|
239
|
-
```
|
|
324
|
+
#### Provide help text in the correct location
|
|
240
325
|
|
|
241
|
-
|
|
242
|
-
</sp-tabs>
|
|
326
|
+
Radio groups should use help text for error messaging and descriptions. Descriptions are valuable for giving context behind why a selection is required, or for clarifying the options.
|
|
243
327
|
|
|
244
|
-
|
|
328
|
+
It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="help-text-negative"`.
|
|
245
329
|
|
|
246
|
-
|
|
330
|
+
See [help text](../help-text) for more information.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@spectrum-web-components/radio",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.0-beta.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public"
|
|
6
6
|
},
|
|
@@ -66,11 +66,11 @@
|
|
|
66
66
|
"lit-html"
|
|
67
67
|
],
|
|
68
68
|
"dependencies": {
|
|
69
|
-
"@spectrum-web-components/base": "1.
|
|
70
|
-
"@spectrum-web-components/field-group": "1.
|
|
71
|
-
"@spectrum-web-components/help-text": "1.
|
|
72
|
-
"@spectrum-web-components/reactive-controllers": "1.
|
|
73
|
-
"@spectrum-web-components/shared": "1.
|
|
69
|
+
"@spectrum-web-components/base": "1.4.0-beta.0",
|
|
70
|
+
"@spectrum-web-components/field-group": "1.4.0-beta.0",
|
|
71
|
+
"@spectrum-web-components/help-text": "1.4.0-beta.0",
|
|
72
|
+
"@spectrum-web-components/reactive-controllers": "1.4.0-beta.0",
|
|
73
|
+
"@spectrum-web-components/shared": "1.4.0-beta.0"
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
76
|
"@spectrum-css/radio": "10.0.0-s2-foundations.17"
|