digitojs 1.0.1 → 1.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "digitojs",
-  "version": "1.0.1",
-  "description": "The only framework-agnostic OTP input state machine powering React, Vue, Svelte, Alpine, Vanilla JS, and Web Components from a single core.",
+  "version": "1.2.1",
+  "description": "Reliable OTP inputs for any framework from a single core.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -71,6 +71,7 @@
     "verification-code",
     "one-time-password",
     "authentication",
+    "headless",
     "passcode",
     "otp-field",
     "react-otp",
@@ -85,6 +86,11 @@
     "typescript"
   ],
   "author": "Olawale Balo — Product Designer + Design Engineer",
+  "homepage": "https://digitojs.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theolawalemi/digito"
+  },
   "license": "MIT",
   "peerDependencies": {
     "react": ">=17",
@@ -106,4 +112,4 @@
     "typescript": "^5.4.0"
   },
   "type": "module"
-}
+}

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,14 +159,17 @@ 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 isReadOnly   = readOnlyOpt
     let successState = false
 
     // ── Build DOM ─────────────────────────────────────────────────────────────
@@ -267,8 +259,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 +430,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', isReadOnly)
     }
 
     // ── Event handlers ─────────────────────────────────────────────────────────
@@ -435,11 +443,19 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
       const pos = hiddenInputEl.selectionStart ?? 0
       if (e.key === 'Backspace') {
         e.preventDefault()
+        if (isReadOnly) 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 (isReadOnly) 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 +486,7 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     })
 
     hiddenInputEl.addEventListener('input', () => {
-      if (isDisabled) return
+      if (isDisabled || isReadOnly) return
       const raw = hiddenInputEl.value
       if (!raw) {
         digito.resetState()
@@ -495,7 +511,7 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
     })
 
     hiddenInputEl.addEventListener('paste', (e) => {
-      if (isDisabled) return
+      if (isDisabled || isReadOnly) return
       e.preventDefault()
       const text = e.clipboardData?.getData('text') ?? ''
       const pos  = hiddenInputEl.selectionStart ?? 0
@@ -557,6 +573,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 +605,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) => {
@@ -639,6 +651,22 @@ export const DigitoAlpine = (Alpine: AlpinePlugin): void => {
         }
       },
 
+      /**
+       * Toggle readOnly at runtime. When `true`, all slot mutations are blocked
+       * but focus, navigation, and copy remain fully functional.
+       * Distinct from `disabled` — no opacity/cursor change, `aria-readonly` is set.
+       */
+      setReadOnly: (value: boolean) => {
+        isReadOnly = value
+        digito.setReadOnly(value)
+        if (value) {
+          hiddenInputEl.setAttribute('aria-readonly', 'true')
+        } else {
+          hiddenInputEl.removeAttribute('aria-readonly')
+        }
+        syncSlotsToDOM()
+      },
+
       /**
        * Programmatically move focus to a specific slot index.
        * Focuses the hidden input and positions the cursor at `slotIndex`.
@@ -655,10 +683,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. */
@@ -110,6 +112,11 @@ export type UseOTPResult = {
   setError:       (isError: boolean) => void
   /** Enable or disable the field at runtime. */
   setDisabled:    (value: boolean) => void
+  /**
+   * Toggle readOnly at runtime. When `true`, all slot mutations are blocked
+   * but focus, navigation, and copy remain fully functional.
+   */
+  setReadOnly:    (value: boolean) => void
   /** Programmatically move focus to a slot index. */
   focus:          (slotIndex: number) => void
   /**
@@ -170,6 +177,8 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     pasteTransformer,
     onInvalidChar,
     value:             controlledValue,
+    defaultValue,
+    readOnly:          readOnlyOpt = false,
     onChange:          onChangeProp,
     onFocus:           onFocusProp,
     onBlur:            onBlurProp,
@@ -185,18 +194,20 @@ 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)
   const timerStore          = writable(timerSecs)
   const isDisabledStore     = writable(initialDisabled)
+  const isReadOnlyStore     = writable(readOnlyOpt)
   const separatorAfterStore = writable(separatorAfterOpt)
   const separatorStore      = writable(separatorOpt)
   const maskedStore         = writable(maskedOpt)
   const maskCharStore       = writable(maskCharOpt)
 
-  let inputEl: HTMLInputElement | null = null
+  let inputEl:    HTMLInputElement | null = null
+  let isReadOnly: boolean                = readOnlyOpt
 
   // ── sync() ─────────────────────────────────────────────────────────────────
   function sync(suppressOnChange = false): void {
@@ -232,6 +243,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 +278,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 +287,17 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
       const pos = node.selectionStart ?? 0
       if (e.key === 'Backspace') {
         e.preventDefault()
+        if (isReadOnly) return
         digito.deleteChar(pos)
         sync()
         const next = digito.state.activeSlot
         requestAnimationFrame(() => node.setSelectionRange(next, next))
+      } else if (e.key === 'Delete') {
+        e.preventDefault()
+        if (isReadOnly) return
+        digito.clearSlot(pos)
+        sync()
+        requestAnimationFrame(() => node.setSelectionRange(pos, pos))
       } else if (e.key === 'ArrowLeft') {
         e.preventDefault()
         digito.moveFocusLeft(pos)
@@ -301,7 +328,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     }
 
     function onChange(e: Event): void {
-      if (get(isDisabledStore)) return
+      if (get(isDisabledStore) || isReadOnly) return
       const raw = (e.target as HTMLInputElement).value
       if (!raw) {
         digito.resetState()
@@ -324,7 +351,7 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     }
 
     function onPaste(e: ClipboardEvent): void {
-      if (get(isDisabledStore)) return
+      if (get(isDisabledStore) || isReadOnly) return
       e.preventDefault()
       const text = e.clipboardData?.getData('text') ?? ''
       const pos  = node.selectionStart ?? 0
@@ -403,6 +430,19 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     digito.setDisabled(value)
   }
 
+  function setReadOnly(value: boolean): void {
+    isReadOnly = value
+    isReadOnlyStore.set(value)
+    digito.setReadOnly(value)
+    if (inputEl) {
+      if (value) {
+        inputEl.setAttribute('aria-readonly', 'true')
+      } else {
+        inputEl.removeAttribute('aria-readonly')
+      }
+    }
+  }
+
   function focus(slotIndex: number): void {
     digito.moveFocusTo(slotIndex)
     inputEl?.focus()
@@ -420,6 +460,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, isReadOnlyStore],
+    ([$s, $dis, $ro]: [DigitoState, boolean, boolean]) => ({
+      ...($s.isComplete ? { 'data-complete': '' } : {}),
+      ...($s.hasError   ? { 'data-invalid':  '' } : {}),
+      ...($dis          ? { 'data-disabled': '' } : {}),
+      ...($ro           ? { 'data-readonly': '' } : {}),
+    })
+  )
+
   return {
     subscribe:      store.subscribe,
     value,
@@ -433,11 +484,13 @@ export function useOTP(options: SvelteOTPOptions = {}): UseOTPResult {
     masked:         maskedStore,
     maskChar:       maskCharStore,
     placeholder:    placeholderOpt,
+    wrapperAttrs,
     action,
     getCode,
     reset,
     setError,
     setDisabled,
+    setReadOnly,
     setValue,
     focus,
   }