@justeattakeaway/pie-chip 0.12.11 → 0.14.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 +79 -28
- package/custom-elements.json +56 -26
- package/dist/index.d.ts +32 -23
- package/dist/index.js +167 -98
- package/dist/react.d.ts +34 -24
- package/dist/react.js +13 -11
- package/package.json +5 -5
- package/src/chip.scss +32 -0
- package/src/defs.ts +9 -8
- package/src/index.ts +147 -51
- package/src/react.ts +4 -2
package/README.md
CHANGED
|
@@ -31,63 +31,114 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
|
|
|
31
31
|
|
|
32
32
|
### Properties
|
|
33
33
|
|
|
34
|
-
| Prop
|
|
35
|
-
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
34
|
+
| Prop | Options | Description | Default |
|
|
35
|
+
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
|
|
36
|
+
| `type` | `"button"`, `"checkbox"` | Sets the functional type of the chip. | `"button"` |
|
|
37
|
+
| `variant` | `"default"`, `"outline"`, `"ghost"` | Sets the variant of the chip. | `"default"` |
|
|
38
|
+
| `disabled` | `true`, `false` | If true, disables the chip. | `false` |
|
|
39
|
+
| `isSelected` | `true`, `false` | If true, the chip component will apply the selected styles. **This is a controlled property, meaning you are responsible for updating its value in response to user interaction events.** | `false` |
|
|
40
|
+
| `isDismissible` | `true`, `false` | If true, displays a close icon. Can be only used if `isSelected` is set to true. When true, the chip itself will not be interactive. Only the close icon will be. | `false` |
|
|
41
|
+
| `isLoading` | `true`, `false` | If true, displays a loading indicator inside the chip. It is advised to provide an appropriate `aria.label` value during and after loading. | `false` |
|
|
42
|
+
| `aria` | `{ label?: string, close?: string, haspopup?: "menu" \| "listbox" \| "tree" \| "grid" \| "dialog" \| "true" \| "false", expanded?: boolean }` | Accessibility properties for the chip. Use `haspopup` and `expanded` for chips that trigger a popup like a menu or dialog. | `undefined` |
|
|
42
43
|
|
|
43
44
|
### Slots
|
|
44
45
|
|
|
45
|
-
| Slot | Description
|
|
46
|
-
|
|
46
|
+
| Slot | Description |
|
|
47
|
+
|-----------|----------------------------------------------------------------|
|
|
47
48
|
| `default` | The default slot is used to pass text into the chip component. |
|
|
48
|
-
| `icon` | Used to pass an icon into the chip component.
|
|
49
|
+
| `icon` | Used to pass an icon into the chip component. |
|
|
49
50
|
|
|
50
51
|
### CSS Variables
|
|
51
52
|
This component does not expose any CSS variables for style overrides.
|
|
52
53
|
|
|
53
54
|
### Events
|
|
54
55
|
|
|
55
|
-
| Event
|
|
56
|
-
|
|
57
|
-
| `
|
|
56
|
+
| Event | Type | Description |
|
|
57
|
+
|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
58
|
+
| `change` | `Event` | **Emitted when a `type="checkbox"` chip is interacted with.** The component will not change its own `isSelected` state. You should use this event to toggle the `isSelected` property in your application's state. |
|
|
59
|
+
| `close` | `Event` | Triggered when the user interacts with the close icon on a dismissible chip. |
|
|
58
60
|
|
|
59
61
|
Visit [Chip | PIE Design System](https://pie.design/components/chip) to view more information on this component.
|
|
60
62
|
|
|
61
63
|
## Usage Examples
|
|
62
64
|
|
|
65
|
+
`pie-chip` is a controlled component. This means you are responsible for listening to events (`change` or `click`) and updating the `isSelected` property. This gives you full control over the component's state and behaviour.
|
|
66
|
+
|
|
63
67
|
**For HTML:**
|
|
68
|
+
### Basic Example (Checkbox)
|
|
64
69
|
|
|
65
|
-
|
|
66
|
-
// import as module into a js file e.g. main.js
|
|
67
|
-
import '@justeattakeaway/pie-webc/components/chip.js'
|
|
68
|
-
```
|
|
70
|
+
Here is how you would manage the state of a single checkbox-type chip.
|
|
69
71
|
|
|
70
72
|
```html
|
|
71
|
-
<pie-chip>
|
|
72
|
-
|
|
73
|
-
<script
|
|
73
|
+
<pie-chip type="checkbox" id="my-checkbox-chip">Enable notifications</pie-chip>
|
|
74
|
+
|
|
75
|
+
<script>
|
|
76
|
+
const checkboxChip = document.getElementById('pie-chip');
|
|
77
|
+
checkboxChip.addEventListener('change', () => {
|
|
78
|
+
// As a controlled component, we update the `isSelected` property ourselves
|
|
79
|
+
checkboxChip.isSelected = !checkboxChip.isSelected;
|
|
80
|
+
console.log('Notification chip is now:', checkboxChip.isSelected ? 'selected' : 'deselected');
|
|
81
|
+
});
|
|
82
|
+
</script>
|
|
74
83
|
```
|
|
75
84
|
|
|
76
85
|
**For Native JS Applications, Vue, Angular, Svelte etc.:**
|
|
86
|
+
### Interactive Chip Groups (Button)
|
|
87
|
+
|
|
88
|
+
You can easily create interactive groups, such as a single-select group where only one chip can be active at a time. For accessibility, it is recommended to wrap functional groups in a `<fieldset>` or give them a `role="group"`.
|
|
89
|
+
|
|
90
|
+
```html
|
|
91
|
+
<div id="single-select-group" role="group" aria-label="Choose a size">
|
|
92
|
+
<pie-chip type="button">Small</pie-chip>
|
|
93
|
+
<pie-chip type="button" isSelected>Medium</pie-chip>
|
|
94
|
+
<pie-chip type="button">Large</pie-chip>
|
|
95
|
+
</div>
|
|
77
96
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
import '@justeattakeaway/pie-webc/components/chip.js';
|
|
97
|
+
<script>
|
|
98
|
+
const chipGroup = document.getElementById('single-select-group');
|
|
81
99
|
|
|
82
|
-
|
|
100
|
+
chipGroup.addEventListener('click', (event) => {
|
|
101
|
+
const clickedChip = event.target.closest('pie-chip');
|
|
102
|
+
|
|
103
|
+
// Ensure a chip was actually clicked
|
|
104
|
+
if (!clickedChip) return;
|
|
105
|
+
|
|
106
|
+
const wasSelected = clickedChip.isSelected;
|
|
107
|
+
const allChips = chipGroup.querySelectorAll('pie-chip');
|
|
108
|
+
|
|
109
|
+
// 1. Deselect all chips in the group
|
|
110
|
+
allChips.forEach(chip => chip.isSelected = false);
|
|
111
|
+
|
|
112
|
+
// 2. Toggle the clicked chip
|
|
113
|
+
// This allows a user to deselect a chip by clicking it again
|
|
114
|
+
clickedChip.isSelected = !wasSelected;
|
|
115
|
+
});
|
|
116
|
+
</script>
|
|
83
117
|
```
|
|
84
118
|
|
|
85
119
|
**For React Applications:**
|
|
86
120
|
|
|
87
121
|
```jsx
|
|
88
122
|
import { PieChip } from '@justeattakeaway/pie-webc/react/chip.js';
|
|
89
|
-
|
|
90
|
-
|
|
123
|
+
import { useState } from 'react';
|
|
124
|
+
|
|
125
|
+
export default function ChipExample () {
|
|
126
|
+
const [isSelected, setIsSelected] = useState(false);
|
|
127
|
+
|
|
128
|
+
// For checkbox chips, use the `onChange` event
|
|
129
|
+
const handleOnChange = () => {
|
|
130
|
+
setIsSelected(!isSelected);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
return (
|
|
134
|
+
<PieChip
|
|
135
|
+
type="checkbox"
|
|
136
|
+
isSelected={isSelected}
|
|
137
|
+
onChange={handleOnChange}>
|
|
138
|
+
Enable notifications
|
|
139
|
+
</PieChip>
|
|
140
|
+
);
|
|
141
|
+
}
|
|
91
142
|
```
|
|
92
143
|
|
|
93
144
|
### Icons
|
|
@@ -101,7 +152,7 @@ We recommend using [@justeattakeaway/pie-icons-webc](https://www.npmjs.com/packa
|
|
|
101
152
|
-->
|
|
102
153
|
<pie-chip>
|
|
103
154
|
<icon-vegan slot="icon"></icon-vegan>
|
|
104
|
-
|
|
155
|
+
Vegan
|
|
105
156
|
</pie-chip>
|
|
106
157
|
```
|
|
107
158
|
|
package/custom-elements.json
CHANGED
|
@@ -22,12 +22,11 @@
|
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"kind": "variable",
|
|
25
|
-
"name": "
|
|
25
|
+
"name": "types",
|
|
26
26
|
"type": {
|
|
27
|
-
"text": "
|
|
27
|
+
"text": "['button', 'checkbox']"
|
|
28
28
|
},
|
|
29
|
-
"default": "'
|
|
30
|
-
"description": "Event name for when the chip is closed."
|
|
29
|
+
"default": "['button', 'checkbox']"
|
|
31
30
|
},
|
|
32
31
|
{
|
|
33
32
|
"kind": "variable",
|
|
@@ -35,7 +34,7 @@
|
|
|
35
34
|
"type": {
|
|
36
35
|
"text": "DefaultProps"
|
|
37
36
|
},
|
|
38
|
-
"default": "{\n variant: 'default',\n disabled: false,\n isSelected: false,\n isLoading: false,\n isDismissible: false,\n}"
|
|
37
|
+
"default": "{\n variant: 'default',\n disabled: false,\n isSelected: false,\n isLoading: false,\n isDismissible: false,\n type: 'button',\n}"
|
|
39
38
|
}
|
|
40
39
|
],
|
|
41
40
|
"exports": [
|
|
@@ -49,9 +48,9 @@
|
|
|
49
48
|
},
|
|
50
49
|
{
|
|
51
50
|
"kind": "js",
|
|
52
|
-
"name": "
|
|
51
|
+
"name": "types",
|
|
53
52
|
"declaration": {
|
|
54
|
-
"name": "
|
|
53
|
+
"name": "types",
|
|
55
54
|
"module": "src/defs.js"
|
|
56
55
|
}
|
|
57
56
|
},
|
|
@@ -89,6 +88,11 @@
|
|
|
89
88
|
"name": "variant",
|
|
90
89
|
"privacy": "public"
|
|
91
90
|
},
|
|
91
|
+
{
|
|
92
|
+
"kind": "field",
|
|
93
|
+
"name": "type",
|
|
94
|
+
"privacy": "public"
|
|
95
|
+
},
|
|
92
96
|
{
|
|
93
97
|
"kind": "field",
|
|
94
98
|
"name": "disabled",
|
|
@@ -119,59 +123,85 @@
|
|
|
119
123
|
},
|
|
120
124
|
{
|
|
121
125
|
"kind": "method",
|
|
122
|
-
"name": "
|
|
126
|
+
"name": "_onCheckboxChange",
|
|
127
|
+
"privacy": "private",
|
|
128
|
+
"description": "Handles the change event for the native checkbox.\nThis component is controlled, so it does not set its own state.\nIt simply forwards the native change event."
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
"kind": "method",
|
|
132
|
+
"name": "_renderSpinner",
|
|
123
133
|
"privacy": "private",
|
|
124
|
-
"
|
|
125
|
-
{
|
|
126
|
-
"
|
|
127
|
-
"type": {
|
|
128
|
-
"text": "Event"
|
|
129
|
-
}
|
|
134
|
+
"return": {
|
|
135
|
+
"type": {
|
|
136
|
+
"text": "TemplateResult"
|
|
130
137
|
}
|
|
131
|
-
|
|
132
|
-
"description": "
|
|
138
|
+
},
|
|
139
|
+
"description": "Template for the loading state spinner."
|
|
133
140
|
},
|
|
134
141
|
{
|
|
135
142
|
"kind": "method",
|
|
136
|
-
"name": "
|
|
143
|
+
"name": "_renderContent",
|
|
137
144
|
"privacy": "private",
|
|
138
145
|
"return": {
|
|
139
146
|
"type": {
|
|
140
147
|
"text": "TemplateResult"
|
|
141
148
|
}
|
|
142
149
|
},
|
|
143
|
-
"description": "
|
|
150
|
+
"description": "Renders the core content of the chip (icon, text, spinner)."
|
|
144
151
|
},
|
|
145
152
|
{
|
|
146
153
|
"kind": "method",
|
|
147
|
-
"name": "
|
|
154
|
+
"name": "_renderCheckbox",
|
|
148
155
|
"privacy": "private",
|
|
149
156
|
"return": {
|
|
150
157
|
"type": {
|
|
151
|
-
"text": "
|
|
158
|
+
"text": "TemplateResult"
|
|
152
159
|
}
|
|
153
160
|
},
|
|
154
|
-
"description": "
|
|
161
|
+
"description": "Template for the checkbox variant.\nThis uses a visually hidden native checkbox for accessibility and form integration."
|
|
162
|
+
},
|
|
163
|
+
{
|
|
164
|
+
"kind": "method",
|
|
165
|
+
"name": "_renderButton",
|
|
166
|
+
"privacy": "private",
|
|
167
|
+
"return": {
|
|
168
|
+
"type": {
|
|
169
|
+
"text": "TemplateResult"
|
|
170
|
+
}
|
|
171
|
+
}
|
|
155
172
|
},
|
|
156
173
|
{
|
|
157
174
|
"kind": "method",
|
|
158
|
-
"name": "
|
|
175
|
+
"name": "_renderDismissible",
|
|
159
176
|
"privacy": "private",
|
|
160
177
|
"return": {
|
|
161
178
|
"type": {
|
|
162
179
|
"text": "TemplateResult"
|
|
163
180
|
}
|
|
164
181
|
},
|
|
165
|
-
"description": "Template for the dismissible
|
|
182
|
+
"description": "Template for the dismissible variant."
|
|
166
183
|
}
|
|
167
184
|
],
|
|
168
185
|
"events": [
|
|
169
186
|
{
|
|
170
187
|
"type": {
|
|
171
|
-
"text": "
|
|
188
|
+
"text": "Event"
|
|
172
189
|
},
|
|
173
|
-
"description": "when a user clicks close button.",
|
|
174
|
-
"name": "
|
|
190
|
+
"description": "when a user clicks the close button.",
|
|
191
|
+
"name": "close"
|
|
192
|
+
},
|
|
193
|
+
{
|
|
194
|
+
"type": {
|
|
195
|
+
"text": "Event"
|
|
196
|
+
},
|
|
197
|
+
"description": "when a user interacts with the chip of type checkbox.",
|
|
198
|
+
"name": "change"
|
|
199
|
+
}
|
|
200
|
+
],
|
|
201
|
+
"mixins": [
|
|
202
|
+
{
|
|
203
|
+
"name": "DelegatesFocusMixin",
|
|
204
|
+
"package": "@justeattakeaway/pie-webc-core"
|
|
175
205
|
}
|
|
176
206
|
],
|
|
177
207
|
"superclass": {
|
package/dist/index.d.ts
CHANGED
|
@@ -6,6 +6,8 @@ import { TemplateResult } from 'lit';
|
|
|
6
6
|
declare type AriaProps = {
|
|
7
7
|
close?: string;
|
|
8
8
|
label?: string;
|
|
9
|
+
haspopup?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | 'true' | 'false';
|
|
10
|
+
expanded?: boolean;
|
|
9
11
|
};
|
|
10
12
|
|
|
11
13
|
export declare interface ChipProps {
|
|
@@ -34,61 +36,68 @@ export declare interface ChipProps {
|
|
|
34
36
|
* Can be only used if `isSelected` is set to true
|
|
35
37
|
*/
|
|
36
38
|
isDismissible?: boolean;
|
|
39
|
+
/**
|
|
40
|
+
* Sets the functional type of the chip. Can be `button` or `checkbox`. Defaults to `button`.
|
|
41
|
+
*/
|
|
42
|
+
type?: typeof types[number];
|
|
37
43
|
}
|
|
38
44
|
|
|
39
45
|
export declare type DefaultProps = ComponentDefaultProps<ChipProps, keyof Omit<ChipProps, 'aria'>>;
|
|
40
46
|
|
|
41
47
|
export declare const defaultProps: DefaultProps;
|
|
42
48
|
|
|
43
|
-
/**
|
|
44
|
-
* Event name for when the chip is closed.
|
|
45
|
-
*
|
|
46
|
-
* @constant
|
|
47
|
-
*/
|
|
48
|
-
export declare const ON_CHIP_CLOSE_EVENT = "pie-chip-close";
|
|
49
|
-
|
|
50
49
|
/**
|
|
51
50
|
* @tagname pie-chip
|
|
52
51
|
* @slot icon - The icon slot
|
|
53
52
|
* @slot - Default slot
|
|
54
|
-
* @event {
|
|
53
|
+
* @event {Event} close - when a user clicks the close button.
|
|
54
|
+
* @event {Event} change - when a user interacts with the chip of type checkbox.
|
|
55
55
|
*/
|
|
56
|
-
export declare class PieChip extends
|
|
56
|
+
export declare class PieChip extends PieChip_base implements ChipProps {
|
|
57
57
|
variant: "default" | "outline" | "ghost";
|
|
58
|
+
type: "button" | "checkbox";
|
|
58
59
|
disabled: boolean;
|
|
59
60
|
isSelected: boolean;
|
|
60
61
|
isLoading: boolean;
|
|
61
62
|
isDismissible: boolean;
|
|
62
63
|
aria: ChipProps['aria'];
|
|
63
64
|
/**
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
65
|
+
* Handles the change event for the native checkbox.
|
|
66
|
+
* This component is controlled, so it does not set its own state.
|
|
67
|
+
* It simply forwards the native change event.
|
|
67
68
|
* @private
|
|
68
69
|
*/
|
|
69
|
-
private
|
|
70
|
+
private _onCheckboxChange;
|
|
70
71
|
/**
|
|
71
|
-
* Template for the loading state
|
|
72
|
-
*
|
|
72
|
+
* Template for the loading state spinner.
|
|
73
73
|
* @private
|
|
74
74
|
*/
|
|
75
|
-
private
|
|
75
|
+
private _renderSpinner;
|
|
76
76
|
/**
|
|
77
|
-
*
|
|
78
|
-
*
|
|
77
|
+
* Renders the core content of the chip (icon, text, spinner).
|
|
79
78
|
* @private
|
|
80
79
|
*/
|
|
81
|
-
private
|
|
80
|
+
private _renderContent;
|
|
82
81
|
/**
|
|
83
|
-
* Template for the
|
|
84
|
-
*
|
|
82
|
+
* Template for the checkbox variant.
|
|
83
|
+
* This uses a visually hidden native checkbox for accessibility and form integration.
|
|
85
84
|
* @private
|
|
86
85
|
*/
|
|
87
|
-
private
|
|
88
|
-
|
|
86
|
+
private _renderCheckbox;
|
|
87
|
+
private _renderButton;
|
|
88
|
+
/**
|
|
89
|
+
* Template for the dismissible variant.
|
|
90
|
+
* @private
|
|
91
|
+
*/
|
|
92
|
+
private _renderDismissible;
|
|
93
|
+
render(): TemplateResult;
|
|
89
94
|
static styles: CSSResult;
|
|
90
95
|
}
|
|
91
96
|
|
|
97
|
+
declare const PieChip_base: typeof PieElement;
|
|
98
|
+
|
|
99
|
+
export declare const types: readonly ["button", "checkbox"];
|
|
100
|
+
|
|
92
101
|
export declare const variants: readonly ["default", "outline", "ghost"];
|
|
93
102
|
|
|
94
103
|
export { }
|