@justeattakeaway/pie-checkbox 0.4.0 → 0.6.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).
@@ -73,16 +71,19 @@ import { PieCheckbox } from '@justeattakeaway/pie-checkbox/dist/react';
 
 ## Props
 
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `name` | `string` | - | The name of the checkbox (used as a key/value pair with `value`). This is required in order to work properly with forms. |
-| `value` | `string` | 'on' | 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". |
-| `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). |
-| `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. |
+| Property | Type                                | Default   | Description |
+|---|-------------------------------------|-----------|---|
+| `name` | `string`                            | -         | The name of the checkbox (used as a key/value pair with `value`). This is required in order to work properly with forms. |
+| `value` | `string`                            | `'on'`      | 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". |
+| `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`   | 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. |
+| `assistiveText` | `string`                            | `''`      | Allows assistive text to be displayed below the checkbox element. |
+| `status` | `'default'`, `'error'`, `'success'` | `'default'` | The status of the checkbox component / assistive text. If you use `status` you must provide an `assistiveText` prop value for accessibility purposes. |
 
 In your markup or JSX, you can then use these to set the properties for the `pie-checkbox` component:
 
@@ -107,4 +108,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

@@ -12,16 +12,32 @@
       "kind": "javascript-module",
       "path": "src/defs.js",
       "declarations": [
+        {
+          "kind": "variable",
+          "name": "statusTypes",
+          "type": {
+            "text": "['default', 'success', 'error']"
+          },
+          "default": "['default', 'success', 'error']"
+        },
         {
           "kind": "variable",
           "name": "defaultProps",
           "type": {
             "text": "DefaultProps"
           },
-          "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    indeterminate: false,\n    checked: 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    status: 'default',\n}"
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "statusTypes",
+          "declaration": {
+            "name": "statusTypes",
+            "module": "src/defs.js"
+          }
+        },
         {
           "kind": "js",
           "name": "defaultProps",
@@ -81,6 +97,13 @@
               "attribute": "checked",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "defaultChecked",
+              "privacy": "public",
+              "attribute": "defaultChecked",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "disabled",
@@ -124,10 +147,28 @@
               "kind": "field",
               "name": "checkbox",
               "type": {
-                "text": "HTMLInputElement | undefined"
+                "text": "HTMLInputElement"
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "assistiveText",
+              "type": {
+                "text": "CheckboxProps['assistiveText'] | undefined"
+              },
+              "privacy": "public",
+              "attribute": "assistiveText"
+            },
+            {
+              "kind": "field",
+              "name": "status",
+              "type": {
+                "text": "CheckboxProps['status'] | undefined"
+              },
+              "privacy": "public",
+              "attribute": "status"
+            },
             {
               "kind": "field",
               "name": "validity",
@@ -183,6 +224,17 @@
                 }
               ],
               "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."
             }
           ],
           "events": [
@@ -217,6 +269,10 @@
               "name": "checked",
               "fieldName": "checked"
             },
