From 2ce7a8aa10a200b87c48f55883028ba9afe61426 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 03:42:54 +0200
Subject: [PATCH 01/17] feat: otp field initial implementation

---
 packages/core/src/constants/index.ts          |   2 +
 packages/core/src/index.ts                    |   1 +
 packages/core/src/useCalendar/useCalendar.ts  |   2 +-
 .../src/useDateTimeField/useDateTimeField.ts  |   2 +-
 packages/core/src/useOtpField/index.ts        |   2 +
 packages/core/src/useOtpField/types.ts        |  16 ++
 packages/core/src/useOtpField/useOtpField.ts  | 270 ++++++++++++++++++
 packages/core/src/useOtpField/useOtpSlot.ts   | 172 +++++++++++
 packages/core/src/useSelect/useSelect.ts      |   2 +-
 packages/core/src/validation/index.ts         |   1 +
 ...alidator.ts => useConstraintsValidator.ts} |   0
 .../validation/useContraintsValidator.spec.ts |   2 +-
 packages/playground/src/App.vue               |   8 +-
 .../playground/src/components/OtpField.vue    |  45 +++
 14 files changed, 515 insertions(+), 10 deletions(-)
 create mode 100644 packages/core/src/useOtpField/index.ts
 create mode 100644 packages/core/src/useOtpField/types.ts
 create mode 100644 packages/core/src/useOtpField/useOtpField.ts
 create mode 100644 packages/core/src/useOtpField/useOtpSlot.ts
 rename packages/core/src/validation/{useContraintsValidator.ts => useConstraintsValidator.ts} (100%)
 create mode 100644 packages/playground/src/components/OtpField.vue

diff --git a/packages/core/src/constants/index.ts b/packages/core/src/constants/index.ts
index a9bd4442..b0034a2d 100644
--- a/packages/core/src/constants/index.ts
+++ b/packages/core/src/constants/index.ts
@@ -21,6 +21,8 @@ export const FieldTypePrefixes = {
   DateTimeField: 'dtf',
   DateTimeSegment: 'dts',
   Calendar: 'cal',
+  OTPField: 'otp',
+  OTPSlot: 'otps',
 } as const;
 
 export const NOOP = () => {};
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index a65fa1aa..95430042 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -13,6 +13,7 @@ export * from './useSelect';
 export * from './useComboBox';
 export * from './useHiddenField';
 export * from './useCustomField';
+export * from './useOtpField';
 export * from './useDateTimeField';
 export * from './useCalendar';
 export * from './usePicker';
diff --git a/packages/core/src/useCalendar/useCalendar.ts b/packages/core/src/useCalendar/useCalendar.ts
index 3295ac84..90bedd44 100644
--- a/packages/core/src/useCalendar/useCalendar.ts
+++ b/packages/core/src/useCalendar/useCalendar.ts
@@ -16,7 +16,7 @@ import { useInputValidity } from '../validation';
 import { fromDateToCalendarZonedDateTime, useTemporalStore } from '../useDateTimeField/useTemporalStore';
 import { PickerContextKey } from '../usePicker';
 import { registerField } from '@formwerk/devtools';
