digitojs 1.0.0

package/src/adapters/vue.ts

@@ -0,0 +1,462 @@
+/**
+ * digito/vue
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Vue 3 adapter — useOTP composable (single hidden-input architecture)
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+
+import {
+  ref,
+  computed,
+  watch,
+  onMounted,
+  onUnmounted,
+  isRef,
+  type Ref,
+} from 'vue'
+
+import {
+  createDigito,
+  createTimer,
+  filterString,
+  type DigitoOptions,
+  type InputType,
+} from '../core/index.js'
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Extended options for the Vue useOTP composable.
+ * Adds controlled-input, separator, and disabled support on top of DigitoOptions.
+ */
+export type VueOTPOptions = DigitoOptions & {
+  /**
+   * Controlled value — pre-fills and drives the slot state from outside the composable.
+   *
+   * Reactive mode (recommended): pass a Ref<string>. The composable watches it
+   * via Vue's reactivity system — changes propagate automatically, making it
+   * fully equivalent to React's controlled-input pattern.
+   * ```ts
+   * const code = ref('')
+   * const otp = useOTP({ value: code, length: 6 })
+   * // Clearing from parent:
+   * code.value = ''
+   * ```
+   *
+   * Static mode: pass a plain string to pre-fill slots once on creation.
+   * Subsequent changes to the string will NOT be reactive (composables run
+   * once during setup()). Use reset() or the Ref pattern for runtime updates.
+   */
+  value?: string | Ref<string>
+  /**
+   * Fires exactly ONCE per user interaction with the current joined code string.
+   * Receives partial values too — not just when the code is complete.
+   */
+  onChange?: (code: string) => void
+  /**
+   * Insert a purely visual separator after this slot index (0-based).
+   * Accepts a single position or an array for multiple separators.
+   * aria-hidden, never part of the value, no effect on the state machine.
+   * Default: 0 (no separator).
+   * @example separatorAfter: 3      ->  [*][*][*] — [*][*][*]
+   * @example separatorAfter: [2, 4] ->  [*][*] — [*][*] — [*][*]
+   */
+  separatorAfter?: number | number[]
+  /**
+   * The character or string to render as the separator.
+   * Default: '—'
+   */
+  separator?: string
+  /**
+   * When `true`, slot templates should display a mask glyph instead of the real
+   * character. The hidden input switches to `type="password"` via `hiddenInputAttrs`.
+   *
+   * `getCode()` and `onComplete` always return real characters.
+   * Use for PIN entry or any sensitive input flow.
+   *
+   * Default: `false`.
+   */
+  masked?: boolean
+  /**
+   * The glyph displayed in filled slots when `masked` is `true`.
+   * Returned as a reactive `Ref<string>` so templates can bind to it directly.
+   *
+   * Default: `'●'` (U+25CF BLACK CIRCLE).
+   * @example maskChar: '*'
+   */
+  maskChar?: string
+}
+
+export type UseOTPResult = {
+  /** Current value of each slot. Empty string = unfilled. */
+  slotValues:       Ref<string[]>
+  /** Index of the currently active slot. */
+  activeSlot:       Ref<number>
+  /** Computed joined code string. */
+  value:            Ref<string>
+  /** True when every slot is filled. */
+  isComplete:       Ref<boolean>
+  /** True when error state is active. */
+  hasError:         Ref<boolean>
+  /** True when the field is disabled. Mirrors the disabled option. */
+  isDisabled:       Ref<boolean>
+  /** Remaining timer seconds. */
+  timerSeconds:     Ref<number>
+  /** True while the hidden input has browser focus. */
+  isFocused:        Ref<boolean>
+  /** The separator slot index/indices for template rendering. */
+  separatorAfter:   Ref<number | number[]>
+  /** The separator character/string to render. */
+  separator:        Ref<string>
+  /**
+   * Whether masked mode is enabled. When true, templates should display
+   * `maskChar.value` instead of the real character. `getCode()` still returns real chars.
+   */
+  masked:           Ref<boolean>
+  /**
+   * The configured mask glyph. Use in templates instead of a hard-coded `●`:
+   * `{{ masked.value && char ? maskChar.value : char }}`
+   */
+  maskChar:         Ref<string>
+  /** The placeholder character for empty slots. Empty string when not set. */
+  placeholder:      string
+  /** Ref to bind to the hidden input element via :ref. */
+  inputRef:         Ref<HTMLInputElement | null>
+  /** Attribute object to spread onto the hidden input via v-bind. */
+  hiddenInputAttrs: Ref<Record<string, unknown>>
+  /** Returns the current joined code string. */
+  getCode:          () => string
+  /** Clear all slots, restart timer, return focus to input. */
+  reset:            () => void
+  /** Apply or clear the error state. */
+  setError:         (isError: boolean) => void
+  /** Programmatically move focus to a slot index. */
+  focus:            (slotIndex: number) => void
+  /** Event handlers to bind on the hidden input. */
+  onKeydown:        (e: KeyboardEvent) => void
+  onChange:         (e: Event) => void
+  onPaste:          (e: ClipboardEvent) => void
+  onFocus:          () => void
+  onBlur:           () => void
+}
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// COMPOSABLE
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Vue 3 composable for OTP input — single hidden-input architecture.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useOTP } from 'digito/vue'
+ * const otp = useOTP({ length: 6, onComplete: (code) => verify(code) })
+ * </script>
+ *
+ * <template>
+ *   <div style="position:relative; display:inline-flex; gap:8px; align-items:center">
+ *     <input
+ *       :ref="(el) => otp.inputRef.value = el"
+ *       v-bind="otp.hiddenInputAttrs.value"
+ *       style="position:absolute;inset:0;opacity:0;z-index:1;cursor:text"
+ *       @keydown="otp.onKeydown"
+ *       @input="otp.onChange"
+ *       @paste="otp.onPaste"
+ *       @focus="otp.onFocus"
+ *       @blur="otp.onBlur"
+ *     />
+ *     <template v-for="(char, i) in otp.slotValues.value" :key="i">
+ *       <span v-if="otp.separatorAfter.value > 0 && i === otp.separatorAfter.value" aria-hidden="true">
+ *         {{ otp.separator.value }}
+ *       </span>
+ *       <div :class="['slot',
+ *         i === otp.activeSlot.value && otp.isFocused.value ? 'is-active'   : '',
+ *         char                                              ? 'is-filled'   : '',
+ *         otp.hasError.value                               ? 'is-error'    : '',
+ *         otp.isComplete.value && !otp.hasError.value      ? 'is-success'  : '',
+ *         otp.isDisabled.value                             ? 'is-disabled' : '',
+ *       ]">{{ char }}</div>
+ *     </template>
+ *   </div>
+ * </template>
+ * ```
+ */
+export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
+  const {
+    length             = 6,
+    type               = 'numeric' as InputType,
+    timer:             timerSecs = 0,
+    disabled:          initialDisabled = false,
+    onComplete,
+    onExpire,
+    onResend,
+    haptic             = true,
+    sound              = false,
+    pattern,
+    pasteTransformer,
+    onInvalidChar,
+    value:             controlledValue,
+    onChange:          onChangeProp,
+    onFocus:           onFocusProp,
+    onBlur:            onBlurProp,
+    separatorAfter:    separatorAfterOpt = 0,
+    separator:         separatorOpt = '—',
+    masked:            maskedOpt = false,
+    maskChar:          maskCharOpt = '\u25CF',
+    autoFocus:         autoFocusOpt = true,
+    name:              nameOpt,
+    placeholder:       placeholderOpt = '',
+    selectOnFocus:     selectOnFocusOpt = false,
+    blurOnComplete:    blurOnCompleteOpt = false,
+  } = options
+
+  // ── Core instance ──────────────────────────────────────────────────────────
+  const digito = createDigito({ length, type, pattern, pasteTransformer, onInvalidChar, onComplete, onExpire, onResend, haptic, sound })
+
+  // ── Reactive state ─────────────────────────────────────────────────────────
+  const slotValues   = ref<string[]>(Array(length).fill(''))
+  const activeSlot   = ref(0)
+  const isComplete   = ref(false)
+  const hasError     = ref(false)
+  const isDisabled   = ref(initialDisabled)
+  const timerSeconds = ref(timerSecs)
+  const isFocused    = ref(false)
+  const inputRef     = ref<HTMLInputElement | null>(null)
+  const separatorAfter = ref<number | number[]>(separatorAfterOpt)
+  const separator      = ref(separatorOpt)
+  const masked         = ref(maskedOpt)
+  const maskChar       = ref(maskCharOpt)
+
+  const value = computed(() => slotValues.value.join(''))
+
+  const hiddenInputAttrs = computed<Record<string, unknown>>(() => ({
+    type:           masked.value ? 'password' : 'text',
+    inputmode:      type === 'numeric' ? 'numeric' : 'text',
+    autocomplete:   'one-time-code',
+    maxlength:      length,
+    disabled:       isDisabled.value,
+    ...(nameOpt      ? { name: nameOpt }          : {}),
+    ...(autoFocusOpt ? { autofocus: true }         : {}),
+    'aria-label':   `Enter your ${length}-${type === 'numeric' ? 'digit' : 'character'} code`,
+    spellcheck:     'false',
+    autocorrect:    'off',
+    autocapitalize: 'off',
+  }))
+
+  // ── sync() ─────────────────────────────────────────────────────────────────
+  function sync(suppressOnChange = false): void {
+    const s          = digito.state
+    slotValues.value = [...s.slotValues]
+    activeSlot.value = s.activeSlot
+    isComplete.value = s.isComplete
+    hasError.value   = s.hasError
+    if (!suppressOnChange) {
+      onChangeProp?.(s.slotValues.join(''))
+    }
+  }
+
+  // ── Controlled value sync ──────────────────────────────────────────────────
+  // When value is a Ref<string>, watch it reactively so parent changes
+  // propagate automatically. When it's a plain string, the arrow-function
+  // source returns a constant — watch fires once via { immediate: true }
+  // and never again (documented static-pre-fill behaviour).
+  if (controlledValue !== undefined) {
+    const watchSource = isRef(controlledValue)
+      ? controlledValue
+      : () => controlledValue as string
+
+    watch(
+      watchSource,
+      (incoming: string) => {
+        const filtered = filterString(incoming.slice(0, length), type, pattern)
+        const current  = digito.state.slotValues.join('')
+        if (filtered === current) return
+
+        digito.resetState()
+        for (let i = 0; i < filtered.length; i++) {
+          digito.inputChar(i, filtered[i])
+        }
+        sync(true)
+        if (inputRef.value) {
+          inputRef.value.value = filtered
+          inputRef.value.setSelectionRange(filtered.length, filtered.length)
+        }
+        onChangeProp?.(filtered)
+      },
+      { immediate: true }
+    )
+  }
+
+  // ── Timer ──────────────────────────────────────────────────────────────────
+  let timerControls: ReturnType<typeof createTimer> | null = null
+
+  onMounted(() => {
+    if (autoFocusOpt && !initialDisabled && inputRef.value) {
+      inputRef.value.focus()
+      inputRef.value.setSelectionRange(0, 0)
+    }
+    if (!timerSecs) return
+    timerControls = createTimer({
+      totalSeconds: timerSecs,
+      onTick:   (r) => { timerSeconds.value = r },
+      onExpire: () => { timerSeconds.value = 0; onExpire?.() },
+    })
+    timerControls.start()
+  })
+
+  onUnmounted(() => timerControls?.stop())
+
+  // ── Event handlers ─────────────────────────────────────────────────────────
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (isDisabled.value) return
+    const pos = inputRef.value?.selectionStart ?? 0
+    if (e.key === 'Backspace') {
+      e.preventDefault()
+      digito.deleteChar(pos)
+      sync()
+      const next = digito.state.activeSlot
+      requestAnimationFrame(() => inputRef.value?.setSelectionRange(next, next))
+    } else if (e.key === 'ArrowLeft') {
+      e.preventDefault()
+      digito.moveFocusLeft(pos)
+      sync()
+      const next = digito.state.activeSlot
+      requestAnimationFrame(() => inputRef.value?.setSelectionRange(next, next))
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault()
+      digito.moveFocusRight(pos)
+      sync()
+      const next = digito.state.activeSlot
+      requestAnimationFrame(() => inputRef.value?.setSelectionRange(next, next))
+    } else if (e.key === 'Tab') {
+      if (e.shiftKey) {
+        if (pos === 0) return
+        e.preventDefault()
+        digito.moveFocusLeft(pos)
+      } else {
+        if (!digito.state.slotValues[pos]) return
+        if (pos >= length - 1) return
+        e.preventDefault()
+        digito.moveFocusRight(pos)
+      }
+      sync()
+      const next = digito.state.activeSlot
+      requestAnimationFrame(() => inputRef.value?.setSelectionRange(next, next))
+    }
+  }
+
+  function onChange(e: Event): void {
+    if (isDisabled.value) return
+    const raw = (e.target as HTMLInputElement).value
+    if (!raw) {
+      digito.resetState()
+      if (inputRef.value) { inputRef.value.value = ''; inputRef.value.setSelectionRange(0, 0) }
+      sync()
+      return
+    }
+    const valid = filterString(raw, type, pattern).slice(0, length)
+    digito.resetState()
+    for (let i = 0; i < valid.length; i++) digito.inputChar(i, valid[i])
+    const next = Math.min(valid.length, length - 1)
+    if (inputRef.value) { inputRef.value.value = valid; inputRef.value.setSelectionRange(next, next) }
+    digito.moveFocusTo(next)
+    sync()
+    if (blurOnCompleteOpt && digito.state.isComplete) {
+      requestAnimationFrame(() => inputRef.value?.blur())
+    }
+  }
+
+  function onPaste(e: ClipboardEvent): void {
+    if (isDisabled.value) return
+    e.preventDefault()
+    const text = e.clipboardData?.getData('text') ?? ''
+    const pos  = inputRef.value?.selectionStart ?? 0
+    digito.pasteString(pos, text)
+    const { slotValues: sv, activeSlot: as } = digito.state
+    if (inputRef.value) { inputRef.value.value = sv.join(''); inputRef.value.setSelectionRange(as, as) }
+    sync()
+    if (blurOnCompleteOpt && digito.state.isComplete) {
+      requestAnimationFrame(() => inputRef.value?.blur())
+    }
+  }
+
+  function onFocus(): void {
+    isFocused.value = true
+    onFocusProp?.()
+    const pos = digito.state.activeSlot
+    requestAnimationFrame(() => {
+      const char = digito.state.slotValues[pos]
+      if (selectOnFocusOpt && char) {
+        inputRef.value?.setSelectionRange(pos, pos + 1)
+      } else {
+        inputRef.value?.setSelectionRange(pos, pos)
+      }
+    })
+  }
+
+  function onBlur(): void {
+    isFocused.value = false
+    onBlurProp?.()
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  function reset(): void {
+    digito.resetState()
+    if (inputRef.value) { inputRef.value.value = ''; inputRef.value.focus(); inputRef.value.setSelectionRange(0, 0) }
+    timerSeconds.value = timerSecs
+    timerControls?.restart()
+    sync()
+  }
+
+  function setError(isError: boolean): void {
+    digito.setError(isError)
+    sync(true)
+  }
+
+  function focus(slotIndex: number): void {
+    digito.moveFocusTo(slotIndex)
+    inputRef.value?.focus()
+    requestAnimationFrame(() => inputRef.value?.setSelectionRange(slotIndex, slotIndex))
+    sync(true)
+  }
+
+  function getCode(): string {
+    return digito.getCode()
+  }
+
+  return {
+    slotValues,
+    activeSlot,
+    value,
+    isComplete,
+    hasError,
+    isDisabled,
+    timerSeconds,
+    isFocused,
+    separatorAfter,
+    separator,
+    masked,
+    maskChar,
+    placeholder:    placeholderOpt,
+    inputRef,
+    hiddenInputAttrs,
+    getCode,
+    reset,
+    setError,
+    focus,
+    onKeydown,
+    onChange,
+    onPaste,
+    onFocus,
+    onBlur,
+  }
+}