@justeattakeaway/pie-checkbox 0.16.0 → 0.16.2

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 CHANGED
@@ -1,40 +1,141 @@
1
- <p align="center">
2
- <img align="center" src="../../../readme_image.png" height="200" alt="">
3
- </p>
1
+ # @justeattakeaway/pie-checkbox
2
+ [Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/components/pie-checkbox) | [Design Documentation](https://pie.design/components/checkbox) | [NPM](https://www.npmjs.com/package/@justeattakeaway/pie-checkbox)
4
3
 
5
- <p align="center">
4
+ <p>
6
5
  <a href="https://www.npmjs.com/@justeattakeaway/pie-checkbox">
7
6
  <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-checkbox.svg">
8
7
  </a>
9
8
  </p>
10
9
 
11
- ## pie-checkbox
12
-
13
- `pie-checkbox` is a Web Component built using the Lit library.
10
+ `@justeattakeaway/pie-checkbox` is a Web Component built using the Lit library. It offers a simple and accessible checkbox component for web applications.
14
11
 
15
- This component can be easily integrated into various frontend frameworks and customized through a set of properties.
12
+ ## Table of Contents
16
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
+ - [Validation](#validation)
22
+ - [Usage Examples](#usage-examples)
23
+ - [Questions and Support](#questions-and-support)
24
+ - [Contributing](#contributing)
17
25
 
18
26
  ## Installation
19
27
 
20
- To install `pie-checkbox` in your application, run the following on your command line:
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
+
36
+ | Prop | Options | Description | Default |
37
+ |------------------|----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
38
+ | `name` | `-` | The name of the checkbox (used as a key/value pair with `value`). This is required in order to work properly with forms. | `-` |
39
+ | `value` | `-` | The value of the input (used as a key/value pair in HTML forms with name). If not passed falls back to the html default value `"on"`. | `"on"` |
40
+ | `required` | `-` | If true, the checkbox is required to be checked before submitting the form. If it is not in checked state, the component validity state will be invalid. | `false` |
41
+ | `disabled` | `-` | Indicates whether or not the checkbox is disabled. | `false` |
42
+ | `checked` | `-` | Controls whether or not the checkbox is checked. | `false` |
43
+ | `defaultChecked` | `-` | Sets the default checked state for the checkbox. This does not directly set the initial checked state when the page loads, use `checked` for that. If the checkbox is inside a form which is reset, the `checked` state will be updated to match `defaultChecked`. | `false` |
44
+ | `indeterminate` | `-` | Indicates whether the checkbox visually shows a horizontal line in the box instead of a check/tick. It has no impact on whether the checkbox's value is used in a form submission. That is decided by the checked state, regardless of the indeterminate state. | `false` |
45
+ | `assistiveText` | `-` | Allows assistive text to be displayed below the checkbox element. | `-` |
46
+ | `status` | `"default"`, `"error"`, `"success"` | The status of the checkbox component / assistive text. If you use `status` you must provide an `assistiveText` prop value for accessibility purposes. | `"default"` |
47
+
48
+ ### Slots
49
+
50
+ | Slot | Description |
51
+ |----------|--------------------------------------------------------------|
52
+ | `default`| The default, unnamed slot is used to pass in text to the component. |
53
+
54
+ ### CSS Variables
55
+ This component does not expose any CSS variables for style overrides.
21
56
 
22
- ```bash
23
- $ npm i @justeattakeaway/pie-checkbox
57
+ ### Events
58
+
59
+ | Event | Type | Description |
60
+ |-----------|---------------|--------------------------------------------------------------|
61
+ | `change` | `CustomEvent` | Triggered after the checked state of a checkbox changes. |
62
+
63
+ ## Forms Usage
64
+
65
+ ### Validation
66
+ The checkbox component utilizes the [constraint validation API](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation) to provide a queryable validity state for consumers. This means that the component's validity can be checked via a `validity` getter.
67
+
68
+ #### Example:
69
+
70
+ ```js
71
+ const checkbox = document.querySelector('pie-checkbox');
72
+ console.log(checkbox.validity.valid);
24
73
  ```
25
- ```bash
26
- $ yarn add @justeattakeaway/pie-checkbox
74
+
75
+ This getter can be useful for reducing the amount of validation code in your application. For example, if you want to create a checkbox that requires attention, you can set the `required` property on the component. You can then check the validity of the input in your application code:
76
+
77
+ ```html
78
+ <pie-checkbox id="my-checkbox" required></pie-checkbox>
27
79
  ```
28
80
 
29
- For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
81
+ ```js
82
+ const checkbox = document.querySelector('pie-checkbox');
83
+ const isValid = checkbox.validity.valid;
30
84
 
31
- ## Documentation
85
+ // We could use this to drive the status and assistiveText properties on our checkbox (this would likely be inside a submit event handler in a real application)
86
+ if (!isValid) {
87
+ checkbox.status = 'error';
88
+ checkbox.assistiveText = 'This checkbox is required';
89
+ }
90
+ ```
32
91
 
33
- Visit [Checkbox | PIE Design System](https://pie.design/components/checkbox/code) to view more information on this component.
92
+ These concepts work just as well inside a Vue or React application.
93
+
94
+ ## Usage Examples
95
+
96
+ **For HTML:**
97
+
98
+ ```js
99
+ // import as module into a js file e.g. main.js
100
+ import '@justeattakeaway/pie-webc/components/checkbox.js'
101
+ ```
102
+
103
+ ```html
104
+ <pie-checkbox name="mycheckbox">Label</pie-checkbox>
105
+
106
+ <!-- Always use aria-label if you are not passing a label -->
107
+ <pie-checkbox name="mycheckbox" aria-label="Label"></pie-checkbox>
108
+ <script type="module" src="/main.js"></script>
109
+ ```
110
+
111
+ **For Native JS Applications, Vue, Angular, Svelte etc.:**
112
+
113
+ ```js
114
+ // import as module into a js file that will be loaded on the page where the component is used.
115
+ import '@justeattakeaway/pie-webc/components/checkbox.js';
116
+ ```
117
+
118
+ ```html
119
+ <pie-checkbox name="mycheckbox">Label</pie-checkbox>
120
+
121
+ <!-- Always use aria-label if you are not passing a label -->
122
+ <pie-checkbox name="mycheckbox" aria-label="Label"></pie-checkbox>
123
+ ```
124
+
125
+ **For React Applications:**
126
+
127
+ ```jsx
128
+ import { PieCheckbox } from '@justeattakeaway/pie-webc/react/checkbox.js';
129
+
130
+ <PieCheckbox name="mycheckbox">Label</PieCheckbox>
131
+
132
+ // Always use aria-label if you are not passing a label
133
+ <PieCheckbox name="mycheckbox" aria-label="Label"></PieCheckbox>
134
+ ```
34
135
 
35
- ## Questions
136
+ ## Questions and Support
36
137
 
37
- Please head to [FAQs | PIE Design System](https://pie.design/support/contact-us/) to see our FAQs and get in touch.
138
+ 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).
38
139
 
39
140
  ## Contributing
40
141
 
@@ -26,7 +26,7 @@
26
26
  "type": {
27
27
  "text": "DefaultProps"
28
28
  },
29
- "default": "{\n // a default value for the html <input type=\"checkbox\" /> value attribute.\n // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value\n value: 'on',\n disabled: false,\n defaultChecked: false,\n checked: false,\n indeterminate: false,\n required: false,\n status: 'default',\n}"
29
+ "default": "{\r\n // a default value for the html <input type=\"checkbox\" /> value attribute.\r\n // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value\r\n value: 'on',\r\n disabled: false,\r\n defaultChecked: false,\r\n checked: false,\r\n indeterminate: false,\r\n required: false,\r\n status: 'default',\r\n}"
30
30
  }
31
31
  ],
32
32
  "exports": [
@@ -179,7 +179,7 @@
179
179
  "text": "ValidityState"
180
180
  },
181
181
  "privacy": "public",
182
- "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",
182
+ "description": "(Read-only) returns a ValidityState with the validity states that this element is in.\r\nhttps://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity",
183
183
  "readonly": true
184
184
  },
185
185
  {
@@ -211,7 +211,7 @@
211
211
  "description": "The latest disabled state of the input."
212
212
  }
213
213
  ],
214
- "description": "Called after the disabled state of the element changes,\neither because the disabled attribute of this element was added or removed;\nor because the disabled state changed on a <fieldset> that's an ancestor of this element."
214
+ "description": "Called after the disabled state of the element changes,\r\neither because the disabled attribute of this element was added or removed;\r\nor because the disabled state changed on a <fieldset> that's an ancestor of this element."
215
215
  },
216
216
  {
217
217
  "kind": "method",
@@ -237,7 +237,7 @@
237
237
  "text": "void"
238
238
  }
239
239
  },
