feat(checkbox): add required prop (#30157)

Issue number: resolves internal

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
- Currently, the screen reader do not announce the component as required
when `required={true}`.

## What is the new behavior?
- Added a new `required` prop to be used for accessibility purposes that
adds the `required` attribute to checkbox's inner native input.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->

Author: OS-giulianasilva

core/api.txt

@@ -403,6 +403,7 @@ ion-checkbox,prop,justify,"end" | "space-between" | "start" | undefined,undefine
 ion-checkbox,prop,labelPlacement,"end" | "fixed" | "stacked" | "start",'start',false,false
 ion-checkbox,prop,mode,"ios" | "md",undefined,false,false
 ion-checkbox,prop,name,string,this.inputId,false,false
+ion-checkbox,prop,required,boolean,false,false,false
 ion-checkbox,prop,value,any,'on',false,false
 ion-checkbox,event,ionBlur,void,true
 ion-checkbox,event,ionChange,CheckboxChangeEventDetail<any>,true

core/src/components.d.ts

@@ -643,6 +643,10 @@ export namespace Components {
           * The name of the control, which is submitted with the form data.
          */
         "name": string;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required": boolean;
         "setFocus": () => Promise<void>;
         /**
           * The value of the checkbox does not mean if it's checked or not, use the `checked` property for that.  The value of a checkbox is analogous to the value of an `<input type="checkbox">`, it's only used when the checkbox participates in a native `<form>`.
@@ -5447,6 +5451,10 @@ declare namespace LocalJSX {
           * Emitted when the checkbox has focus.
          */
         "onIonFocus"?: (event: IonCheckboxCustomEvent<void>) => void;
+        /**
+          * If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
+         */
+        "required"?: boolean;
         /**
           * The value of the checkbox does not mean if it's checked or not, use the `checked` property for that.  The value of a checkbox is analogous to the value of an `<input type="checkbox">`, it's only used when the checkbox participates in a native `<form>`.
          */

core/src/components/checkbox/checkbox.tsx

@@ -98,6 +98,13 @@ export class Checkbox implements ComponentInterface {
    */
   @Prop() alignment?: 'start' | 'center';
 
+  /**
+   * If true, screen readers will announce it as a required field. This property
+   * works only for accessibility purposes, it will not prevent the form from
+   * submitting if the value is invalid.
+   */
+  @Prop() required = false;
+
   /**
    * Emitted when the checked property has changed as a result of a user action such as a click.
    *
@@ -182,6 +189,7 @@ export class Checkbox implements ComponentInterface {
       name,
       value,
       alignment,
+      required,
     } = this;
     const mode = getIonMode(this);
     const path = getSVGPath(mode, indeterminate);
@@ -218,6 +226,7 @@ export class Checkbox implements ComponentInterface {
             onFocus={() => this.onFocus()}
             onBlur={() => this.onBlur()}
             ref={(focusEl) => (this.focusEl = focusEl)}
+            required={required}
             {...inheritedAttributes}
           />
           <div

core/src/components/checkbox/test/checkbox.spec.ts

@@ -54,3 +54,33 @@ describe('ion-checkbox: indeterminate', () => {
     expect(checkbox.getAttribute('aria-checked')).toBe('mixed');
   });
 });
+
+describe('ion-checkbox: required', () => {
+  it('should have a required attribute in inner input when true', async () => {
+    const page = await newSpecPage({
+      components: [Checkbox],
+      html: `
+        <ion-checkbox required="true">Checkbox</ion-checkbox>
+      `,
+    });
+
+    const checkbox = page.body.querySelector('ion-checkbox')!;
+    const nativeInput = checkbox.shadowRoot?.querySelector('input[type=checkbox]')!;
+
+    expect(nativeInput.hasAttribute('required')).toBeTruthy();
+  });
+
+  it('should not have a required attribute in inner input when false', async () => {
+    const page = await newSpecPage({
+      components: [Checkbox],
+      html: `
+        <ion-checkbox required="false">Checkbox</ion-checkbox>
+      `,
+    });
+
+    const checkbox = page.body.querySelector('ion-checkbox')!;
+    const nativeInput = checkbox.shadowRoot?.querySelector('input[type=checkbox]')!;
+
+    expect(nativeInput.hasAttribute('required')).toBeFalsy();
+  });
+});

packages/angular/src/directives/proxies.ts

@@ -507,14 +507,14 @@ export declare interface IonCardTitle extends Components.IonCardTitle {}
 
 
 @ProxyCmp({
-  inputs: ['alignment', 'checked', 'color', 'disabled', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'value']
+  inputs: ['alignment', 'checked', 'color', 'disabled', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'required', 'value']
 })
 @Component({
   selector: 'ion-checkbox',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['alignment', 'checked', 'color', 'disabled', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'value'],
+  inputs: ['alignment', 'checked', 'color', 'disabled', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'required', 'value'],
 })
 export class IonCheckbox {
   protected el: HTMLIonCheckboxElement;

packages/vue/src/proxies.ts

@@ -235,6 +235,7 @@ export const IonCheckbox = /*@__PURE__*/ defineContainer<JSX.IonCheckbox, JSX.Io
   'labelPlacement',
   'justify',
   'alignment',
+  'required',
   'ionChange',
   'ionFocus',
   'ionBlur'