@justeattakeaway/pie-switch 0.18.4 → 0.20.0

package/dist/react.d.ts

@@ -1,6 +1,7 @@
 import type { CSSResult } from 'lit';
 import type { EventName } from '@lit/react';
 import type { LitElement } from 'lit';
+import type { PropertyValues } from 'lit';
 import type { ReactWebComponent } from '@lit/react';
 import type { TemplateResult } from 'lit';
 
@@ -18,24 +19,70 @@ export declare const labelPlacements: readonly ["leading", "trailing"];
  *
  * @constant
  */
-export declare const ON_SWITCH_CHANGED_EVENT = "pie-switch-changed";
+export declare const ON_SWITCH_CHANGED_EVENT = "change";
 
 export declare const PieSwitch: ReactWebComponent<PieSwitch_2, {
-    onPieSwitchChanged: EventName<CustomEvent<any>>;
+    onInvalid: EventName<Event>;
+    onChange: EventName<CustomEvent<any>>;
 }>;
 
 /**
  * @tagname pie-switch
- * @event {CustomEvent} pie-switch-changed - when the switch checked state is changed.
+ * @event {CustomEvent} change - when the switch checked state is changed.
  */
 declare class PieSwitch_2 extends PieSwitch_base implements SwitchProps {
+    static formAssociated: boolean;
+    private readonly _internals;
+    private input?;
+    constructor();
+    protected firstUpdated(_changedProperties: PropertyValues<this>): void;
+    protected updated(_changedProperties: PropertyValues<this>): void;
     label?: string;
     labelPlacement: SwitchProps['labelPlacement'];
     aria: AriaProps;
-    isChecked: boolean;
+    checked: boolean;
+    required: boolean;
+    value: string;
+    name?: string;
     isDisabled: boolean;
     static styles: CSSResult;
+    /**
+     * Ensures that the form value and validation state are in sync with the component.
+     */
+    private handleFormAssociation;
+    /**
+     * The onChange function updates the checkbox state and emits an event for consumers.
+     * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
+     */
     onChange(event: Event): void;
+    /**
+     * Returns a boolean value which indicates validity of the value of the component. If the value is invalid, this method also fires the invalid event on the component.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity
+     * @returns boolean
+     */
+    checkValidity(): boolean;
+    /**
+     * If the value is invalid, this method also fires the invalid event on the element, and (if the event isn't canceled) reports the problem to the user.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity
+     * @returns boolean
+     */
+    reportValidity(): boolean;
+    /**
+     * Allows a consumer to set a custom validation message on the switch. An empty string counts as valid.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * (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;
+    /**
+     * (Read-only) Returns a string representing a localized message that describes the validation constraints that the control does not satisfy (if any).
+     * This string is empty if the component is valid.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage
+     */
+    get validationMessage(): string;
     /**
      * Renders the label for a switch if provided.
      * if invalid value is passed, nothing gets rendered
@@ -58,9 +105,13 @@ export declare interface SwitchProps {
     /**
      * Same as the HTML checked attribute - indicates whether the switch is on or off
      */
-    isChecked?: boolean;
+    checked?: boolean;
+    /**
+     * Same as the HTML required attribute - indicates whether the switch must be turned or not
+     */
+    required: boolean;
     /**
-     * Same as the HTML checked attribute - indicates whether the switch disabled or not
+     * Same as the HTML disabled attribute - indicates whether the switch disabled or not
      */
     isDisabled?: boolean;
     /**
@@ -71,6 +122,14 @@ export declare interface SwitchProps {
      * The placement of the label such as leading or trailing
      */
     labelPlacement?: LabelPlacement;
+    /**
+     * Same as the HTML name attribute - indicates the name of the switch (for use with forms)
+     */
+    name?: string;
+    /**
+     * Same as the HTML value attribute - indicates the value of the switch (for use with forms). Defaults to 'on'.
+     */
+    value: string;
 }
 
 export { }

package/dist/react.js

@@ -1,23 +1,24 @@
 import * as e from "react";
 import { createComponent as t } from "@lit/react";
 import { PieSwitch as i } from "./index.js";
-import { ON_SWITCH_CHANGED_EVENT as w, labelPlacements as l } from "./index.js";
+import { ON_SWITCH_CHANGED_EVENT as h, labelPlacements as w } from "./index.js";
 import "lit";
 import "lit/decorators.js";
 import "@justeattakeaway/pie-webc-core";
 import "@justeattakeaway/pie-icons-webc/IconCheck";