-import { useConstraintsValidator } from '../validation/useContraintsValidator';
+import { useConstraintsValidator } from '../validation/useConstraintsValidator';
 
 export interface CalendarProps {
   /**
diff --git a/packages/core/src/useDateTimeField/useDateTimeField.ts b/packages/core/src/useDateTimeField/useDateTimeField.ts
index 67e84261..7da2b9ee 100644
--- a/packages/core/src/useDateTimeField/useDateTimeField.ts
+++ b/packages/core/src/useDateTimeField/useDateTimeField.ts
@@ -12,7 +12,7 @@ import { ZonedDateTime, Calendar } from '@internationalized/date';
 import { useInputValidity } from '../validation';
 import { createDisabledContext } from '../helpers/createDisabledContext';
 import { registerField } from '@formwerk/devtools';
-import { useConstraintsValidator } from '../validation/useContraintsValidator';
+import { useConstraintsValidator } from '../validation/useConstraintsValidator';
 
 export interface DateTimeFieldProps {
   /**
diff --git a/packages/core/src/useOtpField/index.ts b/packages/core/src/useOtpField/index.ts
new file mode 100644
index 00000000..0f0c1e4a
--- /dev/null
+++ b/packages/core/src/useOtpField/index.ts
@@ -0,0 +1,2 @@
+export * from './useOtpField';
+export * from './useOtpSlot';
diff --git a/packages/core/src/useOtpField/types.ts b/packages/core/src/useOtpField/types.ts
new file mode 100644
index 00000000..6631744e
--- /dev/null
+++ b/packages/core/src/useOtpField/types.ts
@@ -0,0 +1,16 @@
+import { InjectionKey } from 'vue';
+
+export type OtpSlotAcceptType = 'all' | 'numeric' | 'alphanumeric';
+
+export interface OtpSlotRegistration {
+  id: string;
+  focusNext(): void;
+  focusPrevious(): void;
+  setValue(value: string): void;
+}
+
+export interface OtpContext {
+  useSlotRegistration(slot: { focus: () => void }): OtpSlotRegistration;
+}
+
+export const OtpContextKey: InjectionKey<OtpContext> = Symbol('otp-context');
diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
new file mode 100644
index 00000000..41f87104
--- /dev/null
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -0,0 +1,270 @@
+import { computed, provide, ref, toValue } from 'vue';
+import { Reactivify, StandardSchema } from '../types';
+import { OtpContextKey, OtpSlotAcceptType } from './types';
+import { createDescribedByProps, normalizeProps, useUniqId, withRefCapture } from '../utils/common';
+import { FieldTypePrefixes } from '../constants';
+import { useErrorMessage, useLabel } from '../a11y';
+import { exposeField, useFormField } from '../useFormField';
+import { useInputValidity, useConstraintsValidator } from '../validation';
+import { OtpSlotProps } from './useOtpSlot';
+import { createDisabledContext } from '../helpers/createDisabledContext';
+import { registerField } from '@formwerk/devtools';
+
+export interface OTPFieldProps {
+  /**
+   * The label of the OTP field.
+   */
+  label: string;
+
+  /**
+   * The name of the OTP field.
+   */
+  name?: string;
+
+  /**
+   * The model value of the OTP field.
+   */
+  modelValue?: string;
+
+  /**
+   * The initial value of the OTP field.
+   */
+  value?: string;
+
+  /**
+   * Whether the OTP field is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the OTP field is readonly.
+   */
+  readonly?: boolean;
+
+  /**
+   * Whether the OTP field is required.
+   */
+  required?: boolean;
+
+  /**
+   * The length of the OTP field characters.
+   */
+  length?: number;
+
+  /**
+   * The type of the OTP field characters.
+   */
+  accept?: OtpSlotAcceptType;
+
+  /**
+   * The description of the OTP field.
+   */
+  description?: string;
+
+  /**
+   * Schema for field validation.
+   */
+  schema?: StandardSchema<string>;
+
+  /**
+   * Whether to disable HTML validation.
+   */
+  disableHtmlValidation?: boolean;
+
+  /**
+   * The prefix of the OTP field. If you prefix your codes with a character, you can set it here (e.g "G-").
+   */
+  prefix?: string;
+}
+
+export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
+  const props = normalizeProps(_props, ['schema']);
+  const controlEl = ref<HTMLElement>();
+  const id = useUniqId(FieldTypePrefixes.OTPField);
+  const isDisabled = createDisabledContext(props.disabled);
+
+  function withPrefix(value: string | undefined) {
+    const prefix = toValue(props.prefix);
+    if (!prefix) {
+      return value;
+    }
+
+    value = value ?? '';
+    if (value.startsWith(prefix)) {
+      return value;
+    }
+
+    return `${prefix}${value}`;
+  }
+
+  function getRequiredLength() {
+    const prefix = toValue(props.prefix) || '';
+    const length = toValue(props.length) ?? 0;
+
+    return prefix.length + length;
+  }
+
+  const field = useFormField<string>({
+    path: props.name,
+    initialValue: withPrefix(toValue(props.modelValue) ?? toValue(props.value)),
+    disabled: props.disabled,
+    schema: props.schema,
+  });
+
+  const inputsState = ref<string[]>(field.fieldValue.value?.split('') ?? []);
+
+  const { element: inputEl } = useConstraintsValidator({
+    type: 'text',
+    maxLength: getRequiredLength(),
+    minLength: getRequiredLength(),
+    required: props.required,
+    value: () => (field.fieldValue.value?.length === getRequiredLength() ? field.fieldValue.value : ''),
+    source: controlEl,
+  });
+
+  const { validityDetails } = useInputValidity({
+    inputEl,
+    field,
+    disableHtmlValidation: props.disableHtmlValidation,
+  });
+
+  const { descriptionProps, describedByProps } = createDescribedByProps({
+    inputId: id,
+    description: props.description,
+  });
+
+  const { labelProps, labelledByProps } = useLabel({
+    label: props.label,
+    targetRef: controlEl,
+    for: id,
+  });
+
+  const { errorMessageProps, accessibleErrorProps } = useErrorMessage({
+    inputId: id,
+    errorMessage: field.errorMessage,
+  });
+
+  const controlProps = computed(() => {
+    return withRefCapture(
+      {
+        id,
+        role: 'group',
+        ...labelledByProps.value,
+        ...describedByProps.value,
+        ...accessibleErrorProps.value,
+      },
+      controlEl,
+    );
+  });
+
+  function createFocusHandler(direction: 'next' | 'previous') {
+    return () => {
+      if (!controlEl.value) {
+        return;
+      }
+
+      const slots = Array.from(controlEl.value.querySelectorAll('[data-otp-slot][tabindex="0"]')) as HTMLElement[];
+      const currentSlot = controlEl.value.querySelector('[data-otp-slot]:focus') as HTMLElement | null;
+      if (!currentSlot) {
+        slots[0]?.focus();
+        return;
+      }
+
+      const currentIndex = slots.indexOf(currentSlot);
+      if (currentIndex === -1) {
+        slots[0]?.focus();
+        return;
+      }
+
+      const nextSlot = slots[currentIndex + (direction === 'next' ? 1 : -1)];
+      nextSlot?.focus();
+    };
+  }
+
+  const focusNext = createFocusHandler('next');
+  const focusPrevious = createFocusHandler('previous');
+
+  const fieldSlots = computed<OtpSlotProps[]>(() => {
+    const prefix = toValue(props.prefix) || '';
+    const length = prefix.length + (toValue(props.length) ?? 0);
+
+    return Array.from({ length }, (_, index) => ({
+      value: inputsState.value[index] ?? '',
+      disabled: prefix.length ? prefix.length > index : isDisabled.value,
+      readonly: toValue(props.readonly),
+      accept: toValue(props.accept),
+    }));
+  });
+
+  function getActiveSlotIndex() {
+    const slots = Array.from(controlEl.value?.querySelectorAll('[data-otp-slot]') ?? []) as HTMLElement[];
+    const currentSlot = controlEl.value?.querySelector('[data-otp-slot]:focus') as HTMLElement | null;
+    if (!currentSlot) {
+      return -1;
+    }
+
+    return slots.indexOf(currentSlot);
+  }
+
+  provide(OtpContextKey, {
+    useSlotRegistration() {
+      const slotId = useUniqId(FieldTypePrefixes.OTPSlot);
+
+      return {
+        id: slotId,
+        focusNext,
+        focusPrevious,
+        setValue: (value: string) => {
+          const index = getActiveSlotIndex();
+          if (index === -1) {
+            return;
+          }
+
+          inputsState.value[index] = value;
+          const nextValue = withPrefix(inputsState.value.join(''));
+
+          field.setValue(nextValue?.length === getRequiredLength() ? nextValue : withPrefix(''));
+        },
+      };
+    },
+  });
+
+  if (__DEV__) {
+    registerField(field, 'OTP');
+  }
+
+  return exposeField(
+    {
+      /**
+       * The props of the control element.
+       */
+      controlProps,
+
+      /**
+       * The props of the label element.
+       */
+      labelProps,
+
+      /**
+       * The props of the description element.
+       */
+      descriptionProps,
+
+      /**
+       * The validity details of the OTP field.
+       */
+      validityDetails,
+
+      /**
+       * The slots of the OTP field. Use this as an iterable to render with `v-for`.
+       */
+      fieldSlots,
+
+      /**
+       * The props of the error message element.
+       */
+      errorMessageProps,
+    },
+    field,
+  );
+}
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
new file mode 100644
index 00000000..64e3f479
--- /dev/null
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -0,0 +1,172 @@
+import { computed, defineComponent, h, inject, ref, toValue } from 'vue';
+import { Reactivify } from '../types';
+import { hasKeyCode, isInputElement, normalizeProps, warn, withRefCapture } from '../utils/common';
+import { isFirefox } from '../utils/platform';
+import { blockEvent } from '../utils/events';
+import { OtpContextKey, OtpSlotAcceptType } from './types';
+import { createDisabledContext } from '../helpers/createDisabledContext';
+
+export interface OtpSlotProps {
+  /**
+   * The value of the slot.
+   */
+  value: string;
+
+  /**
+   * Whether the slot is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the slot is readonly.
+   */
+  readonly?: boolean;
+
+  /**
+   * The type of the slot.
+   */
+  accept?: OtpSlotAcceptType;
+}
+
+export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
+  const props = normalizeProps(_props);
+  const slotEl = ref<HTMLElement>();
+  const isDisabled = createDisabledContext(props.disabled);
+
+  const acceptMapRegex: Record<OtpSlotAcceptType, RegExp> = {
+    all: /./,
+    numeric: /^\d+$/,
+    alphanumeric: /^[a-zA-Z0-9]+$/,
+  };
+
+  const context = inject(OtpContextKey, {
+    useSlotRegistration() {
+      return {
+        id: '',
+        focusNext: () => {},
+        focusPrevious: () => {},
+        setValue: () => {},
+      };
+    },
+  });
+
+  const { focusNext, focusPrevious, setValue, id } = context.useSlotRegistration({
+    focus() {
+      slotEl.value?.focus();
+    },
+  });
+
+  if (!context) {
+    if (__DEV__) {
+      warn('OtpSlot must be used within an OtpField');
+    }
+  }
+
+  function setElementValue(value: string) {
+    if (!slotEl.value) {
+      return;
+    }
+
+    setValue(value);
+    if (isInputElement(slotEl.value)) {
+      slotEl.value.value = value;
+      return;
+    }
+
+    slotEl.value.textContent = value;
+  }
+
+  const handlers = {
+    onKeydown(e: KeyboardEvent) {
+      if (hasKeyCode(e, 'Backspace') || hasKeyCode(e, 'Delete')) {
+        blockEvent(e);
+        setElementValue('');
+        focusPrevious();
+        return;
+      }
+
+      if (hasKeyCode(e, 'Enter')) {
+        blockEvent(e);
+        focusNext();
+        return;
+      }
+
+      if (hasKeyCode(e, 'ArrowLeft')) {
+        blockEvent(e);
+        focusPrevious();
+        return;
+      }
+
+      if (hasKeyCode(e, 'ArrowRight')) {
+        blockEvent(e);
+        focusNext();
+        return;
+      }
+    },
+    onBeforeinput(e: InputEvent) {
+      // Ignores non printable keys
+      if (!e.data) {
+        return;
+      }
+
+      const re = acceptMapRegex[toValue(props.accept) || 'all'];
+
+      blockEvent(e);
+      if (re.test(e.data)) {
+        setElementValue(e.data);
+        focusNext();
+      }
+    },
+  };
+
+  const slotProps = computed(() => {
+    const isInput = isInputElement(slotEl.value);
+
+    const baseProps: Record<string, unknown> = {
+      [isInput ? 'readonly' : 'aria-readonly']: toValue(props.readonly),
+      [isInput ? 'disabled' : 'aria-disabled']: toValue(props.disabled),
+      'data-otp-slot': true,
+      spellcheck: false,
+      tabindex: isDisabled.value ? '-1' : '0',
+      autocorrect: 'off',
+      autocapitalize: 'off',
+      // TODO: Should be either done or next depending on if it's the last slot
+      enterkeyhint: 'next',
+      ...handlers,
+      style: {
+        caretColor: 'transparent',
+      },
+    };
+
+    if (toValue(props.accept) === 'numeric') {
+      baseProps.inputmode = 'numeric';
+    }
+
+    if (!isInput) {
+      baseProps.contenteditable = isDisabled.value ? 'false' : isFirefox() ? 'true' : 'plaintext-only';
+    } else {
+      baseProps.value = toValue(props.value);
+    }
+
+    return withRefCapture(baseProps, slotEl);
+  });
+
+  return {
+    slotProps,
+    key: id,
+    value: computed(() => toValue(props.value)),
+  };
+}
+
+/**
+ * A helper component that renders an OTP slot. You can build your own with `useOtpSlot`.
+ */
+export const OtpSlot = /*#__PURE__*/ defineComponent<OtpSlotProps>({
+  name: 'OtpSlot',
+  props: ['value', 'disabled', 'readonly', 'accept'],
+  setup(props) {
+    const { slotProps, value, key } = useOtpSlot(props);
+
+    return () => h('span', { ...slotProps.value, key }, value.value);
+  },
+});
diff --git a/packages/core/src/useSelect/useSelect.ts b/packages/core/src/useSelect/useSelect.ts
index 3eb0fc6a..ee97177e 100644
--- a/packages/core/src/useSelect/useSelect.ts
+++ b/packages/core/src/useSelect/useSelect.ts
@@ -15,7 +15,7 @@ import { useListBox } from '../useListBox';
 import { useLabel, useErrorMessage } from '../a11y';
 import { FieldTypePrefixes } from '../constants';
 import { registerField } from '@formwerk/devtools';
