feat(checkbox): add helperText and errorText properties (#30140)

Issue number: resolves #29810 --------- ## What is the current behavior? Checkbox does not support helper and error text. ## What is the new behavior? Adds support for helper and error text, similar to input and textarea. ## Does this introduce a breaking change? - [ ] Yes - [x] No ## Other information - [Bottom Content: Preview](https://ionic-framework-git-rou-11141-ionic1.vercel.app/src/components/checkbox/test/bottom-content) - [Item: Preview](https://ionic-framework-git-rou-11141-ionic1.vercel.app/src/components/checkbox/test/item) --------- Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>

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
@@ -431,8 +433,11 @@ ion-checkbox,css-prop,--size,md
 ion-checkbox,css-prop,--transition,ios
 ion-checkbox,css-prop,--transition,md
 ion-checkbox,part,container
+ion-checkbox,part,error-text
+ion-checkbox,part,helper-text
 ion-checkbox,part,label
 ion-checkbox,part,mark
+ion-checkbox,part,supporting-text
 
 ion-chip,shadow
 ion-chip,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true

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 label and displayed when an error is detected.
+ */
+ "errorText"?: string;
+ /**
+ * Text that is placed under the checkbox label and displayed when no error is detected.
+ */
+ "helperText"?: string;
  /**
  * If `true`, the checkbox will visually appear as indeterminate.
  */
@@ -5419,6 +5427,14 @@ declare namespace LocalJSX {
  * If `true`, the user cannot interact with the checkbox.
  */
  "disabled"?: boolean;
+ /**
+ * Text that is placed under the checkbox label and displayed when an error is detected.
+ */
+ "errorText"?: string;
+ /**
+ * Text that is placed under the checkbox label and displayed when no error is detected.
+ */
+ "helperText"?: string;
  /**
  * If `true`, the checkbox will visually appear as indeterminate.
  */

core/src/components/checkbox/checkbox.scss

@@ -148,46 +148,53 @@ input {
  opacity: 0;
 }
 
-// Justify Content
-// ---------------------------------------------
+// Checkbox Bottom Content
+// ----------------------------------------------------------------
+
+.checkbox-bottom {
+ @include padding(4px, null, null, null);
+
+ display: flex;
 
-:host(.checkbox-justify-space-between) .checkbox-wrapper {
  justify-content: space-between;
-}
 
-:host(.checkbox-justify-start) .checkbox-wrapper {
- justify-content: start;
+ font-size: dynamic-font(12px);
+
+ white-space: normal;
 }
 
-:host(.checkbox-justify-end) .checkbox-wrapper {
- justify-content: end;
+:host(.checkbox-label-placement-stacked) .checkbox-bottom {
+ font-size: dynamic-font(16px);
 }
 
-// Align Items
-// ---------------------------------------------
+// Checkbox Hint Text
+// ----------------------------------------------------------------
 
-:host(.checkbox-alignment-start) .checkbox-wrapper {
- align-items: start;
-}
+/**
+ * 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;
 
-:host(.checkbox-alignment-center) .checkbox-wrapper {
- align-items: center;
+ color: ion-color(danger, base);
 }
 
-// Justify Content & Align Items
-// ---------------------------------------------
+.checkbox-bottom .helper-text {
+ display: block;
 
-// The checkbox should be displayed as block when either justify
-// or alignment is set; otherwise, these properties will have no
-// visible effect.
-:host(.checkbox-justify-space-between),
-:host(.checkbox-justify-start),
-:host(.checkbox-justify-end),
-:host(.checkbox-alignment-start),
-:host(.checkbox-alignment-center) {
+ color: $text-color-step-300;
+}
+
+:host(.ion-touched.ion-invalid) .checkbox-bottom .error-text {
  display: block;
 }
 
+:host(.ion-touched.ion-invalid) .checkbox-bottom .helper-text {
+ display: none;
+}
+
 // Label Placement - Start
 // ----------------------------------------------------------------
 
@@ -217,6 +224,8 @@ input {
  */
 :host(.checkbox-label-placement-end) .checkbox-wrapper {
  flex-direction: row-reverse;
+
+ justify-content: start;
 }
 
 /**
@@ -260,6 +269,8 @@ input {
  */
 :host(.checkbox-label-placement-stacked) .checkbox-wrapper {
  flex-direction: column;
+
+ text-align: center;
 }
 
 :host(.checkbox-label-placement-stacked) .label-text-wrapper {
@@ -287,6 +298,46 @@ input {
  @include transform-origin(center, top);
 }
 
+// Justify Content
+// ---------------------------------------------
+
+:host(.checkbox-justify-space-between) .checkbox-wrapper {
+ justify-content: space-between;
+}
+
+:host(.checkbox-justify-start) .checkbox-wrapper {
+ justify-content: start;
+}
+
+:host(.checkbox-justify-end) .checkbox-wrapper {
+ justify-content: end;
+}
+
+// Align Items
+// ---------------------------------------------
+
+:host(.checkbox-alignment-start) .checkbox-wrapper {
+ align-items: start;
+}
+
+:host(.checkbox-alignment-center) .checkbox-wrapper {
+ align-items: center;
+}
+
+// Justify Content & Align Items
+// ---------------------------------------------
+
+// The checkbox should be displayed as block when either justify
+// or alignment is set; otherwise, these properties will have no
+// visible effect.
+:host(.checkbox-justify-space-between),
+:host(.checkbox-justify-start),
+:host(.checkbox-justify-end),
+:host(.checkbox-alignment-start),
+:host(.checkbox-alignment-center) {
+ display: block;
+}
+
 // Checked / Indeterminate Checkbox
 // ---------------------------------------------
 

core/src/components/checkbox/checkbox.tsx

@@ -17,6 +17,9 @@ import type { CheckboxChangeEventDetail } from './checkbox-interface';
  * @part container - The container for the checkbox mark.
  * @part label - The label text describing the checkbox.
  * @part mark - The checkmark used to indicate the checked state.
+ * @part supporting-text - Supporting text displayed beneath the checkbox label.
+ * @part helper-text - Supporting text displayed beneath the checkbox label when the checkbox is valid.
+ * @part error-text - Supporting text displayed beneath the checkbox label when the checkbox is invalid and touched.
  */
 @Component({
  tag: 'ion-checkbox',
@@ -28,6 +31,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 +65,16 @@ export class Checkbox implements ComponentInterface {
  */
  @Prop() disabled = false;
 
+ /**
+ * Text that is placed under the checkbox label and displayed when an error is detected.
+ */
+ @Prop() errorText?: string;
+
+ /**
+ * Text that is placed under the checkbox label 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.
@@ -174,6 +189,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" part="supporting-text helper-text">
+ {helperText}
+ </div>
+ <div id={errorTextId} class="error-text" part="supporting-text error-text">
+ {errorText}
+ </div>
+ </div>
+ );
+ }
+
  render() {
  const {
  color,
@@ -199,6 +256,8 @@ export class Checkbox implements ComponentInterface {
  return (
  <Host
  aria-checked={indeterminate ? 'mixed' : `${checked}`}
+ aria-describedby={this.getHintTextID()}
+ aria-invalid={this.getHintTextID() === this.errorTextId}
  class={createColorClasses(color, {
  [mode]: true,
  'in-item': hostContext('ion-item', el),
@@ -237,6 +296,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">