+            {
+              "name": "defaultChecked",
+              "fieldName": "defaultChecked"
+            },
             {
               "name": "disabled",
               "type": {
@@ -244,6 +300,20 @@
                 "text": "CheckboxProps['aria']"
               },
               "fieldName": "aria"
+            },
+            {
+              "name": "assistiveText",
+              "type": {
+                "text": "CheckboxProps['assistiveText'] | undefined"
+              },
+              "fieldName": "assistiveText"
+            },
+            {
+              "name": "status",
+              "type": {
+                "text": "CheckboxProps['status'] | undefined"
+              },
+              "fieldName": "status"
             }
           ],
           "mixins": [

package/dist/index.d.ts

@@ -10,7 +10,6 @@ import type { TemplateResult } from 'lit-html';
 export declare type AriaProps = {
     label?: string;
     labelledby?: string;
-    describedby?: string;
 };
 
 export declare interface CheckboxProps {
@@ -31,7 +30,11 @@ export declare interface CheckboxProps {
      */
     disabled?: boolean;
     /**
-     * Indicates whether or not the checkbox is checked.
+     * 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,9 +50,17 @@ export declare interface CheckboxProps {
      * Various ARIA attributes.
      */
     aria?: AriaProps;
+    /**
+     * An optional assistive text to display below the input element. Must be provided when the status is success or error.
+     */
+    assistiveText?: string;
+    /**
+     * The status of the checkbox component / assistive text. Can be default, success or error.
+     */
+    status?: typeof statusTypes[number];
 }
 
-export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked'>;
+export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked' | 'status'>;
 
 export declare const defaultProps: DefaultProps;
 
@@ -67,11 +78,14 @@ export declare class PieCheckbox extends PieCheckbox_base implements CheckboxPro
     label?: CheckboxProps['label'];
     name?: CheckboxProps['name'];
     checked: boolean;
+    defaultChecked: boolean;
     disabled?: CheckboxProps['disabled'];
     required?: CheckboxProps['required'];
     indeterminate?: CheckboxProps['indeterminate'];
     aria: CheckboxProps['aria'];
-    private checkbox?;
+    private checkbox;
+    assistiveText?: CheckboxProps['assistiveText'];
+    status?: CheckboxProps['status'];
     /**
      * (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
@@ -95,10 +109,18 @@ export declare class PieCheckbox extends PieCheckbox_base implements CheckboxPro
      * @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<FormControlInterface> & GenericConstructor<RTLInterface> & typeof LitElement;
 
+export declare const statusTypes: readonly ["default", "success", "error"];
+
 export { }

package/dist/index.js

@@ -1,26 +1,29 @@
-import { LitElement as u, html as b, nothing as d, unsafeCSS as f } from "lit";
-import { FormControlMixin as y, RtlMixin as v, wrapNativeEvent as g, defineCustomElement as k } from "@justeattakeaway/pie-webc-core";
-import { live as x } from "lit/directives/live.js";
-import { property as a, query as $ } from "lit/decorators.js";
-import { ifDefined as C } from "lit/directives/if-defined.js";
-const F = `*,*:after,*:before{box-sizing:inherit}
-`, p = {
+import { LitElement as y, html as f, nothing as p, unsafeCSS as g } from "lit";
+import { property as i, query as C } from "lit/decorators.js";
+import { ifDefined as m } from "lit/directives/if-defined.js";
+import { live as $ } from "lit/directives/live.js";
+import { FormControlMixin as F, RtlMixin as E, wrapNativeEvent as S, validPropertyValues as q, defineCustomElement as A } from "@justeattakeaway/pie-webc-core";
+import "@justeattakeaway/pie-assistive-text";
+const O = `*,*:after,*:before{box-sizing:inherit}
+`, P = ["default", "success", "error"], n = {
   // 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,
+  defaultChecked: !1,
   indeterminate: !1,
-  checked: !1
+  checked: !1,
+  status: "default"
 };
-var _ = Object.defineProperty, q = Object.getOwnPropertyDescriptor, i = (h, e, n, s) => {
-  for (var o = s > 1 ? void 0 : s ? q(e, n) : e, l = h.length - 1, c; l >= 0; l--)
-    (c = h[l]) && (o = (s ? c(e, n, o) : c(o)) || o);
-  return s && o && _(e, n, o), o;
+var _ = Object.defineProperty, w = Object.getOwnPropertyDescriptor, s = (h, e, r, a) => {
+  for (var o = a > 1 ? void 0 : a ? w(e, r) : e, d = h.length - 1, l; d >= 0; d--)
+    (l = h[d]) && (o = (a ? l(e, r, o) : l(o)) || o);
+  return a && o && _(e, r, o), o;
 };
-const O = "pie-checkbox";
-class t extends y(v(u)) {
+const v = "pie-checkbox", b = "assistive-text";
+class t extends F(E(y)) {
   constructor() {
-    super(...arguments), this.value = p.value, this.checked = p.checked, this.required = p.required, this.indeterminate = p.indeterminate;
+    super(...arguments), this.value = n.value, this.checked = n.checked, this.defaultChecked = n.defaultChecked, this.required = n.required, this.indeterminate = n.indeterminate, this.status = n.status;
   }
   /**
    * (Read-only) returns a ValidityState with the validity states that this element is in.
@@ -33,7 +36,7 @@ class t extends y(v(u)) {
    * Ensures that the form value is in sync with the component.
    */
   handleFormAssociation() {
-    !!this._internals.form && !!this.name && this._internals.setFormValue(this.checked ? this.value : null);
+    !!this.form && !!this.name && this._internals.setFormValue(this.checked ? this.value : null);
   }
   /**
    * Called after the disabled state of the element changes,
@@ -55,73 +58,99 @@ class t extends y(v(u)) {
    * @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 s = g(e);
-    this.dispatchEvent(s), this.handleFormAssociation();
+    const { checked: r } = e == null ? void 0 : e.currentTarget;
+    this.checked = r;
+    const a = S(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: e,
-      value: n,
-      name: s,
+      value: r,
+      name: a,
       label: o,
-      disabled: l,
-      required: c,
-      indeterminate: m,
-      aria: r
+      disabled: d,
+      required: l,
+      indeterminate: k,
+      aria: c,
+      assistiveText: u,
+      status: x
     } = this;
-    return b`
+    return f`
         <label data-test-id="checkbox-component">
             <input
                 type="checkbox"
-                .value=${n}
-                ?checked=${x(e)}
-                name=${C(s)}
-                ?disabled=${l}
-                ?required=${c}
-                .indeterminate=${m}
-                aria-label=${(r == null ? void 0 : r.label) || d}
-                aria-labelledby=${o ? d : (r == null ? void 0 : r.labelledby) || d}
-                aria-describedby= ${(r == null ? void 0 : r.describedby) || d}
+                .value=${r}
+                .checked=${$(e)}
+                name=${m(a)}
+                ?disabled=${d}
+                ?required=${l}
+                .indeterminate=${!!k}
+                aria-label=${(c == null ? void 0 : c.label) || p}
+                aria-labelledby=${o ? p : (c == null ? void 0 : c.labelledby) || p}
+                aria-describedby=${m(u ? b : void 0)}
                 @change=${this.handleChange}
                 data-test-id="checkbox-input"
             />
             ${o}
-        </label>`;
+        </label>
+        ${u ? f`<pie-assistive-text id="${b}" variant=${m(x)} data-test-id="pie-checkbox-assistive-text">${u}</pie-assistive-text>` : p}`;
   }
 }
-t.shadowRootOptions = { ...u.shadowRootOptions, delegatesFocus: !0 };
-t.styles = f(F);
-i([
-  a({ type: String })
+t.shadowRootOptions = { ...y.shadowRootOptions, delegatesFocus: !0 };
+t.styles = g(O);
+s([
+  i({ type: String })
 ], t.prototype, "value", 2);
-i([
-  a({ type: String })
+s([
+  i({ type: String })
 ], t.prototype, "label", 2);
-i([
-  a({ type: String })
+s([
+  i({ type: String })
 ], t.prototype, "name", 2);
-i([
-  a({ type: Boolean, reflect: !0 })
+s([
+  i({ type: Boolean, reflect: !0 })
 ], t.prototype, "checked", 2);
-i([
-  a({ type: Boolean, reflect: !0 })
+s([
+  i({ type: Boolean, reflect: !0 })
+], t.prototype, "defaultChecked", 2);
+s([
+  i({ type: Boolean, reflect: !0 })
 ], t.prototype, "disabled", 2);
-i([
-  a({ type: Boolean, reflect: !0 })
+s([
+  i({ type: Boolean, reflect: !0 })
 ], t.prototype, "required", 2);
-i([
-  a({ type: Boolean, reflect: !0 })
+s([
+  i({ type: Boolean, reflect: !0 })
 ], t.prototype, "indeterminate", 2);
-i([
-  a({ type: Object })
+s([
+  i({ type: Object })
 ], t.prototype, "aria", 2);
-i([
-  $('input[type="checkbox"]')
+s([
+  C('input[type="checkbox"]')
 ], t.prototype, "checkbox", 2);
-k(O, t);
+s([
+  i({ type: String })
+], t.prototype, "assistiveText", 2);
+s([
+  i({ type: String }),
+  q(v, P, n.status)
+], t.prototype, "status", 2);
+A(v, t);
 export {
   t as PieCheckbox,
-  p as defaultProps
+  n as defaultProps,
+  P as statusTypes
 };

package/dist/react.d.ts

@@ -11,7 +11,6 @@ import type { TemplateResult } from 'lit-html';
 export declare type AriaProps = {
     label?: string;
     labelledby?: string;
-    describedby?: string;
 };
 
 export declare interface CheckboxProps {
@@ -32,7 +31,11 @@ export declare interface CheckboxProps {
      */
     disabled?: boolean;
     /**
-     * Indicates whether or not the checkbox is checked.
+     * 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,9 +51,17 @@ export declare interface CheckboxProps {
      * Various ARIA attributes.
      */
     aria?: AriaProps;
+    /**
+     * An optional assistive text to display below the input element. Must be provided when the status is success or error.
+     */
+    assistiveText?: string;
+    /**
+     * The status of the checkbox component / assistive text. Can be default, success or error.
+     */
+    status?: typeof statusTypes[number];
 }
 
-export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked'>;
+export declare type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked' | 'status'>;
 
 export declare const defaultProps: DefaultProps;
 
@@ -70,11 +81,14 @@ declare class PieCheckbox_2 extends PieCheckbox_base implements CheckboxProps {
     label?: CheckboxProps['label'];
     name?: CheckboxProps['name'];
     checked: boolean;
+    defaultChecked: boolean;
     disabled?: CheckboxProps['disabled'];
     required?: CheckboxProps['required'];
     indeterminate?: CheckboxProps['indeterminate'];
     aria: CheckboxProps['aria'];
-    private checkbox?;
+    private checkbox;
+    assistiveText?: CheckboxProps['assistiveText'];
+    status?: CheckboxProps['status'];
     /**
      * (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
@@ -98,6 +112,12 @@ declare class PieCheckbox_2 extends PieCheckbox_base implements CheckboxProps {
      * @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;
 }
@@ -110,4 +130,6 @@ declare type PieCheckboxEvents = {
 
 declare type ReactBaseType = React_2.InputHTMLAttributes<HTMLInputElement>;
 
+export declare const statusTypes: readonly ["default", "success", "error"];
+
 export { }

package/dist/react.js

@@ -1,12 +1,13 @@
 import * as e from "react";
 import { createComponent as o } from "@lit/react";
 import { PieCheckbox as t } from "./index.js";
-import { defaultProps as b } from "./index.js";
+import { defaultProps as k, statusTypes as P } 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";
+import "lit/directives/live.js";
+import "@justeattakeaway/pie-webc-core";
+import "@justeattakeaway/pie-assistive-text";
 const r = o({
   displayName: "PieCheckbox",
   elementClass: t,
@@ -16,8 +17,9 @@ const r = o({
     onChange: "change"
     // when checked state is changed.
   }
-}), h = r;
+}), x = r;
 export {
-  h as PieCheckbox,
-  b as defaultProps
+  x as PieCheckbox,
+  k as defaultProps,
+  P as statusTypes
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-checkbox",
   "description": "PIE Design System Checkbox built using Web Components",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -40,6 +40,7 @@
     "cem-plugin-module-file-extensions": "0.0.5"
   },
   "dependencies": {
+    "@justeattakeaway/pie-assistive-text": "0.5.0",
     "@justeattakeaway/pie-webc-core": "0.23.0"
   },
   "volta": {

package/src/defs.ts

@@ -1,9 +1,10 @@
 import { type ComponentDefaultPropsGeneric } from '@justeattakeaway/pie-webc-core';
 
+export const statusTypes = ['default', 'success', 'error'] as const;
+
 export type AriaProps = {
     label?: string;
     labelledby?: string;
-    describedby?: string;
 };
 export interface CheckboxProps {
     /**
@@ -27,7 +28,12 @@ export interface CheckboxProps {
     disabled?: boolean;
 
     /**
-     * Indicates whether or not the checkbox is checked.
+     * 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;
 
@@ -46,16 +52,27 @@ export interface CheckboxProps {
      * Various ARIA attributes.
      */
     aria?: AriaProps;
+
+    /**
+     * An optional assistive text to display below the input element. Must be provided when the status is success or error.
+     */
+    assistiveText?: string;
+
+    /**
+     * The status of the checkbox component / assistive text. Can be default, success or error.
+     */
+    status?: typeof statusTypes[number];
 }
 
-export type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' >;
+export type DefaultProps = ComponentDefaultPropsGeneric<CheckboxProps, 'value' | 'required' | 'indeterminate' | 'checked' | 'defaultChecked' | 'status'>;
 
 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,
+    status: 'default',
 };
