feat(checkbox): add helperText and errorText

Author: brandyscarney

core/api.txt

@@ -398,6 +398,8 @@ ion-checkbox,prop,alignment,"center" | "start" | undefined,undefined,false,false
 ion-checkbox,prop,checked,boolean,false,false,false
 ion-checkbox,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
 ion-checkbox,prop,disabled,boolean,false,false,false
+ion-checkbox,prop,errorText,string | undefined,undefined,false,false
+ion-checkbox,prop,helperText,string | undefined,undefined,false,false
 ion-checkbox,prop,indeterminate,boolean,false,false,false
 ion-checkbox,prop,justify,"end" | "space-between" | "start" | undefined,undefined,false,false
 ion-checkbox,prop,labelPlacement,"end" | "fixed" | "stacked" | "start",'start',false,false
@@ -425,6 +427,14 @@ ion-checkbox,css-prop,--checkmark-color,ios
 ion-checkbox,css-prop,--checkmark-color,md
 ion-checkbox,css-prop,--checkmark-width,ios
 ion-checkbox,css-prop,--checkmark-width,md
+ion-checkbox,css-prop,--highlight-color-focused,ios
+ion-checkbox,css-prop,--highlight-color-focused,md
+ion-checkbox,css-prop,--highlight-color-invalid,ios
+ion-checkbox,css-prop,--highlight-color-invalid,md
+ion-checkbox,css-prop,--highlight-color-valid,ios
+ion-checkbox,css-prop,--highlight-color-valid,md
+ion-checkbox,css-prop,--highlight-height,ios
+ion-checkbox,css-prop,--highlight-height,md
 ion-checkbox,css-prop,--size,ios
 ion-checkbox,css-prop,--size,md
 ion-checkbox,css-prop,--transition,ios

core/src/components.d.ts

@@ -623,6 +623,14 @@ export namespace Components {
           * If `true`, the user cannot interact with the checkbox.
          */
         "disabled": boolean;
+        /**
+          * Text that is placed under the checkbox and displayed when an error is detected.
+         */
+        "errorText"?: string;
+        /**
+          * Text that is placed under the checkbox and displayed when no error is detected.
+         */
+        "helperText"?: string;
         /**
           * If `true`, the checkbox will visually appear as indeterminate.
          */
@@ -5403,6 +5411,14 @@ declare namespace LocalJSX {
           * If `true`, the user cannot interact with the checkbox.
          */
         "disabled"?: boolean;
+        /**
+          * Text that is placed under the checkbox and displayed when an error is detected.
+         */
+        "errorText"?: string;
+        /**
+          * Text that is placed under the checkbox and displayed when no error is detected.
+         */
+        "helperText"?: string;
         /**
           * If `true`, the checkbox will visually appear as indeterminate.
          */

core/src/components/checkbox/checkbox.ios.scss

@@ -21,6 +21,12 @@
   --checkmark-width: #{$checkbox-ios-icon-checkmark-width};
 }
 
+// iOS Checkbox: Hint Text
+// ----------------------------------------------------------------
+
+.checkbox-bottom .helper-text {
+  color: #{$text-color-step-450};
+}
 
 // iOS Checkbox: Disabled
 // -----------------------------------------

core/src/components/checkbox/checkbox.md.scss

@@ -27,6 +27,13 @@
   stroke-dashoffset: 30;
 }
 
+// Material Design Checkbox: Hint Text
+// ----------------------------------------------------------------
+
+.checkbox-bottom .helper-text {
+  color: #{$text-color-step-300};
+}
+
 // Material Design Checkbox: Checked / Indeterminate
 // --------------------------------------------------------
 

core/src/components/checkbox/checkbox.scss

@@ -17,6 +17,11 @@
    * @prop --border-style: Border style of the checkbox icon
    * @prop --border-color-checked: Border color of the checkbox icon when checked
    *
+   * @prop --highlight-height: The height of the highlight on the checkbox. Only applies to md mode
+   * @prop --highlight-color-focused: The color of the highlight on the checkbox when focused
+   * @prop --highlight-color-valid: The color of the highlight on the checkbox when valid
+   * @prop --highlight-color-invalid: The color of the highlight on the checkbox when invalid
+   *
    * @prop --transition: Transition of the checkbox icon
    *
    * @prop --checkmark-color: Color of the checkbox checkmark when checked
@@ -26,6 +31,9 @@
   --border-color-checked: #{ion-color(primary, base)};
   --checkmark-color: #{ion-color(primary, contrast)};
   --transition: none;
+  --highlight-color-focused: #{ion-color(primary, base)};
+  --highlight-color-valid: #{ion-color(success, base)};
+  --highlight-color-invalid: #{ion-color(danger, base)};
 
   display: inline-block;
 