-const s = t({
+const c = t({
   displayName: "PieSwitch",
   elementClass: i,
   react: e,
   tagName: "pie-switch",
   events: {
-    onPieSwitchChanged: "pie-switch-changed"
+    onInvalid: "invalid",
+    onChange: "change"
     // when the switch checked state is changed.
   }
 });
 export {
-  w as ON_SWITCH_CHANGED_EVENT,
-  s as PieSwitch,
-  l as labelPlacements
+  h as ON_SWITCH_CHANGED_EVENT,
+  c as PieSwitch,
+  w as labelPlacements
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-switch",
   "description": "PIE Design System Switch built using Web Components",
-  "version": "0.18.4",
+  "version": "0.20.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -28,11 +28,12 @@
   "author": "Just Eat Takeaway.com - Design System Team",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@justeattakeaway/pie-components-config": "0.6.1"
+    "@justeattakeaway/pie-components-config": "0.7.0"
   },
   "dependencies": {
     "@justeattakeaway/pie-icons-webc": "0.15.0",
-    "@justeattakeaway/pie-webc-core": "0.13.0"
+    "@justeattakeaway/pie-webc-core": "0.13.0",
+    "element-internals-polyfill": "1.3.9"
   },
   "volta": {
     "extends": "../../../package.json"

package/src/defs.ts

@@ -15,9 +15,13 @@ export interface SwitchProps {
     /**
      * Same as the HTML checked attribute - indicates whether the switch is on or off
      */
-    isChecked?: boolean;
+    checked?: boolean;
     /**
-     * Same as the HTML checked attribute - indicates whether the switch disabled or not
+     * Same as the HTML required attribute - indicates whether the switch must be turned or not
+     */
+    required: boolean;
+    /**
+     * Same as the HTML disabled attribute - indicates whether the switch disabled or not
      */
     isDisabled?: boolean;
     /**
@@ -28,6 +32,14 @@ export interface SwitchProps {
      * The placement of the label such as leading or trailing
      */
     labelPlacement?: LabelPlacement;
+    /**
+     * Same as the HTML name attribute - indicates the name of the switch (for use with forms)
+     */
+    name?: string;
+    /**
+     * Same as the HTML value attribute - indicates the value of the switch (for use with forms). Defaults to 'on'.
+     */
+    value: string;
 }
 
 /**
@@ -35,4 +47,4 @@ export interface SwitchProps {
  *
  * @constant
  */
-export const ON_SWITCH_CHANGED_EVENT = 'pie-switch-changed';
+export const ON_SWITCH_CHANGED_EVENT = 'change';

package/src/index.ts

@@ -1,12 +1,13 @@
 import {
-    LitElement, html, unsafeCSS, nothing, TemplateResult,
+    LitElement, html, unsafeCSS, nothing, TemplateResult, PropertyValues,
 } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, query } from 'lit/decorators.js';
 import { RtlMixin, validPropertyValues, defineCustomElement } from '@justeattakeaway/pie-webc-core';
 import styles from './switch.scss?inline';
 import {
     SwitchProps, ON_SWITCH_CHANGED_EVENT, AriaProps, labelPlacements,
 } from './defs';
+import 'element-internals-polyfill';
 import '@justeattakeaway/pie-icons-webc/IconCheck';
 
 // Valid values available to consumers
@@ -16,10 +17,39 @@ const componentSelector = 'pie-switch';
 
 /**
  * @tagname pie-switch
- * @event {CustomEvent} pie-switch-changed - when the switch checked state is changed.
+ * @event {CustomEvent} change - when the switch checked state is changed.
  */
 
 export class PieSwitch extends RtlMixin(LitElement) implements SwitchProps {
+    // TODO - we may want to consider making the element internals code reusable for other form controls.
+    static formAssociated = true;
+
+    private readonly _internals: ElementInternals;
+
+    @query('input[type="checkbox"]')
+    private input?: HTMLInputElement;
+
+    constructor () {
+        super();
+        this._internals = this.attachInternals();
+    }
+
+    protected firstUpdated (_changedProperties: PropertyValues<this>): void {
+        super.firstUpdated(_changedProperties);
+
+        this.handleFormAssociation();
+        // This ensures that invalid events triggered by checkValidity() are propagated to the custom element
+        // for consumers to listen to: https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity
+        this.input?.addEventListener('invalid', (event) => {
+            this.dispatchEvent(new Event('invalid', event));
+        });
+    }
+
+    protected updated (_changedProperties: PropertyValues<this>): void {
+        super.updated(_changedProperties);
+        this.handleFormAssociation();
+    }
+
     @property({ type: String })
     public label?: string;
 
@@ -31,25 +61,102 @@ export class PieSwitch extends RtlMixin(LitElement) implements SwitchProps {
     public aria!: AriaProps;
 
     @property({ type: Boolean, reflect: true })
-    public isChecked = false;
+    public checked = false;
+
+    @property({ type: Boolean, reflect: true })
+    public required = false;
+
+    @property({ type: String })
+    public value = 'on';
+
+    @property({ type: String })
+    public name?: string;
 
     @property({ type: Boolean, reflect: true })
     public isDisabled = false;
 
     static styles = unsafeCSS(styles);
 
+    /**
+     * Ensures that the form value and validation state are in sync with the component.
+     */
+    private handleFormAssociation () : void {
+        const isFormAssociated = !!this._internals.form && !!this.name && !!this.value;
+        if (isFormAssociated) {
+            if (this.isDisabled) {
+                this._internals.setFormValue(null);
+                this._internals.setValidity({});
+            } else if (this.checked) {
+                this._internals.setFormValue(this.value);
+                this._internals.setValidity({});
+            } else {
+                this._internals.setFormValue(null);
+                this._internals.setValidity(this.validity, this.validationMessage, this.input);
+            }
+        }
+    }
+
+    /**
+     * The onChange function updates the checkbox state and emits an event for consumers.
+     * @param {Event} event - This should be the change event that was listened for on an input element with `type="checkbox"`.
+     */
     onChange (event: Event) {
         const { checked } = event?.currentTarget as HTMLInputElement;
-        this.isChecked = checked;
+        this.checked = checked;
         const changedEvent = new CustomEvent(
             ON_SWITCH_CHANGED_EVENT,
             {
                 bubbles: true,
                 composed: true,
-                detail: this.isChecked,
             },
         );
+
         this.dispatchEvent(changedEvent);
+        this.handleFormAssociation();
+    }
+
+    /**
+     * Returns a boolean value which indicates validity of the value of the component. If the value is invalid, this method also fires the invalid event on the component.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity
+     * @returns boolean
+     */
+    public checkValidity (): boolean {
+        return (this.input as HTMLInputElement).checkValidity();
+    }
+
+    /**
+     * If the value is invalid, this method also fires the invalid event on the element, and (if the event isn't canceled) reports the problem to the user.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/reportValidity
+     * @returns boolean
+     */
+    public reportValidity (): boolean {
+        return (this.input as HTMLInputElement).reportValidity();
+    }
+
+    /**
+     * Allows a consumer to set a custom validation message on the switch. An empty string counts as valid.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/setCustomValidity
+     */
+    public setCustomValidity (message: string): void {
+        this.input?.setCustomValidity(message);
+        this._internals.setValidity(this.validity, this.validationMessage, this.input);
+    }
+
+    /**
+     * (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
+     */
+    public get validity (): ValidityState {
+        return (this.input as HTMLInputElement).validity;
+    }
+
+    /**
+     * (Read-only) Returns a string representing a localized message that describes the validation constraints that the control does not satisfy (if any).
+     * This string is empty if the component is valid.
+     * https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage
+     */
+    public get validationMessage (): string {
+        return (this.input as HTMLInputElement).validationMessage;
     }
 
     /**
@@ -77,7 +184,8 @@ export class PieSwitch extends RtlMixin(LitElement) implements SwitchProps {
         const {
             labelPlacement,
             aria,
-            isChecked,
+            checked,
+            required,
             isDisabled,
             isRTL,
         } = this;
@@ -93,20 +201,21 @@ export class PieSwitch extends RtlMixin(LitElement) implements SwitchProps {
                 <label
                     data-test-id="switch-component"
                     class="c-switch"
-                    ?isChecked=${isChecked}>
+                    ?checked=${checked}>
                     <input
                         id="switch"
                         data-test-id="switch-input"
                         role="switch"
                         type="checkbox"
                         class="c-switch-input"
-                        .checked="${isChecked}"
+                        .required=${required}
+                        .checked="${checked}"
                         .disabled="${isDisabled}"
                         @change="${this.onChange}"
                         aria-label="${aria?.label || nothing}"
                         aria-describedby="${aria?.describedBy ? switchId : nothing}">
                     <div class="c-switch-control">
-                        ${isChecked ? html`<icon-check></icon-check>` : nothing}
+                        ${checked ? html`<icon-check></icon-check>` : nothing}
                     </div>
                 </label>
                 ${aria?.describedBy ? html`<div id="${switchId}" data-test-id="${switchId}" class="c-switch-description">${aria?.describedBy}</div>` : nothing}

package/src/switch.scss

@@ -60,7 +60,7 @@
         background-color: hsl(var(--dt-color-interactive-form-h), var(--dt-color-interactive-form-s), calc(var(--dt-color-interactive-form-l) - var(--dt-color-active-01)));
     }
 
-    &[isChecked] {
+    &[checked] {
         @include switch-transition(background-color);
         background-color: var(--switch-bg-color--checked);
 
@@ -85,8 +85,17 @@
 }
 
 .c-switch-input {
-    appearance: none;
-    margin: 0;
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    border: 0;
+    left: 50%;
+    transform: translateX(-50%) translateY(-50%);
+    bottom: 0;
 
     &:disabled {
         background-color: transparent;