feat(input-otp): expose reset and setFocus methods

Author: brandyscarney

core/api.txt

@@ -793,6 +793,8 @@ 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,type,"number" | "text",'number',false,false
 ion-input-otp,prop,value,null | number | string | undefined,'',false,false
+ion-input-otp,method,reset,reset() => Promise<void>
+ion-input-otp,method,setFocus,setFocus(index?: number) => Promise<void>
 ion-input-otp,event,ionBlur,FocusEvent,true
 ion-input-otp,event,ionChange,InputOtpChangeEventDetail,true
 ion-input-otp,event,ionComplete,InputOtpCompleteEventDetail,true

core/src/components.d.ts

@@ -1350,10 +1350,19 @@ export namespace Components {
           * If `true`, the user cannot modify the value.
          */
         "readonly": boolean;
+        /**
+          * Resets the input values and focus state.
+         */
+        "reset": () => Promise<void>;
         /**
           * Where separators should be shown between input boxes. Can be a comma-separated string or an array of numbers.  For example: `"3"` will show a separator after the 3rd input box. `[1,4]` will show a separator after the 1st and 4th input boxes. `"all"` will show a separator between every input box.
          */
         "separators"?: 'all' | string | number[];
+        /**
+          * Sets focus to an input box.
+          * @param index The index of the input box to focus. If not provided, focuses the first empty input box or the last input if all are filled. The input boxes start at index 0.
+         */
+        "setFocus": (index?: number) => Promise<void>;
         /**
           * The shape of the input boxes. If "round" they will have an increased border radius. If "rectangular" they will have no border radius. If "soft" they will have a soft border radius.
          */

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

@@ -3,6 +3,7 @@ import { Component, Element, Event, Host, Prop, State, h, Watch } from '@stencil
 import { printIonWarning } from '@utils/logging';
 import { isRTL } from '@utils/rtl';
 import { createColorClasses } from '@utils/theme';
+import { Method } from 'ionicons/dist/types/stencil-public-runtime';
 
 import { getIonMode } from '../../global/ionic-global';
 import type { Color } from '../../interface';
@@ -240,6 +241,41 @@ export class InputOTP implements ComponentInterface {
     }
   }
 
