digitojs 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.2.0] — 2026-03-14
+
+### Added
+
+- `Delete` key support — clears current slot, stays in place, no backward movement
+- `defaultValue` option — uncontrolled pre-fill on mount, plain string, runs once, does not trigger `onComplete`
+- `readOnly` mode — display and copy, no edit, visually and semantically distinct from `disabled`
+- `data-complete`, `data-invalid`, `data-disabled`, `data-readonly` attributes on the wrapper element across all adapters — boolean presence attributes that mirror field state, compatible with Tailwind `data-*` variants and plain CSS attribute selectors
+
+## [1.0.1] — 2026-03-14
+
+### Changed
+
+- Live demo URL updated to `https://digitojs.vercel.app` in README
+
 ## [1.0.0] — 2026-03-14
 
 ### Added

package/README.md

@@ -1,4 +1,4 @@
-<a href="https://usedigito.vercel.app" target="_blank">
+<a href="https://digitojs.vercel.app" target="_blank">
   <img src="https://raw.githubusercontent.com/theolawalemi/digito/refs/heads/main/assets/banner.png" alt="Digito — Live Demo" width="100%" />
 </a>
 
@@ -13,7 +13,7 @@
 </p>
 
 <p align="center">
-  <a href="https://usedigito.vercel.app"><img src="https://img.shields.io/badge/usedigito.vercel.app-0A0A0A?style=flat-square&logo=vercel&logoColor=white" alt="Live demo" /></a>
+  <a href="https://digitojs.vercel.app"><img src="https://img.shields.io/badge/digitojs.vercel.app-0A0A0A?style=flat-square&logo=vercel&logoColor=white" alt="Live demo" /></a>
   <a href="https://www.npmjs.com/package/digitojs"><img src="https://img.shields.io/npm/v/digitojs?style=flat-square&color=0A0A0A" alt="npm" /></a>
   <a href="https://bundlephobia.com/package/digitojs"><img src="https://img.shields.io/bundlephobia/minzip/digitojs?style=flat-square&color=0A0A0A&label=gzip" /></a>
   <img src="https://img.shields.io/badge/zero_dependencies-0A0A0A?style=flat-square" />
@@ -50,6 +50,9 @@ The core is a **pure state machine** with no DOM or framework dependencies, wrap
 - **`onComplete` deferral** — fires after DOM sync; cancellable without clearing slot values
 - **Native form support** — `name` option wires the hidden input into `<form>` / `FormData`
 - **Fully accessible** — single ARIA-labelled input, `inputMode`, `autocomplete="one-time-code"`, all visual elements `aria-hidden`
+- **`readOnly` mode** — field stays focusable and copyable but blocks all mutations; semantically distinct from `disabled`
+- **`defaultValue`** — uncontrolled pre-fill applied once on mount without triggering `onComplete`
+- **Data attribute state hooks** — `data-complete`, `data-invalid`, `data-disabled`, `data-readonly` set on the wrapper across all adapters for Tailwind `data-*` variant and plain CSS attribute styling
 - **CDN-ready** — two IIFE bundles for no-build usage
 
 ---
@@ -68,6 +71,8 @@ The core is a **pure state machine** with no DOM or framework dependencies, wrap
 | Haptic + sound feedback | ✅ | ✗ | ✗ |
 | `blurOnComplete` (auto-advance) | ✅ | ✗ | ✗ |
 | `onInvalidChar` callback | ✅ | ✗ | ✗ |
+| `readOnly` mode (focusable, no mutations) | ✅ | ✗ | ✗ |
+| Data attribute state hooks | ✅ | ✗ | ✗ |
 | Vanilla JS | ✅ | ✗ | ✗ |
 | Vue | ✅ | ✗ | ✗ |
 | Svelte | ✅ | ✗ | ✗ |
@@ -123,6 +128,8 @@ yarn add digitojs
 
 Digito injects the slot inputs, styles, countdown badge, and resend button automatically. Nothing else to configure.
 
+> **Note:** `verify(code)`, `sendOTP()`, and similar functions used throughout the examples are placeholder names — replace them with your own API calls or application logic.
+
 ---
 
 ## Usage
@@ -140,6 +147,8 @@ Digito injects the slot inputs, styles, countdown badge, and resend button autom
 | Native form submission | `name: 'otp_code'` |
 | Async verification with lock | `setDisabled(true/false)` around API call |
 | Auto-advance after entry | `blurOnComplete: true` |
