feat(pie-switch): DSW-4019 bind the checked prop correctly and add missing form behaviours

.changeset/small-mugs-mix.md

@@ -0,0 +1,9 @@
+---
+"@justeattakeaway/pie-switch": minor
+---
+
+- [Removed] - (Breaking Change) `aria.describedby` support from pie-switch. It was misused as `aria-describedby` expects element IDs to reference existing descriptive elements, which isn’t feasible across Shadow DOM boundaries and being text conflicted with aria-label, internal labels, and external label handling.
+- [Added] - Wrapped the checked value with the [lit live directive ](https://lit.dev/docs/api/directives/#live) to ensure the DOM and component state stay in sync.
+- [Added] - Missing `defaultChecked` prop and form rest logic
+- [Changed] - Refactored the toggle between leading and trailing labels to be handled via CSS.
+- [Changed] - Updated the component to use a `<div>` as the parent wrapper when the label prop isn’t provided. This avoids nested `<label>` elements when consumers wrap the component with [an external label](https://webc.pie.design/?path=/docs/components-switch--overview#external-labels), which is an [invalid](https://forum.freecodecamp.org/t/nesting-label/462466) HTML pattern

apps/pie-storybook/stories/pie-switch.stories.ts

@@ -14,10 +14,6 @@ type SwitchStoryMeta = Meta<SwitchProps>;
 const defaultArgs: SwitchProps = {
     ...defaultProps,
     label: 'Label',
-    aria: {
-        label: 'switch label',
-        describedBy: 'switch description',
-    },
     name: 'switch',
     value: 'switchValue',
 };
@@ -33,6 +29,13 @@ const switchStoryMeta: SwitchStoryMeta = {
                 summary: defaultProps.checked,
             },
         },
+        defaultChecked: {
+            description: 'The default checked state of the switch (not necessarily the same as the current checked state). Used when the switch is part of a form that is reset.',
+            control: 'boolean',
+            defaultValue: {
+                summary: defaultProps.defaultChecked,
+            },
+        },
         disabled: {
             description: 'Same as the HTML disabled attribute - indicates whether the switch is disabled or not',
             control: 'boolean',
@@ -107,6 +110,7 @@ const Template : TemplateFunction<SwitchProps> = (props) => {
     const {
         aria,
         checked,
+        defaultChecked,
         disabled,
         label,
         labelPlacement,
@@ -125,6 +129,7 @@ const Template : TemplateFunction<SwitchProps> = (props) => {
             .aria="${aria}"
             ?required="${required}"
             ?checked="${checked}"
+            ?defaultChecked="${defaultChecked}"
             ?disabled="${disabled}"
             @change="${changeAction}">
         </pie-switch>`;
@@ -222,7 +227,6 @@ const MultiSwitchFormTemplate: TemplateFunction<SwitchProps> = (props: SwitchPro
     name: 'onion',
     aria: {
         label: 'a custom label for the onion switch',
-        describedBy: 'a custom description for the onion switch',
     },
     value: 'onion_yes',
     checked: false,

apps/pie-storybook/stories/testing/pie-switch.test.stories.ts

@@ -2,6 +2,7 @@ import { html, nothing } from 'lit';
 import { type Meta } from '@storybook/web-components';
 
 import '@justeattakeaway/pie-webc/components/switch';
+import '@justeattakeaway/pie-webc/components/button';
 import { type SwitchProps, labelPlacements, defaultProps } from '@justeattakeaway/pie-webc/components/switch';
 import '@justeattakeaway/pie-icons-webc/dist/IconCheck.js';
 
@@ -14,10 +15,6 @@ type SwitchStoryMeta = Meta<SwitchProps>;
 const defaultArgs: SwitchProps = {
     ...defaultProps,
     label: 'Label',
-    aria: {
-        label: 'switch label',
-        describedBy: 'switch description',
-    },
     name: 'switch',
     value: 'switchValue',
 };
@@ -32,6 +29,12 @@ const switchStoryMeta: SwitchStoryMeta = {
                 summary: defaultProps.checked,
             },
         },
+        defaultChecked: {
+            control: 'boolean',
+            defaultValue: {
+                summary: defaultProps.defaultChecked,
+            },
+        },
         disabled: {
             control: 'boolean',
             defaultValue: {
@@ -89,43 +92,57 @@ const changeAction = () => console.info(EXPECTED_EVENT_MESSAGE);
 const submitAction = (event: Event) => {
     event.preventDefault(); // Prevent the actual submission
 
-    const formLog = document.querySelector('#formLog') as HTMLElement;
+    const form = event.currentTarget as HTMLFormElement;
+    const formLog = form.parentElement?.querySelector('#formLog') as HTMLElement | null;
+    const output = form.parentElement?.querySelector('#formDataOutput') as HTMLDivElement | null;
 
     // Display a success message to the user when they submit the form
-    formLog.innerHTML = 'Form submitted!';
-    formLog.style.display = 'block';
+    if (formLog) {
+        formLog.innerHTML = 'Form submitted!';
+        formLog.style.display = 'block';
+    }
+
+    // Serialize form data into an object so tests can assert submitted payload.
+    const formData = new FormData(form);
+    const formDataObj: Record<string, unknown> = {};
+
+    formData.forEach((value, key) => {
+        formDataObj[key] = value;
+    });
+
+    if (output) {
+        output.innerText = JSON.stringify(formDataObj);
+    }
 
     // Reset the success message after roughly 8 seconds
     setTimeout(() => {
-        formLog.innerHTML = '';
-        formLog.style.display = 'none';
+        if (formLog) {
+            formLog.innerHTML = '';
+            formLog.style.display = 'none';
+        }
     }, 8000);
 };
 
-const submitActionTestForm = (event: Event) => {
-    event.preventDefault(); // Prevent the actual submission
-
-    const form = document.querySelector('#testForm') as HTMLFormElement;
-
-    // Serialize form data
-    const formData = new FormData(form);
-    const formDataObj: Record<string, unknown> = {};
+const resetAction = (event: Event) => {
+    const form = event.currentTarget as HTMLFormElement;
+    const formLog = form.parentElement?.querySelector('#formLog') as HTMLElement | null;
+    const output = form.parentElement?.querySelector('#formDataOutput') as HTMLDivElement | null;
 
-    // Serialize form data into an object
-    formData.forEach((value, key) => { formDataObj[key] = value; });
+    if (formLog) {
+        formLog.innerHTML = '';
+        formLog.style.display = 'none';
+    }
 
-    // Append serialized form data as JSON to a hidden element
-    const dataHolder = document.createElement('div');
-    dataHolder.id = 'formDataJson';
-    dataHolder.textContent = JSON.stringify(formDataObj);
-    dataHolder.style.display = 'none';
-    document.body.appendChild(dataHolder);
+    if (output) {
+        output.innerText = '';
+    }
 };
 
 const Template : TemplateFunction<SwitchProps> = (props) => {
     const {
         aria,
         checked,
+        defaultChecked,
         disabled,
         label,
         labelPlacement,
@@ -144,35 +161,27 @@ const Template : TemplateFunction<SwitchProps> = (props) => {
             .aria="${aria}"
             ?required="${required}"
             ?checked="${checked}"
+            ?defaultChecked="${defaultChecked}"
             ?disabled="${disabled}"
             @change="${changeAction}">
         </pie-switch>`;
 };
 
 const FormTemplate: TemplateFunction<SwitchProps> = (props: SwitchProps) => html`
     <p id="formLog" style="display: none; font-size: 2rem; color: var(--dt-color-support-positive);"></p>
-    <form id="testForm" @submit="${submitAction}">
-
-    <section>
-    ${Template({
-    ...props,
-})}
-    </section>
-    <button id="submitButton" type="submit"">Submit</button>
-    </form>
-`;
-
-const TestFormTemplate: TemplateFunction<SwitchProps> = (props: SwitchProps) => html`
-    <p id="formLog" style="display: none; font-size: 2rem; color: var(--dt-color-support-positive);"></p>
-    <form id="testForm" @submit="${submitActionTestForm}" action="/default-endpoint" method="POST">
+    <form id="testForm" @submit="${submitAction}" @reset="${resetAction}">
 
     <section>
     ${Template({
     ...props,
 })}
     </section>
-    <button id="submitButton" type="submit">Submit</button>
+    <div style="display: flex; gap: var(--dt-spacing-b); align-items: center; margin-top: var(--dt-spacing-c);">
+        <pie-button id="resetButton" type="reset" variant="secondary">Reset</pie-button>
+        <pie-button id="submitButton" type="submit">Submit</pie-button>
+    </div>
     </form>
+    <div id="formDataOutput"></div>
 `;
 
 const ExternalLabelsTemplate: TemplateFunction<SwitchProps> = (props: SwitchProps) => html`
@@ -183,6 +192,7 @@ const ExternalLabelsTemplate: TemplateFunction<SwitchProps> = (props: SwitchProp
         name="${props.name || nothing}"
         value="${props.value || nothing}"
         ?checked="${props.checked}"
+        ?defaultChecked="${props.defaultChecked}"
         @change="${changeAction}">
     </pie-switch>
 
@@ -195,6 +205,7 @@ const ExternalLabelsTemplate: TemplateFunction<SwitchProps> = (props: SwitchProp
             data-test-id="external-switch-wrapping"
             name="${props.name || nothing}"
             value="${props.value || nothing}"
+            ?defaultChecked="${props.defaultChecked}"
             @change="${changeAction}">
         </pie-switch>
     </label>
@@ -208,16 +219,16 @@ const ExternalLabelsTemplate: TemplateFunction<SwitchProps> = (props: SwitchProp
         data-test-id="external-switch-multi"
         name="${props.name || nothing}"
         value="${props.value || nothing}"
+        ?defaultChecked="${props.defaultChecked}"
         @change="${changeAction}">
     </pie-switch>
+
 `;
 
 const createSwitchStory = createStory(Template, defaultArgs);
 
 const createSwitchStoryWithForm = createStory<SwitchProps>(FormTemplate, defaultArgs);
 
-const createSwitchTestStoryWithForm = createStory<SwitchProps>(TestFormTemplate, defaultArgs);
-
 const createSwitchStoryWithExternalLabels = createStory<SwitchProps>(ExternalLabelsTemplate, defaultArgs);
 
 const formIntegrationOnly = {
@@ -236,8 +247,6 @@ export const Default = createSwitchStory({}, {
 
 export const FormIntegration = createSwitchStoryWithForm();
 
-export const TestFormIntegration = createSwitchTestStoryWithForm();
-
 export const ExternalLabels = createSwitchStoryWithExternalLabels();
 
 const baseSharedPropsMatrix: Partial<Record<keyof SwitchProps, unknown[]>> = {

packages/components/pie-switch/README.md

@@ -36,11 +36,12 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 | Prop            | Options                                | Description                                                                                                                       | Default     |
 |------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|-------------|
 | `checked`        | `true`, `false`                        | Same as the HTML `checked` attribute; indicates whether the switch is on or off.                                                 | `false`     |
+| `defaultChecked` | `true`, `false`                        | Sets the default checked state for the switch. This does not directly set the initial checked state when the page loads, use `checked` for that. If the switch is inside a form which is reset, the `checked` state will be updated to match `defaultChecked`. | `false`     |
 | `disabled`       | `true`, `false`                        | Same as the HTML `disabled` attribute; indicates whether the switch is disabled or not.                                          | `false`     |
 | `required`       | `true`, `false`                        | Same as the HTML `required` attribute; indicates whether the switch must be turned on when submitted as part of a form.          | `false`     |
 | `label`          | —                                      | The label text for the switch.                                                                                                   | —           |
 | `labelPlacement` | `"leading"`, `"trailing"`              | Set the placement of the label. Leading will have the label before the switch, taking writing direction into account.            | `"leading"` |
-| `aria`           | `{ label?: string, describedBy?: string }` | The ARIA labels used for the switch.                                                                                             | `undefined` |
+| `aria`           | `{ label?: string }`                       | The ARIA labels used for the switch.                                                                                             | `undefined` |
 | `name`           | —                                      | Indicates the name of the switch (for use with forms).                                                                            | —           |
 | `value`          | —                                      | Indicates the value of the switch (for use with forms).                                                                           | `"on"`      |
 

packages/components/pie-switch/src/defs.ts

@@ -3,8 +3,7 @@ import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 export const labelPlacements = ['leading', 'trailing'] as const;
 
 type AriaProps = {
-    label?: string,
-    describedBy?: string
+    label?: string
 };
 
 export interface SwitchProps {
@@ -16,6 +15,11 @@ export interface SwitchProps {
      * Same as the HTML checked attribute - indicates whether the switch is on or off
      */
     checked?: boolean;
+    /**
+     * The default checked state of the switch (not necessarily the same as the current checked state).
+        * Used when the switch is part of a form that is reset.
+     */
+    defaultChecked?: boolean;
     /**
      * Same as the HTML required attribute - indicates whether the switch must be turned or not
      */
@@ -53,6 +57,7 @@ export type DefaultProps = ComponentDefaultProps<SwitchProps, keyof Omit<SwitchP
 
 export const defaultProps: DefaultProps = {
     checked: false,
+    defaultChecked: false,
     disabled: false,
     labelPlacement: 'leading',
     required: false,