digitojs 1.0.0

package/dist/core/machine.js

@@ -0,0 +1,328 @@
+/**
+ * digito/core/machine
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Pure OTP state machine — zero DOM, zero framework, zero side effects.
+ * All adapters import `createDigito` from here (via core/index.ts).
+ *
+ * Subscription system: pass a listener to `subscribe()` to be notified after
+ * every state mutation. Compatible with XState / Zustand-style patterns:
+ *
+ *   const otp = createDigito({ length: 6 })
+ *   const unsub = otp.subscribe(state => console.log(state))
+ *   // ... later:
+ *   unsub()
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+import { filterChar, filterString } from './filter.js';
+import { triggerHapticFeedback, triggerSoundFeedback } from './feedback.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// INTERNAL HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
+/** Returns `true` when every slot contains exactly one character. */
+function allSlotsFilled(slotValues) {
+    return slotValues.every(v => v.length === 1);
+}
+/** Clamp `index` to the inclusive range `[min, max]`. */
+function clampIndex(index, min, max) {
+    return Math.max(min, Math.min(max, index));
+}
+/** Join all slot values into a single string (the OTP code). */
+function joinSlots(slotValues) {
+    return slotValues.join('');
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// FACTORY
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Creates a pure OTP state machine.
+ * Returns action functions, a `state` getter, a `subscribe` method, and a
+ * `getState` snapshot helper — no DOM, no side effects.
+ */
+export function createDigito(options = {}) {
+    // Security: guard against invalid length values.
+    // Negative numbers would throw a RangeError from Array(); zero would produce
+    // a permanently-incomplete input with no slots. Clamp to a safe minimum of 1.
+    const rawLength = options.length ?? 6;
+    // Guard against NaN (e.g. parseInt('', 10) from a missing data-attribute).
+    // NaN would propagate through Math.floor and crash Array() with RangeError.
+    const length = isNaN(rawLength) ? 6 : Math.max(1, Math.floor(rawLength));
+    const { type = 'numeric', pattern, onComplete, onInvalidChar, haptic = true, sound = false, pasteTransformer, } = options;
+    // `disabled` is mutable so setDisabled() can toggle it at runtime without
+    // 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;
+    let state = {
+        slotValues: Array(length).fill(''),
+        activeSlot: 0,
+        hasError: false,
+        isComplete: false,
+        timerSeconds: options.timer ?? 0,
+    };
+    // ── Subscription set ──────────────────────────────────────────────────────
+    const listeners = new Set();
+    function applyState(patch) {
+        state = { ...state, ...patch };
+        // Notify all subscribers with a deep copy of slotValues so they cannot
+        // mutate the live array. A simple { ...state } is a shallow copy — the
+        // slotValues array reference would be shared, letting a subscriber silently
+        // corrupt internal state.
+        if (listeners.size > 0) {
+            const snapshot = { ...state, slotValues: [...state.slotValues] };
+            listeners.forEach(fn => fn(snapshot));
+        }
+        return state;
+    }
+    /**
+     * Handle for the pending onComplete timeout.
+     * Stored so resetState() can cancel it if the user clears the input
+     * within the 10ms defer window (e.g. rapid type-then-delete).
+     */
+    let completeTimeoutId = null;
+    /** Fire onComplete after a short delay so DOM sync can finish first. */
+    function notifyCompleteIfReady(slotValues) {
+        if (!allSlotsFilled(slotValues) || !onComplete)
+            return;
+        if (haptic)
+            triggerHapticFeedback();
+        if (sound)
+            triggerSoundFeedback();
+        const code = joinSlots(slotValues);
+        if (completeTimeoutId !== null)
+            clearTimeout(completeTimeoutId);
+        completeTimeoutId = setTimeout(() => {
+            completeTimeoutId = null;
+            onComplete(code);
+        }, 10);
+    }
+    /**
+     * Cancel any pending onComplete callback without clearing slot state.
+     * Use this after a programmatic fill (e.g. controlled-value sync in adapters)
+     * to prevent a parent-driven pre-fill from triggering onComplete as if the
+     * user had typed the code.
+     */
+    function cancelPendingComplete() {
+        if (completeTimeoutId !== null) {
+            clearTimeout(completeTimeoutId);
+            completeTimeoutId = null;
+        }
+    }
+    // ── Actions ────────────────────────────────────────────────────────────────
+    /**
+     * Process a single character typed into `slotIndex`.
+     * Invalid characters leave the slot unchanged and keep focus in place.
+     * Out-of-bounds indices are silently ignored to prevent sparse-array corruption.
+     */
+    function inputChar(slotIndex, char) {
+        if (disabled)
+            return state;
+        if (slotIndex < 0 || slotIndex >= length)
+            return state;
+        const validChar = filterChar(char, type, pattern);
+        if (!validChar) {
+            // Fire onInvalidChar for single rejected characters (not empty/multi-char)
+            if (char.length === 1)
+                onInvalidChar?.(char, slotIndex);
+            // Only notify subscribers if focus actually needs to move. Firing applyState
+            // when activeSlot is already slotIndex causes a spurious state notification
+            // on every invalid keystroke, which can trigger expensive re-renders.
+            if (state.activeSlot !== slotIndex) {
+                return applyState({ activeSlot: slotIndex });
+            }
+            return state;
+        }
+        const slotValues = [...state.slotValues];
+        slotValues[slotIndex] = validChar;
+        const nextSlot = slotIndex < length - 1 ? slotIndex + 1 : length - 1;
+        const newState = applyState({
+            slotValues,
+            activeSlot: nextSlot,
+            hasError: false,
+            isComplete: allSlotsFilled(slotValues),
+        });
+        notifyCompleteIfReady(slotValues);
+        return newState;
+    }
+    /**
+     * Handle backspace at `slotIndex`.
+     * Clears the current slot if filled, otherwise clears the previous slot and moves back.
+     */
+    function deleteChar(slotIndex) {
+        if (disabled)
+            return state;
+        if (slotIndex < 0 || slotIndex >= length)
+            return state;
+        const slotValues = [...state.slotValues];
+        if (slotValues[slotIndex]) {
+            slotValues[slotIndex] = '';
+            return applyState({ slotValues, activeSlot: slotIndex, isComplete: false });
+        }
+        const prevSlot = clampIndex(slotIndex - 1, 0, length - 1);
+        slotValues[prevSlot] = '';
+        return applyState({ slotValues, activeSlot: prevSlot, isComplete: false });
+    }
+    /** Move focus one slot to the left, clamped to slot 0. */
+    function moveFocusLeft(slotIndex) {
+        return applyState({ activeSlot: clampIndex(slotIndex - 1, 0, length - 1) });
+    }
+    /** Move focus one slot to the right, clamped to the last slot. */
+    function moveFocusRight(slotIndex) {
+        return applyState({ activeSlot: clampIndex(slotIndex + 1, 0, length - 1) });
+    }
+    /**
+     * Smart paste — distributes valid characters from `cursorSlot` forward,
+     * wrapping around to slot 0 if the string is longer than the remaining slots.
+     *
+     * Examples (length = 6, type = numeric):
+     *   paste(0, '123456') → fills all slots
+     *   paste(5, '847291') → slot5='8', slot0='4', slot1='7', slot2='2', slot3='9', slot4='1'
+     *   paste(0, '84AB91') → filtered='8491', fills slots 0–3, slots 4–5 unchanged
+     */
+    function pasteString(cursorSlot, rawText) {
+        if (disabled)
+            return state;
+        let transformed;
+        try {
+            transformed = pasteTransformer ? pasteTransformer(rawText) : rawText;
+        }
+        catch (err) {
+            console.warn('[digito] pasteTransformer threw — using raw paste text.', err);
+            transformed = rawText;
+        }
+        // Report each rejected character so adapters can provide inline feedback.
+        // Tracks the effective write cursor so the reported slot index matches where
+        // the character would have landed if it had been valid.
+        if (onInvalidChar && transformed) {
+            let slotCursor = cursorSlot;
+            for (const char of Array.from(transformed)) {
+                if (filterChar(char, type, pattern)) {
+                    slotCursor = (slotCursor + 1) % length;
+                }
+                else {
+                    onInvalidChar(char, slotCursor);
+                }
+            }
+        }
+        const validChars = filterString(transformed, type, pattern);
+        if (!validChars)
+            return state;
+        const slotValues = [...state.slotValues];
+        let writeSlot = cursorSlot;
+        for (let i = 0; i < validChars.length && i < length; i++) {
+            slotValues[writeSlot] = validChars[i];
+            writeSlot = (writeSlot + 1) % length;
+        }
+        const charsWritten = Math.min(validChars.length, length);
+        const nextActiveSlot = charsWritten >= length
+            ? length - 1
+            : (cursorSlot + charsWritten) % length;
+        const newState = applyState({
+            slotValues,
+            activeSlot: nextActiveSlot,
+            hasError: false,
+            isComplete: allSlotsFilled(slotValues),
+        });
+        notifyCompleteIfReady(slotValues);
+        return newState;
+    }
+    /** Set or clear the error state. Triggers haptic feedback when setting. */
+    function setError(isError) {
+        if (isError && haptic)
+            triggerHapticFeedback();
+        return applyState({ hasError: isError });
+    }
+    /** Clear all slots and reset to initial state. Cancels any pending onComplete callback. */
+    function resetState() {
+        if (completeTimeoutId !== null) {
+            clearTimeout(completeTimeoutId);
+            completeTimeoutId = null;
+        }
+        return applyState({
+            slotValues: Array(length).fill(''),
+            activeSlot: 0,
+            hasError: false,
+            isComplete: false,
+            timerSeconds: options.timer ?? 0,
+        });
+    }
+    /** Move focus to a specific slot index. */
+    function moveFocusTo(slotIndex) {
+        return applyState({ activeSlot: clampIndex(slotIndex, 0, length - 1) });
+    }
+    /**
+     * Reactively enable or disable the input.
+     * When `true`, inputChar / deleteChar / pasteString are silently ignored.
+     * Navigation (moveFocusLeft/Right/To) is always allowed regardless of state.
+     *
+     * Prefer this over passing `disabled` at construction time whenever you need
+     * to toggle disabled at runtime (e.g. during async verification).
+     */
+    function setDisabled(value) {
+        disabled = value;
+    }
+    /**
+     * Subscribe to state changes. The listener is called after every mutation
+     * with a shallow copy of the new state.
+     *
+     * @returns An unsubscribe function — call it to stop receiving updates.
+     *
+     * @example
+     * ```ts
+     * const otp = createDigito({ length: 6 })
+     * const unsub = otp.subscribe(state => console.log(state.slotValues))
+     * // Later:
+     * unsub()
+     * ```
+     */
+    function subscribe(listener) {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    }
+    return {
+        /** Current state snapshot. */
+        get state() { return state; },
+        // Input actions
+        inputChar,
+        deleteChar,
+        moveFocusLeft,
+        moveFocusRight,
+        pasteString,
+        // State control
+        setError,
+        resetState,
+        moveFocusTo,
+        /**
+         * Cancel any pending onComplete callback without resetting slot state.
+         * Intended for adapter-layer controlled-value syncs where a programmatic
+         * fill should not be treated as a user completing the code.
+         */
+        cancelPendingComplete,
+        /**
+         * Toggle the disabled state at runtime.
+         * Affects inputChar, deleteChar, and pasteString only.
+         * Navigation actions are always allowed.
+         */
+        setDisabled,
+        /** Returns the current joined code string. */
+        getCode: () => joinSlots(state.slotValues),
+        /**
+         * Returns a copy of the current state with a cloned slotValues array.
+         * Mutations to the returned object (including its slotValues array) will
+         * not affect live state.
+         */
+        getSnapshot: () => ({ ...state, slotValues: [...state.slotValues] }),
+        /**
+         * Subscribe to state changes. Returns an unsubscribe function.
+         * Compatible with XState / Zustand-style patterns.
+         */
+        subscribe,
+        /**
+         * Returns a copy of the current state with a cloned slotValues array.
+         * Equivalent to `digito.getSnapshot()` — provided for ergonomic parity
+         * with state-management libraries that expose a `getState()` method.
+         */
+        getState: () => ({ ...state, slotValues: [...state.slotValues] }),
+    };
+}
+//# sourceMappingURL=machine.js.map

package/dist/core/machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine.js","sourceRoot":"","sources":["../../src/core/machine.ts"],"names":[],"mappings":"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"}

package/dist/core/timer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * digito/core/timer
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Standalone countdown timer — re-exported from core for use by adapters and
+ * developers who want to drive their own timer UI.
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+import type { TimerOptions, TimerControls } from './types.js';
+/**
+ * Create a 1-second countdown timer.
+ *
+ * Lifecycle notes:
+ * - `start()` is idempotent — it stops any running interval before starting a
+ *   new one, so calling it twice never produces double-ticking.
+ * - If `totalSeconds <= 0`, `onExpire` fires synchronously on `start()` and no
+ *   interval is created (avoids decrementing to -1 and passing invalid values).
+ * - `reset()` stops and restores remaining seconds without restarting.
+ * - `restart()` is shorthand for `reset()` followed immediately by `start()`.
+ *   Used by the vanilla adapter's "Resend" button to reset the countdown.
+ */
+export declare function createTimer(options: TimerOptions): TimerControls;
+//# sourceMappingURL=timer.d.ts.map

package/dist/core/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../../src/core/timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAkDhE"}

package/dist/core/timer.js

@@ -0,0 +1,67 @@
+/**
+ * digito/core/timer
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Standalone countdown timer — re-exported from core for use by adapters and
+ * developers who want to drive their own timer UI.
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+/**
+ * Create a 1-second countdown timer.
+ *
+ * Lifecycle notes:
+ * - `start()` is idempotent — it stops any running interval before starting a
+ *   new one, so calling it twice never produces double-ticking.
+ * - If `totalSeconds <= 0`, `onExpire` fires synchronously on `start()` and no
+ *   interval is created (avoids decrementing to -1 and passing invalid values).
+ * - `reset()` stops and restores remaining seconds without restarting.
+ * - `restart()` is shorthand for `reset()` followed immediately by `start()`.
+ *   Used by the vanilla adapter's "Resend" button to reset the countdown.
+ */
+export function createTimer(options) {
+    const { totalSeconds, onTick, onExpire } = options;
+    let remainingSeconds = totalSeconds;
+    let intervalId = null;
+    /** Stop the running interval. No-op if already stopped. */
+    function stop() {
+        if (intervalId !== null) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+    }
+    /** Stop the interval and restore `remainingSeconds` to `totalSeconds`. Does not restart. */
+    function reset() {
+        stop();
+        remainingSeconds = totalSeconds;
+    }
+    /**
+     * Start ticking. Stops any existing interval first to prevent double-ticking.
+     * If `totalSeconds <= 0`, fires `onExpire` immediately without creating an interval.
+     */
+    function start() {
+        stop();
+        // Guard: if totalSeconds is zero or negative, fire onExpire immediately
+        // without starting an interval. Without this, the first tick would decrement
+        // to -1 and pass an invalid value to onTick before calling onExpire.
+        if (totalSeconds <= 0) {
+            onExpire?.();
+            return;
+        }
+        intervalId = setInterval(() => {
+            remainingSeconds -= 1;
+            onTick?.(remainingSeconds);
+            if (remainingSeconds <= 0) {
+                stop();
+                onExpire?.();
+            }
+        }, 1000);
+    }
+    /** Reset to `totalSeconds` and immediately start ticking. */
+    function restart() {
+        reset();
+        start();
+    }
+    return { start, stop, reset, restart };
+}
+//# sourceMappingURL=timer.js.map

package/dist/core/timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.js","sourceRoot":"","sources":["../../src/core/timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAqB;IAC/C,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAA;IAElD,IAAI,gBAAgB,GAAG,YAAY,CAAA;IACnC,IAAI,UAAU,GAA0C,IAAI,CAAA;IAE5D,2DAA2D;IAC3D,SAAS,IAAI;QACX,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,aAAa,CAAC,UAAU,CAAC,CAAA;YACzB,UAAU,GAAG,IAAI,CAAA;QACnB,CAAC;IACH,CAAC;IAED,4FAA4F;IAC5F,SAAS,KAAK;QACZ,IAAI,EAAE,CAAA;QACN,gBAAgB,GAAG,YAAY,CAAA;IACjC,CAAC;IAED;;;OAGG;IACH,SAAS,KAAK;QACZ,IAAI,EAAE,CAAA;QACN,wEAAwE;QACxE,6EAA6E;QAC7E,qEAAqE;QACrE,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;YACtB,QAAQ,EAAE,EAAE,CAAA;YACZ,OAAM;QACR,CAAC;QACD,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,gBAAgB,IAAI,CAAC,CAAA;YACrB,MAAM,EAAE,CAAC,gBAAgB,CAAC,CAAA;YAC1B,IAAI,gBAAgB,IAAI,CAAC,EAAE,CAAC;gBAC1B,IAAI,EAAE,CAAA;gBACN,QAAQ,EAAE,EAAE,CAAA;YACd,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,CAAA;IACV,CAAC;IAED,6DAA6D;IAC7D,SAAS,OAAO;QACd,KAAK,EAAE,CAAA;QACP,KAAK,EAAE,CAAA;IACT,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;AACxC,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * digito/core/types
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Shared TypeScript interfaces and type aliases used across the core modules.
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+/** The set of characters each slot will accept. */
+export type InputType = 'numeric' | 'alphabet' | 'alphanumeric' | 'any';
+/** Snapshot of the OTP field state at any point in time. */
+export type DigitoState = {
+    /** Current value of each slot. Empty string means unfilled. */
+    slotValues: string[];
+    /** Index of the currently focused slot. */
+    activeSlot: number;
+    /** Whether an error state is active. */
+    hasError: boolean;
+    /** True when every slot contains a valid character. */
+    isComplete: boolean;
+    /**
+     * Mirrors the initial timer value — NOT a live countdown.
+     * The live countdown is managed by each adapter layer.
+     * Do not use this field to read remaining time; use the adapter's onTick callback instead.
+     */
+    timerSeconds: number;
+};
+/** Configuration options passed to `createDigito` or `initDigito`. */
+export type DigitoOptions = {
+    /** Number of input slots. Default: `6`. */
+    length?: number;
+    /** Character set accepted by each slot. Default: `'numeric'`. */
+    type?: InputType;
+    /** Countdown duration in seconds. `0` disables the timer. Default: `0`. */
+    timer?: number;
+    /** Resend cooldown in seconds after the user clicks Resend. Default: `30`. */
+    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. */
+    onTick?: (remainingSeconds: number) => void;
+    /** Called when the countdown reaches zero. */
+    onExpire?: () => void;
+    /** Called when the resend action is triggered. */
+    onResend?: () => void;
+    /** Vibrate on completion and error via `navigator.vibrate`. Default: `true`. */
+    haptic?: boolean;
+    /** Play a short tone on completion via Web Audio API. Default: `false`. */
+    sound?: boolean;
+    /**
+     * When `true`, all input actions (typing, backspace, paste) are silently ignored.
+     * Use this during async verification to prevent the user modifying the code.
+     * Default: `false`.
+     */
+    disabled?: boolean;
+    /**
+     * Arbitrary per-character regex. When provided, each typed/pasted character must
+     * match this pattern to be accepted into a slot.
+     *
+     * Takes precedence over the named `type` for character validation only —
+     * `type` still controls `inputMode` and ARIA labels on the hidden input.
+     *
+     * The regex should match a **single character**:
+     * @example pattern: /^[0-9A-F]$/   — uppercase hex only
+     * @example pattern: /^[2-9A-HJ-NP-Z]$/  — ambiguity-free alphanumeric (no 0/O, 1/I/L)
+     */
+    pattern?: RegExp;
+    /**
+     * Optional transform applied to the raw clipboard text before it is filtered
+     * and distributed into slots. Runs before `filterString` inside `pasteString()`.
+     *
+     * Use to strip formatting from pasted codes that real users copy from emails or
+     * SMS messages (e.g. `"G-123456"` → `"123456"`, `"123 456"` → `"123456"`).
+     *
+     * The return value is then passed through the normal `filterString` + `pattern`
+     * validation, so you only need to handle the structural formatting — character
+     * validity is still enforced automatically.
+     *
+     * @example pasteTransformer: (raw) => raw.replace(/\s+|-/g, '')
+     * @example pasteTransformer: (raw) => raw.toUpperCase()
+     */
+    pasteTransformer?: (raw: string) => string;
+    /**
+     * Auto-focus the hidden input when the component mounts.
+     * Set to `false` to prevent the field from stealing focus on load.
+     * Default: `true`.
+     */
+    autoFocus?: boolean;
+    /**
+     * The `name` attribute to set on the hidden input for native HTML form
+     * submission and `FormData` compatibility.
+     * @example name: 'otp'  →  FormData includes otp=123456
+     */
+    name?: string;
+    /**
+     * Called when the hidden input gains browser focus.
+     * Use to show contextual help or update surrounding UI.
+     */
+    onFocus?: () => void;
+    /**
+     * Called when the hidden input loses browser focus.
+     * Use to trigger validation or hide contextual help.
+     */
+    onBlur?: () => void;
+    /**
+     * Character to display in empty (unfilled) slots as a visual hint.
+     * Common choices: `'○'`, `'_'`, `'·'`, `'•'`.
+     * Default: `''` (blank — no placeholder).
+     * @example placeholder: '○'
+     */
+    placeholder?: string;
+    /**
+     * When `true`, focusing a slot that already contains a character selects that
+     * character so the next keystroke replaces it in-place.
+     * When `false` (default), the cursor is placed at the slot position and the
+     * existing character must be deleted before a new one can be entered.
+     * Default: `false`.
+     */
+    selectOnFocus?: boolean;
+    /**
+     * When `true`, the hidden input is automatically blurred when all slots are
+     * filled. Removes focus styling and hides the fake caret once the code is
+     * complete. Useful for flows that immediately submit or verify on completion.
+     * Default: `false`.
+     */
+    blurOnComplete?: boolean;
+    /**
+     * Called when the user types or pastes a character that is rejected by the
+     * current `type` or `pattern` filter.
+     *
+     * Receives the raw rejected character and the zero-based slot index where
+     * entry was attempted. Use to display inline feedback such as
+     * "Only digits are allowed" or highlight the offending slot.
+     *
+     * @example
+     * onInvalidChar: (char, index) => console.warn(`Rejected "${char}" at slot ${index}`)
+     */
+    onInvalidChar?: (char: string, index: number) => void;
+};
+/** Options for the standalone `createTimer` utility. */
+export type TimerOptions = {
+    /** Total countdown duration in seconds. */
+    totalSeconds: number;
+    /** Called every second with the remaining seconds. */
+    onTick?: (remainingSeconds: number) => void;
+    /** Called when the countdown reaches zero. */
+    onExpire?: () => void;
+};
+/** Controls returned by `createTimer`. */
+export type TimerControls = {
+    /** Start the countdown. */
+    start: () => void;
+    /** Stop and pause the countdown. */
+    stop: () => void;
+    /** Reset remaining time back to `totalSeconds` without starting. */
+    reset: () => void;
+    /** Reset and immediately start again. */
+    restart: () => void;
+};
+/** Listener function invoked after every state mutation in `createDigito`. */
+export type StateListener = (state: DigitoState) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,cAAc,GAAG,KAAK,CAAA;AAEvE,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG;IACxB,+DAA+D;IAC/D,UAAU,EAAG,MAAM,EAAE,CAAA;IACrB,2CAA2C;IAC3C,UAAU,EAAG,MAAM,CAAA;IACnB,wCAAwC;IACxC,QAAQ,EAAK,OAAO,CAAA;IACpB,uDAAuD;IACvD,UAAU,EAAG,OAAO,CAAA;IACpB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG;IAC1B,2CAA2C;IAC3C,MAAM,CAAC,EAAQ,MAAM,CAAA;IACrB,iEAAiE;IACjE,IAAI,CAAC,EAAU,SAAS,CAAA;IACxB,2EAA2E;IAC3E,KAAK,CAAC,EAAS,MAAM,CAAA;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAG,MAAM,CAAA;IACrB,oEAAoE;IACpE,UAAU,CAAC,EAAI,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACrC,sFAAsF;IACtF,MAAM,CAAC,EAAQ,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,8CAA8C;IAC9C,QAAQ,CAAC,EAAM,MAAM,IAAI,CAAA;IACzB,kDAAkD;IAClD,QAAQ,CAAC,EAAM,MAAM,IAAI,CAAA;IACzB,gFAAgF;IAChF,MAAM,CAAC,EAAQ,OAAO,CAAA;IACtB,2EAA2E;IAC3E,KAAK,CAAC,EAAS,OAAO,CAAA;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAM,OAAO,CAAA;IACtB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAO,MAAM,CAAA;IACrB;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1C;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;CACtD,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG;IACzB,2CAA2C;IAC3C,YAAY,EAAI,MAAM,CAAA;IACtB,sDAAsD;IACtD,MAAM,CAAC,EAAS,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,CAAA;IAClD,8CAA8C;IAC9C,QAAQ,CAAC,EAAO,MAAM,IAAI,CAAA;CAC3B,CAAA;AAED,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG;IAC1B,2BAA2B;IAC3B,KAAK,EAAI,MAAM,IAAI,CAAA;IACnB,oCAAoC;IACpC,IAAI,EAAK,MAAM,IAAI,CAAA;IACnB,oEAAoE;IACpE,KAAK,EAAI,MAAM,IAAI,CAAA;IACnB,yCAAyC;IACzC,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA"}

package/dist/core/types.js

@@ -0,0 +1,10 @@
+/**
+ * digito/core/types
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Shared TypeScript interfaces and type aliases used across the core modules.
+ *
+ * @author  Olawale Balo — Product Designer + Design Engineer
+ * @license MIT
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}