-import { useConstraintsValidator } from '../validation/useContraintsValidator';
+import { useConstraintsValidator } from '../validation/useConstraintsValidator';
 
 export interface SelectProps<TOption, TValue = TOption> {
   /**
diff --git a/packages/core/src/validation/index.ts b/packages/core/src/validation/index.ts
index aa92e539..8f02b596 100644
--- a/packages/core/src/validation/index.ts
+++ b/packages/core/src/validation/index.ts
@@ -1 +1,2 @@
+export * from './useConstraintsValidator';
 export * from './useInputValidity';
diff --git a/packages/core/src/validation/useContraintsValidator.ts b/packages/core/src/validation/useConstraintsValidator.ts
similarity index 100%
rename from packages/core/src/validation/useContraintsValidator.ts
rename to packages/core/src/validation/useConstraintsValidator.ts
diff --git a/packages/core/src/validation/useContraintsValidator.spec.ts b/packages/core/src/validation/useContraintsValidator.spec.ts
index bebb2232..ed84da96 100644
--- a/packages/core/src/validation/useContraintsValidator.spec.ts
+++ b/packages/core/src/validation/useContraintsValidator.spec.ts
@@ -1,5 +1,5 @@
 import { nextTick, onMounted, ref } from 'vue';
-import { useConstraintsValidator } from './useContraintsValidator';
+import { useConstraintsValidator } from './useConstraintsValidator';
 import { fireEvent, render, screen } from '@testing-library/vue';
 import { renderSetup } from '@test-utils/index';
 
diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index f5e2911f..5ffc02c4 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -1,11 +1,7 @@
 <script setup lang="ts">
-import DateField from '@/components/DateField.vue';
-
-const min = new Date(2025, 0, 4, 0, 0, 0, 0);
-const value = new Date('2025-01-15');
-const max = new Date('2025-01-20');
+import OtpField from '@/components/OtpField.vue';
 </script>
 
 <template>
-  <DateField name="birthdate" label="Birth Date" />
+  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required />
 </template>
diff --git a/packages/playground/src/components/OtpField.vue b/packages/playground/src/components/OtpField.vue
new file mode 100644
index 00000000..ab86cd23
--- /dev/null
+++ b/packages/playground/src/components/OtpField.vue
@@ -0,0 +1,45 @@
+<template>
+  <div class="OTP">
+    <div class="label" v-bind="labelProps">{{ label }}</div>
+
+    <div class="control" v-bind="controlProps">
+      <OtpSlot v-for="slot in fieldSlots" v-bind="slot" />
+    </div>
+
+    <span v-bind="errorMessageProps" class="w-full truncate error-message">
+      {{ errorMessage }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useOtpField, OTPFieldProps, OtpSlot } from '@formwerk/core';
+
+const props = defineProps<OTPFieldProps>();
+
+const { controlProps, labelProps, errorMessage, errorMessageProps, fieldSlots } = useOtpField(props);
+</script>
+
+<style scoped>
+@reference "../style.css";
+
+.OTP {
+  @apply flex flex-col gap-2;
+
+  .label {
+    @apply text-lg font-semibold text-white;
+  }
+
+  [data-otp-slot] {
+    @apply w-10 h-10 rounded-md border-2 border-zinc-700 bg-zinc-800 text-white font-medium text-2xl text-center;
+
+    &[aria-disabled='true'] {
+      @apply bg-zinc-700 opacity-50;
+    }
+  }
+
+  .control {
+    @apply flex gap-2;
+  }
+}
+</style>

From b0552bc6be8a1a75d433d708afaa352d02228097 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 03:53:02 +0200
Subject: [PATCH 02/17] feat: implement masked prop

---
 packages/core/src/useOtpField/useOtpField.ts |  6 ++++++
 packages/core/src/useOtpField/useOtpSlot.ts  | 20 +++++++++++++++++---
 packages/playground/src/App.vue              |  2 +-
 3 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 41f87104..341db0e4 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -36,6 +36,11 @@ export interface OTPFieldProps {
    */
   disabled?: boolean;
 
+  /**
+   * Whether the OTP field is masked.
+   */
+  masked?: boolean;
+
   /**
    * Whether the OTP field is readonly.
    */
@@ -193,6 +198,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
       disabled: prefix.length ? prefix.length > index : isDisabled.value,
       readonly: toValue(props.readonly),
       accept: toValue(props.accept),
+      masked: prefix.length <= index && toValue(props.masked),
     }));
   });
 
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index 64e3f479..dc55407a 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -22,6 +22,11 @@ export interface OtpSlotProps {
    */
   readonly?: boolean;
 
+  /**
+   * Whether the slot is masked.
+   */
+  masked?: boolean;
+
   /**
    * The type of the slot.
    */
@@ -62,6 +67,14 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
     }
   }
 
+  function withMask(value: string | undefined) {
+    if (!toValue(props.masked) || !value) {
+      return value ?? '';
+    }
+
+    return '•'.repeat(value.length);
+  }
+
   function setElementValue(value: string) {
     if (!slotEl.value) {
       return;
@@ -73,7 +86,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       return;
     }
 
-    slotEl.value.textContent = value;
+    slotEl.value.textContent = withMask(value);
   }
 
   const handlers = {
@@ -146,6 +159,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       baseProps.contenteditable = isDisabled.value ? 'false' : isFirefox() ? 'true' : 'plaintext-only';
     } else {
       baseProps.value = toValue(props.value);
+      baseProps.type = toValue(props.masked) ? 'password' : 'text';
     }
 
     return withRefCapture(baseProps, slotEl);
@@ -154,7 +168,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
   return {
     slotProps,
     key: id,
-    value: computed(() => toValue(props.value)),
+    value: computed(() => withMask(toValue(props.value))),
   };
 }
 
