@justeattakeaway/pie-checkbox 0.3.1 → 0.5.0

package/README.md

@@ -30,11 +30,9 @@ This component can be easily integrated into various frontend frameworks and cus
 To install `pie-checkbox` in your application, run the following on your command line:
 
 ```bash
-# npm
-$ npm i @justeattakeaway/pie-checkbox
+npm i @justeattakeaway/pie-checkbox
 
-# yarn
-$ yarn add @justeattakeaway/pie-checkbox
+yarn add @justeattakeaway/pie-checkbox
 ```
 
 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).
@@ -80,7 +78,8 @@ import { PieCheckbox } from '@justeattakeaway/pie-checkbox/dist/react';
 | `required` | `boolean` | `false` | 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. |
 | `label` | `string` | '' | Text associated with the checkbox. If there is no label to provide, make sure to pass label, labelledby or describedby to the aria property. |
 | `disabled` | `boolean` | `false` | Indicates whether or not the checkbox is disabled. |
-| `checked` | `boolean` | `false` | Indicates whether or not the checkbox is checked by default (when the page loads). |
+| `checked` | `boolean` | `false` | Controls whether or not the checkbox is checked. |
+| `defaultChecked` | `boolean` | `false` | 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`. |
 | `indeterminate` | `boolean` | `false` | 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. |
 | `aria` | `object` | {} | accepts `label`, `labeledby` and `describedby` keys with string values. |
 
@@ -107,4 +106,4 @@ In your markup or JSX, you can then use these to set the properties for the `pie
 
 ## Contributing
 
-Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

package/custom-elements.json

@@ -18,7 +18,7 @@
           "type": {
             "text": "DefaultProps"
           },
-          "default": "{\n    required: false,\n    indeterminate: false,\n}"
+          "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    required: false,\n    defaultChecked: false,\n    indeterminate: false,\n    checked: false,\n}"
         }
       ],
       "exports": [
@@ -40,12 +40,6 @@
           "kind": "class",
           "description": "",
           "name": "PieCheckbox",
-          "slots": [
-            {
-              "description": "Default slot (checkbox label)",
-              "name": ""
-            }
-          ],
           "members": [
             {
               "kind": "field",
@@ -59,9 +53,6 @@
             {
               "kind": "field",
               "name": "value",
-              "type": {
-                "text": "CheckboxProps['value']"
-              },
               "privacy": "public",
               "attribute": "value"
             },
@@ -86,11 +77,16 @@
             {
               "kind": "field",
               "name": "checked",
-              "type": {
-                "text": "CheckboxProps['checked'] | undefined"
-              },
               "privacy": "public",
-              "attribute": "checked"
+              "attribute": "checked",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "defaultChecked",
+              "privacy": "public",
+              "attribute": "defaultChecked",
+              "reflects": true
             },
             {
               "kind": "field",
@@ -119,7 +115,8 @@
                 "text": "CheckboxProps['indeterminate'] | undefined"
               },
               "privacy": "public",
-              "attribute": "indeterminate"
+              "attribute": "indeterminate",
+              "reflects": true
             },
             {
               "kind": "field",
@@ -134,7 +131,7 @@
               "kind": "field",
               "name": "checkbox",
               "type": {
-                "text": "HTMLInputElement | undefined"
+                "text": "HTMLInputElement"
               },
               "privacy": "private"
             },
@@ -149,27 +146,75 @@
               "readonly": true
             },
             {
-              "kind": "field",
+              "kind": "method",
+              "name": "handleFormAssociation",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Ensures that the form value is in sync with the component."
+            },
+            {
+              "kind": "method",
+              "name": "formDisabledCallback",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "disabled",
+                  "type": {
+                    "text": "boolean"
+                  },
+                  "description": "The latest disabled state of the input."
+                }
+              ],
+              "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."
+            },
+            {
+              "kind": "method",
               "name": "handleChange",
               "privacy": "private",
-              "description": "The onChange function updates the checkbox state and emits an event for consumers.",
               "parameters": [
                 {
-                  "description": "This should be the change event that was listened for on an input element with `type=\"checkbox\"`.",
                   "name": "event",
                   "type": {
                     "text": "Event"
-                  }
+                  },
+                  "description": "This should be the change event that was listened for on an input element with `type=\"checkbox\"`."
+                }
+              ],
+              "description": "Captures the native change event and wraps it in a custom event."
+            },
+            {
+              "kind": "method",
+              "name": "formResetCallback",
+              "privacy": "public",
+              "return": {
+                "type": {
+                  "text": "void"
                 }
-              ]
+              },
+              "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."
             }
           ],
