@decidables/decidables-elements 0.0.3 → 0.1.1

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 (12) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/LICENSE.md +641 -750
  3. package/README.md +279 -203
  4. package/lib/decidablesElements.esm.js +2034 -2235
  5. package/lib/decidablesElements.esm.js.map +1 -1
  6. package/lib/decidablesElements.esm.min.js +758 -3
  7. package/lib/decidablesElements.esm.min.js.map +1 -1
  8. package/lib/decidablesElements.umd.js +2035 -2236
  9. package/lib/decidablesElements.umd.js.map +1 -1
  10. package/lib/decidablesElements.umd.min.js +758 -3
  11. package/lib/decidablesElements.umd.min.js.map +1 -1
  12. package/package.json +10 -7
package/README.md CHANGED
@@ -1,204 +1,279 @@
1
1
  <!--lint ignore first-heading-level-->
2
2
 
3
- # decidables-elements: Basic UI Web Components for [**decidables**](https://github.com/decidables/decidables)
3
+ # **`@decidables/decidables-elements`**<br>Web Components for Basic UI in [**decidables**](https://decidables.github.io)
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@decidables/decidables-elements?logo=npm)](https://www.npmjs.com/package/@decidables/decidables-elements)
6
+ [![license](https://img.shields.io/npm/l/@decidables/decidables-elements?color=informational)](https://github.com/decidables/decidables/blob/main/LICENSE.md)
7
+
8
+ This package provides basic user interface web components for use in all of the explorables. This
9
+ facilitates a consistent look and feel. They try to use the native inputs when possible, but build
10
+ on them for new elements like a switch, and composite elements like a slider with a linked spinner.
4
11
 
5
12
  ## Usage
6
13
 
7
- - Install:
8
- ```shell
9
- yarn add @decidables/decidables-elements
10
- ```
11
- - Use:
12
- ```javascript
13
- import '@decidables/decidables-elements';
14
- ```
15
- A bare import is used to register the elements in the custom registry, so they are then available
16
- for use in HTML.
14
+ ### Install
15
+
16
+ ```shell
17
+ yarn add @decidables/decidables-elements
18
+ ```
19
+
20
+ ### Use
21
+
22
+ ```javascript
23
+ import '@decidables/decidables-elements';
24
+ ```
25
+
26
+ A bare import is used to register the elements in the custom registry, so they are then available
27
+ for use in HTML.
17
28
 
18
29
  ## Contents
19
30
 
20
- - Components
21
- - `DecidablesButton`: Button for taking actions
22
- - `<decidables-button></decidables-button>`
23
- - Slot: *unnamed*
24
- - Inline content as label
25
- - Attribute: `disabled`
26
- - Boolean (default: `false`)
27
- - In disabled state user can't interact
28
- - Example:
29
- ```html
30
- <decidables-button disabled>
31
- Click me
32
- </decidables-button>
33
- ```
34
- - `DecidablesSlider`: Slider w/spinner for selecting a numeric value from a range
35
- - `<decidables-slider></decidables-slider>`
36
- - Slot: *unnamed*
37
- - Inline content as label
38
- - Attribute: `disabled`
39
- - Boolean (default: `false`)
40
- - In disabled state user can't interact
41
- - Attribute: `max`
42
- - Number (default: `undefined`)
43
- - Maximum value the slider can take
44
- - Attribute: `min`
45
- - Number (default: `undefined`)
46
- - Minimum value the slider can take
47
- - Attribute: `step`
48
- - Number (default: `undefined`)
49
- - Amount that value increments with smallest movement of the slider
50
- - Attribute: `value`
51
- - Number (default: `undefined`)
52
- - Initial value of the slider
53
- - Example:
54
- ```html
55
- <decidables-slider disabled max="0" min="100" step="2" value="50">
56
- Move me
57
- </decidables-slider>
58
- ```
59
- - `DecidablesSpinner`: Text field w/spinner arrows for selecting a continuous numeric value
60
- - `<decidables-spinner></decidables-spinner>`
61
- - Slot: *unnamed*
62
- - Inline content as label
63
- - Attribute: `disabled`
64
- - Boolean (default: `false`)
65
- - In disabled state user can't interact
66
- - Attribute: `max`
67
- - Number (default: `undefined`)
68
- - Maximum value the slider can take
69
- - Attribute: `min`
70
- - Number (default: `undefined`)
71
- - Minimum value the slider can take
72
- - Attribute: `step`
73
- - Number (default: `undefined`)
74
- - Amount that value increments with smallest movement of the slider
75
- - Attribute: `value`
76
- - Number (default: `undefined`)
77
- - Initial value of the slider
78
- - Example:
79
- ```html
80
- <decidables-spinner disabled max="0" min="100" step="2" value="50">
81
- Change me
82
- </decidables-spinner>
83
- ```
84
- - `DecidablesSwitch`: Switch for turning an option on or off
85
- - `<decidables-switch></decidables-switch>`
86
- - Slot: *unnamed*
87
- - Inline content as label for **on** state
88
- - Slot: `off-label`
89
- - Inline content as label for **off** state
90
- - Attribute: `disabled`
91
- - Boolean (default: `false`)
92
- - In disabled state user can't interact
93
- - Attribute: `checked`
94
- - Number (default: `false`)
95
- - Whether the switch is **on** (`true`) or **off** ('false`)
96
- - Example:
97
- ```html
98
- <decidables-switch disabled checked>
99
- <span>On</span>
100
- <span slot="off-label">Off</span>
101
- </decidables-switch>
102
- ```
103
- - `DecidablesToggleOption`: One option in a toggle set
104
- - `<decidables-toggle-option></decidables-toggle-option>`
105
- - Slot: *unnamed*
106
- - Inline content as label for option
107
- - Attribute: `disabled`
108
- - Boolean (default: `false`)
109
- - In disabled state user can't interact
110
- - Attribute: `checked`
111
- - Number (default: `false`)
112
- - Whether the option is selected (`true`) or not ('false`)
113
- - Attribute: `name`
114
- - String (default: `undefined`)
115
- - An identifier to be shared by all options in a mutually exclusive group
116
- - Attribute: `value`
117
- - String (default: `undefined`)
118
- - An identifier specific to this option to uniquely identify it in the group
119
- - Example:
120
- ```html
121
- <decidables-toggle-option disabled name="flavors" value="chocolate" checked>
122
- Chocolate
123
- </decidables-toggle-option>
124
- ```
125
- - `DecidablesToggle`: Toggle for selecting one option from a set
126
- - `<decidables-toggle></decidables-toggle>`
127
- - Slot: *unnamed*
128
- - Inline content as label for set
129
- - Slot: `label`
130
- - Inline content as legend for options
131
- - Attribute: `disabled`
132
- - Boolean (default: `false`)
133
- - In disabled state user can't interact
134
- - Example:
135
- ```html
136
- <decidables-toggle disabled>
137
- <span>Pick one</span>
138
- <span slot="label">Flavors</span>
139
- <decidables-toggle-option disabled name="flavors" value="chocolate">
140
- Chocolate
141
- </decidables-toggle-option>
142
- <decidables-toggle-option disabled name="flavors" value="strawberry">
143
- Strawberry
144
- </decidables-toggle-option>
145
- <decidables-toggle-option disabled name="flavors" value="vanilla" checked>
146
- Vanilla
147
- </decidables-toggle-option>
148
- </decidables-toggle>
149
- ```
150
- - Base class
151
- - `DecidablesElement`: Base class for all *decidables* web components
152
- - To define a new element:
153
- ```javascript
154
- export default class DecidablesSomething extends DecidablesElement {
155
- ...
156
- }
157
- ```
158
- - This library is built on `Lit`, so the resulting `DecidableElement` is also a `LitElement`
159
- - Utilities
160
- - `DecidablesConverterArray`: Utility for attributes that can take an array of values
161
- - If you are defining a `DecidablesElement` with an attribute that can take an array of numbers,
162
- then you can use this to automatically convert between a space-separated list as the attribute
163
- and an `Array` of numbers as the property:
164
- ```javascript
165
- static get properties() {
166
- return {
167
- stuff: {
168
- attribute: 'values',
169
- converter: DecidablesConverterArray,
170
- reflect: true,
171
- },
172
- };
173
- };
174
- ```
175
- ```html
176
- <decidables-something values="1.23 3.56 -2.97"></decidables-something>
177
- ```
178
- And `this.values` will be the `Array`: `[1.23 3.56 -2.97]`
179
- - `DecidablesConverterSet`: Utility for attributes that can take a set of values
180
- - If you are defining a `DecidablesElement` with an attribute that can take a set of string
181
- values, then you can use this to automatically convert between a space-separated list as the
182
- attribute and a `Set` of strings as the property:
183
- ```javascript
184
- static get properties() {
185
- return {
186
- stuff: {
187
- attribute: 'stuff',
188
- converter: DecidablesConverterSet,
189
- reflect: true,
190
- },
191
- };
192
- };
193
- ```
194
- ```html
195
- <decidables-something stuff="this that other"></decidables-something>
196
- ```
197
- And `this.stuff` will be a `Set` with members: `'this'`, `'that'`, and `'other'`
198
-
199
- ---
200
-
201
- ## Features/Bugs/Notes
31
+ ### Components
32
+
33
+ #### `DecidablesButton` / `<decidables-button>`
34
+
35
+ Button for taking actions
36
+
37
+ ##### Slots
38
+
39
+ - *unnamed*
40
+ - Inline content as label
41
+
42
+ ##### Attributes
43
+
44
+ - `disabled: boolean = false`
45
+ - In disabled state user can't interact
46
+
47
+ ##### Example
48
+
49
+ ```html
50
+ <decidables-button disabled>
51
+ Click me
52
+ </decidables-button>
53
+ ```
54
+
55
+ #### `DecidablesSlider` / `<decidables-slider>`
56
+
57
+ Slider w/spinner for selecting a numeric value from a range
58
+
59
+ ##### Slots
60
+
61
+ - *unnamed*
62
+ - Inline content as label
63
+
64
+ ##### Attributes
65
+
66
+ - `disabled: boolean = false`
67
+ - In disabled state user can't interact
68
+ - `max: number = undefined`
69
+ - Maximum value the slider can take
70
+ - `min: number = undefined`
71
+ - Minimum value the slider can take
72
+ - `step: number = undefined`
73
+ - Amount that value increments with smallest movement of the slider
74
+ - `value: number = undefined`
75
+ - Initial value of the slider
76
+
77
+ ##### Example
78
+
79
+ ```html
80
+ <decidables-slider disabled max="0" min="100" step="2" value="50">
81
+ Move me
82
+ </decidables-slider>
83
+ ```
84
+
85
+ #### `DecidablesSpinner` / `<decidables-spinner>`
86
+
87
+ Text field w/spinner arrows for selecting a continuous numeric value
88
+
89
+ ##### Slots
90
+
91
+ - *unnamed*
92
+ - Inline content as label
93
+
94
+ ##### Attributes
95
+
96
+ - `disabled: boolean = false`
97
+ - In disabled state user can't interact
98
+ - `max: number = undefined`
99
+ - Maximum value the slider can take
100
+ - `min: number = undefined`
101
+ - Minimum value the slider can take
102
+ - `step: number = undefined`
103
+ - Amount that value increments with smallest movement of the slider
104
+ - `value: number = undefined`
105
+ - Initial value of the slider
106
+
107
+ ##### Example
108
+
109
+ ```html
110
+ <decidables-spinner disabled max="0" min="100" step="2" value="50">
111
+ Change me
112
+ </decidables-spinner>
113
+ ```
114
+
115
+ #### `DecidablesSwitch` / `<decidables-switch>`
116
+
117
+ Switch for turning an option on or off
118
+
119
+ ##### Slots
120
+
121
+ - *unnamed*
122
+ - Inline content as label for **on** state
123
+ - `off-label`
124
+ - Inline content as label for **off** state
125
+
126
+ ##### Attributes
127
+
128
+ - `disabled: boolean = false`
129
+ - In disabled state user can't interact
130
+ - `checked: number = false`
131
+ - Whether the switch is **on** (`true`) or **off** (`false`)
132
+
133
+ ##### Example
134
+
135
+ ```html
136
+ <decidables-switch disabled checked>
137
+ <span>On</span>
138
+ <span slot="off-label">Off</span>
139
+ </decidables-switch>
140
+ ```
141
+
142
+ #### `DecidablesToggleOption` / `<decidables-toggle-option>`
143
+
144
+ One option in a toggle set
145
+
146
+ ##### Slots
147
+
148
+ - *unnamed*
149
+ - Inline content as label for option
150
+
151
+ ##### Attributes
152
+
153
+ - `disabled: boolean = false`
154
+ - In disabled state user can't interact
155
+ - `checked: number = false`
156
+ - Whether the option is selected (`true`) or not ('false`)
157
+ - `name: string = undefined`
158
+ - An identifier to be shared by all options in a mutually exclusive group
159
+ - `value: string = undefined`
160
+ - An identifier specific to this option to uniquely identify it in the group
161
+
162
+ ##### Example
163
+
164
+ ```html
165
+ <decidables-toggle-option disabled name="flavors" value="chocolate" checked>
166
+ Chocolate
167
+ </decidables-toggle-option>
168
+ ```
169
+
170
+ #### `DecidablesToggle` / `<decidables-toggle>`
171
+
172
+ Toggle for selecting one option from a set
173
+
174
+ ##### Slots
175
+
176
+ - *unnamed*
177
+ - Inline content as label for set
178
+ - `label`
179
+ - Inline content as legend for options
180
+
181
+ ##### Attributes
182
+
183
+ - `disabled: boolean = false`
184
+ - In disabled state user can't interact
185
+
186
+ ##### Example
187
+
188
+ ```html
189
+ <decidables-toggle disabled>
190
+ <span>Pick one</span>
191
+ <span slot="label">Flavors</span>
192
+ <decidables-toggle-option disabled name="flavors" value="chocolate">
193
+ Chocolate
194
+ </decidables-toggle-option>
195
+ <decidables-toggle-option disabled name="flavors" value="strawberry">
196
+ Strawberry
197
+ </decidables-toggle-option>
198
+ <decidables-toggle-option disabled name="flavors" value="vanilla" checked>
199
+ Vanilla
200
+ </decidables-toggle-option>
201
+ </decidables-toggle>
202
+ ```
203
+
204
+ ### Base class
205
+
206
+ #### `DecidablesElement`
207
+
208
+ Base class for all *decidables* web components
209
+
210
+ To define a new element:
211
+
212
+ ```javascript
213
+ export default class DecidablesSomething extends DecidablesElement {
214
+ ...
215
+ }
216
+ ```
217
+
218
+ This library is built on `Lit`, so the resulting `DecidableElement` is also a `LitElement`
219
+
220
+ ### Utilities
221
+
222
+ #### `DecidablesConverterArray`
223
+
224
+ Utility for attributes that can take an array of values
225
+
226
+ If you are defining a `DecidablesElement` with an attribute that can take an array of numbers,
227
+ then you can use this to automatically convert between a space-separated list as the attribute
228
+ and an `Array` of numbers as the property:
229
+
230
+ ```javascript
231
+ static get properties() {
232
+ return {
233
+ stuff: {
234
+ attribute: 'values',
235
+ converter: DecidablesConverterArray,
236
+ reflect: true,
237
+ },
238
+ };
239
+ };
240
+ ```
241
+
242
+ ```html
243
+ <decidables-something values="1.23 3.56 -2.97"></decidables-something>
244
+ ```
245
+
246
+ And `this.values` will be the `Array`: `[1.23 3.56 -2.97]`
247
+
248
+ #### `DecidablesConverterSet`
249
+
250
+ Utility for attributes that can take a set of values
251
+
252
+ If you are defining a `DecidablesElement` with an attribute that can take a set of string
253
+ values, then you can use this to automatically convert between a space-separated list as the
254
+ attribute and a `Set` of strings as the property:
255
+
256
+ ```javascript
257
+ static get properties() {
258
+ return {
259
+ stuff: {
260
+ attribute: 'stuff',
261
+ converter: DecidablesConverterSet,
262
+ reflect: true,
263
+ },
264
+ };
265
+ };
266
+ ```
267
+
268
+ ```html
269
+ <decidables-something stuff="this that other"></decidables-something>
270
+ ```
271
+
272
+ And `this.stuff` will be a `Set` with members: `'this'`, `'that'`, and `'other'`
273
+
274
+ ## Development
275
+
276
+ ### Features/Bugs/Notes
202
277
 
203
278
  - Custom spinner that looks better than User Agent spinners?
204
279
  - Edge/IE11 - slider shadow is clipped
@@ -206,11 +281,7 @@
206
281
  - Firefox - spinner arrows look ugly and asymmetrical
207
282
  - IE11 - No CSS variables outside custom elements (and not patched by ShadyCSS!)
208
283
 
209
- ---
210
-
211
- ## Development Tooling
212
-
213
- ### Local Scripts
284
+ ### Package Scripts
214
285
 
215
286
  - `yarn lint`
216
287
  - Lints markdown, scripts and styles
@@ -223,9 +294,7 @@
223
294
  - `yarn build`
224
295
  - Builds bundles from `src/` to `lib/`
225
296
 
226
- ---
227
-
228
- ## File Organization
297
+ ### File Organization
229
298
 
230
299
  - `decidables-elements/`
231
300
  - `lib/` (Bundles created from `src/` by `build`) **\[autogenerated\]**
@@ -233,6 +302,13 @@
233
302
  - `test/` (Testing files)
234
303
  - `coverage/` (Code coverage results) **\[autogenerated\]**
235
304
  - `CHANGELOG.md` (Based on conventional commits) **\[autogenerated\]**
236
- - `gulpfile.js` (Config for *gulp*)
237
- - `package.json` (Config for *yarn* and *npm*)
305
+ - `gulpfile.js` (Tasks for *gulp*)
306
+ - `package.json` (Package config for *yarn* and *npm*)
238
307
  - `README.md` (This file)
308
+
309
+ ## [License](https://github.com/decidables/decidables/blob/main/LICENSE.md)
310
+
311
+ The content of this project is licensed under [Creative Commons Attribution-ShareAlike 4.0
312
+ International License (CC-BY-SA-4.0)](https://creativecommons.org/licenses/by-sa/4.0/) and the
313
+ source code of this project is licensed under [GNU General Public License v3.0 or any later version
314
+ (GPL-3.0-or-later)](https://www.gnu.org/licenses/gpl-3.0.html).