-

package/src/index.ts

@@ -1,23 +1,27 @@
 import {
     LitElement, html, unsafeCSS, PropertyValues, nothing,
 } from 'lit';
+import { property, query } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { live } from 'lit/directives/live.js';
+
 import {
     RtlMixin,
     defineCustomElement,
     wrapNativeEvent,
     FormControlMixin,
+    validPropertyValues,
 } 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';
+import '@justeattakeaway/pie-assistive-text';
 
 import styles from './checkbox.scss?inline';
-import { CheckboxProps, defaultProps } from './defs';
+import { CheckboxProps, defaultProps, statusTypes } from './defs';
 
 // Valid values available to consumers
 export * from './defs';
 
 const componentSelector = 'pie-checkbox';
+const assistiveTextIdValue = 'assistive-text';
 
 /**
  * @tagname pie-checkbox
@@ -38,6 +42,9 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
     @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'];
 
@@ -51,7 +58,14 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
     public aria: CheckboxProps['aria'];
 
     @query('input[type="checkbox"]')
-    private checkbox?: HTMLInputElement;
+    private checkbox!: HTMLInputElement;
+
+    @property({ type: String })
+    public assistiveText?: CheckboxProps['assistiveText'];
+
+    @property({ type: String })
+    @validPropertyValues(componentSelector, statusTypes, defaultProps.status)
+    public status?: CheckboxProps['status'] = defaultProps.status;
 
     /**
      * (Read-only) returns a ValidityState with the validity states that this element is in.
@@ -65,7 +79,7 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
      * Ensures that the form value is in sync with the component.
      */
     private handleFormAssociation () : void {
-        const isFormAssociated = !!this._internals.form && !!this.name;
+        const isFormAssociated = !!this.form && !!this.name;
         if (isFormAssociated) {
             this._internals.setFormValue(this.checked ? this.value : null);
         }
@@ -108,6 +122,24 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
         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 {
             checked,
@@ -118,6 +150,8 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
             required,
             indeterminate,
             aria,
+            assistiveText,
+            status,
         } = this;
 
         return html`
@@ -125,19 +159,20 @@ export class PieCheckbox extends FormControlMixin(RtlMixin(LitElement)) implemen
             <input
                 type="checkbox"
                 .value=${value}
-                ?checked=${live(checked)}
+                .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}
+                aria-describedby=${ifDefined(assistiveText ? assistiveTextIdValue : undefined)}
                 @change=${this.handleChange}
                 data-test-id="checkbox-input"
             />
             ${label}
-        </label>`;
+        </label>
+        ${assistiveText ? html`<pie-assistive-text id="${assistiveTextIdValue}" variant=${ifDefined(status)} data-test-id="pie-checkbox-assistive-text">${assistiveText}</pie-assistive-text>` : nothing}`;
     }
 
     // Renders a `CSSResult` generated from SCSS by Vite