digitojs 1.0.0 → 1.2.0

package/src/adapters/alpine.ts

@@ -28,6 +28,7 @@ import {
   createDigito,
   createTimer,
   filterString,
+  formatCountdown,
   type DigitoOptions,
   type InputType,
 } from '../core/index.js'
@@ -96,18 +97,6 @@ type AlpineOTPOptions = DigitoOptions & {
   maskChar?:       string
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// HELPERS
-// ─────────────────────────────────────────────────────────────────────────────
-
-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')}`
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // PLUGIN
 // ─────────────────────────────────────────────────────────────────────────────
@@ -170,12 +159,14 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       placeholder        = '',
       selectOnFocus      = false,
       blurOnComplete     = false,
+      defaultValue       = '',
+      readOnly:          readOnlyOpt = false,
     } = options
 
     // Normalise separatorAfter to an array for consistent rendering
     const separatorAfterPositions: number[] = Array.isArray(rawSepAfter) ? rawSepAfter : [rawSepAfter]
 
-    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 })
 
     let isDisabled   = initialDisabled
     let successState = false
@@ -267,8 +258,19 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     hiddenInputEl.setAttribute('autocapitalize', 'off')
     hiddenInputEl.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;opacity:0;border:none;outline:none;background:transparent;color:transparent;caret-color:transparent;z-index:1;cursor:text;font-size:1px'
     if (inputName) hiddenInputEl.name = inputName
+    if (readOnlyOpt) hiddenInputEl.setAttribute('aria-readonly', 'true')
     wrapperEl.appendChild(hiddenInputEl)
 
+    // Apply defaultValue once on mount — no onComplete, no onChange
+    if (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()
+        hiddenInputEl.value = filtered
+      }
+    }
+
     // ── Built-in timer + resend (mirrors vanilla adapter) ──────────────────────
     let timerBadgeEl:       HTMLSpanElement   | null = null
     let resendActionBtn:    HTMLButtonElement | null = null
@@ -427,6 +429,11 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       // resets selectionStart/End in some browsers, clobbering the cursor.
       const newValue = slotValues.join('')
       if (hiddenInputEl.value !== newValue) hiddenInputEl.value = newValue
+
+      wrapperEl.toggleAttribute('data-complete', digito.state.isComplete)
+      wrapperEl.toggleAttribute('data-invalid',  digito.state.hasError)
+      wrapperEl.toggleAttribute('data-disabled', isDisabled)
+      wrapperEl.toggleAttribute('data-readonly', readOnlyOpt)
     }
 
     // ── Event handlers ─────────────────────────────────────────────────────────