+  /**
+   * Resets the input values and focus state.
+   */
+  @Method()
+  async reset() {
+    this.inputValues = Array(this.length).fill('');
+    this.value = '';
+
+    this.focusedValue = null;
+    this.hasFocus = false;
+
+    this.inputRefs.forEach((input) => {
+      input.blur();
+    });
+
+    this.updateTabIndexes();
+  }
+
+  /**
+   * Sets focus to an input box.
+   * @param index The index of the input box to focus. If not provided,
+   * focuses the first empty input box or the last input if all are filled.
+   * The input boxes start at index 0.
+   */
+  @Method()
+  async setFocus(index?: number) {
+    if (typeof index === 'number') {
+      const validIndex = Math.max(0, Math.min(index, this.length - 1));
+      this.inputRefs[validIndex]?.focus();
+    } else {
+      const tabbableIndex = this.getTabbableIndex();
+      this.inputRefs[tabbableIndex]?.focus();
+    }
+  }
+
   /**
    * Get the regex pattern for allowed characters.
    * If a pattern is provided, use it to create a regex pattern

core/src/components/input-otp/test/basic/index.html

@@ -24,6 +24,10 @@
         grid-row-gap: 20px;
         grid-column-gap: 20px;
       }
+
+      button {
+        margin: 8px 2px !important;
+      }
     </style>
   </head>
 
@@ -75,6 +79,15 @@ <h2>Readonly</h2>
             <h2>Invalid</h2>
             <ion-input-otp class="ion-invalid">Description</ion-input-otp>
             <ion-input-otp fill="solid" class="ion-invalid">Description</ion-input-otp>
+
+            <h2>Methods</h2>
+            <ion-input-otp id="inputOtpMethods" value="1234">Description</ion-input-otp>
+            <div style="display: flex; justify-content: center">
+              <button id="reset">Reset</button>
+              <button id="focus">Focus</button>
+              <button id="focus-third">Focus Third</button>
+              <button id="focus-and-reset">Focus and Reset</button>
+            </div>
           </div>
         </div>
       </ion-content>
@@ -112,6 +125,23 @@ <h2>Invalid</h2>
         document.addEventListener('ionBlur', (ev) => {
           console.log('ionBlur', ev);
         });
+
+        document.getElementById('reset').addEventListener('click', () => {
+          inputOtpMethods.reset();
+        });
+
+        document.getElementById('focus').addEventListener('click', () => {
+          inputOtpMethods.setFocus();
+        });
+
+        document.getElementById('focus-third').addEventListener('click', () => {
+          inputOtpMethods.setFocus(2);
+        });
+
+        document.getElementById('focus-and-reset').addEventListener('click', () => {
+          inputOtpMethods.setFocus();
+          inputOtpMethods.reset();
+        });
       </script>
     </ion-app>
   </body>

core/src/components/input-otp/test/basic/input-otp.e2e.ts

@@ -744,3 +744,94 @@ configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) =>
     });
   });
 });
+
+/**
+ * Methods are the same across modes & directions
+ */
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ title, config }) => {
+  test.describe(title('input-otp: setFocus method'), () => {
+    test('should focus the specified input box when index is provided', async ({ page }) => {
+      await page.setContent(`<ion-input-otp>Description</ion-input-otp>`, config);
+
+      const inputOtp = page.locator('ion-input-otp');
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.setFocus(2);
+      });
+
+      const thirdInput = page.locator('ion-input-otp input').nth(2);
+      await expect(thirdInput).toBeFocused();
+    });
+
+    test('should focus first empty input when no index is provided and not all inputs are filled', async ({ page }) => {
+      await page.setContent(`<ion-input-otp value="12">Description</ion-input-otp>`, config);
+
+      const inputOtp = page.locator('ion-input-otp');
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.setFocus();
+      });
+
+      const thirdInput = page.locator('ion-input-otp input').nth(2);
+      await expect(thirdInput).toBeFocused();
+    });
+
+    test('should focus last input when no index is provided and all inputs are filled', async ({ page }) => {
+      await page.setContent(`<ion-input-otp value="1234">Description</ion-input-otp>`, config);
+
+      const inputOtp = page.locator('ion-input-otp');
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.setFocus();
+      });
+
+      const lastInput = page.locator('ion-input-otp input').last();
+      await expect(lastInput).toBeFocused();
+    });
+
+    test('should clamp invalid indices to valid range', async ({ page }) => {
+      await page.setContent(`<ion-input-otp>Description</ion-input-otp>`, config);
+
+      const inputOtp = page.locator('ion-input-otp');
+
+      // Test negative index
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.setFocus(-1);
+      });
+      const firstInput = page.locator('ion-input-otp input').first();
+      await expect(firstInput).toBeFocused();
+
+      // Test index beyond length
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.setFocus(10);
+      });
+      const lastInput = page.locator('ion-input-otp input').last();
+      await expect(lastInput).toBeFocused();
+    });
+  });
+
+  test.describe(title('input-otp: reset method'), () => {
+    test('should clear all input values and reset focus state', async ({ page }) => {
+      await page.setContent(`<ion-input-otp value="1234">Description</ion-input-otp>`, config);
+
+      const inputOtp = page.locator('ion-input-otp');
+      const inputBoxes = page.locator('ion-input-otp input');
+
+      // Focus an input first
+      await inputBoxes.nth(2).focus();
+      await expect(inputBoxes.nth(2)).toBeFocused();
+
+      // Call reset
+      await inputOtp.evaluate((el: HTMLIonInputOtpElement) => {
+        el.reset();
+      });
+
+      // Check that values are cleared
+      await expect(inputOtp).toHaveJSProperty('value', '');
+      await expect(inputBoxes.nth(0)).toHaveValue('');
+      await expect(inputBoxes.nth(1)).toHaveValue('');
+      await expect(inputBoxes.nth(2)).toHaveValue('');
+      await expect(inputBoxes.nth(3)).toHaveValue('');
+
+      // Check that focus is removed
+      await expect(inputBoxes.nth(2)).not.toBeFocused();
+    });
+  });
+});

packages/angular/src/directives/proxies.ts

@@ -1018,7 +1018,8 @@ This event will not emit when programmatically setting the `value` property.
 
 
 @ProxyCmp({
-  inputs: ['color', 'disabled', 'fill', 'inputmode', 'length', 'pattern', 'readonly', 'separators', 'shape', 'size', 'type', 'value']
+  inputs: ['color', 'disabled', 'fill', 'inputmode', 'length', 'pattern', 'readonly', 'separators', 'shape', 'size', 'type', 'value'],
+  methods: ['reset', 'setFocus']
 })
 @Component({
   selector: 'ion-input-otp',

packages/angular/standalone/src/directives/proxies.ts

@@ -984,7 +984,8 @@ export declare interface IonInfiniteScrollContent extends Components.IonInfinite
 
 @ProxyCmp({
   defineCustomElementFn: defineIonInputOtp,
-  inputs: ['color', 'disabled', 'fill', 'inputmode', 'length', 'pattern', 'readonly', 'separators', 'shape', 'size', 'type', 'value']
+  inputs: ['color', 'disabled', 'fill', 'inputmode', 'length', 'pattern', 'readonly', 'separators', 'shape', 'size', 'type', 'value'],
+  methods: ['reset', 'setFocus']
 })
 @Component({
   selector: 'ion-input-otp',