feat(input-otp): convert to a form associated shadow component #30785 (#30884)

Issue number: internal

---------

## What is the current behavior?
Input Otp uses `scoped` encapsulation. This causes issues with CSP compatibility and is inconsistent with our goal of having all components use Shadow DOM.

## What is the new behavior?
- Converts `ion-input-otp` to `shadow` with `formAssociated: true`
- Adds shadow parts for inner elements

## Does this introduce a breaking change?
- [x] Yes
- [ ] No

BREAKING CHANGE:

Input Otp has been converted to use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).

If you were targeting the internals of `ion-input-otp` in your CSS, you will need to target the `group`, `container`, `native`, `separator` or `description` [Shadow Parts](https://ionicframework.com/docs/theming/css-shadow-parts) instead, or use the provided CSS Variables.

---------

Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>

Author: brandyscarney

BREAKING.md

@@ -20,6 +20,7 @@ This is a comprehensive list of the breaking changes introduced in the major ver
   - [Chip](#version-9x-chip)
   - [Datetime](#version-9x-datetime)
   - [Grid](#version-9x-grid)
+  - [Input Otp](#version-9x-input-otp)
   - [Radio Group](#version-9x-radio-group)
   - [Textarea](#version-9x-textarea)
 
@@ -185,6 +186,12 @@ To reorder two columns where column 1 has `size="9" push="3"` and column 2 has `
 </ion-grid>
 ```
 
+<h4 id="version-9x-input-otp">Input Otp</h4>
+
+Converted `ion-input-otp` to use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
+
+If you were targeting the internals of `ion-input-otp` in your CSS, you will need to target the `group`, `container`, `native`, `separator` or `description` [Shadow Parts](https://ionicframework.com/docs/theming/css-shadow-parts) instead, or use the provided CSS Variables.
+
 <h4 id="version-9x-radio-group">Radio Group</h4>
 
 Converted `ion-radio-group` to use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).

core/api.txt

@@ -1035,18 +1035,20 @@ ion-input,css-prop,--placeholder-opacity,ionic
 ion-input,css-prop,--placeholder-opacity,ios
 ion-input,css-prop,--placeholder-opacity,md
 
-ion-input-otp,scoped
+ion-input-otp,shadow
 ion-input-otp,prop,autocapitalize,string,'off',false,false
 ion-input-otp,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
 ion-input-otp,prop,disabled,boolean,false,false,true
 ion-input-otp,prop,fill,"outline" | "solid" | undefined,'outline',false,false
 ion-input-otp,prop,inputmode,"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url" | undefined,undefined,false,false
 ion-input-otp,prop,length,number,4,false,false
+ion-input-otp,prop,mode,"ios" | "md",undefined,false,false
 ion-input-otp,prop,pattern,string | undefined,undefined,false,false
 ion-input-otp,prop,readonly,boolean,false,false,true
 ion-input-otp,prop,separators,number[] | string | undefined,undefined,false,false
 ion-input-otp,prop,shape,"rectangular" | "round" | "soft",'round',false,false
 ion-input-otp,prop,size,"large" | "medium" | "small",'medium',false,false
+ion-input-otp,prop,theme,"ios" | "md" | "ionic",undefined,false,false
 ion-input-otp,prop,type,"number" | "text",'number',false,false
 ion-input-otp,prop,value,null | number | string | undefined,'',false,false
 ion-input-otp,method,setFocus,setFocus(index?: number) => Promise<void>
@@ -1127,6 +1129,11 @@ ion-input-otp,css-prop,--separator-width,md
 ion-input-otp,css-prop,--width,ionic
 ion-input-otp,css-prop,--width,ios
 ion-input-otp,css-prop,--width,md
+ion-input-otp,part,container
+ion-input-otp,part,description
+ion-input-otp,part,group
+ion-input-otp,part,native
+ion-input-otp,part,separator
 
 ion-input-password-toggle,shadow
 ion-input-password-toggle,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true

core/src/components.d.ts

@@ -1779,6 +1779,10 @@ export namespace Components {
           * @default 4
          */
         "length": number;
+        /**
+          * The mode determines the platform behaviors of the component.
+         */
+        "mode"?: "ios" | "md";
         /**
           * A regex pattern string for allowed characters. Defaults based on type.  For numbers (`type="number"`): `"[\p{N}]"` For text (`type="text"`): `"[\p{L}\p{N}]"`
          */
@@ -1807,6 +1811,10 @@ export namespace Components {
           * @default 'medium'
          */
         "size": 'small' | 'medium' | 'large';
+        /**
+          * The theme determines the visual appearance of the component.
+         */
+        "theme"?: "ios" | "md" | "ionic";
         /**
           * The type of input allowed in the input boxes.
           * @default 'number'
@@ -7762,6 +7770,10 @@ declare namespace LocalJSX {
           * @default 4
          */
         "length"?: number;
+        /**
+          * The mode determines the platform behaviors of the component.
+         */
+        "mode"?: "ios" | "md";
         /**
           * Emitted when the input group loses focus.
          */
@@ -7805,6 +7817,10 @@ declare namespace LocalJSX {
           * @default 'medium'
          */
         "size"?: 'small' | 'medium' | 'large';
+        /**
+          * The theme determines the visual appearance of the component.
+         */
+        "theme"?: "ios" | "md" | "ionic";
         /**
           * The type of input allowed in the input boxes.
           * @default 'number'

core/src/components/input-otp/input-otp.common.scss

@@ -94,10 +94,13 @@
   background: var(--background);
   color: var(--color);
 
+  font-family: inherit;
   font-size: inherit;
 
   text-align: center;
   appearance: none;
+
+  box-sizing: border-box;
 }
 
 :host(.has-focus) .native-input {

core/src/components/input-otp/input-otp.native.scss

@@ -19,6 +19,8 @@
   --highlight-color-valid: #{ion-color(success, base)};
   --highlight-color-invalid: #{ion-color(danger, base)};
 
+  font-family: $font-family-base;
+
   font-size: dynamic-font(14px);
 }
 

core/src/components/input-otp/input-otp.tsx

@@ -1,5 +1,6 @@
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
-import { Component, Element, Event, Fragment, Host, Prop, State, h, Watch } from '@stencil/core';
+import { AttachInternals, Component, Element, Event, Fragment, Host, Prop, State, h, Watch } from '@stencil/core';
+import { reportValidityToElementInternals } from '@utils/forms';
 import type { Attributes } from '@utils/helpers';
 import { inheritAriaAttributes } from '@utils/helpers';
 import { printIonWarning } from '@utils/logging';
@@ -16,14 +17,25 @@ import type {
   InputOtpInputEventDetail,
 } from './input-otp-interface';
 
+/**
+ * @virtualProp {"ios" | "md"} mode - The mode determines the platform behaviors of the component.
+ * @virtualProp {"ios" | "md" | "ionic"} theme - The theme determines the visual appearance of the component.
+ *
+ * @part group - The container element that wraps all input boxes.
+ * @part container - The wrapper element for each individual input box.
+ * @part native - The native input element.
+ * @part separator - The separator element displayed between input boxes.
+ * @part description - The container element for the description text.
+ */
 @Component({
   tag: 'ion-input-otp',
   styleUrls: {
     ios: 'input-otp.ios.scss',
     md: 'input-otp.md.scss',
     ionic: 'input-otp.ionic.scss',
   },
-  scoped: true,
+  shadow: true,
+  formAssociated: true,
 })
 export class InputOTP implements ComponentInterface {
   private inheritedAttributes: Attributes = {};
@@ -47,6 +59,8 @@ export class InputOTP implements ComponentInterface {
 
   @Element() el!: HTMLIonInputOtpElement;
 
+  @AttachInternals() internals!: ElementInternals;
+
   @State() private inputValues: string[] = [];
   @State() hasFocus = false;
   @State() private previousInputValues: string[] = [];
@@ -69,6 +83,14 @@ export class InputOTP implements ComponentInterface {
    */
   @Prop({ reflect: true }) disabled = false;
 
+  /**
+   * Update element internals when disabled prop changes
+   */
+  @Watch('disabled')
+  protected disabledChanged() {
+    this.updateElementInternals();
+  }
+
   /**
    * The fill for the input boxes. If `"solid"` the input boxes will have a background. If
    * `"outline"` the input boxes will be transparent with a border.
@@ -197,6 +219,7 @@ export class InputOTP implements ComponentInterface {
   valueChanged() {
     this.initializeValues();
     this.updateTabIndexes();
+    this.updateElementInternals();
   }
 
   /**
@@ -272,6 +295,7 @@ export class InputOTP implements ComponentInterface {
 
   componentDidLoad() {
     this.updateTabIndexes();
+    this.updateElementInternals();
   }
 
   /**
@@ -356,6 +380,50 @@ export class InputOTP implements ComponentInterface {
     }
   }
 
+  /**
+   * Gets the value of the input group as a string for form submission.
+   * Returns an empty string if the value is null or undefined.
+   */
+  private getValue(): string {
+    return this.value != null ? this.value.toString() : '';
+  }
+
+  /**
+   * Called when the form state is restored.
+   * Restores the component's value.
+   */
+  formStateRestoreCallback(value: string) {
+    this.value = value;
+  }
+
+  /**
+   * Called when the form is reset.
+   * Resets the component's value.
+   */
+  formResetCallback() {
+    this.value = '';
+  }
+
+  /**
+   * Updates the form value and reports validity state to the browser via
+   * ElementInternals. This should be called when the component loads, when
+   * the disabled prop changes, and when the value changes to ensure the form
+   * value stays in sync and validation state is updated.
+   */
+  private updateElementInternals() {
+    // Disabled form controls should not be included in form data
+    // Pass null to setFormValue when disabled to exclude it from form submission
+    const value = this.disabled ? null : this.getValue();
+    // ElementInternals may not be fully available in test environments
+    // so we need to check if the method exists before calling it
+    if (typeof this.internals.setFormValue === 'function') {
+      this.internals.setFormValue(value);
+    }
+    // Use the first input element for validity reporting since all inputs
+    // share the same validation state
+    reportValidityToElementInternals(this.inputRefs[0] ?? null, this.internals);
+  }
+
   /**
    * Emits an `ionChange` event.
    * This API should be called for user committed changes.
@@ -817,12 +885,19 @@ export class InputOTP implements ComponentInterface {
           'input-otp-readonly': readonly,
         })}
       >
-        <div role="group" aria-label="One-time password input" class="input-otp-group" {...inheritedAttributes}>
+        <div
+          role="group"
+          aria-label="One-time password input"
+          class="input-otp-group"
+          part="group"
+          {...inheritedAttributes}
+        >
           {Array.from({ length }).map((_, index) => (
             <>
-              <div class="native-wrapper">
+              <div class="native-wrapper" part="container">
                 <input
                   class="native-input"
+                  part="native"
                   id={`${inputId}-${index}`}
                   aria-label={`Input ${index + 1} of ${length}`}
                   type="text"
@@ -842,7 +917,7 @@ export class InputOTP implements ComponentInterface {
                   onPaste={this.onPaste}
                 />
               </div>
-              {this.showSeparator(index) && <div class="input-otp-separator" />}
+              {this.showSeparator(index) && <div class="input-otp-separator" part="separator" />}
             </>
           ))}
         </div>
@@ -851,6 +926,7 @@ export class InputOTP implements ComponentInterface {
             'input-otp-description': true,
             'input-otp-description-hidden': !hasDescription,
           }}
+          part="description"
         >
           <slot></slot>
         </div>