+| Pre-fill on mount (uncontrolled) | `defaultValue: '123456'` |
+| Display-only / read-only field | `readOnly: true` |
 
 ---
 
@@ -197,7 +206,7 @@ export function OTPInput() {
   })
 
   return (
-    <div style={{ position: 'relative', display: 'inline-flex', gap: 10 }}>
+    <div {...otp.wrapperProps} style={{ position: 'relative', display: 'inline-flex', gap: 10 }}>
       <HiddenOTPInput {...otp.hiddenInputProps} />
 
       {otp.slotValues.map((_, i) => {
@@ -241,7 +250,7 @@ const otp = useOTP({ length: 6, onComplete: (code) => verify(code) })
 </script>
 
 <template>
-  <div style="position: relative; display: inline-flex; gap: 10px">
+  <div v-bind="otp.wrapperAttrs.value" style="position: relative; display: inline-flex; gap: 10px">
     <input
       :ref="(el) => (otp.inputRef.value = el as HTMLInputElement)"
       v-bind="otp.hiddenInputAttrs"
@@ -252,18 +261,22 @@ const otp = useOTP({ length: 6, onComplete: (code) => verify(code) })
       @focus="otp.onFocus"
       @blur="otp.onBlur"
     />
-    <div
-      v-for="(char, i) in otp.slotValues.value"
-      :key="i"
-      class="slot"
-      :class="{
-        'is-active':  i === otp.activeSlot.value && otp.isFocused.value,
-        'is-filled':  !!char,
-        'is-error':   otp.hasError.value,
-      }"
-    >
-      {{ char }}
-    </div>
+    <template v-for="(char, i) in otp.slotValues.value" :key="i">
+      <span
+        v-if="otp.separatorAfter.value && i === otp.separatorAfter.value"
+        aria-hidden="true"
+      >{{ otp.separator.value }}</span>
+      <div
+        class="slot"
+        :class="{
+          'is-active':  i === otp.activeSlot.value && otp.isFocused.value,
+          'is-filled':  !!char,
+          'is-error':   otp.hasError.value,
+        }"
+      >
+        {{ char || otp.placeholder }}
+      </div>
+    </template>
   </div>
 </template>
 ```
@@ -287,20 +300,23 @@ code.value = ''  // resets the field reactively
   const otp = useOTP({ length: 6, onComplete: (code) => verify(code) })
 </script>
 
-<div style="position: relative; display: inline-flex; gap: 10px">
+<div {...$otp.wrapperAttrs} style="position: relative; display: inline-flex; gap: 10px">
   <input
     use:otp.action
     style="position: absolute; inset: 0; opacity: 0; z-index: 1"
   />
 
   {#each $otp.slotValues as char, i}
+    {#if $otp.separatorAfter && i === $otp.separatorAfter}
+      <span aria-hidden="true">{$otp.separator}</span>
+    {/if}
     <div
       class="slot"
       class:is-active={i === $otp.activeSlot}
       class:is-filled={!!char}
       class:is-error={$otp.hasError}
     >
-      {char}
+      {char || otp.placeholder}
     </div>
   {/each}
 </div>
@@ -414,6 +430,7 @@ const otp = useOTP(options)
 | Property | Type | Description |
 |---|---|---|
 | `hiddenInputProps` | `object` | Spread onto the `<input>` or use `<HiddenOTPInput>` |
+| `wrapperProps` | `object` | Spread onto the wrapper `<div>` — carries `data-*` state attributes |
 | `slotValues` | `string[]` | Current character per slot (`''` = empty) |
 | `activeSlot` | `number` | Zero-based index of the focused slot |
 | `isComplete` | `boolean` | All slots filled |
@@ -421,13 +438,17 @@ const otp = useOTP(options)
 | `isDisabled` | `boolean` | Disabled state active |
 | `isFocused` | `boolean` | Hidden input has browser focus |
 | `timerSeconds` | `number` | Remaining countdown seconds |
+| `separatorAfter` | `number \| number[]` | Separator position(s) for JSX rendering |
+| `separator` | `string` | Separator character to render |
 | `getSlotProps(i)` | `(number) => SlotRenderProps` | Full render metadata for slot `i` |
 | `getCode()` | `() => string` | Joined code string |
 | `reset()` | `() => void` | Clear all slots, restart timer |
 | `setError(bool)` | `(boolean) => void` | Toggle error state |
-| `setDisabled(bool)` | `(boolean) => void` | Toggle disabled state |
 | `focus(i)` | `(number) => void` | Move focus to slot |
 
+> **Note:** React does not expose a `setDisabled()` method. Pass `disabled` as an option prop instead — update it via your component's state (e.g. `const [isVerifying, setIsVerifying] = useState(false)` → `useOTP({ disabled: isVerifying })`).
+
+
 **`SlotRenderProps`** (from `getSlotProps(i)`):
 
 | Prop | Type | Description |
@@ -460,7 +481,8 @@ const otp = useOTP(options)
 
 | Property | Type | Description |
 |---|---|---|
-| `hiddenInputAttrs` | `object` | Bind with `v-bind` |
+| `hiddenInputAttrs` | `object` | Bind with `v-bind` on the hidden `<input>` |
+| `wrapperAttrs` | `Ref<object>` | Bind with `v-bind` on the wrapper element — carries `data-*` state attributes |
 | `inputRef` | `Ref<HTMLInputElement \| null>` | Bind with `:ref` |
 | `slotValues` | `Ref<string[]>` | Current slot values |
 | `activeSlot` | `Ref<number>` | Focused slot index |
@@ -472,6 +494,9 @@ const otp = useOTP(options)
 | `isDisabled` | `Ref<boolean>` | Disabled state active |
 | `masked` | `Ref<boolean>` | Masked mode active |
 | `maskChar` | `Ref<string>` | Configured mask glyph |
+| `separatorAfter` | `Ref<number \| number[]>` | Separator position(s) for template rendering |
+| `separator` | `Ref<string>` | Separator character to render |
+| `placeholder` | `string` | Placeholder character for empty slots |
 | `onKeydown` | handler | Bind with `@keydown` |
 | `onChange` | handler | Bind with `@input` |
 | `onPaste` | handler | Bind with `@paste` |
@@ -499,12 +524,16 @@ const otp = useOTP(options)
 |---|---|---|
 | `subscribe` | Store | Subscribe to full OTP state |
 | `action` | Svelte action | Use with `use:otp.action` on the hidden `<input>` |
+| `wrapperAttrs` | `Readable<object>` | Spread with `{...$otp.wrapperAttrs}` on wrapper — carries `data-*` state attributes |
 | `value` | Derived store | Joined code string |
 | `isComplete` | Derived store | All slots filled |
 | `hasError` | Derived store | Error state |
 | `activeSlot` | Derived store | Focused slot index |
 | `timerSeconds` | Writable store | Remaining countdown |
 | `masked` | Writable store | Masked mode |
+| `separatorAfter` | Writable store | Separator position(s) for template rendering |
+| `separator` | Writable store | Separator character to render |
+| `placeholder` | `string` | Placeholder character for empty slots |
 | `getCode()` | `() => string` | Joined code |
 | `reset()` | `() => void` | Clear and reset |
 | `setError(bool)` | `(boolean) => void` | Toggle error |
@@ -535,6 +564,8 @@ otp.moveFocusTo(index)
 otp.setError(bool)
 otp.resetState()
 otp.setDisabled(bool)
+otp.setReadOnly(bool)        // toggle readOnly at runtime
+otp.clearSlot(slotIndex)     // clear slot in place (Delete key semantics)
 otp.cancelPendingComplete()  // cancel onComplete without clearing slots
 
 // Query
@@ -586,6 +617,20 @@ filterString('84AB91', 'numeric')   // → '8491'
 
 ---
 
+### `formatCountdown(totalSeconds)` — Utility
+
+Formats a second count as a `m:ss` string. Used internally by the built-in timer UI; exported for custom timer displays.
+
+```ts
+import { formatCountdown } from 'digitojs/core'
+
+formatCountdown(65)   // → "1:05"
+formatCountdown(30)   // → "0:30"
+formatCountdown(9)    // → "0:09"
+```
+
+---
+
 ## Configuration Options
 
 All options are accepted by every adapter unless otherwise noted.
@@ -616,6 +661,8 @@ All options are accepted by every adapter unless otherwise noted.
 | `separatorAfter` | `number \| number[]` | — | 1-based slot index/indices to insert a visual separator after |
 | `separator` | `string` | `'—'` | Separator character to render |
 | `disabled` | `boolean` | `false` | Disable all input on mount |
+| `readOnly` | `boolean` | `false` | Block mutations while keeping the field focusable and copyable |
+| `defaultValue` | `string` | — | Uncontrolled pre-fill applied once on mount; does not trigger `onComplete` |
 | `haptic` | `boolean` | `true` | `navigator.vibrate(10)` on completion and error |
 | `sound` | `boolean` | `false` | Play 880 Hz tone via Web Audio on completion |
 
@@ -630,27 +677,28 @@ Set on `.digito-wrapper` (vanilla) or `digito-input` (web component) to theme th
 ```css
 .digito-wrapper {
   /* Dimensions */
-  --digito-size:          56px;     /* slot width + height    */
-  --digito-gap:           12px;     /* gap between slots      */
-  --digito-radius:        10px;     /* slot border radius     */
-  --digito-font-size:     24px;     /* digit font size        */
+  --digito-size:          56px;             /* slot width + height    */
+  --digito-gap:           12px;             /* gap between slots      */
+  --digito-radius:        10px;             /* slot border radius     */
+  --digito-font-size:     24px;             /* digit font size        */
 
   /* Colors */
-  --digito-color:         #0A0A0A;  /* digit text color       */
-  --digito-bg:            #FAFAFA;  /* empty slot background  */
-  --digito-bg-filled:     #FFFFFF;  /* filled slot background */
-  --digito-border-color:  #E5E5E5;  /* default slot border    */
-  --digito-active-color:  #3D3D3D;  /* active border + ring   */
-  --digito-error-color:   #FB2C36;  /* error border + ring    */
-  --digito-success-color: #00C950;  /* success border + ring  */
-  --digito-caret-color:   #3D3D3D;  /* fake caret color       */
-  --digito-timer-color:   #5C5C5C;  /* footer text            */
-
-  /* Placeholder & separator */
-  --digito-placeholder-color: #D3D3D3;
-  --digito-placeholder-size:  16px;
-  --digito-separator-color:   #A1A1A1;
-  --digito-separator-size:    18px;
+  --digito-color:         #0A0A0A;        /* digit text color       */
+  --digito-bg:            #FAFAFA;        /* empty slot background  */
+  --digito-bg-filled:     #FFFFFF;        /* filled slot background */
+  --digito-border-color:  #E5E5E5;        /* default slot border    */
+  --digito-active-color:  #3D3D3D;        /* active border + ring   */
+  --digito-error-color:   #FB2C36;        /* error border + ring    */
+  --digito-success-color: #00C950;        /* success border + ring  */
+  --digito-caret-color:   #3D3D3D;        /* fake caret color       */
+  --digito-timer-color:   #5C5C5C;        /* footer text            */
+
+  /* Placeholder, separator & mask */
+  --digito-placeholder-color: #D3D3D3;    /* placeholder glyph color */
+  --digito-placeholder-size:  16px;         /* placeholder glyph size  */
+  --digito-separator-color:   #A1A1A1;    /* separator text color    */
+  --digito-separator-size:    18px;         /* separator font size     */
+  --digito-masked-size:       16px;         /* mask glyph font size    */
 }
 ```
 
@@ -663,6 +711,7 @@ Set on `.digito-wrapper` (vanilla) or `digito-input` (web component) to theme th
 | `.digito-slot.is-filled` | Slot contains a character |
 | `.digito-slot.is-error` | Error state is active |
 | `.digito-slot.is-success` | Success state is active |
+| `.digito-slot.is-disabled` | Field is disabled |
 | `.digito-caret` | The blinking caret inside the active empty slot |
 | `.digito-timer` | The "Code expires in…" countdown row |
 | `.digito-timer-badge` | The red pill countdown badge |
@@ -670,6 +719,28 @@ Set on `.digito-wrapper` (vanilla) or `digito-input` (web component) to theme th
 | `.digito-resend-btn` | The resend chip button |
 | `.digito-separator` | The visual separator between slot groups |
 
+### Data Attribute State Hooks
+
+All adapters set boolean presence attributes on the wrapper element that mirror the current field state — no extra JS needed. Works with Tailwind `data-*` variants and plain CSS attribute selectors.
+
+| Attribute | Set when |
+|---|---|
+| `data-complete` | All slots are filled |
+| `data-invalid` | Error state is active |
+| `data-disabled` | Field is disabled |
+| `data-readonly` | Field is in read-only mode |
+
+```css
+/* Plain CSS */
+.digito-wrapper[data-complete] { border-color: var(--digito-success-color); }
+.digito-wrapper[data-invalid]  { animation: shake 0.2s; }
+```
+
+```html
+<!-- Tailwind -->
+<div class="digito-wrapper data-[complete]:ring-green-500 data-[invalid]:ring-red-500"></div>
+```
+
 ---
 
 ## Accessibility
@@ -684,7 +755,7 @@ Digito is built with accessibility as a first-class concern:
 - **`maxLength`** — constrains native input to `length`.
 - **`type="password"` in masked mode** — triggers the OS password keyboard on mobile.
 - **Native form integration** — the `name` option wires the hidden input into `<form>` and `FormData`, compatible with any form submission approach.
-- **Keyboard navigation** — full keyboard support (`←`, `→`, `Backspace`, `Tab`). No mouse required.
+- **Keyboard navigation** — full keyboard support (`←`, `→`, `Backspace`, `Delete`, `Tab`). No mouse required.
 
 ---
 
@@ -694,6 +765,7 @@ Digito is built with accessibility as a first-class concern:
 |---|---|
 | `0–9` / `a–z` / `A–Z` | Fill current slot and advance focus |
 | `Backspace` | Clear current slot; step back if already empty |
+| `Delete` | Clear current slot; focus stays in place |
 | `←` | Move focus one slot left |
 | `→` | Move focus one slot right |
 | `Cmd/Ctrl+V` | Smart paste from cursor slot, wrapping if needed |
@@ -732,7 +804,7 @@ Digito is built with accessibility as a first-class concern:
 
 ```
 digitojs                → Vanilla JS adapter + core utilities
-digitojs/core           → createDigito, createTimer, filterChar, filterString (no DOM)
+digitojs/core           → createDigito, createTimer, formatCountdown, filterChar, filterString (no DOM)
 digitojs/react          → useOTP hook + HiddenOTPInput + SlotRenderProps
 digitojs/vue            → useOTP composable
 digitojs/svelte         → useOTP store + action
@@ -744,6 +816,7 @@ All exports are fully typed. Core utilities are also available from the main ent
 
 ```ts
 import { createDigito, createTimer, filterChar, filterString } from 'digitojs'
+import { formatCountdown } from 'digitojs/core'
 ```
 
 ---

package/dist/adapters/alpine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alpine.d.ts","sourceRoot":"","sources":["../../src/adapters/alpine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAUH,yEAAyE;AACzE,KAAK,mBAAmB,GAAG;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,KAAK,EAAO,MAAM,CAAA;IAClB,qEAAqE;IACrE,SAAS,EAAG,MAAM,EAAE,CAAA;CACrB,CAAA;AAED,kEAAkE;AAClE,KAAK,wBAAwB,GAAG;IAC9B,iFAAiF;IACjF,QAAQ,EAAO,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IACxC,qFAAqF;IACrF,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAA;IAC7E,wFAAwF;IACxF,OAAO,EAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACvC,qFAAqF;IACrF,MAAM,EAAS,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;CACxC,CAAA;AAED,kFAAkF;AAClF,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,wBAAwB,KAAK;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,KACrH,IAAI,CAAA;CACV,CAAA;AAoDD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,KAAG,IAshBnD,CAAA"}
+{"version":3,"file":"alpine.d.ts","sourceRoot":"","sources":["../../src/adapters/alpine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH,yEAAyE;AACzE,KAAK,mBAAmB,GAAG;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,KAAK,EAAO,MAAM,CAAA;IAClB,qEAAqE;IACrE,SAAS,EAAG,MAAM,EAAE,CAAA;CACrB,CAAA;AAED,kEAAkE;AAClE,KAAK,wBAAwB,GAAG;IAC9B,iFAAiF;IACjF,QAAQ,EAAO,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAA;IACxC,qFAAqF;IACrF,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,KAAK,IAAI,CAAA;IAC7E,wFAAwF;IACxF,OAAO,EAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IACvC,qFAAqF;IACrF,MAAM,EAAS,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;CACxC,CAAA;AAED,kFAAkF;AAClF,KAAK,YAAY,GAAG;IAClB,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,wBAAwB,KAAK;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,KACrH,IAAI,CAAA;CACV,CAAA;AAwCD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,YAAY,KAAG,IAyiBnD,CAAA"}

package/dist/adapters/alpine.js

@@ -23,17 +23,7 @@
  * @author  Olawale Balo — Product Designer + Design Engineer
  * @license MIT
  */
-import { createDigito, createTimer, filterString, } from '../core/index.js';
-// ─────────────────────────────────────────────────────────────────────────────
-// HELPERS
-// ─────────────────────────────────────────────────────────────────────────────
-function formatCountdown(totalSeconds) {
-    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')}`;
-}
+import { createDigito, createTimer, filterString, formatCountdown, } from '../core/index.js';
 // ─────────────────────────────────────────────────────────────────────────────
 // PLUGIN
 // ─────────────────────────────────────────────────────────────────────────────
@@ -68,10 +58,10 @@ export const DigitoAlpine = (Alpine) => {
             console.error('[x-digito] failed to evaluate expression:', err);
             options = {};
         }
-        const { length = 6, type = 'numeric', timer: timerSecs = 0, disabled: initialDisabled = false, onComplete, onExpire, onResend, onTick: onTickProp, haptic = true, sound = false, pattern, pasteTransformer, onInvalidChar, onChange: onChangeProp, onFocus: onFocusProp, onBlur: onBlurProp, separatorAfter: rawSepAfter = 0, separator = '—', resendAfter: resendCooldown = 30, masked = false, maskChar = '\u25CF', autoFocus = true, name: inputName, placeholder = '', selectOnFocus = false, blurOnComplete = false, } = options;
+        const { length = 6, type = 'numeric', timer: timerSecs = 0, disabled: initialDisabled = false, onComplete, onExpire, onResend, onTick: onTickProp, haptic = true, sound = false, pattern, pasteTransformer, onInvalidChar, onChange: onChangeProp, onFocus: onFocusProp, onBlur: onBlurProp, separatorAfter: rawSepAfter = 0, separator = '—', resendAfter: resendCooldown = 30, masked = false, maskChar = '\u25CF', autoFocus = true, name: inputName, placeholder = '', selectOnFocus = false, blurOnComplete = false, defaultValue = '', readOnly: readOnlyOpt = false, } = options;
         // Normalise separatorAfter to an array for consistent rendering
         const separatorAfterPositions = 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;
         // ── Build DOM ─────────────────────────────────────────────────────────────
@@ -156,7 +146,19 @@ export const DigitoAlpine = (Alpine) => {
         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 = null;
         let resendActionBtn = null;
@@ -309,6 +311,10 @@ export const DigitoAlpine = (Alpine) => {
             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 ─────────────────────────────────────────────────────────
         hiddenInputEl.addEventListener('keydown', (e) => {
@@ -317,12 +323,23 @@ export const DigitoAlpine = (Alpine) => {
             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);
@@ -358,7 +375,7 @@ export const DigitoAlpine = (Alpine) => {
             }
         });
         hiddenInputEl.addEventListener('input', () => {
-            if (isDisabled)
+            if (isDisabled || readOnlyOpt)
                 return;
             const raw = hiddenInputEl.value;
             if (!raw) {
@@ -384,7 +401,7 @@ export const DigitoAlpine = (Alpine) => {
             }
         });
         hiddenInputEl.addEventListener('paste', (e) => {
-            if (isDisabled)
+            if (isDisabled || readOnlyOpt)
                 return;
             e.preventDefault();
             const text = e.clipboardData?.getData('text') ?? '';
@@ -449,51 +466,44 @@ export const DigitoAlpine = (Alpine) => {
             hiddenInputEl.setSelectionRange(0, 0);
             syncSlotsToDOM();
         });
+        // ── Internal helpers (shared by public API methods below) ─────────────────
+        /** Tears down running timers and removes built-in footer elements from the DOM. */
+        function teardown() {
+            mainCountdown?.stop();
+            resendCountdown?.stop();
+            builtInFooterEl?.remove();
+            builtInResendRowEl?.remove();
+        }
+        /** Resets slot state, restarts timers, and restores focus — shared by reset() and resend(). */
+        function doReset() {
+            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.
+        ;
         wrapperEl._digito = {
             /** Returns the current joined code string (e.g. `"123456"`). */
             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) => {
                 if (isError)
@@ -548,10 +558,7 @@ export const DigitoAlpine = (Alpine) => {
         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();
             },
         };