feat(checkbox): ionChange fires on user interaction (#25923)

BREAKING CHANGE:

`ionChange` is no longer emitted when the `checked` property of `ion-checkbox` is modified externally. `ionChange` is only emitted from user committed changes, such as clicking or tapping the checkbox.

core/src/components/checkbox/checkbox.tsx

@@ -63,7 +63,10 @@ export class Checkbox implements ComponentInterface {
   @Prop() value: any | null = 'on';
 
   /**
-   * Emitted when the checked property has changed.
+   * Emitted when the checked property has changed
+   * as a result of a user action such as a click.
+   * This event will not emit when programmatically
+   * setting the checked property.
    */
   @Event() ionChange!: EventEmitter<CheckboxChangeEventDetail>;
 
@@ -88,11 +91,7 @@ export class Checkbox implements ComponentInterface {
   }
 
   @Watch('checked')
-  checkedChanged(isChecked: boolean) {
-    this.ionChange.emit({
-      checked: isChecked,
-      value: this.value,
-    });
+  checkedChanged() {
     this.emitStyle();
   }
 
@@ -114,11 +113,25 @@ export class Checkbox implements ComponentInterface {
     }
   }
 
-  private onClick = (ev: any) => {
+  /**
+   * Sets the checked property and emits
+   * the ionChange event. Use this to update the
+   * checked state in response to user-generated
+   * actions such as a click.
+   */
+  private setChecked = (state: boolean) => {
+    const isChecked = (this.checked = state);
+    this.ionChange.emit({
+      checked: isChecked,
+      value: this.value,
+    });
+  };
+
+  private toggleChecked = (ev: any) => {
     ev.preventDefault();
 
     this.setFocus();
-    this.checked = !this.checked;
+    this.setChecked(!this.checked);
     this.indeterminate = false;
   };
 
@@ -153,7 +166,6 @@ export class Checkbox implements ComponentInterface {
 
     return (
       <Host
-        onClick={this.onClick}
         aria-labelledby={label ? labelId : null}
         aria-checked={`${checked}`}
         aria-hidden={disabled ? 'true' : null}
@@ -176,6 +188,7 @@ export class Checkbox implements ComponentInterface {
           aria-checked={`${checked}`}
           disabled={disabled}
           id={inputId}
+          onChange={this.toggleChecked}
           onFocus={() => this.onFocus()}
           onBlur={() => this.onBlur()}
           ref={(focusEl) => (this.focusEl = focusEl)}

core/src/components/checkbox/test/basic/checkbox.e2e.ts

@@ -10,3 +10,52 @@ test.describe('checkbox: basic', () => {
     expect(await page.screenshot()).toMatchSnapshot(`checkbox-basic-${page.getSnapshotSettings()}.png`);
   });
 });
+
+test.describe('checkbox: ionChange', () => {
+  test.beforeEach(({ skip }) => {
+    skip.rtl();
+  });
+  test('should fire ionChange when interacting with checkbox', async ({ page }) => {
+    await page.setContent(`
+      <ion-checkbox value="my-checkbox"></ion-checkbox>
+    `);
+
+    const ionChange = await page.spyOnEvent('ionChange');
+    const checkbox = page.locator('ion-checkbox');
+
+    await checkbox.click();
+    await expect(ionChange).toHaveReceivedEventDetail({ value: 'my-checkbox', checked: true });
+
+    await checkbox.click();
+    await expect(ionChange).toHaveReceivedEventDetail({ value: 'my-checkbox', checked: false });
+  });
+
+  test('should fire ionChange when interacting with checkbox in item', async ({ page }) => {
+    await page.setContent(`
+      <ion-item>
+        <ion-checkbox value="my-checkbox"></ion-checkbox>
+      </ion-item>
+    `);
+
+    const ionChange = await page.spyOnEvent('ionChange');
+    const item = page.locator('ion-item');
+
+    await item.click();
+    await expect(ionChange).toHaveReceivedEventDetail({ value: 'my-checkbox', checked: true });
+
+    await item.click();
+    await expect(ionChange).toHaveReceivedEventDetail({ value: 'my-checkbox', checked: false });
+  });
+
+  test('should not fire when programmatically setting a value', async ({ page }) => {
+    await page.setContent(`
+      <ion-checkbox value="my-checkbox"></ion-checkbox>
+    `);
+
+    const ionChange = await page.spyOnEvent('ionChange');
+    const checkbox = page.locator('ion-checkbox');
+
+    await checkbox.evaluate((el: HTMLIonCheckboxElement) => (el.checked = true));
+    await expect(ionChange).not.toHaveReceivedEvent();
+  });
+});