@spectrum-web-components/switch 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.
Files changed (2) hide show
  1. package/README.md +94 -55
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- ## Description
1
+ ## Overview
2
2
 
3
3
  An `<sp-switch>` is used to turn an option on or off. Switches allow users to select the state of a single option at a time. Use a switch rather than a checkbox when activating (or deactivating) an option, instead of selecting.
4
4
 
@@ -24,41 +24,28 @@ When looking to leverage the `Switch` base class as a type and/or for extension
24
24
  import { Switch } from '@spectrum-web-components/switch';
25
25
  ```
26
26
 
27
- ## Example
27
+ ### Anatomy
28
+
29
+ A switch consists of a switch input and slotted label.
28
30
 
29
31
  ```html
30
- <sp-switch label="Switch" onclick="spAlert(this, '<sp-switch> clicked!')">
31
- Switch
32
- </sp-switch>
32
+ <sp-switch>Email notifications</sp-switch>
33
33
  ```
34
34
 
35
- ### Standard switch buttons
36
-
37
- Standard switches are the default style for switches. They are optimal for
38
- application panels where all visual elements are monochrome in order to direct
39
- focus to the content.
40
-
41
- ```html-live
42
- <div style="display: flex; justify-content: space-between;">
43
- <div style="display: flex; flex-direction: column;">
44
- <h4 class="spectrum-Heading--subtitle1">Default</h4>
45
- <sp-field-group selected="first" name="example" vertical>
46
- <sp-switch value="off">Switch Off</sp-switch>
47
- <sp-switch value="on" checked>Switch On</sp-switch>
48
- </sp-field-group>
49
- </div>
50
-
51
- <div style="display: flex; flex-direction: column;">
52
- <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
53
- <sp-field-group selected="first" name="example" vertical>
54
- <sp-switch disabled value="off">Switch Off</sp-switch>
55
- <sp-switch disabled value="on" checked>Switch On</sp-switch>
56
- </sp-field-group>
57
- </div>
58
- </div>
35
+ #### Checked
36
+
37
+ A switch can be checked by setting the `checked` property/attribute.
38
+
39
+ ```html demo
40
+ <sp-field-group vertical>
41
+ <sp-switch>Not checked</sp-switch>
42
+ <sp-switch checked>Checked</sp-switch>
43
+ </sp-field-group>
59
44
  ```
60
45
 
61
- ## Sizes
46
+ ### Options
47
+
48
+ #### Sizes
62
49
 
63
50
  <sp-tabs selected="m" auto label="Size Attribute Options">
64
51
  <sp-tab value="s">Small</sp-tab>
@@ -95,42 +82,94 @@ focus to the content.
95
82
  </sp-tab-panel>
96
83
  </sp-tabs>
97
84
 
98
- ### Emphasized radio buttons
85
+ #### Emphasized
99
86
 
100
- Emphasized switches are a secondary style for switches. The blue color provides a
101
- visual prominence that is optimal for forms, settings, etc. where the switches
87
+ Emphasized switches, which use the `empahasized` attribute/property are a
88
+ secondary style for switches. The blue color provides a visual prominence
89
+ that is optimal for forms, settings, etc. where the switches
102
90
  need to be noticed.
103
91
 
104
- ```html-live
105
- <div style="display: flex; justify-content: space-between;">
106
- <div style="display: flex; flex-direction: column;">
107
- <h4 class="spectrum-Heading--subtitle1">Default</h4>
108
- <sp-field-group selected="first" name="example" vertical>
109
- <sp-switch emphasized value="off">Switch Off</sp-switch>
110
- <sp-switch emphasized value="on" checked>Switch On</sp-switch>
111
- </sp-field-group>
112
- </div>
113
-
114
- <div style="display: flex; flex-direction: column;">
115
- <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
116
- <sp-field-group selected="first" name="example" vertical>
117
- <sp-switch emphasized disabled value="off">Switch Off</sp-switch>
118
- <sp-switch emphasized disabled value="on" checked>Switch On</sp-switch>
119
- </sp-field-group>
120
- </div>
121
- </div>
92
+ ```html
93
+ <sp-field-group vertical>
94
+ <sp-switch emphasized>Emphasized</sp-switch>
95
+ <sp-switch emphasized checked>Emphasized and checked</sp-switch>
96
+ </sp-field-group>
97
+ ```
98
+
99
+ ### States
100
+
101
+ A switch can be disabled using the `disabled` property/attribute.
102
+
103
+ ```html demo
104
+ <sp-field-group vertical>
105
+ <sp-switch disabled>Disabled</sp-switch>
106
+ <sp-switch disabled checked>Disabled and checked</sp-switch>
107
+ </sp-field-group>
122
108
  ```
123
109
 
124
- ### Handling events
110
+ ### Behaviors
111
+
112
+ #### Handling events
125
113
 
126
114
  Event handlers for clicks and other user actions can be registered on an `<sp-switch>` similar to a standard `<input type="checkbox">` element.
127
115
 
128
116
  ```html
