digitojs 1.0.1 → 1.2.0

package/src/adapters/vue.ts

@@ -129,6 +129,8 @@ export type UseOTPResult = {
   inputRef:         Ref<HTMLInputElement | null>
   /** Attribute object to spread onto the hidden input via v-bind. */
   hiddenInputAttrs: Ref<Record<string, unknown>>
+  /** Spread onto the wrapper element to expose state as data attributes for CSS/Tailwind targeting. */
+  wrapperAttrs:     Ref<Record<string, string | undefined>>
   /** Returns the current joined code string. */
   getCode:          () => string
   /** Clear all slots, restart timer, return focus to input. */
@@ -203,6 +205,8 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
     pasteTransformer,
     onInvalidChar,
     value:             controlledValue,
+    defaultValue,
+    readOnly:          readOnlyOpt = false,
     onChange:          onChangeProp,
     onFocus:           onFocusProp,
     onBlur:            onBlurProp,
@@ -218,7 +222,7 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
   } = options
 
   // ── Core instance ──────────────────────────────────────────────────────────
-  const digito = createDigito({ length, type, pattern, pasteTransformer, onInvalidChar, onComplete, onExpire, onResend, haptic, sound })
+  const digito = createDigito({ length, type, pattern, pasteTransformer, onInvalidChar, onComplete, onExpire, onResend, haptic, sound, readOnly: readOnlyOpt })
 
   // ── Reactive state ─────────────────────────────────────────────────────────
   const slotValues   = ref<string[]>(Array(length).fill(''))
@@ -248,6 +252,14 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
     spellcheck:     'false',
     autocorrect:    'off',
     autocapitalize: 'off',
+    ...(readOnlyOpt ? { 'aria-readonly': 'true' } : {}),
+  }))
+
+  const wrapperAttrs = computed<Record<string, string | undefined>>(() => ({
+    ...(isComplete.value ? { 'data-complete': '' } : {}),
+    ...(hasError.value   ? { 'data-invalid':  '' } : {}),
+    ...(isDisabled.value ? { 'data-disabled': '' } : {}),
+    ...(readOnlyOpt      ? { 'data-readonly': '' } : {}),
   }))
 
   // ── sync() ─────────────────────────────────────────────────────────────────