@@ -163,7 +177,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
  */
 export const OtpSlot = /*#__PURE__*/ defineComponent<OtpSlotProps>({
   name: 'OtpSlot',
-  props: ['value', 'disabled', 'readonly', 'accept'],
+  props: ['value', 'disabled', 'readonly', 'accept', 'masked'],
   setup(props) {
     const { slotProps, value, key } = useOtpSlot(props);
 
diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index 5ffc02c4..bb836a49 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -3,5 +3,5 @@ import OtpField from '@/components/OtpField.vue';
 </script>
 
 <template>
-  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required />
+  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required masked />
 </template>

From 42fa4b0478e581029fc949433897aacf653df9aa Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 04:01:04 +0200
Subject: [PATCH 03/17] feat: added onCompleted callback

---
 packages/core/src/useOtpField/useOtpField.ts | 40 +++++++++++++++-----
 packages/playground/src/App.vue              |  9 ++++-
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 341db0e4..5e3a207e 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -1,5 +1,5 @@
-import { computed, provide, ref, toValue } from 'vue';
-import { Reactivify, StandardSchema } from '../types';
+import { computed, provide, ref, toValue, watch } from 'vue';
+import { MaybeAsync, Reactivify, StandardSchema } from '../types';
 import { OtpContextKey, OtpSlotAcceptType } from './types';
 import { createDescribedByProps, normalizeProps, useUniqId, withRefCapture } from '../utils/common';
 import { FieldTypePrefixes } from '../constants';
@@ -80,10 +80,15 @@ export interface OTPFieldProps {
    * The prefix of the OTP field. If you prefix your codes with a character, you can set it here (e.g "G-").
    */
   prefix?: string;
+
+  /**
+   * The callback function that is called when the OTP field is completed.
+   */
+  onCompleted?: (value: string) => MaybeAsync<void>;
 }
 
-export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
-  const props = normalizeProps(_props, ['schema']);
+export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onCompleted'>) {
+  const props = normalizeProps(_props, ['schema', 'onCompleted']);
   const controlEl = ref<HTMLElement>();
   const id = useUniqId(FieldTypePrefixes.OTPField);
   const isDisabled = createDisabledContext(props.disabled);
@@ -91,7 +96,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
   function withPrefix(value: string | undefined) {
     const prefix = toValue(props.prefix);
     if (!prefix) {
-      return value;
+      return value ?? '';
     }
 
     value = value ?? '';
@@ -116,7 +121,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
     schema: props.schema,
   });
 
-  const inputsState = ref<string[]>(field.fieldValue.value?.split('') ?? []);
+  const inputsState = ref<string[]>(withPrefix(toValue(props.modelValue) ?? toValue(props.value)).split(''));
 
   const { element: inputEl } = useConstraintsValidator({
     type: 'text',
@@ -212,6 +217,20 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
     return slots.indexOf(currentSlot);
   }
 
+  watch(field.fieldValue, value => {
+    if (!value) {
+      inputsState.value = withPrefix('').split('');
+      return;
+    }
+
+    const expected = withPrefix(inputsState.value.join(''));
+    if (expected === value) {
+      return;
+    }
+
+    inputsState.value = value.split('');
+  });
+
   provide(OtpContextKey, {
     useSlotRegistration() {
       const slotId = useUniqId(FieldTypePrefixes.OTPSlot);
@@ -227,9 +246,12 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema'>) {
           }
 
           inputsState.value[index] = value;
-          const nextValue = withPrefix(inputsState.value.join(''));
-
-          field.setValue(nextValue?.length === getRequiredLength() ? nextValue : withPrefix(''));
+          const nextValue = inputsState.value.join('');
+          const isCompleted = nextValue?.length === getRequiredLength();
+          field.setValue(nextValue);
+          if (isCompleted) {
+            props.onCompleted?.(nextValue);
+          }
         },
       };
     },
diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index bb836a49..c7f0e88b 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -1,7 +1,14 @@
 <script setup lang="ts">
 import OtpField from '@/components/OtpField.vue';
+import { useForm } from '@formwerk/core';
+const form = useForm();
+
+function onCompleted(value: string) {
+  console.log('onCompleted', value);
+}
 </script>
 
 <template>
-  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required masked />
+  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required @completed="onCompleted" />
+  <button @click="form.setValue('otp', 'G-4321')">Set OTP</button>
 </template>

From b9b75cacbbd61dfc46a4897ef7f2e40bfaa80df8 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 15:52:22 +0200
Subject: [PATCH 04/17] feat: handle paste

---
 packages/core/src/useOtpField/types.ts       |  1 +
 packages/core/src/useOtpField/useOtpField.ts | 64 ++++++++++++++++++--
 packages/core/src/useOtpField/useOtpSlot.ts  | 17 +++---
 packages/core/src/useOtpField/utils.ts       | 13 ++++
 4 files changed, 79 insertions(+), 16 deletions(-)
 create mode 100644 packages/core/src/useOtpField/utils.ts

diff --git a/packages/core/src/useOtpField/types.ts b/packages/core/src/useOtpField/types.ts
index 6631744e..7492f58b 100644
--- a/packages/core/src/useOtpField/types.ts
+++ b/packages/core/src/useOtpField/types.ts
@@ -7,6 +7,7 @@ export interface OtpSlotRegistration {
   focusNext(): void;
   focusPrevious(): void;
   setValue(value: string): void;
+  handlePaste(event: ClipboardEvent): void;
 }
 
 export interface OtpContext {
diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 5e3a207e..8848fa5d 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -9,6 +9,8 @@ import { useInputValidity, useConstraintsValidator } from '../validation';
 import { OtpSlotProps } from './useOtpSlot';
 import { createDisabledContext } from '../helpers/createDisabledContext';
 import { registerField } from '@formwerk/devtools';
+import { isValueAccepted } from './utils';
+import { blockEvent } from '../utils/events';
 
 export interface OTPFieldProps {
   /**
@@ -231,6 +233,60 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
     inputsState.value = value.split('');
   });
 
+  function onPaste(event: ClipboardEvent) {
+    const text = event.clipboardData?.getData('text/plain') || '';
+    blockEvent(event);
+    if (!text.length) {
+      return;
+    }
+
+    if (!isValueAccepted(text, toValue(props.accept) || 'all')) {
+      return;
+    }
+
+    const prefixed = withPrefix(text).split('');
+    if (prefixed.length === getRequiredLength()) {
+      prefixed.forEach((value, index) => {
+        inputsState.value[index] = value;
+      });
+
+      updateFieldValue();
+      return;
+    }
+
+    const currentIndex = getActiveSlotIndex();
+    if (currentIndex === -1) {
+      return;
+    }
+
+    // Fill input states starting from the active index
+    const prefixLength = (toValue(props.prefix) || '').length;
+    const maxLength = getRequiredLength();
+    const availableSlots = maxLength - currentIndex;
+
+    // Only take characters that can fit in the remaining slots
+    const textToFill = text.slice(0, availableSlots);
+
+    // Skip prefix slots if we're pasting into a position after the prefix
+    if (currentIndex >= prefixLength) {
+      for (let i = 0; i < textToFill.length; i++) {
+        const char = textToFill[i];
+        inputsState.value[currentIndex + i] = char;
+      }
+    }
+
+    updateFieldValue();
+  }
+
+  function updateFieldValue() {
+    const nextValue = inputsState.value.join('');
+    const isCompleted = nextValue?.length === getRequiredLength();
+    field.setValue(nextValue);
+    if (isCompleted) {
+      props.onCompleted?.(nextValue);
+    }
+  }
+
   provide(OtpContextKey, {
     useSlotRegistration() {
       const slotId = useUniqId(FieldTypePrefixes.OTPSlot);
@@ -239,6 +295,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
         id: slotId,
         focusNext,
         focusPrevious,
+        handlePaste: onPaste,
         setValue: (value: string) => {
           const index = getActiveSlotIndex();
           if (index === -1) {
@@ -246,12 +303,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
           }
 
           inputsState.value[index] = value;
-          const nextValue = inputsState.value.join('');
-          const isCompleted = nextValue?.length === getRequiredLength();
-          field.setValue(nextValue);
-          if (isCompleted) {
-            props.onCompleted?.(nextValue);
-          }
+          updateFieldValue();
         },
       };
     },
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index dc55407a..d31c73ed 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -5,6 +5,7 @@ import { isFirefox } from '../utils/platform';
 import { blockEvent } from '../utils/events';
 import { OtpContextKey, OtpSlotAcceptType } from './types';
 import { createDisabledContext } from '../helpers/createDisabledContext';
+import { isValueAccepted } from './utils';
 
 export interface OtpSlotProps {
   /**
@@ -38,12 +39,6 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
   const slotEl = ref<HTMLElement>();
   const isDisabled = createDisabledContext(props.disabled);
 
-  const acceptMapRegex: Record<OtpSlotAcceptType, RegExp> = {
-    all: /./,
-    numeric: /^\d+$/,
-    alphanumeric: /^[a-zA-Z0-9]+$/,
-  };
-
   const context = inject(OtpContextKey, {
     useSlotRegistration() {
       return {
@@ -51,11 +46,12 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
         focusNext: () => {},
         focusPrevious: () => {},
         setValue: () => {},
+        handlePaste: () => {},
       };
     },
   });
 
-  const { focusNext, focusPrevious, setValue, id } = context.useSlotRegistration({
+  const { focusNext, focusPrevious, setValue, id, handlePaste } = context.useSlotRegistration({
     focus() {
       slotEl.value?.focus();
     },
@@ -90,6 +86,9 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
   }
 
   const handlers = {
+    onPaste(e: ClipboardEvent) {
+      handlePaste(e);
+    },
     onKeydown(e: KeyboardEvent) {
       if (hasKeyCode(e, 'Backspace') || hasKeyCode(e, 'Delete')) {
         blockEvent(e);
@@ -122,10 +121,8 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
         return;
       }
 
-      const re = acceptMapRegex[toValue(props.accept) || 'all'];
-
       blockEvent(e);
-      if (re.test(e.data)) {
+      if (isValueAccepted(e.data, toValue(props.accept) || 'all')) {
         setElementValue(e.data);
         focusNext();
       }
diff --git a/packages/core/src/useOtpField/utils.ts b/packages/core/src/useOtpField/utils.ts
new file mode 100644
index 00000000..8e80a56d
--- /dev/null
+++ b/packages/core/src/useOtpField/utils.ts
@@ -0,0 +1,13 @@
+import { OtpSlotAcceptType } from './types';
+
+const acceptMapRegex: Record<OtpSlotAcceptType, RegExp> = {
+  all: /./,
+  numeric: /^\d+$/,
+  alphanumeric: /^[a-zA-Z0-9]+$/,
+};
+
+export function isValueAccepted(value: string, accept: OtpSlotAcceptType) {
+  const regex = acceptMapRegex[accept];
+
+  return regex.test(value);
+}

From c8265ed6d020521793c818f4668986f49aed62d3 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 16:44:41 +0200
Subject: [PATCH 05/17] fix: add autocomplete off

---
 packages/core/src/useDateTimeField/useDateTimeSegment.ts | 2 ++
 packages/core/src/useOtpField/useOtpSlot.ts              | 4 ++++
 2 files changed, 6 insertions(+)

diff --git a/packages/core/src/useDateTimeField/useDateTimeSegment.ts b/packages/core/src/useDateTimeField/useDateTimeSegment.ts
index de3b502f..89b2be12 100644
--- a/packages/core/src/useDateTimeField/useDateTimeSegment.ts
+++ b/packages/core/src/useDateTimeField/useDateTimeSegment.ts
@@ -45,6 +45,7 @@ interface DateTimeSegmentDomProps {
   inputmode?: string;
   autocorrect?: string;
   enterkeyhint?: string;
+  autocomplete?: string;
   'aria-valuemin'?: number;
   'aria-valuemax'?: number;
   'aria-valuenow'?: number;
@@ -207,6 +208,7 @@ export function useDateTimeSegment(_props: Reactivify<DateTimeSegmentProps>) {
       'aria-label': isNonEditable() ? undefined : toValue(props.type),
       'aria-readonly': toValue(props.readonly) ? true : undefined,
       autocorrect: isNonEditable() ? undefined : 'off',
+      autocomplete: isNonEditable() ? undefined : 'off',
       spellcheck: isNonEditable() ? undefined : false,
       enterkeyhint: isNonEditable() ? undefined : isLast() ? 'done' : 'next',
       inputmode: 'none',
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index d31c73ed..bda902a2 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -139,6 +139,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       spellcheck: false,
       tabindex: isDisabled.value ? '-1' : '0',
       autocorrect: 'off',
+      autocomplete: 'off',
       autocapitalize: 'off',
       // TODO: Should be either done or next depending on if it's the last slot
       enterkeyhint: 'next',
@@ -153,6 +154,9 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
     }
 
     if (!isInput) {
+      baseProps['aria-role'] = 'textbox';
+      baseProps['aria-label'] = toValue(props.value) || 'Enter a character';
+      baseProps['aria-multiline'] = 'false';
       baseProps.contenteditable = isDisabled.value ? 'false' : isFirefox() ? 'true' : 'plaintext-only';
     } else {
       baseProps.value = toValue(props.value);

From 60719f2d1872531b664b5e17522b853403fb6142 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 16:45:54 +0200
Subject: [PATCH 06/17] fix: emit complete event on next tick

---
 packages/core/src/useOtpField/useOtpField.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 8848fa5d..529618b2 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -1,4 +1,4 @@
-import { computed, provide, ref, toValue, watch } from 'vue';
+import { computed, nextTick, provide, ref, toValue, watch } from 'vue';
 import { MaybeAsync, Reactivify, StandardSchema } from '../types';
 import { OtpContextKey, OtpSlotAcceptType } from './types';
 import { createDescribedByProps, normalizeProps, useUniqId, withRefCapture } from '../utils/common';
@@ -283,7 +283,9 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
     const isCompleted = nextValue?.length === getRequiredLength();
     field.setValue(nextValue);
     if (isCompleted) {
-      props.onCompleted?.(nextValue);
+      nextTick(() => {
+        props.onCompleted?.(nextValue);
+      });
     }
   }
 

From 8639550a2d1f2d6869f47b52fac3e7d0d14057e8 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 16:46:12 +0200
Subject: [PATCH 07/17] chore: playground stuff

---
 packages/playground/src/App.vue               |  9 +++++---
 .../playground/src/components/OtpField.vue    |  4 ++--
 .../playground/src/components/OtpSlot.vue     | 23 +++++++++++++++++++
 3 files changed, 31 insertions(+), 5 deletions(-)
 create mode 100644 packages/playground/src/components/OtpSlot.vue

diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index c7f0e88b..2fdbdaff 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -4,11 +4,14 @@ import { useForm } from '@formwerk/core';
 const form = useForm();
 
 function onCompleted(value: string) {
-  console.log('onCompleted', value);
+  alert(`onCompleted: ${value}`);
 }
 </script>
 
 <template>
-  <OtpField name="otp" label="OTP" :length="4" accept="numeric" prefix="G-" required @completed="onCompleted" />
-  <button @click="form.setValue('otp', 'G-4321')">Set OTP</button>
+  <OtpField name="otp" label="OTP" :length="6" prefix="G-" masked @completed="onCompleted" />
+
+  <div class="flex w-full">
+    <button @click="form.setValue('otp', 'G-4321')">Set OTP</button>
+  </div>
 </template>
diff --git a/packages/playground/src/components/OtpField.vue b/packages/playground/src/components/OtpField.vue
index ab86cd23..efbd4afe 100644
--- a/packages/playground/src/components/OtpField.vue
+++ b/packages/playground/src/components/OtpField.vue
@@ -13,8 +13,8 @@
 </template>
 
 <script setup lang="ts">
-import { useOtpField, OTPFieldProps, OtpSlot } from '@formwerk/core';
-
+import { useOtpField, OTPFieldProps } from '@formwerk/core';
+import OtpSlot from './OtpSlot.vue';
 const props = defineProps<OTPFieldProps>();
 
 const { controlProps, labelProps, errorMessage, errorMessageProps, fieldSlots } = useOtpField(props);
diff --git a/packages/playground/src/components/OtpSlot.vue b/packages/playground/src/components/OtpSlot.vue
new file mode 100644
index 00000000..8efe5a44
--- /dev/null
+++ b/packages/playground/src/components/OtpSlot.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { OtpSlotProps, useOtpSlot } from '@formwerk/core';
+
+const props = defineProps<OtpSlotProps>();
+
+const { slotProps } = useOtpSlot(props);
+</script>
+
+<template>
+  <input v-bind="slotProps" class="otp-slot" />
+</template>
+
+<style scoped>
+@reference "../style.css";
+
+.otp-slot {
+  @apply w-10 h-10 rounded-md border-2 border-zinc-700 bg-red-500 text-white font-medium text-2xl text-center;
+
+  &:disabled {
+    @apply bg-zinc-700 opacity-50;
+  }
+}
+</style>

From c531be86f1d3e9e173ee155dfc776e42d5da16ae Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 16:48:12 +0200
Subject: [PATCH 08/17] chore: changeset

---
 .changeset/major-groups-rescue.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/major-groups-rescue.md

diff --git a/.changeset/major-groups-rescue.md b/.changeset/major-groups-rescue.md
new file mode 100644
index 00000000..29a61409
--- /dev/null
+++ b/.changeset/major-groups-rescue.md
@@ -0,0 +1,5 @@
+---
+'@formwerk/core': minor
+---
+
+feat: add OTP Field

From 41f9d3acf6fcce04271d14a51d80aa04e2bc4fcd Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Sun, 9 Mar 2025 16:56:53 +0200
Subject: [PATCH 09/17] feat: remove cursor color transparency

---
 packages/core/src/useOtpField/useOtpSlot.ts | 3 ---
 packages/playground/src/App.vue             | 2 +-
 2 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index bda902a2..168d8368 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -144,9 +144,6 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       // TODO: Should be either done or next depending on if it's the last slot
       enterkeyhint: 'next',
       ...handlers,
-      style: {
-        caretColor: 'transparent',
-      },
     };
 
     if (toValue(props.accept) === 'numeric') {
diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index 2fdbdaff..7d97148f 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -9,7 +9,7 @@ function onCompleted(value: string) {
 </script>
 
 <template>
-  <OtpField name="otp" label="OTP" :length="6" prefix="G-" masked @completed="onCompleted" />
+  <OtpField name="otp" label="OTP" accept="numeric" :length="4" prefix="G-" masked @completed="onCompleted" />
 
   <div class="flex w-full">
     <button @click="form.setValue('otp', 'G-4321')">Set OTP</button>

From b73402b0311460dfa4e83cc01c294eda3217a7f6 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 00:05:19 +0200
Subject: [PATCH 10/17] feat: handle the enterkeyhint

---
 packages/core/src/useOtpField/types.ts       | 1 +
 packages/core/src/useOtpField/useOtpField.ts | 8 +++++++-
 packages/core/src/useOtpField/useOtpSlot.ts  | 8 ++++----
 3 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/core/src/useOtpField/types.ts b/packages/core/src/useOtpField/types.ts
index 7492f58b..bb97ca86 100644
--- a/packages/core/src/useOtpField/types.ts
+++ b/packages/core/src/useOtpField/types.ts
@@ -8,6 +8,7 @@ export interface OtpSlotRegistration {
   focusPrevious(): void;
   setValue(value: string): void;
   handlePaste(event: ClipboardEvent): void;
+  isLast(): boolean;
 }
 
 export interface OtpContext {
diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 529618b2..3d9a87e3 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -289,16 +289,22 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
     }
   }
 
+  let registeredSlots = 0;
+
   provide(OtpContextKey, {
     useSlotRegistration() {
       const slotId = useUniqId(FieldTypePrefixes.OTPSlot);
+      const index = registeredSlots++;
 
       return {
         id: slotId,
         focusNext,
         focusPrevious,
+        isLast() {
+          return index === getRequiredLength() - 1;
+        },
         handlePaste: onPaste,
-        setValue: (value: string) => {
+        setValue(value: string) {
           const index = getActiveSlotIndex();
           if (index === -1) {
             return;
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index 168d8368..f6b24f31 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -43,6 +43,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
     useSlotRegistration() {
       return {
         id: '',
+        isLast: () => true,
         focusNext: () => {},
         focusPrevious: () => {},
         setValue: () => {},
@@ -51,7 +52,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
     },
   });
 
-  const { focusNext, focusPrevious, setValue, id, handlePaste } = context.useSlotRegistration({
+  const { focusNext, focusPrevious, setValue, id, handlePaste, isLast } = context.useSlotRegistration({
     focus() {
       slotEl.value?.focus();
     },
@@ -139,10 +140,9 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       spellcheck: false,
       tabindex: isDisabled.value ? '-1' : '0',
       autocorrect: 'off',
-      autocomplete: 'off',
+      autocomplete: 'one-time-code',
       autocapitalize: 'off',
-      // TODO: Should be either done or next depending on if it's the last slot
-      enterkeyhint: 'next',
+      enterkeyhint: isLast() ? 'done' : 'next',
       ...handlers,
     };
 

From b150f7b2d313df57939ae93d96b923a3f945f486 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 00:08:05 +0200
Subject: [PATCH 11/17] fix: role attribute name :facepalm:

---
 packages/core/src/useOtpField/useOtpSlot.ts     | 2 +-
 packages/playground/src/components/OtpField.vue | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index f6b24f31..07377cde 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -151,7 +151,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
     }
 
     if (!isInput) {
-      baseProps['aria-role'] = 'textbox';
+      baseProps.role = 'textbox';
       baseProps['aria-label'] = toValue(props.value) || 'Enter a character';
       baseProps['aria-multiline'] = 'false';
       baseProps.contenteditable = isDisabled.value ? 'false' : isFirefox() ? 'true' : 'plaintext-only';
diff --git a/packages/playground/src/components/OtpField.vue b/packages/playground/src/components/OtpField.vue
index efbd4afe..ab86cd23 100644
--- a/packages/playground/src/components/OtpField.vue
+++ b/packages/playground/src/components/OtpField.vue
@@ -13,8 +13,8 @@
 </template>
 
 <script setup lang="ts">
-import { useOtpField, OTPFieldProps } from '@formwerk/core';
-import OtpSlot from './OtpSlot.vue';
+import { useOtpField, OTPFieldProps, OtpSlot } from '@formwerk/core';
+
 const props = defineProps<OTPFieldProps>();
 
 const { controlProps, labelProps, errorMessage, errorMessageProps, fieldSlots } = useOtpField(props);

From 7255ec7d1fac8a53e9bc343b4d18978d724ba9e8 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 01:11:25 +0200
Subject: [PATCH 12/17] feat: enhance OTP field masking and auto-focus behavior

---
 packages/core/src/useOtpField/useOtpField.ts | 21 +++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 3d9a87e3..0a1d1689 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -9,7 +9,7 @@ import { useInputValidity, useConstraintsValidator } from '../validation';
 import { OtpSlotProps } from './useOtpSlot';
 import { createDisabledContext } from '../helpers/createDisabledContext';
 import { registerField } from '@formwerk/devtools';
-import { isValueAccepted } from './utils';
+import { DEFAULT_MASK, isValueAccepted } from './utils';
 import { blockEvent } from '../utils/events';
 
 export interface OTPFieldProps {
@@ -41,7 +41,7 @@ export interface OTPFieldProps {
   /**
    * Whether the OTP field is masked.
    */
-  masked?: boolean;
+  mask?: boolean | string;
 
   /**
    * Whether the OTP field is readonly.
@@ -205,7 +205,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
       disabled: prefix.length ? prefix.length > index : isDisabled.value,
       readonly: toValue(props.readonly),
       accept: toValue(props.accept),
-      masked: prefix.length <= index && toValue(props.masked),
+      masked: prefix.length <= index && !!toValue(props.mask),
     }));
   });
 
@@ -219,6 +219,12 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
     return slots.indexOf(currentSlot);
   }
 
+  function focusIndex(index: number) {
+    const slots = Array.from(controlEl.value?.querySelectorAll('[data-otp-slot]') ?? []) as HTMLElement[];
+
+    slots[index]?.focus();
+  }
+
   watch(field.fieldValue, value => {
     if (!value) {
       inputsState.value = withPrefix('').split('');
@@ -250,6 +256,8 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
         inputsState.value[index] = value;
       });
 
+      // Focuses the last slot
+      focusIndex(getRequiredLength() - 1);
       updateFieldValue();
       return;
     }
@@ -275,6 +283,8 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
       }
     }
 
+    // Focuses the next slot
+    focusIndex(Math.min(currentIndex + textToFill.length, getRequiredLength() - 1));
     updateFieldValue();
   }
 
@@ -292,6 +302,11 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
   let registeredSlots = 0;
 
   provide(OtpContextKey, {
+    getMaskCharacter: () => {
+      const mask = toValue(props.mask);
+
+      return typeof mask === 'string' ? mask[0] : DEFAULT_MASK;
+    },
     useSlotRegistration() {
       const slotId = useUniqId(FieldTypePrefixes.OTPSlot);
       const index = registeredSlots++;

From 673110fbd6b107c9950af77a78bc20b4c3066e90 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 01:11:40 +0200
Subject: [PATCH 13/17] feat: improve OTP slot registration and masking
 flexibility

---
 packages/core/src/useOtpField/types.ts      |  3 +-
 packages/core/src/useOtpField/useOtpSlot.ts | 47 +++++++--------------
 packages/core/src/useOtpField/utils.ts      |  2 +
 3 files changed, 20 insertions(+), 32 deletions(-)

diff --git a/packages/core/src/useOtpField/types.ts b/packages/core/src/useOtpField/types.ts
index bb97ca86..24a1c859 100644
--- a/packages/core/src/useOtpField/types.ts
+++ b/packages/core/src/useOtpField/types.ts
@@ -12,7 +12,8 @@ export interface OtpSlotRegistration {
 }
 
 export interface OtpContext {
-  useSlotRegistration(slot: { focus: () => void }): OtpSlotRegistration;
+  useSlotRegistration(): OtpSlotRegistration;
+  getMaskCharacter(): string;
 }
 
 export const OtpContextKey: InjectionKey<OtpContext> = Symbol('otp-context');
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index 07377cde..75962f6f 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -1,4 +1,4 @@
-import { computed, defineComponent, h, inject, ref, toValue } from 'vue';
+import { computed, defineComponent, h, inject, ref, toValue, useId } from 'vue';
 import { Reactivify } from '../types';
 import { hasKeyCode, isInputElement, normalizeProps, warn, withRefCapture } from '../utils/common';
 import { isFirefox } from '../utils/platform';
@@ -39,24 +39,9 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
   const slotEl = ref<HTMLElement>();
   const isDisabled = createDisabledContext(props.disabled);
 
-  const context = inject(OtpContextKey, {
-    useSlotRegistration() {
-      return {
-        id: '',
-        isLast: () => true,
-        focusNext: () => {},
-        focusPrevious: () => {},
-        setValue: () => {},
-        handlePaste: () => {},
-      };
-    },
-  });
+  const context = inject(OtpContextKey, null);
 
-  const { focusNext, focusPrevious, setValue, id, handlePaste, isLast } = context.useSlotRegistration({
-    focus() {
-      slotEl.value?.focus();
-    },
-  });
+  const registration = context?.useSlotRegistration();
 
   if (!context) {
     if (__DEV__) {
@@ -69,7 +54,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       return value ?? '';
     }
 
-    return '•'.repeat(value.length);
+    return context?.getMaskCharacter().repeat(value.length) ?? '';
   }
 
   function setElementValue(value: string) {
@@ -77,7 +62,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       return;
     }
 
-    setValue(value);
+    registration?.setValue(value);
     if (isInputElement(slotEl.value)) {
       slotEl.value.value = value;
       return;
@@ -88,31 +73,31 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
 
   const handlers = {
     onPaste(e: ClipboardEvent) {
-      handlePaste(e);
+      registration?.handlePaste(e);
     },
     onKeydown(e: KeyboardEvent) {
       if (hasKeyCode(e, 'Backspace') || hasKeyCode(e, 'Delete')) {
         blockEvent(e);
         setElementValue('');
-        focusPrevious();
+        registration?.focusPrevious();
         return;
       }
 
       if (hasKeyCode(e, 'Enter')) {
         blockEvent(e);
-        focusNext();
+        registration?.focusNext();
         return;
       }
 
       if (hasKeyCode(e, 'ArrowLeft')) {
         blockEvent(e);
-        focusPrevious();
+        registration?.focusPrevious();
         return;
       }
 
       if (hasKeyCode(e, 'ArrowRight')) {
         blockEvent(e);
-        focusNext();
+        registration?.focusNext();
         return;
       }
     },
@@ -125,7 +110,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       blockEvent(e);
       if (isValueAccepted(e.data, toValue(props.accept) || 'all')) {
         setElementValue(e.data);
-        focusNext();
+        registration?.focusNext();
       }
     },
   };
@@ -142,7 +127,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       autocorrect: 'off',
       autocomplete: 'one-time-code',
       autocapitalize: 'off',
-      enterkeyhint: isLast() ? 'done' : 'next',
+      enterkeyhint: registration?.isLast() ? 'done' : 'next',
       ...handlers,
     };
 
@@ -165,7 +150,7 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
 
   return {
     slotProps,
-    key: id,
+    key: registration?.id ?? useId(),
     value: computed(() => withMask(toValue(props.value))),
   };
 }
@@ -173,12 +158,12 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
 /**
  * A helper component that renders an OTP slot. You can build your own with `useOtpSlot`.
  */
-export const OtpSlot = /*#__PURE__*/ defineComponent<OtpSlotProps>({
+export const OtpSlot = /*#__PURE__*/ defineComponent<OtpSlotProps & { as?: string }>({
   name: 'OtpSlot',
-  props: ['value', 'disabled', 'readonly', 'accept', 'masked'],
+  props: ['value', 'disabled', 'readonly', 'accept', 'masked', 'as'],
   setup(props) {
     const { slotProps, value, key } = useOtpSlot(props);
 
-    return () => h('span', { ...slotProps.value, key }, value.value);
+    return () => h(props.as || 'span', { ...slotProps.value, key }, value.value);
   },
 });
diff --git a/packages/core/src/useOtpField/utils.ts b/packages/core/src/useOtpField/utils.ts
index 8e80a56d..fa8fa5f4 100644
--- a/packages/core/src/useOtpField/utils.ts
+++ b/packages/core/src/useOtpField/utils.ts
@@ -11,3 +11,5 @@ export function isValueAccepted(value: string, accept: OtpSlotAcceptType) {
 
   return regex.test(value);
 }
+
+export const DEFAULT_MASK = '•';

From 660fba77e5a1cd6bffddfe51c17a9e42dffac9a9 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 01:15:15 +0200
Subject: [PATCH 14/17] test: add comprehensive test suite for OTP field and
 slot components

---
 .../core/src/useOtpField/useOtpField.spec.ts  | 630 ++++++++++++++++++
 .../core/src/useOtpField/useOtpSlot.spec.ts   |  24 +
 packages/playground/src/App.vue               |   2 +-
 3 files changed, 655 insertions(+), 1 deletion(-)
 create mode 100644 packages/core/src/useOtpField/useOtpField.spec.ts
 create mode 100644 packages/core/src/useOtpField/useOtpSlot.spec.ts

diff --git a/packages/core/src/useOtpField/useOtpField.spec.ts b/packages/core/src/useOtpField/useOtpField.spec.ts
new file mode 100644
index 00000000..3cfee2e5
--- /dev/null
+++ b/packages/core/src/useOtpField/useOtpField.spec.ts
@@ -0,0 +1,630 @@
+import { OTPFieldProps, useOtpField, OtpSlot } from '.';
+import { isValueAccepted } from './utils';
+import { fireEvent, render, screen } from '@testing-library/vue';
+import { axe } from 'vitest-axe';
+import { Component, defineComponent } from 'vue';
+import { flush, renderSetup } from '@test-utils/index';
+
+const InputBase: string = `
+  <div>
+    <div v-bind="controlProps" data-testid="control">
+      <OtpSlot v-for="slot in fieldSlots" v-bind="slot" data-testid="slot" :as="slotType" />
+    </div>
+    <label v-bind="labelProps">{{ label }}</label>
+    <span v-bind="errorMessageProps">{{ errorMessage }}</span>
+    <span data-testid="value">{{ fieldValue }}</span>
+  </div>
+`;
+
+function createOtpField(props: OTPFieldProps, template = InputBase, slotType = 'span'): Component {
+  return defineComponent({
+    template,
+    inheritAttrs: false,
+    components: { OtpSlot },
+    setup() {
+      const otp = useOtpField(props);
+
+      return {
+        ...props,
+        ...otp,
+        slotType,
+      };
+    },
+  });
+}
+
+describe('useOtpField', () => {
+  describe('has no a11y violations', () => {
+    test('with basic configuration', async () => {
+      const OtpField = createOtpField({ label: 'OTP Code', length: 4 });
+
+      await render({
+        components: { OtpField },
+        template: `
+          <div data-testid="fixture">
+            <OtpField />
+          </div>
+        `,
+      });
+
+      vi.useRealTimers();
+      expect(await axe(screen.getByTestId('fixture'))).toHaveNoViolations();
+      vi.useFakeTimers();
+    });
+  });
+
+  describe('initialization', () => {
+    test('initializes with empty value by default', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4 });
+      });
+
+      expect(fieldValue.value).toBe('');
+    });
+
+    test('initializes with provided modelValue', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, modelValue: '1234' });
+      });
+
+      expect(fieldValue.value).toBe('1234');
+    });
+
+    test('initializes with provided value', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, value: '5678' });
+      });
+
+      expect(fieldValue.value).toBe('5678');
+    });
+
+    test('initializes with prefix if provided', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-', value: '1234' });
+      });
+
+      expect(fieldValue.value).toBe('G-1234');
+    });
+
+    test('adds prefix to value if not already present', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-', value: '1234' });
+      });
+
+      expect(fieldValue.value).toBe('G-1234');
+    });
+
+    test('does not duplicate prefix if already present in value', async () => {
+      const { fieldValue } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-', value: 'G-1234' });
+      });
+
+      expect(fieldValue.value).toBe('G-1234');
+    });
+  });
+
+  describe('field slots', () => {
+    test('creates correct number of slots based on length', async () => {
+      const { fieldSlots } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4 });
+      });
+
+      expect(fieldSlots.value.length).toBe(4);
+    });
+
+    test('creates correct number of slots with prefix', async () => {
+      const { fieldSlots } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-' });
+      });
+
+      expect(fieldSlots.value.length).toBe(6); // 'G-' (2 chars) + 4 slots
+    });
+
+    test('prefix slots are disabled', async () => {
+      const { fieldSlots } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-' });
+      });
+
+      expect(fieldSlots.value[0].disabled).toBe(true);
+      expect(fieldSlots.value[1].disabled).toBe(true);
+      expect(fieldSlots.value[2].disabled).toBe(false);
+    });
+
+    test('prefix slots are not masked', async () => {
+      const { fieldSlots } = await renderSetup(() => {
+        return useOtpField({ label: 'OTP Code', length: 4, prefix: 'G-', mask: true });
+      });
+
+      expect(fieldSlots.value[0].masked).toBe(false);
+      expect(fieldSlots.value[1].masked).toBe(false);
+      expect(fieldSlots.value[2].masked).toBe(true);
+    });
+  });
+
+  describe('paste functionality', () => {
+    test('handles paste event', async () => {
+      const OtpField = createOtpField({ label: 'OTP Code', length: 4 });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+      const pasteEvent = new Event('paste');
+      (pasteEvent as any).clipboardData = {
+        getData: () => '1234',
+      };
+
+      await fireEvent(slots[0], pasteEvent);
+      await flush();
+
+      expect(screen.getByTestId('value')).toHaveTextContent('1234');
+    });
+
+    test('respects accept type for paste', async () => {
+      // Test the isValueAccepted utility function directly
+      expect(isValueAccepted('1234', 'numeric')).toBe(true);
+      expect(isValueAccepted('abcd', 'numeric')).toBe(false);
+      expect(isValueAccepted('a1b2', 'alphanumeric')).toBe(true);
+      expect(isValueAccepted('a1b2!', 'alphanumeric')).toBe(false);
+      expect(isValueAccepted('anything!', 'all')).toBe(true);
+    });
+
+    test('handles paste starting from a middle slot', async () => {
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 6,
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Fill the first two slots manually
+      await fireEvent.focus(slots[0]);
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: '2', cancelable: true }));
+      await flush();
+
+      // Focus should now be on the third slot
+      expect(document.activeElement).toBe(slots[2]);
+
+      // Create a paste event with a partial value
+      const partialPasteEvent = new Event('paste');
+      (partialPasteEvent as any).clipboardData = {
+        getData: () => '345', // 3 digits to paste into slots 2, 3, and 4
+      };
+
+      await fireEvent(slots[2], partialPasteEvent);
+      await flush();
+
+      // Verify that the first 5 slots are filled (2 manual + 3 pasted)
+      expect(screen.getByTestId('value').textContent).toBe('12345');
+
+      // Focus should move to the sixth slot (after the pasted content)
+      expect(document.activeElement).toBe(slots[5]);
+
+      // Fill the last slot
+      await fireEvent(slots[5], new InputEvent('beforeinput', { data: '6', cancelable: true }));
+      await flush();
+
+      // Now all slots should be filled
+      expect(screen.getByTestId('value').textContent).toBe('123456');
+    });
+  });
+
+  describe('validation', () => {
+    test('validates required field', async () => {
+      const OtpField = createOtpField({ label: 'OTP Code', length: 4, required: true });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      await fireEvent.invalid(screen.getAllByTestId('slot')[0]);
+      await flush();
+
+      expect(screen.getByTestId('control')).toHaveErrorMessage('Constraints not satisfied');
+    });
+  });
+
+  describe('completion callback', () => {
+    test('calls onCompleted when all slots are filled', async () => {
+      const onCompleted = vi.fn();
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 4,
+        onCompleted,
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+      await fireEvent.focus(slots[0]);
+      await flush();
+
+      // somehow it doesn't work for the first slot
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: '2', cancelable: true }));
+      await fireEvent(slots[2], new InputEvent('beforeinput', { data: '3', cancelable: true }));
+      await fireEvent(slots[3], new InputEvent('beforeinput', { data: '4', cancelable: true }));
+
+      expect(onCompleted).toHaveBeenCalledWith('1234');
+    });
+  });
+
+  describe('keyboard navigation', () => {
+    test('provides slot registration with navigation functions', async () => {
+      // We can't directly test focusNext and focusPrevious as they're not exposed
+      // in the return value, but we can verify the component renders correctly
+      const OtpField = createOtpField({ label: 'OTP Code', length: 4 });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      // Verify slots are rendered
+      const slots = screen.getAllByTestId('slot');
+      expect(slots.length).toBe(4);
+    });
+
+    test('navigates between slots using arrow keys', async () => {
+      const OtpField = createOtpField(
+        {
+          label: 'OTP Code',
+          length: 4,
+        },
+        InputBase,
+        'input',
+      );
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      await flush();
+      const slots = screen.getAllByTestId('slot');
+
+      // Focus the first slot
+      await fireEvent.focus(slots[0]);
+
+      // Press right arrow key to move to the next slot
+      await fireEvent.keyDown(slots[0], { key: 'ArrowRight', code: 'ArrowRight' });
+      await flush();
+      expect(document.activeElement).toBe(slots[0]);
+
+      // Press right arrow key again to move to the third slot
+      await fireEvent.keyDown(slots[1], { key: 'ArrowRight', code: 'ArrowRight' });
+      await flush();
+      expect(document.activeElement).toBe(slots[1]);
+
+      // Press left arrow key to move back to the second slot
+      await fireEvent.keyDown(slots[2], { key: 'ArrowLeft', code: 'ArrowLeft' });
+      await flush();
+      expect(document.activeElement).toBe(slots[0]);
+
+      // Press left arrow key again to move back to the first slot
+      await fireEvent.keyDown(slots[1], { key: 'ArrowLeft', code: 'ArrowLeft' });
+      await flush();
+      expect(document.activeElement).toBe(slots[0]);
+    });
+
+    test('automatically moves focus to next slot after input', async () => {
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 4,
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Focus the first slot
+      await fireEvent.focus(slots[0]);
+
+      // Enter a value in the first slot
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await flush();
+
+      // Focus should automatically move to the next slot
+      expect(document.activeElement).toBe(slots[1]);
+
+      // Enter a value in the second slot
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: '2', cancelable: true }));
+      await flush();
+
+      // Focus should automatically move to the third slot
+      expect(document.activeElement).toBe(slots[2]);
+
+      // Enter a value in the third slot
+      await fireEvent(slots[2], new InputEvent('beforeinput', { data: '3', cancelable: true }));
+      await flush();
+
+      // Focus should automatically move to the fourth slot
+      expect(document.activeElement).toBe(slots[3]);
+
+      // Enter a value in the fourth slot
+      await fireEvent(slots[3], new InputEvent('beforeinput', { data: '4', cancelable: true }));
+      await flush();
+
+      // Focus should remain on the last slot as there's nowhere else to go
+      expect(document.activeElement).toBe(slots[3]);
+
+      // Verify the complete value
+      expect(screen.getByTestId('value').textContent).toBe('1234');
+    });
+
+    test('handles backspace key to clear and navigate to previous slot', async () => {
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 4,
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Fill all slots
+      await fireEvent.focus(slots[0]);
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: '2', cancelable: true }));
+      await fireEvent(slots[2], new InputEvent('beforeinput', { data: '3', cancelable: true }));
+      await fireEvent(slots[3], new InputEvent('beforeinput', { data: '4', cancelable: true }));
+      await flush();
+
+      // Verify all slots are filled
+      expect(screen.getByTestId('value').textContent).toBe('1234');
+
+      // Press backspace on the last slot
+      await fireEvent.keyDown(slots[3], { key: 'Backspace', code: 'Backspace' });
+      await flush();
+      await flush();
+
+      // The last slot should be cleared and focus should remain on it
+      expect(screen.getByTestId('value').textContent).toBe('123');
+      expect(document.activeElement).toBe(slots[2]);
+
+      // Press backspace again on the empty last slot
+      await fireEvent.keyDown(slots[2], { key: 'Backspace', code: 'Backspace' });
+      await flush();
+
+      // Focus should move to the previous slot
+      expect(document.activeElement).toBe(slots[1]);
+
+      // Press backspace on the third slot
+      await fireEvent.keyDown(slots[1], { key: 'Backspace', code: 'Backspace' });
+      await flush();
+
+      // The third slot should be cleared and focus should remain on it
+      expect(screen.getByTestId('value').textContent).toBe('1');
+      expect(document.activeElement).toBe(slots[0]);
+    });
+
+    test('handles enter key to move to the next slot', async () => {
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 4,
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Focus the first slot
+      await fireEvent.focus(slots[0]);
+
+      // Press enter on the first slot
+      await fireEvent.keyDown(slots[0], { key: 'Enter', code: 'Enter' });
+      await flush();
+
+      // Focus should move to the next slot
+      expect(document.activeElement).toBe(slots[0]);
+
+      // Press enter on the second slot
+      await fireEvent.keyDown(slots[0], { key: 'Enter', code: 'Enter' });
+      await flush();
+
+      // Focus should move to the third slot
+      expect(document.activeElement).toBe(slots[1]);
+    });
+  });
+
+  describe('masked input', () => {
+    test('renders masked inputs when masked is true', async () => {
+      const OtpField = createOtpField(
+        {
+          label: 'OTP Code',
+          length: 4,
+          mask: true,
+        },
+        InputBase,
+        'input',
+      );
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Verify all slots are rendered as password inputs
+      slots.forEach(slot => {
+        expect(slot).toHaveAttribute('type', 'password');
+      });
+    });
+
+    test('renders text inputs when masked is false', async () => {
+      const OtpField = createOtpField(
+        {
+          label: 'OTP Code',
+          length: 4,
+          mask: false,
+        },
+        InputBase,
+        'input',
+      );
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Verify all slots are rendered as text inputs
+      slots.forEach(slot => {
+        expect(slot).toHaveAttribute('type', 'text');
+      });
+    });
+
+    test('renders mixed input types with prefix and masked', async () => {
+      const OtpField = createOtpField(
+        {
+          label: 'OTP Code',
+          length: 4,
+          prefix: 'G-',
+          mask: true,
+        },
+        InputBase,
+        'input',
+      );
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Prefix slots should be text type
+      expect(slots[0]).toHaveAttribute('type', 'text');
+      expect(slots[1]).toHaveAttribute('type', 'text');
+
+      // Non-prefix slots should be password type
+      expect(slots[2]).toHaveAttribute('type', 'password');
+      expect(slots[3]).toHaveAttribute('type', 'password');
+      expect(slots[4]).toHaveAttribute('type', 'password');
+      expect(slots[5]).toHaveAttribute('type', 'password');
+    });
+
+    test('masks entered values while maintaining correct underlying value', async () => {
+      const OtpField = createOtpField(
+        {
+          label: 'OTP Code',
+          length: 4,
+          mask: true,
+        },
+        InputBase,
+        'span',
+      );
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+
+      // Enter values in the slots
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: '2', cancelable: true }));
+      await fireEvent(slots[2], new InputEvent('beforeinput', { data: '3', cancelable: true }));
+      await fireEvent(slots[3], new InputEvent('beforeinput', { data: '4', cancelable: true }));
+
+      await flush();
+
+      // Verify the underlying field value is correct
+      expect(screen.getByTestId('value').textContent).toBe('1234');
+
+      // Verify each slot has the correct value attribute but is visually masked
+      slots.forEach(slot => {
+        expect(slot).toHaveTextContent('•');
+      });
+    });
+  });
+
+  describe('input acceptance', () => {
+    test('accepts only numeric input when accept is set to numeric', async () => {
+      // Create a spy on console.warn to check if warnings are logged
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      const OtpField = createOtpField({
+        label: 'OTP Code',
+        length: 4,
+        accept: 'numeric',
+      });
+
+      await render({
+        components: { OtpField },
+        template: `<OtpField />`,
+      });
+
+      const slots = screen.getAllByTestId('slot');
+      await fireEvent.focus(slots[0]);
+      await flush();
+
+      // Test numeric input (should be accepted)
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+      await fireEvent(slots[0], new InputEvent('beforeinput', { data: '1', cancelable: true }));
+
+      // Test non-numeric input (should be rejected)
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: 'a', cancelable: true }));
+      await fireEvent(slots[1], new InputEvent('beforeinput', { data: 'a', cancelable: true }));
+
+      // Check the field value - should only contain the numeric input
+      expect(screen.getByTestId('value').textContent).toBe('1');
+
+      // Test paste event with mixed content
+      const pasteEvent = new Event('paste');
+      (pasteEvent as any).clipboardData = {
+        getData: () => '12ab',
+      };
+
+      await fireEvent(slots[0], pasteEvent);
+      await flush();
+
+      // Should not update with mixed content paste
+      expect(screen.getByTestId('value').textContent).toBe('1');
+
+      // Test paste event with numeric content
+      const numericPasteEvent = new Event('paste');
+      (numericPasteEvent as any).clipboardData = {
+        getData: () => '1234',
+      };
+
+      await fireEvent(slots[0], numericPasteEvent);
+      await flush();
+
+      // Should update with numeric content paste
+      expect(screen.getByTestId('value').textContent).toBe('1234');
+
+      // Restore the spy
+      warnSpy.mockRestore();
+    });
+  });
+});
diff --git a/packages/core/src/useOtpField/useOtpSlot.spec.ts b/packages/core/src/useOtpField/useOtpSlot.spec.ts
new file mode 100644
index 00000000..8d0c1f9c
--- /dev/null
+++ b/packages/core/src/useOtpField/useOtpSlot.spec.ts
@@ -0,0 +1,24 @@
+import { OtpSlot } from '.';
+import { render } from '@testing-library/vue';
+import { describe, expect, test, vi } from 'vitest';
+import { flush } from '@test-utils/index';
+
+describe('useOtpSlot', () => {
+  describe('when used without OtpField context', () => {
+    test('should warn when rendered without OtpField context', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      // Render OtpSlot without a parent OtpField
+      await render({
+        components: { OtpSlot },
+        template: `<OtpSlot value="" />`,
+      });
+
+      await flush();
+      // Verify that the warning was shown
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith('[Formwerk]: OtpSlot must be used within an OtpField');
+
+      warnSpy.mockRestore();
+    });
+  });
+});
diff --git a/packages/playground/src/App.vue b/packages/playground/src/App.vue
index 7d97148f..8486a5f9 100644
--- a/packages/playground/src/App.vue
+++ b/packages/playground/src/App.vue
@@ -9,7 +9,7 @@ function onCompleted(value: string) {
 </script>
 
 <template>
-  <OtpField name="otp" label="OTP" accept="numeric" :length="4" prefix="G-" masked @completed="onCompleted" />
+  <OtpField name="otp" label="OTP" accept="numeric" :length="4" @completed="onCompleted" />
 
   <div class="flex w-full">
     <button @click="form.setValue('otp', 'G-4321')">Set OTP</button>

From dd34cea2c82991751b849685e4429a46db963849 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 01:20:55 +0200
Subject: [PATCH 15/17] feat: improve OTP field length calculation with smart
 default

---
 packages/core/src/useOtpField/useOtpField.ts | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 0a1d1689..54c51740 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -111,7 +111,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
 
   function getRequiredLength() {
     const prefix = toValue(props.prefix) || '';
-    const length = toValue(props.length) ?? 0;
+    const length = getLength();
 
     return prefix.length + length;
   }
@@ -123,6 +123,17 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
     schema: props.schema,
   });
 