129
- <sp-switch id="switch-example" onclick="spAlert(this, '<sp-radio> clicked!')">
117
+ <sp-switch id="switch-example" onclick="spAlert(this, '<sp-switch> clicked!')">
130
118
  Web component
131
119
  </sp-switch>
132
120
  ```
133
121
 
134
- ## Accessibility
122
+ ### Accessibility
135
123
 
136
- Switch are accessible by default, rendered in HTML using the `<input type="checkbox">` element with the appropriate accessibility role, `switch`. When the Switch is `checked` or `invalid`, the appropriate ARIA state attribute will automatically be applied.
124
+ Switch are rendered in HTML using the `<input type="checkbox">` element with the appropriate accessibility role, `switch`. When the Switch is `checked`, the appropriate ARIA state attribute will automatically be applied.
125
+
126
+ #### Include a label
127
+
128
+ A switch is required to have either a visible text label nested inside `<sp-switch>` itself.
129
+
130
+ ```html
131
+ <sp-switch>Email notifications</sp-switch>
132
+ ```
133
+
134
+ Standalone switches should be used in situations where the context is clear without an associated text label. For example, a switch located at the top of a panel next to the panel's title makes it clear that the switch will enable/disable the panel options.
135
+
136
+ <!--
137
+ TODO: Update below when https://github.com/adobe/spectrum-web-components/issues/3269 is addressed.
138
+ -->
139
+
140
+ In those cases, you can use CSS to visually hide the text label.
141
+
142
+ ```html
143
+ <div id="settings">
144
+ <sp-field-label for="notifications-settings">Notifications</sp-field-label>
145
+ <sp-switch id="notify">
146
+ <span class="visually-hidden">Notifications</span>
147
+ </sp-switch>
148
+ <sp-field-group id="notifications-settings" vertical>
149
+ <sp-switch disabled>Email</sp-switch>
150
+ <sp-switch disabled>Telephone</sp-switch>
151
+ <sp-switch disabled>Text</sp-switch>
152
+ </sp-field-group>
153
+ </div>
154
+
155
+ <style>
156
+ .visually-hidden {
157
+ clip: rect(0 0 0 0);
158
+ clip-path: inset(50%);
159
+ height: 1px;
160
+ overflow: hidden;
161
+ position: absolute;
162
+ white-space: nowrap;
163
+ width: 1px;
164
+ }
165
+ #settings {
166
+ display: grid;
167
+ grid-gap: 10px;
168
+ grid-template-columns: calc(100% - 50px) 50px;
169
+ }
170
+ #notifications-settings {
171
+ grid-column: 1 / 3;
172
+ grid-row: 2;
173
+ }
174
+ </style>
175
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spectrum-web-components/switch",
3
- "version": "1.3.0-testing.0",
3
+ "version": "1.3.1-beta.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -59,8 +59,8 @@
59
59
  "lit-html"
60
60
  ],
61
61
  "dependencies": {
62
- "@spectrum-web-components/base": "^1.3.0-testing.0",
63
- "@spectrum-web-components/checkbox": "^1.3.0-testing.0"
62
+ "@spectrum-web-components/base": "1.3.1-beta.0",
63
+ "@spectrum-web-components/checkbox": "1.3.1-beta.0"
64
64
  },
65
65
  "devDependencies": {
66
66
  "@spectrum-css/switch": "6.0.0-s2-foundations.16"