240
- "description": "Called when the form that contains this component is reset.\nIf the current checked state is different to the default checked state,\nthe checked state is reset to the default checked state and a `change` event is emitted."
240
+ "description": "Called when the form that contains this component is reset.\r\nIf the current checked state is different to the default checked state,\r\nthe checked state is reset to the default checked state and a `change` event is emitted."
241
241
  }
242
242
  ],
243
243
  "events": [
package/dist/index.js CHANGED
@@ -10,7 +10,7 @@ const k = class k extends y {
10
10
  this.getAttribute("v") || this.setAttribute("v", k.v);
11
11
  }
12
12
  };
13
- k.v = "0.16.0";
13
+ k.v = "0.16.2";
14
14
  let p = k;
15
15
  const T = '*,*:after,*:before{box-sizing:inherit}@keyframes checkboxCheck{0%{width:0;height:0;border-color:#fff;transform:translateZ(0) rotate(45deg)}33%{width:8px;height:0;transform:translateZ(0) rotate(45deg)}to{width:8px;height:16px;border-color:#fff;border-bottom-right-radius:2px;transform:translate3d(0,-16px,1px) rotate(45deg)}}@keyframes scaleDown{0%{transform:scale(1)}to{transform:scale(0)}}@keyframes scaleUp{0%{transform:scale(0)}33%{transform:scale(.5)}to{transform:scale(1)}}.c-checkbox-tick{content:"";display:flex;flex:0 0 auto;width:var(--checkbox-width);height:var(--checkbox-height);margin:var(--checkbox-margin);border:1px solid var(--checkbox-border-color);border-radius:var(--checkbox-radius);background-color:var(--checkbox-bg-color)}@media (prefers-reduced-motion: no-preference){.c-checkbox-tick{transition:background-color var(--dt-motion-timing-100) var(--checkbox-motion-easing),border-color var(--dt-motion-timing-100) var(--checkbox-motion-easing);animation:scaleDown var(--dt-motion-timing-100) var(--checkbox-motion-easing)}}.c-checkbox-tick.is-disabled{--checkbox-bg-color: var(--dt-color-container-strong);--checkbox-border-color: var(--dt-color-disabled-01)}.c-checkbox-tick.c-checkbox-tick--status-error{--checkbox-border-color: var(--dt-color-support-error)}@media (prefers-reduced-motion: no-preference){.c-checkbox-tick.c-checkbox-tick--checked{animation:scaleUp var(--dt-motion-timing-100) var(--checkbox-motion-easing)}}.c-checkbox-tick.c-checkbox-tick--checked:not(.is-disabled){--checkbox-bg-color: var(--dt-color-interactive-brand);--checkbox-border-color: var(--checkbox-bg-color)}.c-checkbox-tick.c-checkbox-tick--checked.c-checkbox-tick--status-error{--checkbox-bg-color: var(--dt-color-support-error);--checkbox-border-color: var(--checkbox-bg-color)}.c-checkbox-tick.c-checkbox-tick--checked:before{content:"";position:relative;top:55%;left:14%;border-right:2px solid transparent;border-bottom:2px solid transparent;transform:rotate(45deg);transform-origin:0% 100%;animation:checkboxCheck var(--dt-motion-timing-150) var(--checkbox-motion-easing) forwards}@media (prefers-reduced-motion: reduce){.c-checkbox-tick.c-checkbox-tick--checked:before{animation-duration:1ms!important;animation-delay:0!important;animation-iteration-count:1!important;width:8px;height:16px;border-color:#fff;border-bottom-right-radius:2px;transform:translate3d(0,-16px,0) rotate(45deg)}}@media only percy{.c-checkbox-tick.c-checkbox-tick--checked:before{animation:none;width:8px;height:16px;border-color:#fff;border-bottom-right-radius:2px;transform:translate3d(0,-16px,0) rotate(45deg)}}.c-checkbox-tick.c-checkbox-tick--checked.c-checkbox-tick--rtl:before{left:unset;right:50%}.c-checkbox-tick.c-checkbox-tick--indeterminate:not(.is-disabled){--checkbox-bg-color: var(--dt-color-interactive-brand);--checkbox-border-color: var(--checkbox-bg-color)}.c-checkbox-tick.c-checkbox-tick--indeterminate.c-checkbox-tick--status-error{--checkbox-bg-color: var(--dt-color-support-error);--checkbox-border-color: var(--checkbox-bg-color)}.c-checkbox-tick.c-checkbox-tick--indeterminate:after{width:16px}@media (prefers-reduced-motion: no-preference){.c-checkbox-tick.c-checkbox-tick--indeterminate:after{transition:width var(--dt-motion-timing-100) var(--checkbox-motion-easing) var(--dt-motion-timing-100)}}.c-checkbox-text{display:inline;flex:1 1 auto;align-self:center;min-width:0;margin-inline-start:var(--checkbox-gap);white-space:normal;color:var(--checkbox-content-color);font-size:var(--checkbox-font-size);line-height:var(--checkbox-line-height);font-weight:var(--checkbox-font-weight)}.c-checkbox-tick:after{content:"";position:relative;top:47%;left:14%;width:0;height:2px;background-color:#fff}.c-checkbox-tick.c-checkbox-tick--rtl:after{left:unset;right:14%}.c-checkbox{--checkbox-height: 24px;--checkbox-width: 24px;--checkbox-radius: var(--dt-radius-rounded-a);--checkbox-margin: 1px;--checkbox-gap: var(--dt-spacing-b);--checkbox-font-size: calc(var(--dt-font-body-l-size) * 1px);--checkbox-line-height: calc(var(--dt-font-body-l-line-height) * 1px);--checkbox-font-weight: var(--dt-font-weight-regular);--checkbox-bg-color: var(--dt-color-container-default);--checkbox-border-color: var(--dt-color-border-form);--checkbox-content-color: var(--dt-color-content-default);--checkbox-motion-easing: var(--dt-motion-easing-persistent-functional);display:flex;flex-direction:column}.c-checkbox input{display:block;position:absolute;height:1px;width:1px;overflow:hidden;clip:rect(1px,1px,1px,1px);clip-path:inset(1px);white-space:nowrap}.c-checkbox label{display:flex;max-width:100%;white-space:nowrap;cursor:pointer}.c-checkbox:hover .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) - var(--dt-color-hover-01)) );transition:background-color var(--dt-motion-timing-200) var(--checkbox-motion-easing),border-color var(--dt-motion-timing-200) var(--checkbox-motion-easing)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox:hover .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}.c-checkbox:active .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) - var(--dt-color-active-01)) );transition:background-color var(--dt-motion-timing-100) var(--checkbox-motion-easing),border-color var(--dt-motion-timing-100) var(--checkbox-motion-easing)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox:active .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-active-01-bg) var(--dt-color-active-01), var(--dt-color-container-default))}}.c-checkbox.is-disabled label{cursor:not-allowed}.c-checkbox input:focus-visible+label .c-checkbox-tick{box-shadow:0 0 0 2px var(--dt-color-focus-inner),0 0 0 4px var(--dt-color-focus-outer);outline:none}.c-checkbox.is-disabled:hover .c-checkbox-tick,.c-checkbox.is-disabled:active .c-checkbox-tick{--checkbox-bg-color: var(--dt-color-container-strong);--checkbox-border-color: var(--dt-color-disabled-01)}.c-checkbox.c-checkbox--status-error:hover .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) - var(--dt-color-hover-01)) )}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--status-error:hover .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-container-default))}}.c-checkbox.c-checkbox--status-error:active .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) - var(--dt-color-active-01)) )}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--status-error:active{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-active-01-bg) var(--dt-color-active-01), var(--dt-color-container-default))}}.c-checkbox.c-checkbox--checked:not(.is-disabled):hover .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate:not(.is-disabled):hover .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-interactive-brand-h), var(--dt-color-interactive-brand-s), calc(var(--dt-color-interactive-brand-l) - var(--dt-color-hover-01)) );--checkbox-border-color: var(--checkbox-bg-color)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--checked:not(.is-disabled):hover .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate:not(.is-disabled):hover .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-interactive-brand));--checkbox-border-color: var(--checkbox-bg-color)}}.c-checkbox.c-checkbox--checked.c-checkbox--status-error:hover .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate.c-checkbox--status-error:hover .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-support-error-h), var(--dt-color-support-error-s), calc(var(--dt-color-support-error-l) - var(--dt-color-hover-01)) );--checkbox-border-color: var(--checkbox-bg-color)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--checked.c-checkbox--status-error:hover .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate.c-checkbox--status-error:hover .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-hover-01-bg) var(--dt-color-hover-01), var(--dt-color-support-error));--checkbox-border-color: var(--checkbox-bg-color)}}.c-checkbox.c-checkbox--checked:not(.is-disabled):active .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate:not(.is-disabled):active .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-interactive-brand-h), var(--dt-color-interactive-brand-s), calc(var(--dt-color-interactive-brand-l) - var(--dt-color-active-01)) );--checkbox-border-color: var(--checkbox-bg-color)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--checked:not(.is-disabled):active .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate:not(.is-disabled):active .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-active-01-bg) var(--dt-color-active-01), var(--dt-color-interactive-brand));--checkbox-border-color: var(--checkbox-bg-color)}}.c-checkbox.c-checkbox--checked.c-checkbox--status-error:active .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate.c-checkbox--status-error:active .c-checkbox-tick{--checkbox-bg-color: hsl( var(--dt-color-support-error-h), var(--dt-color-support-error-s), calc(var(--dt-color-support-error-l) - var(--dt-color-active-01)) );--checkbox-border-color: var(--checkbox-bg-color)}@supports (background-color: color-mix(in srgb,black,white)){.c-checkbox.c-checkbox--checked.c-checkbox--status-error:active .c-checkbox-tick,.c-checkbox.c-checkbox--indeterminate.c-checkbox--status-error:active .c-checkbox-tick{--checkbox-bg-color: color-mix(in srgb, var(--dt-color-active-01-bg) var(--dt-color-active-01), var(--dt-color-support-error));--checkbox-border-color: var(--checkbox-bg-color)}}', z = ["default", "success", "error"], a = {
16
16
  // a default value for the html <input type="checkbox" /> value attribute.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@justeattakeaway/pie-checkbox",
3
3
  "description": "PIE Design System Checkbox built using Web Components",
4
- "version": "0.16.0",
4
+ "version": "0.16.2",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "https://github.com/justeattakeaway/pie",
@@ -45,8 +45,8 @@
45
45
  "cem-plugin-module-file-extensions": "0.0.5"
46
46
  },
47
47
  "dependencies": {
48
- "@justeattakeaway/pie-assistive-text": "0.10.0",
49
- "@justeattakeaway/pie-webc-core": "0.26.0"
48
+ "@justeattakeaway/pie-assistive-text": "0.10.2",
49
+ "@justeattakeaway/pie-webc-core": "1.0.0"
50
50
  },
51
51
  "volta": {
52
52
  "extends": "../../../package.json"