@@ -148,6 +156,56 @@ input {
   opacity: 0;
 }
 
+// Checkbox Bottom Content
+// ----------------------------------------------------------------
+
+.checkbox-bottom {
+  /**
+   * The bottom content should take on the start and end
+   * padding so it is always aligned with either the label
+   * or the start of the checkbox.
+   */
+  @include padding(5px, null, null, null);
+
+  display: flex;
+
+  justify-content: space-between;
+
+  font-size: dynamic-font(12px);
+
+  white-space: normal;
+}
+
+:host(.checkbox-label-placement-stacked) .checkbox-bottom {
+  font-size: dynamic-font(16px);
+}
+
+// Checkbox Hint Text
+// ----------------------------------------------------------------
+
+/**
+ * Error text should only be shown when .ion-invalid is
+ * present on the checkbox. Otherwise the helper text should
+ * be shown.
+ */
+.checkbox-bottom .error-text {
+  display: none;
+
+  color: var(--highlight-color-invalid);
+}
+
+.checkbox-bottom .helper-text {
+  display: block;
+}
+
+:host(.ion-touched.ion-invalid) .checkbox-bottom .error-text {
+  display: block;
+}
+
+:host(.ion-touched.ion-invalid) .checkbox-bottom .helper-text {
+  display: none;
+}
+
 // Justify Content
 // ---------------------------------------------
 

core/src/components/checkbox/checkbox.tsx

@@ -28,6 +28,8 @@ import type { CheckboxChangeEventDetail } from './checkbox-interface';
 })
 export class Checkbox implements ComponentInterface {
   private inputId = `ion-cb-${checkboxIds++}`;
+  private helperTextId = `${this.inputId}-helper-text`;
+  private errorTextId = `${this.inputId}-error-text`;
   private focusEl?: HTMLElement;
   private inheritedAttributes: Attributes = {};
 
@@ -60,6 +62,16 @@ export class Checkbox implements ComponentInterface {
    */
   @Prop() disabled = false;
 
+  /**
+   * Text that is placed under the checkbox and displayed when an error is detected.
+   */
+  @Prop() errorText?: string;
+
+  /**
+   * Text that is placed under the checkbox and displayed when no error is detected.
+   */
+  @Prop() helperText?: string;
+
   /**
    * The value of the checkbox does not mean if it's checked or not, use the `checked`
    * property for that.
@@ -167,6 +179,48 @@ export class Checkbox implements ComponentInterface {
     this.toggleChecked(ev);
   };
 
+  private getHintTextID(): string | undefined {
+    const { el, helperText, errorText, helperTextId, errorTextId } = this;
+
+    if (el.classList.contains('ion-touched') && el.classList.contains('ion-invalid') && errorText) {
+      return errorTextId;
+    }
+
+    if (helperText) {
+      return helperTextId;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Responsible for rendering helper text and error text.
+   * This element should only be rendered if hint text is set.
+   */
+  private renderHintText() {
+    const { helperText, errorText, helperTextId, errorTextId } = this;
+
+    /**
+     * undefined and empty string values should
+     * be treated as not having helper/error text.
+     */
+    const hasHintText = !!helperText || !!errorText;
+    if (!hasHintText) {
+      return;
+    }
+
+    return (
+      <div class="checkbox-bottom">
+        <div id={helperTextId} class="helper-text">
+          {helperText}
+        </div>
+        <div id={errorTextId} class="error-text">
+          {errorText}
+        </div>
+      </div>
+    );
+  }
+
   render() {
     const {
       color,
@@ -218,6 +272,8 @@ export class Checkbox implements ComponentInterface {
             onFocus={() => this.onFocus()}
             onBlur={() => this.onBlur()}
             ref={(focusEl) => (this.focusEl = focusEl)}
+            aria-describedby={this.getHintTextID()}
+            aria-invalid={this.getHintTextID() === this.errorTextId}
             {...inheritedAttributes}
           />
           <div
@@ -228,6 +284,7 @@ export class Checkbox implements ComponentInterface {
             part="label"
           >
             <slot></slot>
+            {this.renderHintText()}
           </div>
           <div class="native-wrapper">
             <svg class="checkbox-icon" viewBox="0 0 24 24" part="container">

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', 'errorText', 'helperText', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', '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', 'errorText', 'helperText', 'indeterminate', 'justify', 'labelPlacement', 'mode', 'name', 'value'],
 })
 export class IonCheckbox {
   protected el: HTMLElement;

packages/vue/src/proxies.ts

@@ -217,6 +217,8 @@ export const IonCheckbox = /*@__PURE__*/ defineContainer<JSX.IonCheckbox, JSX.Io
   'checked',
   'indeterminate',
   'disabled',
+  'errorText',
+  'helperText',
   'value',
   'labelPlacement',
   'justify',