@@ -435,11 +442,19 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       const pos = hiddenInputEl.selectionStart ?? 0
       if (e.key === 'Backspace') {
         e.preventDefault()
+        if (readOnlyOpt) return
         digito.deleteChar(pos)
         syncSlotsToDOM()
         onChangeProp?.(digito.getCode())
         const next = digito.state.activeSlot
         requestAnimationFrame(() => hiddenInputEl.setSelectionRange(next, next))
+      } else if (e.key === 'Delete') {
+        e.preventDefault()
+        if (readOnlyOpt) return
+        digito.clearSlot(pos)
+        syncSlotsToDOM()
+        onChangeProp?.(digito.getCode())
+        requestAnimationFrame(() => hiddenInputEl.setSelectionRange(pos, pos))
       } else if (e.key === 'ArrowLeft') {
         e.preventDefault()
         digito.moveFocusLeft(pos)
@@ -470,7 +485,7 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     })
 
     hiddenInputEl.addEventListener('input', () => {
-      if (isDisabled) return
+      if (isDisabled || readOnlyOpt) return
       const raw = hiddenInputEl.value
       if (!raw) {
         digito.resetState()
@@ -495,7 +510,7 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     })
 
     hiddenInputEl.addEventListener('paste', (e) => {
-      if (isDisabled) return
+      if (isDisabled || readOnlyOpt) return
       e.preventDefault()
       const text = e.clipboardData?.getData('text') ?? ''
       const pos  = hiddenInputEl.selectionStart ?? 0
@@ -557,6 +572,30 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       syncSlotsToDOM()
     })
 
+    // ── Internal helpers (shared by public API methods below) ─────────────────
+
+    /** Tears down running timers and removes built-in footer elements from the DOM. */
+    function teardown(): void {
+      mainCountdown?.stop()
+      resendCountdown?.stop()
+      builtInFooterEl?.remove()
+      builtInResendRowEl?.remove()
+    }
+
+    /** Resets slot state, restarts timers, and restores focus — shared by reset() and resend(). */
+    function doReset(): void {
+      digito.resetState()
+      hiddenInputEl.value = ''
+      if (timerBadgeEl)       timerBadgeEl.textContent = formatCountdown(timerSecs)
+      if (builtInFooterEl)    builtInFooterEl.style.display    = 'flex'
+      if (builtInResendRowEl) builtInResendRowEl.classList.remove('is-visible')
+      resendCountdown?.stop()
+      mainCountdown?.restart()
+      if (!isDisabled) hiddenInputEl.focus()
+      hiddenInputEl.setSelectionRange(0, 0)
+      syncSlotsToDOM()
+    }
+
     // ── Public API on element ──────────────────────────────────────────────────
     // Exposed on `el._digito` for programmatic control from Alpine components or
     // external JavaScript. Mirrors the DigitoInstance interface from the vanilla adapter.
@@ -565,41 +604,13 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       getCode:  () => digito.getCode(),
 
       /** Stop timers and remove built-in footer elements. Call before removing the element. */
-      destroy: () => {
-        mainCountdown?.stop()
-        resendCountdown?.stop()
-        builtInFooterEl?.remove()
-        builtInResendRowEl?.remove()
-      },
+      destroy: () => teardown(),
 
       /** Clear all slots, re-focus, reset to idle state, and restart the built-in timer. */
-      reset: () => {
-        digito.resetState()
-        hiddenInputEl.value = ''
-        if (timerBadgeEl)       timerBadgeEl.textContent = formatCountdown(timerSecs)
-        if (builtInFooterEl)    builtInFooterEl.style.display    = 'flex'
-        if (builtInResendRowEl) builtInResendRowEl.classList.remove('is-visible')
-        resendCountdown?.stop()
-        mainCountdown?.restart()
-        if (!isDisabled) hiddenInputEl.focus()
-        hiddenInputEl.setSelectionRange(0, 0)
-        syncSlotsToDOM()
-      },
+      reset: () => doReset(),
 
       /** Reset and fire the `onResend` callback. */
-      resend: () => {
-        digito.resetState()
-        hiddenInputEl.value = ''
-        if (timerBadgeEl)       timerBadgeEl.textContent = formatCountdown(timerSecs)
-        if (builtInFooterEl)    builtInFooterEl.style.display    = 'flex'
-        if (builtInResendRowEl) builtInResendRowEl.classList.remove('is-visible')
-        resendCountdown?.stop()
-        mainCountdown?.restart()
-        if (!isDisabled) hiddenInputEl.focus()
-        hiddenInputEl.setSelectionRange(0, 0)
-        syncSlotsToDOM()
-        onResend?.()
-      },
+      resend: () => { doReset(); onResend?.() },
 
       /** Apply or clear the error state on all visual slots. */
       setError: (isError: boolean) => {
@@ -655,10 +666,7 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     return {
       /** Alpine calls this when the component is destroyed. Stops timers and removes footer elements. */
       cleanup() {
-        mainCountdown?.stop()
-        resendCountdown?.stop()
-        builtInFooterEl?.remove()
-        builtInResendRowEl?.remove()
+        teardown()
         digito.resetState()
       },
     }

package/src/adapters/react.tsx

@@ -61,6 +61,13 @@ export type ReactOTPOptions = DigitoOptions & {
    * Compatible with react-hook-form via <Controller>.
    */
   value?: string
+  /**
+   * Uncontrolled initial value. Applied once on mount when `value` is undefined.
+   * Does not trigger `onComplete` or `onChange`.
+   */
+  defaultValue?: string
+  /** When `true`, mutations are blocked; focus/navigation/copy remain allowed. */
+  readOnly?: boolean
   /**
    * Fires exactly ONCE per user interaction with the current joined code string.
    * Receives partial values too — not just when the code is complete.
@@ -211,6 +218,8 @@ export type UseOTPResult = {
   setError:         (isError: boolean) => void
   /** Programmatically move focus to a specific slot index. */
   focus:            (slotIndex: number) => void
+  /** Spread onto the wrapper element to expose state as data attributes for CSS targeting. */
+  wrapperProps: Record<string, string | undefined>
   /**
    * The separator slot index/indices for JSX rendering.
    * Insert a visual divider AFTER each position. `0` / empty array = no separator.
@@ -268,6 +277,8 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
     pasteTransformer,
     onInvalidChar,
     value:           controlledValue,
+    defaultValue,
+    readOnly:        readOnlyProp = false,
     onChange:        onChangeProp,
     onFocus:         onFocusProp,
     onBlur:          onBlurProp,
@@ -308,6 +319,7 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
   const digitoRef = useRef(
     createDigito({
       length, type, haptic, sound, pattern, pasteTransformer,
+      readOnly:      readOnlyProp,
       onComplete:    (code) => onCompleteRef.current?.(code),
       onExpire:      ()     => onExpireRef.current?.(),
       onResend:      ()     => onResendRef.current?.(),
@@ -316,9 +328,13 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
   )
   const digito = digitoRef.current
 
-  // ── Disabled ref ───────────────────────────────────────────────────────────
-  const disabledRef = useRef(disabled)
-  useEffect(() => { disabledRef.current = disabled }, [disabled])
+  // ── Disabled / readOnly refs ────────────────────────────────────────────────
+  // Stored in refs so memoized callbacks (useCallback with [] deps) always read
+  // the latest value without needing to be recreated on every render.
+  const disabledRef  = useRef(disabled)
+  const readOnlyRef  = useRef(readOnlyProp)
+  useEffect(() => { disabledRef.current = disabled    }, [disabled])
+  useEffect(() => { readOnlyRef.current = readOnlyProp }, [readOnlyProp])
 
   // ── State ──────────────────────────────────────────────────────────────────
   const [state, setState]               = useState<DigitoState>(digito.state)
@@ -364,6 +380,19 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [controlledValue, length])
 
+  // ── defaultValue — applied once on mount when no controlled value is present ─
+  useEffect(() => {
+    if (controlledValue !== undefined || !defaultValue) return
+    const filtered = filterString(defaultValue.slice(0, length), type, pattern)
+    if (!filtered) return
+    digito.resetState()
+    for (let i = 0; i < filtered.length; i++) digito.inputChar(i, filtered[i])
+    digito.cancelPendingComplete()
+    setState({ ...digito.state })
+    if (inputRef.current) { inputRef.current.value = filtered; inputRef.current.setSelectionRange(filtered.length, filtered.length) }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
   // ── Timer ──────────────────────────────────────────────────────────────────
   useEffect(() => {
     if (!timerSecs) return
@@ -385,10 +414,17 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
     const pos = inputRef.current?.selectionStart ?? 0
     if (e.key === 'Backspace') {
       e.preventDefault()
+      if (readOnlyRef.current) return
       digito.deleteChar(pos)
       sync()
       const next = digito.state.activeSlot
       requestAnimationFrame(() => inputRef.current?.setSelectionRange(next, next))
+    } else if (e.key === 'Delete') {
+      e.preventDefault()
+      if (readOnlyRef.current) return
+      digito.clearSlot(pos)
+      sync()
+      requestAnimationFrame(() => inputRef.current?.setSelectionRange(pos, pos))
     } else if (e.key === 'ArrowLeft') {
       e.preventDefault()
       digito.moveFocusLeft(pos)
@@ -419,7 +455,7 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
   }, [])
 
   const onChange = useCallback((e: ChangeEvent<HTMLInputElement>) => {
-    if (disabledRef.current) return
+    if (disabledRef.current || readOnlyRef.current) return
     const raw = e.target.value
     if (!raw) {
       digito.resetState()
@@ -440,7 +476,7 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
   }, [type, length, blurOnComplete])
 
   const onPaste = useCallback((e: ClipboardEvent<HTMLInputElement>) => {
-    if (disabledRef.current) return
+    if (disabledRef.current || readOnlyRef.current) return
     e.preventDefault()
     const text = e.clipboardData.getData('text')
     const pos  = inputRef.current?.selectionStart ?? 0
@@ -525,6 +561,7 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
     spellCheck:     false,
     autoCorrect:    'off',
     autoCapitalize: 'off',
+    ...(readOnlyProp ? { 'aria-readonly': 'true' as const } : {}),
     onKeyDown,
     onChange,
     onPaste,
@@ -532,6 +569,13 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
     onBlur,
   }
 
+  const wrapperProps: Record<string, string | undefined> = {
+    ...(state.isComplete ? { 'data-complete': '' } : {}),
+    ...(state.hasError   ? { 'data-invalid':  '' } : {}),
+    ...(disabled         ? { 'data-disabled': '' } : {}),
+    ...(readOnlyProp     ? { 'data-readonly': '' } : {}),
+  }
+
   return {
     slotValues:    state.slotValues,
     activeSlot:    state.activeSlot,
@@ -548,6 +592,7 @@ export function useOTP(options: ReactOTPOptions = {}): UseOTPResult {
     separator,
     hiddenInputProps,
     getSlotProps,
+    wrapperProps,
   }
 }
 

package/src/adapters/svelte.ts

@@ -7,7 +7,7 @@
  * @license MIT
  */
 
-import { writable, derived, get } from 'svelte/store'
+import { writable, derived, get, type Readable, type Writable } from 'svelte/store'
 
 import {
   createDigito,
@@ -74,32 +74,34 @@ export type SvelteOTPOptions = DigitoOptions & {
 
 export type UseOTPResult = {
   /** Subscribe to the full state store. */
-  subscribe:      ReturnType<typeof writable>['subscribe']
+  subscribe:      Writable<DigitoState>['subscribe']
   /** Derived — joined code string. */
-  value:          ReturnType<typeof derived>
+  value:          Readable<string>
   /** Derived — completion boolean. */
-  isComplete:     ReturnType<typeof derived>
+  isComplete:     Readable<boolean>
   /** Derived — error boolean. */
-  hasError:       ReturnType<typeof derived>
+  hasError:       Readable<boolean>
   /** Derived — active slot index. */
-  activeSlot:     ReturnType<typeof derived>
+  activeSlot:     Readable<number>
   /** Remaining timer seconds store. */
-  timerSeconds:   ReturnType<typeof writable>
+  timerSeconds:   Writable<number>
   /** Whether the field is currently disabled. */
-  isDisabled:     ReturnType<typeof writable>
-  /** The separator slot index store. -1 = no separator. */
-  separatorAfter: ReturnType<typeof writable>
+  isDisabled:     Writable<boolean>
+  /** The separator slot index store. */
+  separatorAfter: Writable<number | number[]>
   /** The separator character store. */
-  separator:      ReturnType<typeof writable>
+  separator:      Writable<string>
   /** Whether masked mode is active. When true, templates should render `maskChar` instead of char. */
-  masked:         ReturnType<typeof writable>
+  masked:         Writable<boolean>
   /**
    * The configured mask glyph store. Use in templates instead of a hard-coded `●`:
    * `{$otp.masked && char ? $otp.maskChar : char}`
    */
-  maskChar:       ReturnType<typeof writable>
+  maskChar:       Writable<string>
   /** The placeholder character for empty slots. Empty string when not set. */
   placeholder:    string
+  /** Derived — spread onto the wrapper element as data attributes for CSS/Tailwind targeting. */
+  wrapperAttrs:   Readable<Record<string, string | undefined>>
   /** Svelte action to bind to the single hidden input. */
   action:         (node: HTMLInputElement) => { destroy: () => void }
   /** Returns the current joined code string. */
@@ -170,6 +172,8 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     pasteTransformer,
     onInvalidChar,
     value:             controlledValue,
+    defaultValue,
+    readOnly:          readOnlyOpt = false,
     onChange:          onChangeProp,
     onFocus:           onFocusProp,
     onBlur:            onBlurProp,
@@ -185,7 +189,7 @@ export function useOTP(options: SvelteOTPOptions = {}): 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 })
 
   // ── Stores ─────────────────────────────────────────────────────────────────
   const store               = writable(digito.state)
@@ -232,6 +236,14 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
 
   if (controlledValue !== undefined) {
     setValue(controlledValue)
+  } else if (defaultValue) {
+    // Apply defaultValue once — no onComplete, no onChange
+    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)
+    }
   }
 
   // ── Timer ──────────────────────────────────────────────────────────────────
@@ -259,6 +271,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     node.setAttribute('aria-label',      `Enter your ${length}-${type === 'numeric' ? 'digit' : 'character'} code`)
     node.setAttribute('autocorrect',     'off')
     node.setAttribute('autocapitalize',  'off')
+    if (readOnlyOpt) node.setAttribute('aria-readonly', 'true')
 
     const unsubDisabled = isDisabledStore.subscribe((v: boolean) => { node.disabled = v })
 
@@ -267,10 +280,17 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
       const pos = node.selectionStart ?? 0
       if (e.key === 'Backspace') {
         e.preventDefault()
+        if (readOnlyOpt) return
         digito.deleteChar(pos)
         sync()
         const next = digito.state.activeSlot
         requestAnimationFrame(() => node.setSelectionRange(next, next))
+      } else if (e.key === 'Delete') {
+        e.preventDefault()
+        if (readOnlyOpt) return
+        digito.clearSlot(pos)
+        sync()
+        requestAnimationFrame(() => node.setSelectionRange(pos, pos))
       } else if (e.key === 'ArrowLeft') {
         e.preventDefault()
         digito.moveFocusLeft(pos)
@@ -301,7 +321,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     }
 
     function onChange(e: Event): void {
-      if (get(isDisabledStore)) return
+      if (get(isDisabledStore) || readOnlyOpt) return
       const raw = (e.target as HTMLInputElement).value
       if (!raw) {
         digito.resetState()
@@ -324,7 +344,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     }
 
     function onPaste(e: ClipboardEvent): void {
-      if (get(isDisabledStore)) return
+      if (get(isDisabledStore) || readOnlyOpt) return
       e.preventDefault()
       const text = e.clipboardData?.getData('text') ?? ''
       const pos  = node.selectionStart ?? 0
@@ -420,6 +440,17 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
   const hasError   = derived(store, ($s: DigitoState) => $s.hasError)
   const activeSlot = derived(store, ($s: DigitoState) => $s.activeSlot)
 
+  // Derived wrapper data attributes for CSS/Tailwind targeting
+  const wrapperAttrs = derived(
+    [store, isDisabledStore],
+    ([$s, $dis]: [DigitoState, boolean]) => ({
+      ...($s.isComplete ? { 'data-complete': '' } : {}),
+      ...($s.hasError   ? { 'data-invalid':  '' } : {}),
+      ...($dis          ? { 'data-disabled': '' } : {}),
+      ...(readOnlyOpt   ? { 'data-readonly': '' } : {}),
+    })
+  )
+
   return {
     subscribe:      store.subscribe,
     value,
@@ -433,6 +464,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     masked:         maskedStore,
     maskChar:       maskCharStore,
     placeholder:    placeholderOpt,
+    wrapperAttrs,
     action,
     getCode,
     reset,

package/src/adapters/vanilla.ts

@@ -36,6 +36,7 @@ import {
   createDigito,
   createTimer,
   filterString,
+  formatCountdown,
   type DigitoOptions,
   type InputType,
 } from '../core/index.js'
@@ -89,7 +90,7 @@ const INJECTED_STYLE_ID = 'digito-styles'
  *   --digito-bg-filled         Slot background when filled  (default: #FFFFFF)
  *   --digito-color             Digit text colour            (default: #0A0A0A)
  *   --digito-border-color      Default slot border          (default: #E5E5E5)
- *   --digito-active-color      Active slot border + ring    (default: #757575)
+ *   --digito-active-color      Active slot border + ring    (default: #3D3D3D)
  *   --digito-error-color       Error border, ring + badge   (default: #FB2C36)
  *   --digito-success-color     Success border + ring        (default: #00C950)
  *   --digito-timer-color       Timer label text colour      (default: #5C5C5C)
@@ -237,6 +238,8 @@ function mountOnWrapper(
   const onExpire        = options.onExpire
   const pattern         = options.pattern
   let   isDisabled      = options.disabled    ?? false
+  const isReadOnly      = options.readOnly    ?? false
+  const defaultValue    = options.defaultValue ?? ''
 
   // New options
   const autoFocus      = options.autoFocus !== false         // default true
@@ -275,6 +278,7 @@ function mountOnWrapper(
     sound:            options.sound    ?? false,
     haptic:           options.haptic   ?? true,
     disabled:         isDisabled,
+    readOnly:         isReadOnly,
   })
 
   // ── Build DOM ────────────────────────────────────────────────────────────
@@ -330,6 +334,18 @@ function mountOnWrapper(
   rootEl.appendChild(hiddenInputEl)
   wrapperEl.appendChild(rootEl)
 
+  if (isReadOnly) hiddenInputEl.setAttribute('aria-readonly', 'true')
+
+  // Apply defaultValue once on mount — no onComplete, no onChange
+  if (defaultValue) {
+    const filtered = filterString(defaultValue.slice(0, slotCount), inputType, pattern)
+    if (filtered) {
+      for (let i = 0; i < filtered.length; i++) otpCore.inputChar(i, filtered[i])
+      otpCore.cancelPendingComplete()
+      hiddenInputEl.value = filtered
+    }
+  }
+
   // ── Password manager badge guard ─────────────────────────────────────────
   let disconnectPasswordManagerWatch: () => void = () => {}
   requestAnimationFrame(() => {
@@ -487,6 +503,12 @@ function mountOnWrapper(
     // resets selectionStart/End in some browsers, clobbering the cursor.
     const newValue = slotValues.join('')
     if (hiddenInputEl.value !== newValue) hiddenInputEl.value = newValue
+
+    // Expose component state as data attributes for CSS/Tailwind targeting
+    wrapperEl.toggleAttribute('data-complete', otpCore.state.isComplete)
+    wrapperEl.toggleAttribute('data-invalid',  otpCore.state.hasError)
+    wrapperEl.toggleAttribute('data-disabled', isDisabled)
+    wrapperEl.toggleAttribute('data-readonly', isReadOnly)
   }
 
   // ── Event handlers ────────────────────────────────────────────────────────
@@ -496,9 +518,16 @@ function mountOnWrapper(
 
     if (event.key === 'Backspace') {
       event.preventDefault()
+      if (isReadOnly) return
       otpCore.deleteChar(cursorPos)
       syncSlotsToDOM()
       hiddenInputEl.setSelectionRange(otpCore.state.activeSlot, otpCore.state.activeSlot)
+    } else if (event.key === 'Delete') {
+      event.preventDefault()
+      if (isReadOnly) return
+      otpCore.clearSlot(cursorPos)
+      syncSlotsToDOM()
+      hiddenInputEl.setSelectionRange(cursorPos, cursorPos)
     } else if (event.key === 'Tab') {
       if (event.shiftKey) {
         // Shift+Tab: move to previous slot, or exit to previous DOM element from first slot
@@ -532,6 +561,7 @@ function mountOnWrapper(
   }
 
   function onHiddenInputChange(_event: Event): void {
+    if (isReadOnly) return
     const rawValue = hiddenInputEl.value
 
     if (!rawValue) {
@@ -567,6 +597,7 @@ function mountOnWrapper(
 
   function onHiddenInputPaste(event: ClipboardEvent): void {
     event.preventDefault()
+    if (isReadOnly) return
     const pastedText = event.clipboardData?.getData('text') ?? ''
     const cursorPos  = hiddenInputEl.selectionStart ?? 0
     otpCore.pasteString(cursorPos, pastedText)
@@ -716,19 +747,6 @@ function mountOnWrapper(
 }
 
 
-// ─────────────────────────────────────────────────────────────────────────────
-// HELPERS
-// ─────────────────────────────────────────────────────────────────────────────
-
-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')}`
-}
-
-
 // ─────────────────────────────────────────────────────────────────────────────
 // PASSWORD MANAGER BADGE GUARD
 // ─────────────────────────────────────────────────────────────────────────────