-          "attributes": [
+          "events": [
             {
-              "name": "value",
               "type": {
-                "text": "CheckboxProps['value']"
+                "text": "CustomEvent"
               },
+              "description": "when checked state is changed.",
+              "name": "change"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "value",
               "fieldName": "value"
             },
             {
@@ -188,11 +233,12 @@
             },
             {
               "name": "checked",
-              "type": {
-                "text": "CheckboxProps['checked'] | undefined"
-              },
               "fieldName": "checked"
             },
+            {
+              "name": "defaultChecked",
+              "fieldName": "defaultChecked"
+            },
             {
               "name": "disabled",
               "type": {
@@ -223,6 +269,10 @@
             }
           ],
           "mixins": [
+            {
+              "name": "FormControlMixin",
+              "package": "@justeattakeaway/pie-webc-core"
+            },
             {
               "name": "RtlMixin",
               "package": "@justeattakeaway/pie-webc-core"

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { ComponentDefaultPropsGeneric } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
+import type { FormControlInterface } from '@justeattakeaway/pie-webc-core';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
 import type { TemplateResult } from 'lit-html';
 
@@ -29,7 +31,11 @@ export declare interface CheckboxProps {
      */
     disabled?: boolean;
     /**
-     * Same as the HTML checked attribute - indicates whether or not the checkbox is checked by default (when the page loads).
+     * The default checked state of the checkbox (not necessarily the same as the current checked state).
+     */
+    defaultChecked?: boolean;
+    /**
+     * The checked state of the checkbox.
      */
     checked?: boolean;
     /**
@@ -47,13 +53,13 @@ export declare interface CheckboxProps {
     aria?: AriaProps;
 }
 
-export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'required' | 'indeterminate'>;
+export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked'>;
 
 export declare const defaultProps: DefaultProps;
 
 /**
  * @tagname pie-checkbox
- * @slot - Default slot (checkbox label)
+ * @event {CustomEvent} change - when checked state is changed.
  */
 export declare class PieCheckbox extends PieCheckbox_base implements CheckboxProps {
     static shadowRootOptions: {
@@ -61,29 +67,49 @@ export declare class PieCheckbox extends PieCheckbox_base implements CheckboxPro
         mode: ShadowRootMode;
         slotAssignment?: SlotAssignmentMode | undefined;
     };
-    value: CheckboxProps['value'];
+    value: string;
     label?: CheckboxProps['label'];
     name?: CheckboxProps['name'];
-    checked?: CheckboxProps['checked'];
+    checked: boolean;
+    defaultChecked: boolean;
     disabled?: CheckboxProps['disabled'];
     required?: CheckboxProps['required'];
     indeterminate?: CheckboxProps['indeterminate'];
     aria: CheckboxProps['aria'];
-    private checkbox?;
+    private checkbox;
     /**
      * (Read-only) returns a ValidityState with the validity states that this element is in.
      * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
      */
     get validity(): ValidityState;
     /**
-     * The onChange function updates the checkbox state and emits an event for consumers.
+     * Ensures that the form value is in sync with the component.
+     */
+    private handleFormAssociation;
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the input.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    protected firstUpdated(_changedProperties: PropertyValues<this>): void;
+    protected updated(_changedProperties: PropertyValues<this>): void;
+    /**
+     * Captures the native change event and wraps it in a custom event.
      * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
      */
     private handleChange;
+    /**
+     * Called when the form that contains this component is reset.
+     * If the current checked state is different to the default checked state,
+     * the checked state is reset to the default checked state and a `change` event is emitted.
+     */
+    formResetCallback(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
-declare const PieCheckbox_base: GenericConstructor<RTLInterface> & typeof LitElement;
+declare const PieCheckbox_base: GenericConstructor<FormControlInterface> & GenericConstructor<RTLInterface> & typeof LitElement;
 
 export { }

package/dist/index.js

@@ -1,24 +1,27 @@
-import { LitElement as y, html as m, nothing as d, unsafeCSS as f } from "lit";
-import { RtlMixin as v, wrapNativeEvent as g, defineCustomElement as $ } from "@justeattakeaway/pie-webc-core";
-import { property as n, query as x } from "lit/decorators.js";
-import { ifDefined as h } from "lit/directives/if-defined.js";
-const q = `*,*:after,*:before{box-sizing:inherit}
-`, b = {
+import { LitElement as u, html as f, nothing as h, unsafeCSS as b } from "lit";
+import { FormControlMixin as y, RtlMixin as k, wrapNativeEvent as v, defineCustomElement as C } from "@justeattakeaway/pie-webc-core";
+import { live as g } from "lit/directives/live.js";
+import { property as s, query as x } from "lit/decorators.js";
+import { ifDefined as $ } from "lit/directives/if-defined.js";
+const F = `*,*:after,*:before{box-sizing:inherit}
+`, d = {
+  // a default value for the html <input type="checkbox" /> value attribute.
+  // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value
+  value: "on",
   required: !1,
-  indeterminate: !1
+  defaultChecked: !1,
+  indeterminate: !1,
+  checked: !1
 };
-var C = Object.defineProperty, O = Object.getOwnPropertyDescriptor, o = (c, i, p, a) => {
-  for (var t = a > 1 ? void 0 : a ? O(i, p) : i, l = c.length - 1, s; l >= 0; l--)
-    (s = c[l]) && (t = (a ? s(i, p, t) : s(t)) || t);
-  return a && t && C(i, p, t), t;
+var E = Object.defineProperty, q = Object.getOwnPropertyDescriptor, r = (p, e, n, a) => {
+  for (var o = a > 1 ? void 0 : a ? q(e, n) : e, c = p.length - 1, l; c >= 0; c--)
+    (l = p[c]) && (o = (a ? l(e, n, o) : l(o)) || o);
+  return a && o && E(e, n, o), o;
 };
-const P = "pie-checkbox";
-class e extends v(y) {
+const A = "pie-checkbox";
+class t extends y(k(u)) {
   constructor() {
-    super(...arguments), this.required = b.required, this.indeterminate = b.indeterminate, this.handleChange = (i) => {
-      const p = g(i);
-      this.dispatchEvent(p);
-    };
+    super(...arguments), this.value = d.value, this.checked = d.checked, this.defaultChecked = d.defaultChecked, this.required = d.required, this.indeterminate = d.indeterminate;
   }
   /**
    * (Read-only) returns a ValidityState with the validity states that this element is in.
@@ -27,68 +30,114 @@ class e extends v(y) {
   get validity() {
     return this.checkbox.validity;
   }
+  /**
+   * Ensures that the form value is in sync with the component.
+   */
+  handleFormAssociation() {
+    !!this.form && !!this.name && this._internals.setFormValue(this.checked ? this.value : null);
+  }
+  /**
+   * Called after the disabled state of the element changes,
+   * either because the disabled attribute of this element was added or removed;
+   * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+   * @param disabled - The latest disabled state of the input.
+   */
+  formDisabledCallback(e) {
+    this.disabled = e;
+  }
+  firstUpdated(e) {
+    super.firstUpdated(e), this.handleFormAssociation();
+  }
+  updated(e) {
+    super.updated(e), this.handleFormAssociation();
+  }
+  /**
+   * Captures the native change event and wraps it in a custom event.
+   * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
+   */
+  handleChange(e) {
+    const { checked: n } = e == null ? void 0 : e.currentTarget;
+    this.checked = n;
+    const a = v(e);
+    this.dispatchEvent(a), this.handleFormAssociation();
+  }
+  /**
+   * Called when the form that contains this component is reset.
+   * If the current checked state is different to the default checked state,
+   * the checked state is reset to the default checked state and a `change` event is emitted.
+   */
+  formResetCallback() {
+    if (this.checked === this.defaultChecked)
+      return;
+    this.checked = this.defaultChecked;
+    const e = new Event("change", { bubbles: !0, composed: !0 });
+    this.dispatchEvent(e), this.handleFormAssociation();
+  }
   render() {
     const {
-      checked: i,
-      value: p,
+      checked: e,
+      value: n,
       name: a,
-      label: t,
-      disabled: l,
-      required: s,
-      indeterminate: u,
-      aria: r
+      label: o,
+      disabled: c,
+      required: l,
+      indeterminate: m,
+      aria: i
     } = this;
-    return m`
-        <label>
+    return f`
+        <label data-test-id="checkbox-component">
             <input
                 type="checkbox"
-                ?checked=${h(i)}
-                .value=${h(p)}
-                name=${h(a)}
-                ?disabled=${l}
-                ?required=${s}
-                .indeterminate=${u}
-                aria-label=${(r == null ? void 0 : r.label) || d}
-                aria-labelledby=${t ? d : (r == null ? void 0 : r.labelledby) || d}
-                aria-describedby= ${(r == null ? void 0 : r.describedby) || d}
+                .value=${n}
+                .checked=${g(e)}
+                name=${$(a)}
+                ?disabled=${c}
+                ?required=${l}
+                .indeterminate=${!!m}
+                aria-label=${(i == null ? void 0 : i.label) || h}
+                aria-labelledby=${o ? h : (i == null ? void 0 : i.labelledby) || h}
+                aria-describedby= ${(i == null ? void 0 : i.describedby) || h}
                 @change=${this.handleChange}
-                data-test-id="pie-checkbox"
+                data-test-id="checkbox-input"
             />
-            ${t}
+            ${o}
         </label>`;
   }
 }
-e.shadowRootOptions = { ...y.shadowRootOptions, delegatesFocus: !0 };
-e.styles = f(q);
-o([
-  n({ type: String })
-], e.prototype, "value", 2);
-o([
-  n({ type: String })
-], e.prototype, "label", 2);
-o([
-  n({ type: String })
-], e.prototype, "name", 2);
-o([
-  n({ type: Boolean })
-], e.prototype, "checked", 2);
-o([
-  n({ type: Boolean, reflect: !0 })
-], e.prototype, "disabled", 2);
-o([
-  n({ type: Boolean, reflect: !0 })
-], e.prototype, "required", 2);
-o([
-  n({ type: Boolean })
-], e.prototype, "indeterminate", 2);
-o([
-  n({ type: Object })
-], e.prototype, "aria", 2);
-o([
-  x("input")
-], e.prototype, "checkbox", 2);
-$(P, e);
+t.shadowRootOptions = { ...u.shadowRootOptions, delegatesFocus: !0 };
+t.styles = b(F);
+r([
+  s({ type: String })
+], t.prototype, "value", 2);
+r([
+  s({ type: String })
+], t.prototype, "label", 2);
+r([
+  s({ type: String })
+], t.prototype, "name", 2);
+r([
+  s({ type: Boolean, reflect: !0 })
+], t.prototype, "checked", 2);
+r([
+  s({ type: Boolean, reflect: !0 })
+], t.prototype, "defaultChecked", 2);
+r([
+  s({ type: Boolean, reflect: !0 })
+], t.prototype, "disabled", 2);
+r([
+  s({ type: Boolean, reflect: !0 })
+], t.prototype, "required", 2);
+r([
+  s({ type: Boolean, reflect: !0 })
+], t.prototype, "indeterminate", 2);
+r([
+  s({ type: Object })
+], t.prototype, "aria", 2);
+r([
+  x('input[type="checkbox"]')
+], t.prototype, "checkbox", 2);
+C(A, t);
 export {
-  e as PieCheckbox,
-  b as defaultProps
+  t as PieCheckbox,
+  d as defaultProps
 };

package/dist/react.d.ts

@@ -1,7 +1,9 @@
 import { ComponentDefaultPropsGeneric } from '@justeattakeaway/pie-webc-core';
 import type { CSSResult } from 'lit';
+import type { FormControlInterface } from '@justeattakeaway/pie-webc-core';
 import type { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
 import * as React_2 from 'react';
 import type { RTLInterface } from '@justeattakeaway/pie-webc-core';
 import type { TemplateResult } from 'lit-html';
@@ -30,7 +32,11 @@ export declare interface CheckboxProps {
      */
     disabled?: boolean;
     /**
-     * Same as the HTML checked attribute - indicates whether or not the checkbox is checked by default (when the page loads).
+     * The default checked state of the checkbox (not necessarily the same as the current checked state).
+     */
+    defaultChecked?: boolean;
+    /**
+     * The checked state of the checkbox.
      */
     checked?: boolean;
     /**
@@ -48,15 +54,15 @@ export declare interface CheckboxProps {
     aria?: AriaProps;
 }
 
-export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'required' | 'indeterminate'>;
+export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked'>;
 
 export declare const defaultProps: DefaultProps;
 
-export declare const PieCheckbox: React_2.ForwardRefExoticComponent<CheckboxProps & React_2.RefAttributes<PieCheckbox_2> & ReactBaseType>;
+export declare const PieCheckbox: React_2.ForwardRefExoticComponent<CheckboxProps & React_2.RefAttributes<PieCheckbox_2> & PieCheckboxEvents & ReactBaseType>;
 
 /**
  * @tagname pie-checkbox
- * @slot - Default slot (checkbox label)
+ * @event {CustomEvent} change - when checked state is changed.
  */
 declare class PieCheckbox_2 extends PieCheckbox_base implements CheckboxProps {
     static shadowRootOptions: {
@@ -64,31 +70,55 @@ declare class PieCheckbox_2 extends PieCheckbox_base implements CheckboxProps {
         mode: ShadowRootMode;
         slotAssignment?: SlotAssignmentMode | undefined;
     };
-    value: CheckboxProps['value'];
+    value: string;
     label?: CheckboxProps['label'];
     name?: CheckboxProps['name'];
-    checked?: CheckboxProps['checked'];
+    checked: boolean;
+    defaultChecked: boolean;
     disabled?: CheckboxProps['disabled'];
     required?: CheckboxProps['required'];
     indeterminate?: CheckboxProps['indeterminate'];
     aria: CheckboxProps['aria'];
-    private checkbox?;
+    private checkbox;
     /**
      * (Read-only) returns a ValidityState with the validity states that this element is in.
      * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validity
      */
     get validity(): ValidityState;
     /**
-     * The onChange function updates the checkbox state and emits an event for consumers.
+     * Ensures that the form value is in sync with the component.
+     */
+    private handleFormAssociation;
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the input.
+     */
+    formDisabledCallback(disabled: boolean): void;
+    protected firstUpdated(_changedProperties: PropertyValues<this>): void;
+    protected updated(_changedProperties: PropertyValues<this>): void;
+    /**
+     * Captures the native change event and wraps it in a custom event.
      * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
      */
     private handleChange;
+    /**
+     * Called when the form that contains this component is reset.
+     * If the current checked state is different to the default checked state,
+     * the checked state is reset to the default checked state and a `change` event is emitted.
+     */
+    formResetCallback(): void;
     render(): TemplateResult<1>;
     static styles: CSSResult;
 }
 
-declare const PieCheckbox_base: GenericConstructor<RTLInterface> & typeof LitElement;
+declare const PieCheckbox_base: GenericConstructor<FormControlInterface> & GenericConstructor<RTLInterface> & typeof LitElement;
+
+declare type PieCheckboxEvents = {
+    onChange?: (event: CustomEvent) => void;
+};
 
-declare type ReactBaseType = React_2.HTMLAttributes<HTMLElement>;
+declare type ReactBaseType = React_2.InputHTMLAttributes<HTMLInputElement>;
 
 export { }

package/dist/react.js

@@ -1,9 +1,10 @@
 import * as e from "react";
 import { createComponent as o } from "@lit/react";
 import { PieCheckbox as t } from "./index.js";
-import { defaultProps as h } from "./index.js";
+import { defaultProps as b } from "./index.js";
 import "lit";
 import "@justeattakeaway/pie-webc-core";
+import "lit/directives/live.js";
 import "lit/decorators.js";
 import "lit/directives/if-defined.js";
 const r = o({
@@ -11,9 +12,12 @@ const r = o({
   elementClass: t,
   react: e,
   tagName: "pie-checkbox",
-  events: {}
-}), x = r;
+  events: {
+    onChange: "change"
+    // when checked state is changed.
+  }
+}), h = r;
 export {
-  x as PieCheckbox,
-  h as defaultProps
+  h as PieCheckbox,
+  b as defaultProps
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-checkbox",
   "description": "PIE Design System Checkbox built using Web Components",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/defs-react.ts

@@ -1,8 +1,3 @@
 import React from 'react';
-/**
- * TODO: Verify if ReactBaseType can be set as a more specific React interface
- * Use the React IntrinsicElements interface to find how to map standard HTML elements to existing React Interfaces
- * Example: an HTML button maps to `React.ButtonHTMLAttributes<HTMLButtonElement>`
- * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0bb210867d16170c4a08d9ce5d132817651a0f80/types/react/index.d.ts#L2829
- */
-export type ReactBaseType = React.HTMLAttributes<HTMLElement>
+
+export type ReactBaseType = React.InputHTMLAttributes<HTMLInputElement>

package/src/defs.ts

@@ -27,7 +27,12 @@ export interface CheckboxProps {
     disabled?: boolean;
 
     /**
-     * Same as the HTML checked attribute - indicates whether or not the checkbox is checked by default (when the page loads).
+     * The default checked state of the checkbox (not necessarily the same as the current checked state).
+     */
+    defaultChecked?: boolean;
+
+    /**
+     * The checked state of the checkbox.
      */
     checked?: boolean;
 
@@ -48,10 +53,14 @@ export interface CheckboxProps {
     aria?: AriaProps;
 }
 
-export type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'required' | 'indeterminate'>;
+export type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked'>;
 
 export const defaultProps: DefaultProps = {
+    // a default value for the html <input type="checkbox" /> value attribute.
+    // https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#value
+    value: 'on',
     required: false,
+    defaultChecked: false,
     indeterminate: false,
+    checked: false,
 };
-

package/src/index.ts

@@ -1,11 +1,13 @@
 import {
-    LitElement, html, unsafeCSS, nothing,
+    LitElement, html, unsafeCSS, PropertyValues, nothing,
 } from 'lit';
 import {
     RtlMixin,
     defineCustomElement,
     wrapNativeEvent,
+    FormControlMixin,
 } from '@justeattakeaway/pie-webc-core';
+import { live } from 'lit/directives/live.js';
 import { property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
@@ -19,13 +21,13 @@ const componentSelector = 'pie-checkbox';
 
 /**
  * @tagname pie-checkbox
- * @slot - Default slot (checkbox label)
+ * @event {CustomEvent} change - when checked state is changed.
  */
-export class PieCheckbox extends RtlMixin(LitElement) implements CheckboxProps {
+export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implements CheckboxProps {
     static shadowRootOptions = { ...LitElement.shadowRootOptions, delegatesFocus: true };
 
     @property({ type: String })
-    public value: CheckboxProps['value'];
+    public value = defaultProps.value;
 
     @property({ type: String })
     public label?: CheckboxProps['label'];
@@ -33,8 +35,11 @@ export class PieCheckbox extends RtlMixin(LitElement) implements CheckboxProps {
     @property({ type: String })
     public name?: CheckboxProps['name'];
 
-    @property({ type: Boolean })
-    public checked?: CheckboxProps['checked'];
+    @property({ type: Boolean, reflect: true })
+    public checked = defaultProps.checked;
+
+    @property({ type: Boolean, reflect: true })
+    public defaultChecked = defaultProps.defaultChecked;
 
     @property({ type: Boolean, reflect: true })
     public disabled?: CheckboxProps['disabled'];
@@ -42,14 +47,14 @@ export class PieCheckbox extends RtlMixin(LitElement) implements CheckboxProps {
     @property({ type: Boolean, reflect: true })
     public required?: CheckboxProps['required'] = defaultProps.required;
 
-    @property({ type: Boolean })
+    @property({ type: Boolean, reflect: true })
     public indeterminate?: CheckboxProps['indeterminate'] = defaultProps.indeterminate;
 
     @property({ type: Object })
     public aria: CheckboxProps['aria'];
 
-    @query('input')
-    private checkbox?: HTMLInputElement;
+    @query('input[type="checkbox"]')
+    private checkbox!: HTMLInputElement;
 
     /**
      * (Read-only) returns a ValidityState with the validity states that this element is in.
@@ -60,16 +65,69 @@ export class PieCheckbox extends RtlMixin(LitElement) implements CheckboxProps {
     }
 
     /**
-     * The onChange function updates the checkbox state and emits an event for consumers.
+     * Ensures that the form value is in sync with the component.
+     */
+    private handleFormAssociation () : void {
+        const isFormAssociated = !!this.form && !!this.name;
+        if (isFormAssociated) {
+            this._internals.setFormValue(this.checked ? this.value : null);
+        }
+    }
+
+    /**
+     * Called after the disabled state of the element changes,
+     * either because the disabled attribute of this element was added or removed;
+     * or because the disabled state changed on a <fieldset> that's an ancestor of this element.
+     * @param disabled - The latest disabled state of the input.
+     */
+    public formDisabledCallback (disabled: boolean): void {
+        this.disabled = disabled;
+    }
+
+    protected firstUpdated (_changedProperties: PropertyValues<this>): void {
+        super.firstUpdated(_changedProperties);
+
+        this.handleFormAssociation();
+    }
+
+    protected updated (_changedProperties: PropertyValues<this>): void {
+        super.updated(_changedProperties);
+
+        this.handleFormAssociation();
+    }
+
+    /**
+     * Captures the native change event and wraps it in a custom event.
      * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
      */
-    private handleChange = (event: Event) => {
+    private handleChange (event: Event) {
+        const { checked } = event?.currentTarget as HTMLInputElement;
+        this.checked = checked;
         // This is because some events set `composed` to `false`.
         // Reference: https://javascript.info/shadow-dom-events#event-composed
         const customChangeEvent = wrapNativeEvent(event);
-
         this.dispatchEvent(customChangeEvent);
-    };
+
+        this.handleFormAssociation();
+    }
+
+    /**
+     * Called when the form that contains this component is reset.
+     * If the current checked state is different to the default checked state,
+     * the checked state is reset to the default checked state and a `change` event is emitted.
+     */
+    public formResetCallback () : void {
+        if (this.checked === this.defaultChecked) {
+            return;
+        }
+
+        this.checked = this.defaultChecked;
+
+        const changeEvent = new Event('change', { bubbles: true, composed: true });
+        this.dispatchEvent(changeEvent);
+
+        this.handleFormAssociation();
+    }
 
     render () {
         const {
@@ -84,20 +142,20 @@ export class PieCheckbox extends RtlMixin(LitElement) implements CheckboxProps {
         } = this;
 
         return html`
-        <label>
+        <label data-test-id="checkbox-component">
             <input
                 type="checkbox"
-                ?checked=${ifDefined(checked)}
-                .value=${ifDefined(value)}
+                .value=${value}
+                .checked=${live(checked)}
                 name=${ifDefined(name)}
                 ?disabled=${disabled}
                 ?required=${required}
-                .indeterminate=${indeterminate}
+                .indeterminate=${!!indeterminate}
                 aria-label=${aria?.label || nothing}
                 aria-labelledby=${label ? nothing : aria?.labelledby || nothing}
                 aria-describedby= ${aria?.describedby || nothing}
                 @change=${this.handleChange}
-                data-test-id="pie-checkbox"
+                data-test-id="checkbox-input"
             />
             ${label}
         </label>`;

package/src/react.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { createComponent } from '@lit/react';
+import { createComponent, EventName } from '@lit/react';
 import { PieCheckbox as PieCheckboxLit } from './index';
 import { CheckboxProps } from './defs';
 
@@ -10,10 +10,16 @@ const PieCheckboxReact = createComponent({
     elementClass: PieCheckboxLit,
     react: React,
     tagName: 'pie-checkbox',
-    events: {},
+    events: {
+        onChange: 'change' as EventName<CustomEvent>, // when checked state is changed.
+    },
 });
 
-type ReactBaseType = React.HTMLAttributes<HTMLElement>
+type ReactBaseType = React.InputHTMLAttributes<HTMLInputElement>
+
+type PieCheckboxEvents = {
+    onChange?: (event: CustomEvent) => void;
+};
 
 export const PieCheckbox = PieCheckboxReact as React.ForwardRefExoticComponent<React.PropsWithoutRef<CheckboxProps>
-    & React.RefAttributes<PieCheckboxLit> & ReactBaseType>;
+    & React.RefAttributes<PieCheckboxLit> & PieCheckboxEvents & ReactBaseType>;