@@ -298,6 +310,15 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
   let timerControls: ReturnType<typeof createTimer> | null = null
 
   onMounted(() => {
+    if (controlledValue === undefined && defaultValue) {
+      const filtered = filterString(defaultValue.slice(0, length), type, pattern)
+      if (filtered) {
+        for (let i = 0; i < filtered.length; i++) digito.inputChar(i, filtered[i])
+        digito.cancelPendingComplete()
+        sync(true)
+        if (inputRef.value) { inputRef.value.value = filtered; inputRef.value.setSelectionRange(filtered.length, filtered.length) }
+      }
+    }
     if (autoFocusOpt && !initialDisabled && inputRef.value) {
       inputRef.value.focus()
       inputRef.value.setSelectionRange(0, 0)
@@ -320,10 +341,17 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
     const pos = inputRef.value?.selectionStart ?? 0
     if (e.key === 'Backspace') {
       e.preventDefault()
+      if (readOnlyOpt) return
       digito.deleteChar(pos)
       sync()
       const next = digito.state.activeSlot
       requestAnimationFrame(() => inputRef.value?.setSelectionRange(next, next))
+    } else if (e.key === 'Delete') {
+      e.preventDefault()
+      if (readOnlyOpt) return
+      digito.clearSlot(pos)
+      sync()
+      requestAnimationFrame(() => inputRef.value?.setSelectionRange(pos, pos))
     } else if (e.key === 'ArrowLeft') {
       e.preventDefault()
       digito.moveFocusLeft(pos)
@@ -354,7 +382,7 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
   }
 
   function onChange(e: Event): void {
-    if (isDisabled.value) return
+    if (isDisabled.value || readOnlyOpt) return
     const raw = (e.target as HTMLInputElement).value
     if (!raw) {
       digito.resetState()
@@ -375,7 +403,7 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
   }
 
   function onPaste(e: ClipboardEvent): void {
-    if (isDisabled.value) return
+    if (isDisabled.value || readOnlyOpt) return
     e.preventDefault()
     const text = e.clipboardData?.getData('text') ?? ''
     const pos  = inputRef.value?.selectionStart ?? 0
@@ -449,6 +477,7 @@ export function useOTP(options: VueOTPOptions = {}): UseOTPResult {
     placeholder:    placeholderOpt,
     inputRef,
     hiddenInputAttrs,
+    wrapperAttrs,
     getCode,
     reset,
     setError,

package/src/adapters/web-component.ts

@@ -45,6 +45,7 @@ import {
   createDigito,
   createTimer,
   filterString,
+  formatCountdown,
   type InputType,
 } from '../core/index.js'
 
@@ -208,16 +209,6 @@ const STYLES = `
   .digito-wc-resend-btn:disabled { color: #A1A1A1; cursor: not-allowed; background: #F5F5F5; }
 `
 
-// ─────────────────────────────────────────────────────────────────────────────
-// HELPERS
-// ─────────────────────────────────────────────────────────────────────────────
-
-function formatCountdown(totalSeconds: number): string {
-  const m = Math.floor(totalSeconds / 60)
-  const s = totalSeconds % 60
-  return m > 0 ? `${m}:${String(s).padStart(2, '0')}` : `0:${String(s).padStart(2, '0')}`
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // WEB COMPONENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -228,7 +219,7 @@ class DigitoInput extends HTMLElement {
    * Any change to these attributes causes a full shadow DOM rebuild so the
    * component always reflects its attribute state without manual reconciliation.
    */
-  static observedAttributes = ['length', 'type', 'timer', 'resend-after', 'disabled', 'separator-after', 'separator', 'masked', 'mask-char', 'name', 'placeholder', 'auto-focus', 'select-on-focus', 'blur-on-complete']
+  static observedAttributes = ['length', 'type', 'timer', 'resend-after', 'disabled', 'readonly', 'separator-after', 'separator', 'masked', 'mask-char', 'name', 'placeholder', 'auto-focus', 'select-on-focus', 'blur-on-complete', 'default-value']
 
   // Shadow DOM references — rebuilt in full on every attributeChangedCallback.
   private slotEls:        HTMLDivElement[]              = []
@@ -245,6 +236,7 @@ class DigitoInput extends HTMLElement {
   // Runtime mutable state — toggled by setDisabled() without a full rebuild.
   private _isDisabled  = false
   private _isSuccess   = false
+  private _isReadOnly  = false
 
   // JS-property-only options. These cannot be expressed as HTML attributes
   // (RegExp and functions are not serialisable to strings), so they are stored
@@ -375,6 +367,8 @@ class DigitoInput extends HTMLElement {
     return isNaN(v) || v < 1 ? 30 : Math.floor(v)
   }
   private get _disabledAttr():    boolean   { return this.hasAttribute('disabled') }
+  private get _readOnlyAttr():    boolean   { return this.hasAttribute('readonly') }
+  private get _defaultValue():    string    { return this.getAttribute('default-value') ?? '' }
   /** Parses `separator-after="2,4"` into `[2, 4]`. Filters NaN and zero values. */
   private get _separatorAfter():  number[]  {
     const v = this.getAttribute('separator-after')
@@ -418,6 +412,7 @@ class DigitoInput extends HTMLElement {
     const selectOnFocus      = this._selectOnFocus
     const blurOnComplete     = this._blurOnComplete
     this._isDisabled         = this._disabledAttr
+    this._isReadOnly         = this._readOnlyAttr
 
     this.timerCtrl?.stop()
     this.resendCountdown?.stop()
@@ -495,6 +490,7 @@ class DigitoInput extends HTMLElement {
       pattern:          this._pattern,
       pasteTransformer: this._pasteTransformer,
       onInvalidChar:    this._onInvalidChar,
+      readOnly:         this._isReadOnly,
       onComplete: (code) => {
         // Call JS property setter AND dispatch CustomEvent
         this._onComplete?.(code)
@@ -573,6 +569,19 @@ class DigitoInput extends HTMLElement {
       })
     }
 
+    if (this._isReadOnly) hiddenInput.setAttribute('aria-readonly', 'true')
+
+    // Apply defaultValue once on build — no onComplete, no change event
+    const dv = this._defaultValue
+    if (dv) {
+      const filtered = filterString(dv.slice(0, length), type, this._pattern)
+      if (filtered) {
+        for (let i = 0; i < filtered.length; i++) this.digito!.inputChar(i, filtered[i])
+        this.digito!.cancelPendingComplete()
+        hiddenInput.value = filtered
+      }
+    }
+
     this.attachEvents(selectOnFocus, blurOnComplete)
 
     if (this._isDisabled) this.applyDisabledDOM(true)
@@ -645,6 +654,11 @@ class DigitoInput extends HTMLElement {
     // resets selectionStart/End in some browsers, clobbering the cursor.
     const newValue = slotValues.join('')
     if (this.hiddenInput.value !== newValue) this.hiddenInput.value = newValue
+
+    this.toggleAttribute('data-complete', this.digito.state.isComplete)
+    this.toggleAttribute('data-invalid',  this.digito.state.hasError)
+    this.toggleAttribute('data-disabled', this._isDisabled)
+    this.toggleAttribute('data-readonly', this._isReadOnly)
   }
 
   /**
@@ -679,11 +693,19 @@ class DigitoInput extends HTMLElement {
       const pos = input.selectionStart ?? 0
       if (e.key === 'Backspace') {
         e.preventDefault()
+        if (this._isReadOnly) return
         digito.deleteChar(pos)
         this.syncSlotsToDOM()
         this.dispatchChange()
         const next = digito.state.activeSlot
         requestAnimationFrame(() => input.setSelectionRange(next, next))
+      } else if (e.key === 'Delete') {
+        e.preventDefault()
+        if (this._isReadOnly) return
+        digito.clearSlot(pos)
+        this.syncSlotsToDOM()
+        this.dispatchChange()
+        requestAnimationFrame(() => input.setSelectionRange(pos, pos))
       } else if (e.key === 'ArrowLeft') {
         e.preventDefault()
         digito.moveFocusLeft(pos)
@@ -712,7 +734,7 @@ class DigitoInput extends HTMLElement {
     })
 
     input.addEventListener('input', () => {
-      if (this._isDisabled) return
+      if (this._isDisabled || this._isReadOnly) return
       const raw = input.value
       if (!raw) {
         digito.resetState()
@@ -737,7 +759,7 @@ class DigitoInput extends HTMLElement {
     })
 
     input.addEventListener('paste', (e) => {
-      if (this._isDisabled) return
+      if (this._isDisabled || this._isReadOnly) return
       e.preventDefault()
       const text = e.clipboardData?.getData('text') ?? ''
       const pos  = input.selectionStart ?? 0

package/src/core/index.ts

@@ -11,6 +11,6 @@
 
 export type { InputType, DigitoState, DigitoOptions, TimerOptions, TimerControls, StateListener } from './types.js'
 export { filterChar, filterString }                from './filter.js'
-export { createTimer }                             from './timer.js'
+export { createTimer, formatCountdown }            from './timer.js'
 export { triggerHapticFeedback, triggerSoundFeedback } from './feedback.js'
 export { createDigito }                            from './machine.js'

package/src/core/machine.ts

@@ -73,6 +73,8 @@ export function createDigito(options: DigitoOptions = {}) {
   // requiring the instance to be recreated. Adapters that pass disabled at
   // construction time still work — the initial value is honoured.
   let disabled = options.disabled ?? false
+  // `readOnly` allows focus/navigation while blocking all slot mutations.
+  let readOnly = options.readOnly ?? false
 
   let state: DigitoState = {
     slotValues:   Array(length).fill('') as string[],
@@ -140,7 +142,7 @@ export function createDigito(options: DigitoOptions = {}) {
    * Out-of-bounds indices are silently ignored to prevent sparse-array corruption.
    */
   function inputChar(slotIndex: number, char: string): DigitoState {
-    if (disabled) return state
+    if (disabled || readOnly) return state
     if (slotIndex < 0 || slotIndex >= length) return state
     const validChar = filterChar(char, type, pattern)
     if (!validChar) {
@@ -176,7 +178,7 @@ export function createDigito(options: DigitoOptions = {}) {
    * Clears the current slot if filled, otherwise clears the previous slot and moves back.
    */
   function deleteChar(slotIndex: number): DigitoState {
-    if (disabled) return state
+    if (disabled || readOnly) return state
     if (slotIndex < 0 || slotIndex >= length) return state
     const slotValues = [...state.slotValues]
 
@@ -210,7 +212,7 @@ export function createDigito(options: DigitoOptions = {}) {
    *   paste(0, '84AB91') → filtered='8491', fills slots 0–3, slots 4–5 unchanged
    */
   function pasteString(cursorSlot: number, rawText: string): DigitoState {
-    if (disabled) return state
+    if (disabled || readOnly) return state
 
     let transformed: string
     try {
@@ -261,6 +263,20 @@ export function createDigito(options: DigitoOptions = {}) {
     return newState
   }
 
+  /**
+   * Clear the slot at slotIndex without moving focus.
+   * Used by the Delete key — differs from deleteChar (backspace) which steps the cursor back.
+   * Returns early when the slot is already empty, the field is disabled, or readOnly.
+   */
+  function clearSlot(slotIndex: number): DigitoState {
+    if (disabled || readOnly) return state
+    if (slotIndex < 0 || slotIndex >= length) return state
+    if (!state.slotValues[slotIndex]) return state
+    const slotValues = [...state.slotValues]
+    slotValues[slotIndex] = ''
+    return applyState({ slotValues, activeSlot: slotIndex, isComplete: false })
+  }
+
   /** Set or clear the error state. Triggers haptic feedback when setting. */
   function setError(isError: boolean): DigitoState {
     if (isError && haptic) triggerHapticFeedback()
@@ -299,6 +315,14 @@ export function createDigito(options: DigitoOptions = {}) {
     disabled = value
   }
 
+  /**
+   * Toggle readOnly at runtime. When `true`, all slot mutations are blocked
+   * but navigation and focus remain fully functional.
+   */
+  function setReadOnly(value: boolean): void {
+    readOnly = value
+  }
+
   /**
    * Subscribe to state changes. The listener is called after every mutation
    * with a shallow copy of the new state.
@@ -325,6 +349,7 @@ export function createDigito(options: DigitoOptions = {}) {
     // Input actions
     inputChar,
     deleteChar,
+    clearSlot,
     moveFocusLeft,
     moveFocusRight,
     pasteString,
@@ -348,6 +373,9 @@ export function createDigito(options: DigitoOptions = {}) {
      */
     setDisabled,
 
+    /** Toggle readOnly at runtime. Blocks mutations, preserves navigation. */
+    setReadOnly,
+
     /** Returns the current joined code string. */
     getCode:     () => joinSlots(state.slotValues),
     /**

package/src/core/timer.ts

@@ -73,3 +73,18 @@ export function createTimer(options: TimerOptions): TimerControls {
 
   return { start, stop, reset, restart }
 }
+
+/**
+ * Format a second count as a `m:ss` countdown string (e.g. `"1:05"`, `"0:30"`).
+ * Used by the vanilla, alpine, and web-component adapters for their built-in timer UI.
+ *
+ * @example formatCountdown(65) → "1:05"
+ * @example formatCountdown(9)  → "0:09"
+ */
+export function formatCountdown(totalSeconds: number): string {
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  return minutes > 0
+    ? `${minutes}:${String(seconds).padStart(2, '0')}`
+    : `0:${String(seconds).padStart(2, '0')}`
+}

package/src/core/types.ts

@@ -40,11 +40,25 @@ export type DigitoOptions = {
   resendAfter?:  number
   /** Called with the joined code string when all slots are filled. */
   onComplete?:   (code: string) => void
-  /** Called every second with the remaining seconds. Use to drive a custom timer UI. */
+  /**
+   * Called every second with the remaining seconds. Use to drive a custom timer UI.
+   *
+   * **Adapter note:** Only fires in adapters that include a built-in countdown timer
+   * (vanilla, alpine, web component). In React, Vue, and Svelte the timer is managed
+   * separately inside each adapter — pass `onTick` as part of those adapters' options.
+   * Has no effect when passed directly to `createDigito`.
+   */
   onTick?:       (remainingSeconds: number) => void
   /** Called when the countdown reaches zero. */
   onExpire?:     () => void
-  /** Called when the resend action is triggered. */
+  /**
+   * Called when the resend action is triggered.
+   *
+   * **Adapter note:** Only fires automatically in adapters with a built-in Resend button
+   * (vanilla, alpine, web component). In React, Vue, and Svelte there is no built-in
+   * Resend button — call `onResend` manually in your own UI handler.
+   * Has no effect when passed directly to `createDigito`.
+   */
   onResend?:     () => void
   /** Vibrate on completion and error via `navigator.vibrate`. Default: `true`. */
   haptic?:       boolean
@@ -127,6 +141,20 @@ export type DigitoOptions = {
    * Default: `false`.
    */
   blurOnComplete?: boolean
+  /**
+   * Uncontrolled initial value applied once on mount.
+   * Distributed across slots exactly like user input but does NOT trigger
+   * `onComplete` or fire change events. Ignored when a `value` prop is present.
+   * Default: `undefined` (no pre-fill).
+   */
+  defaultValue?: string
+  /**
+   * When `true`, all slot mutations (typing, backspace, delete, paste) are
+   * blocked while focus, selection, arrow navigation, and copy remain allowed.
+   * Semantically distinct from `disabled` — the field is readable and focusable.
+   * Default: `false`.
+   */
+  readOnly?: boolean
   /**
    * Called when the user types or pastes a character that is rejected by the
    * current `type` or `pattern` filter.

package/src/index.ts

@@ -6,7 +6,6 @@
  *
  * @author  Olawale Balo — Product Designer + Design Engineer
  * @license MIT
- * @version 1.0.0
  */
 
 // Core — pure logic, zero DOM