+  function getLength() {
+    const propLength = toValue(props.length);
+    if (propLength) {
+      return propLength;
+    }
+
+    const prefix = toValue(props.prefix);
+
+    return prefix ? 4 : 6;
+  }
+
   const inputsState = ref<string[]>(withPrefix(toValue(props.modelValue) ?? toValue(props.value)).split(''));
 
   const { element: inputEl } = useConstraintsValidator({
@@ -198,7 +209,7 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
 
   const fieldSlots = computed<OtpSlotProps[]>(() => {
     const prefix = toValue(props.prefix) || '';
-    const length = prefix.length + (toValue(props.length) ?? 0);
+    const length = prefix.length + getLength();
 
     return Array.from({ length }, (_, index) => ({
       value: inputsState.value[index] ?? '',

From a6e5e45b464cbfa44887bec1abd69967ecc981f7 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 02:05:08 +0200
Subject: [PATCH 16/17] feat: prevent input in readonly or disabled OTP fields

---
 packages/core/src/useOtpField/useOtpField.ts | 5 +++++
 packages/core/src/useOtpField/useOtpSlot.ts  | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index 54c51740..b76491bd 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -251,6 +251,11 @@ export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onComp
   });
 
   function onPaste(event: ClipboardEvent) {
+    if (toValue(props.readonly) || isDisabled.value) {
+      blockEvent(event);
+      return;
+    }
+
     const text = event.clipboardData?.getData('text/plain') || '';
     blockEvent(event);
     if (!text.length) {
diff --git a/packages/core/src/useOtpField/useOtpSlot.ts b/packages/core/src/useOtpField/useOtpSlot.ts
index 75962f6f..3a782547 100644
--- a/packages/core/src/useOtpField/useOtpSlot.ts
+++ b/packages/core/src/useOtpField/useOtpSlot.ts
@@ -108,6 +108,10 @@ export function useOtpSlot(_props: Reactivify<OtpSlotProps>) {
       }
 
       blockEvent(e);
+      if (toValue(props.readonly) || isDisabled.value) {
+        return;
+      }
+
       if (isValueAccepted(e.data, toValue(props.accept) || 'all')) {
         setElementValue(e.data);
         registration?.focusNext();

From 12d510ac27610e632f076771ced3503783fddf19 Mon Sep 17 00:00:00 2001
From: Abdelrahman Awad <me@awad.dev>
Date: Mon, 10 Mar 2025 02:16:56 +0200
Subject: [PATCH 17/17] refactor: rename OTP field type to follow naming
 convention

---
 packages/core/src/useOtpField/index.ts            | 1 +
 packages/core/src/useOtpField/useOtpField.spec.ts | 4 ++--
 packages/core/src/useOtpField/useOtpField.ts      | 4 ++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/core/src/useOtpField/index.ts b/packages/core/src/useOtpField/index.ts
index 0f0c1e4a..0176fe71 100644
--- a/packages/core/src/useOtpField/index.ts
+++ b/packages/core/src/useOtpField/index.ts
@@ -1,2 +1,3 @@
 export * from './useOtpField';
 export * from './useOtpSlot';
+export * from './types';
diff --git a/packages/core/src/useOtpField/useOtpField.spec.ts b/packages/core/src/useOtpField/useOtpField.spec.ts
index 3cfee2e5..a3e735bf 100644
--- a/packages/core/src/useOtpField/useOtpField.spec.ts
+++ b/packages/core/src/useOtpField/useOtpField.spec.ts
@@ -1,4 +1,4 @@
-import { OTPFieldProps, useOtpField, OtpSlot } from '.';
+import { OtpFieldProps, useOtpField, OtpSlot } from '.';
 import { isValueAccepted } from './utils';
 import { fireEvent, render, screen } from '@testing-library/vue';
 import { axe } from 'vitest-axe';
@@ -16,7 +16,7 @@ const InputBase: string = `
   </div>
 `;
 
-function createOtpField(props: OTPFieldProps, template = InputBase, slotType = 'span'): Component {
+function createOtpField(props: OtpFieldProps, template = InputBase, slotType = 'span'): Component {
   return defineComponent({
     template,
     inheritAttrs: false,
diff --git a/packages/core/src/useOtpField/useOtpField.ts b/packages/core/src/useOtpField/useOtpField.ts
index b76491bd..d5ae0850 100644
--- a/packages/core/src/useOtpField/useOtpField.ts
+++ b/packages/core/src/useOtpField/useOtpField.ts
@@ -12,7 +12,7 @@ import { registerField } from '@formwerk/devtools';
 import { DEFAULT_MASK, isValueAccepted } from './utils';
 import { blockEvent } from '../utils/events';
 
-export interface OTPFieldProps {
+export interface OtpFieldProps {
   /**
    * The label of the OTP field.
    */
@@ -89,7 +89,7 @@ export interface OTPFieldProps {
   onCompleted?: (value: string) => MaybeAsync<void>;
 }
 
-export function useOtpField(_props: Reactivify<OTPFieldProps, 'schema' | 'onCompleted'>) {
+export function useOtpField(_props: Reactivify<OtpFieldProps, 'schema' | 'onCompleted'>) {
   const props = normalizeProps(_props, ['schema', 'onCompleted']);
   const controlEl = ref<HTMLElement>();
   const id = useUniqId(FieldTypePrefixes.OTPField);