@justeattakeaway/pie-switch 1.4.1 → 1.4.3
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 +122 -14
- package/custom-elements.json +7 -7
- package/dist/index.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,34 +1,142 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
</p>
|
|
1
|
+
# @justeattakeaway/pie-switch
|
|
2
|
+
[Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-switch) | [Design Documentation](https://pie.design/components/switch) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-switch)
|
|
4
3
|
|
|
5
|
-
<p
|
|
4
|
+
<p>
|
|
6
5
|
<a href="https://www.npmjs.com/@justeattakeaway/pie-switch">
|
|
7
6
|
<img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-switch.svg">
|
|
8
7
|
</a>
|
|
9
8
|
</p>
|
|
10
9
|
|
|
11
|
-
|
|
10
|
+
`@justeattakeaway/pie-switch` is a Web Component built using the Lit library. It offers a simple and accessible interactive switch component for web applications.
|
|
11
|
+
|
|
12
|
+
## Table of Contents
|
|
12
13
|
|
|
13
|
-
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Documentation](#documentation)
|
|
16
|
+
- [Properties](#properties)
|
|
17
|
+
- [Slots](#slots)
|
|
18
|
+
- [CSS Variables](#css-variables)
|
|
19
|
+
- [Events](#events)
|
|
20
|
+
- [Forms Usage](#forms-usage)
|
|
21
|
+
- [Form Validation](#form-validation)
|
|
22
|
+
- [Usage Examples](#usage-examples)
|
|
23
|
+
- [Questions and Support](#questions-and-support)
|
|
24
|
+
- [Contributing](#contributing)
|
|
14
25
|
|
|
15
26
|
## Installation
|
|
16
27
|
|
|
17
|
-
To install
|
|
28
|
+
> To install any of our web components in your application, we would suggest following the [getting started guide](https://webc.pie.design/?path=/docs/introduction-getting-started--docs) to set up your project.
|
|
29
|
+
|
|
30
|
+
Ideally, you should install the component using the **`@justeattakeaway/pie-webc`** package, which includes all of the components. Or you can install the individual component package.
|
|
31
|
+
|
|
32
|
+
## Documentation
|
|
33
|
+
|
|
34
|
+
### Properties
|
|
35
|
+
| Prop | Options | Description | Default |
|
|
36
|
+
|------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------|
|
|
37
|
+
| `checked` | `true`, `false` | Same as the HTML `checked` attribute; indicates whether the switch is on or off. | `false` |
|
|
38
|
+
| `disabled` | `true`, `false` | Same as the HTML `disabled` attribute; indicates whether the switch is disabled or not. | `false` |
|
|
39
|
+
| `required` | `true`, `false` | Same as the HTML `required` attribute; indicates whether the switch must be turned on when submitted as part of a form. | `false` |
|
|
40
|
+
| `label` | — | The label text for the switch. | — |
|
|
41
|
+
| `labelPlacement` | `"leading"`, `"trailing"` | Set the placement of the label. Leading will have the label before the switch, taking writing direction into account. | `"leading"` |
|
|
42
|
+
| `aria` | `{ label?: string, describedBy?: string }` | The ARIA labels used for the switch. | `undefined` |
|
|
43
|
+
| `name` | — | Indicates the name of the switch (for use with forms). | — |
|
|
44
|
+
| `value` | — | Indicates the value of the switch (for use with forms). | `"on"` |
|
|
45
|
+
|
|
46
|
+
### Slots
|
|
47
|
+
This component does not have any slots. All content is passed through properties.
|
|
48
|
+
|
|
49
|
+
### CSS Variables
|
|
50
|
+
This component does not expose any CSS variables for style overrides.
|
|
18
51
|
|
|
19
|
-
|
|
20
|
-
npm i @justeattakeaway/pie-switch
|
|
52
|
+
### Events
|
|
21
53
|
|
|
22
|
-
|
|
54
|
+
This component does not emit any custom events. In order to add event listening to this component, you can treat it like a native HTML element in your application.
|
|
55
|
+
|
|
56
|
+
## Forms Usage
|
|
57
|
+
The `pie-switch` component can be integrated into HTML forms similarly to native HTML input elements. The component will associate itself with any form it is placed inside. As long as you provide a `name` attribute, the component will be included in the form's submission payload. A `value` attribute can also be provided, but if not then it will have a default value of `on`.
|
|
58
|
+
|
|
59
|
+
```html
|
|
60
|
+
<form action="/default-endpoint" method="POST">
|
|
61
|
+
<pie-switch name="switch" value="someValue" label="Click me"></pie-switch>
|
|
62
|
+
<button type="submit">Submit</button>
|
|
63
|
+
</form>
|
|
23
64
|
```
|
|
24
65
|
|
|
25
|
-
|
|
66
|
+
### Form Validation
|
|
67
|
+
To make `pie-switch` a required form field, simply add the `required` attribute to the component markup. This will prevent the form from being submitted if the switch is not toggled and will trigger native HTML form validation.
|
|
68
|
+
|
|
69
|
+
Currently this defaults to browser styling, but this may be updated in the future.
|
|
70
|
+
|
|
71
|
+
```html
|
|
72
|
+
<form action="/default-endpoint" method="POST">
|
|
73
|
+
<pie-switch name="switch" value="someValue" label="Click me" required></pie-switch>
|
|
74
|
+
<button type="submit">Submit</button>
|
|
75
|
+
</form>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
To set a custom validation message, please call the `setCustomValidity` method exposed by the component. This will allow you to set a custom message that will be displayed when the form is submitted without the switch being toggled.
|
|
79
|
+
|
|
80
|
+
This behaviour is consistent with native HTML input elements. We may revisit this to provide a prop to set the custom validation message in the future.
|
|
26
81
|
|
|
27
|
-
|
|
82
|
+
```js
|
|
83
|
+
const switch = document.querySelector('pie-switch');
|
|
84
|
+
switch.setCustomValidity('Please toggle the switch');
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Usage Examples
|
|
88
|
+
|
|
89
|
+
**For HTML:**
|
|
90
|
+
|
|
91
|
+
```js
|
|
92
|
+
// import as module into a js file e.g. main.js
|
|
93
|
+
import '@justeattakeaway/pie-webc/components/card.js';
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
```html
|
|
97
|
+
<pie-switch
|
|
98
|
+
id="switch"
|
|
99
|
+
checked
|
|
100
|
+
label="Label"
|
|
101
|
+
labelPlacement="trailing"
|
|
102
|
+
onchange="(event) => {
|
|
103
|
+
console.log(event.target.checked);
|
|
104
|
+
}"></pie-switch>
|
|
105
|
+
|
|
106
|
+
<script type="module" src="/main.js"></script>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**For Native JS Applications, Vue, Angular, Svelte etc.:**
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
// Vue templates (using Nuxt 3)
|
|
113
|
+
import '@justeattakeaway/pie-webc/components/switch.js';
|
|
114
|
+
|
|
115
|
+
<pie-switch
|
|
116
|
+
id="switch"
|
|
117
|
+
checked
|
|
118
|
+
label="Label"
|
|
119
|
+
labelPlacement="trailing"
|
|
120
|
+
@change="handleChange">
|
|
121
|
+
</pie-switch>
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**For React Applications:**
|
|
125
|
+
|
|
126
|
+
```jsx
|
|
127
|
+
import { PieSwitch } from '@justeattakeaway/pie-webc/react/switch.js';
|
|
128
|
+
|
|
129
|
+
<PieSwitch
|
|
130
|
+
id="switch"
|
|
131
|
+
checked
|
|
132
|
+
label="Label"
|
|
133
|
+
labelPlacement="trailing"
|
|
134
|
+
onChange={handleChange}/></PieSwitch>
|
|
135
|
+
```
|
|
28
136
|
|
|
29
|
-
## Questions
|
|
137
|
+
## Questions and Support
|
|
30
138
|
|
|
31
|
-
|
|
139
|
+
If you work at Just Eat Takeaway.com, please contact us on **#help-designsystem**. Otherwise, please raise an issue on [Github](https://github.com/justeattakeaway/pie/issues).
|
|
32
140
|
|
|
33
141
|
## Contributing
|
|
34
142
|
|
package/custom-elements.json
CHANGED
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
"type": {
|
|
36
36
|
"text": "DefaultProps"
|
|
37
37
|
},
|
|
38
|
-
"default": "{\
|
|
38
|
+
"default": "{\n checked: false,\n disabled: false,\n labelPlacement: 'leading',\n required: false,\n value: 'on',\n}"
|
|
39
39
|
}
|
|
40
40
|
],
|
|
41
41
|
"exports": [
|
|
@@ -186,7 +186,7 @@
|
|
|
186
186
|
"text": ""
|
|
187
187
|
}
|
|
188
188
|
},
|
|
189
|
-
"description": "Returns a boolean value which indicates validity of the value of the component. If the value is invalid, this method also fires the invalid event on the component.\
|
|
189
|
+
"description": "Returns a boolean value which indicates validity of the value of the component. If the value is invalid, this method also fires the invalid event on the component.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity"
|
|
190
190
|
},
|
|
191
191
|
{
|
|
192
192
|
"kind": "method",
|
|
@@ -197,7 +197,7 @@
|
|
|
197
197
|
"text": ""
|
|
198
198
|
}
|
|
199
199
|
},
|
|
200
|
-
"description": "If the value is invalid, this method also fires the invalid event on the element, and (if the event isn't canceled) reports the problem to the user.\
|
|
200
|
+
"description": "If the value is invalid, this method also fires the invalid event on the element, and (if the event isn't canceled) reports the problem to the user.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity"
|
|
201
201
|
},
|
|
202
202
|
{
|
|
203
203
|
"kind": "method",
|
|
@@ -216,7 +216,7 @@
|
|
|
216
216
|
}
|
|
217
217
|
}
|
|
218
218
|
],
|
|
219
|
-
"description": "Allows a consumer to set a custom validation message on the switch. An empty string counts as valid.\
|
|
219
|
+
"description": "Allows a consumer to set a custom validation message on the switch. An empty string counts as valid.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity"
|
|
220
220
|
},
|
|
221
221
|
{
|
|
222
222
|
"kind": "field",
|
|
@@ -225,7 +225,7 @@
|
|
|
225
225
|
"text": "ValidityState"
|
|
226
226
|
},
|
|
227
227
|
"privacy": "public",
|
|
228
|
-
"description": "(Read-only) returns a ValidityState with the validity states that this element is in.\
|
|
228
|
+
"description": "(Read-only) returns a ValidityState with the validity states that this element is in.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity",
|
|
229
229
|
"readonly": true
|
|
230
230
|
},
|
|
231
231
|
{
|
|
@@ -235,7 +235,7 @@
|
|
|
235
235
|
"text": "string"
|
|
236
236
|
},
|
|
237
237
|
"privacy": "public",
|
|
238
|
-
"description": "(Read-only) Returns a string representing a localized message that describes the validation constraints that the control does not satisfy (if any).\
|
|
238
|
+
"description": "(Read-only) Returns a string representing a localized message that describes the validation constraints that the control does not satisfy (if any).\nThis string is empty if the component is valid.\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage",
|
|
239
239
|
"readonly": true
|
|
240
240
|
},
|
|
241
241
|
{
|
|
@@ -250,7 +250,7 @@
|
|
|
250
250
|
}
|
|
251
251
|
}
|
|
252
252
|
],
|
|
253
|
-
"description": "If a label is provided, renders it if `labelPlacement` matches the given position.\
|
|
253
|
+
"description": "If a label is provided, renders it if `labelPlacement` matches the given position.\nIf no label is provided, or `labelPlacement` does not match the given position, nothing is rendered."
|
|
254
254
|
},
|
|
255
255
|
{
|
|
256
256
|
"kind": "method",
|
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@justeattakeaway/pie-switch",
|
|
3
3
|
"description": "PIE Design System Switch built using Web Components",
|
|
4
|
-
"version": "1.4.
|
|
4
|
+
"version": "1.4.3",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "https://github.com/justeattakeaway/pie",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"cem-plugin-module-file-extensions": "0.0.5"
|
|
46
46
|
},
|
|
47
47
|
"dependencies": {
|
|
48
|
-
"@justeattakeaway/pie-icons-webc": "1.
|
|
48
|
+
"@justeattakeaway/pie-icons-webc": "1.11.1",
|
|
49
49
|
"@justeattakeaway/pie-webc-core": "1.0.0",
|
|
50
50
|
"@justeattakeaway/pie-wrapper-react": "0.14.3",
|
|
51
51
|
"element-internals-polyfill": "1.3.11"
|