@pienter/ui 0.2.0 → 0.5.0

package/utils/controllers/otp.ts

@@ -1,252 +0,0 @@
-/**
- * Configuration for `mountInputOTP`. The controller wires N
- * `<input class="v-input-otp__slot">` single-character inputs inside
- * an InputOTP wrapper for the canonical one-time-code UX:
- *  - Type a character matching `pattern` → fill, advance focus.
- *  - Backspace on a filled slot → clear it (focus stays).
- *  - Backspace on an empty slot → focus + clear the previous slot.
- *  - Arrow Left / Right → move focus between slots.
- *  - Paste a multi-character string → distribute across slots starting
- *    from the focused position; characters that fail the pattern are
- *    silently skipped.
- *
- * `onChange` receives the concatenated OTP string after every change.
- * Empty slots are represented as the empty string in the concatenation
- * (so a partial code like `"12  "` reflects two filled slots and two
- * empty), keeping the contract simple for consumers building reactive
- * UIs that need to know when the code is complete (`value.length ===
- * length` AND `!value.includes(' ')` — the controller emits a
- * literal-empty for unfilled slots, NOT a space; see implementation).
- */
-export interface InputOTPConfig {
-    /**
-     * Optional regex used to validate each typed / pasted character.
-     * Defaults to digits-only (`/^[0-9]$/`). Pass an alphanumeric or
-     * uppercase-letter pattern when the OTP code is not a PIN.
-     */
-    pattern?: RegExp;
-    /**
-     * Callback fired on every value change with the concatenated OTP
-     * string. Length always equals the slot count; unfilled slots are
-     * the empty character so consumers can distinguish "fully entered"
-     * from "partial".
-     */
-    onChange?: (value: string) => void;
-}
-
-/**
- * Mount the InputOTP controller on `wrapperEl`, which MUST be the
- * `<div class="v-input-otp">` wrapper containing N
- * `<input class="v-input-otp__slot">` children. The wrapper is the
- * only DOM the controller modifies (slot focus / value); the surrounding
- * `.v-field` scaffold (label, hint, errors) is owned by the framework
- * component.
- *
- * Lifecycle (non-stateful per CONVENTIONS — teardown-only signature):
- * 1. On mount: locate all slot inputs via `.v-input-otp__slot`.
- * 2. Wire `input`, `keydown`, `paste`, and `focus` listeners on each
- *    slot. Behaviours:
- *    - **input**: validate against `pattern`. Reject (clear the slot)
- *      if invalid; advance focus to the next empty slot if valid and
- *      not the last.
- *    - **keydown** Backspace: if the current slot is empty, focus +
- *      clear the previous; if filled, clear it (stay).
- *    - **keydown** ArrowLeft / ArrowRight: navigate between slots.
- *    - **paste**: distribute pasted characters across slots starting
- *      from the focused index. Pattern-failing characters are skipped
- *      so a paste of "123-456" with a digit pattern yields "123456".
- *      Focus lands on the slot after the last filled one (or the last
- *      slot if all were filled).
- * 3. Every value change dispatches `input` and `change` events
- *    (bubbling) on the wrapper element, plus calls `onChange` with
- *    the joined OTP string. The hidden `<input name>` paired by the
- *    framework component receives the same value via `dispatchEvent`
- *    on its element when the wrapper emits.
- * 4. `teardown()`: removes all listeners. The slot DOM is left in
- *    place; the framework owns markup cleanup.
- *
- * Mounting on a wrapper without slot inputs is a graceful no-op.
- *
- * Per CONVENTIONS, the InputOTP wrapper does NOT use `aria-hidden`
- * or `role="group"` on the slot row — each slot is a native input
- * with its own `aria-label="Digit N of M"`. The form-primitive
- * `.v-field` label still applies to the group as a whole; per-slot
- * labels are screen-reader specific.
- */
-export function mountInputOTP(
-    wrapperEl: HTMLElement,
-    config: InputOTPConfig = {},
-): () => void {
-    const slots = Array.from(
-        wrapperEl.querySelectorAll<HTMLInputElement>('input.v-input-otp__slot'),
-    );
-    if (slots.length === 0) {
-        // Graceful no-op: wrapper is missing slot inputs.
-        return () => {};
-    }
-
-    const pattern = config.pattern ?? /^[0-9]$/;
-    const onChange = config.onChange;
-
-    // The hidden input the framework component renders for FormData
-    // serialization (named via `:name`). Optional — if absent, the
-    // controller still works for client-only state.
-    const hiddenInput = wrapperEl.querySelector<HTMLInputElement>(
-        'input.v-input-otp__hidden',
-    );
-
-    function readValue(): string {
-        return slots
-            .map((s) => (s.value.length > 0 ? s.value[0] : ''))
-            .join('');
-    }
-
-    function notifyChange(): void {
-        const value = readValue();
-        if (hiddenInput) {
-            hiddenInput.value = value;
-            hiddenInput.dispatchEvent(new Event('input', { bubbles: true }));
-            hiddenInput.dispatchEvent(new Event('change', { bubbles: true }));
-        }
-        onChange?.(value);
-    }
-
-    function focusSlot(index: number): void {
-        const target = slots[index];
-        if (target) {
-            target.focus();
-            // Select the slot's content so a typed digit overwrites cleanly.
-            target.select();
-        }
-    }
-
-    function findThisIndex(target: EventTarget | null): number {
-        if (!(target instanceof HTMLInputElement)) return -1;
-        return slots.indexOf(target);
-    }
-
-    function handleInput(event: Event): void {
-        const idx = findThisIndex(event.target);
-        if (idx === -1) return;
-        const slot = slots[idx];
-        if (!slot) return;
-        const value = slot.value;
-
-        // Native paste / IME may deliver multi-character input — defer to
-        // the paste handler for that case; here, normalize single-char.
-        if (value.length === 0) {
-            notifyChange();
-            return;
-        }
-
-        if (value.length > 1) {
-            // Multi-char input (paste fallback path on browsers that fire
-            // `input` instead of `paste`): keep only the last character if
-            // it matches the pattern; the explicit `paste` handler covers
-            // the typical Cmd+V flow.
-            const last = value[value.length - 1] ?? '';
-            slot.value = pattern.test(last) ? last : '';
-        } else if (!pattern.test(value)) {
-            // Reject invalid character.
-            slot.value = '';
-            notifyChange();
-            return;
-        }
-
-        notifyChange();
-
-        // Advance focus to the next empty slot (or the next slot if all
-        // remaining are filled — matches the Reka UI / shadcn UX).
-        if (slot.value.length === 1 && idx < slots.length - 1) {
-            focusSlot(idx + 1);
-        }
-    }
-
-    function handleKeydown(event: KeyboardEvent): void {
-        const idx = findThisIndex(event.target);
-        if (idx === -1) return;
-        const slot = slots[idx];
-        if (!slot) return;
-
-        if (event.key === 'Backspace') {
-            if (slot.value.length === 0 && idx > 0) {
-                event.preventDefault();
-                const prev = slots[idx - 1];
-                if (prev) {
-                    prev.value = '';
-                    notifyChange();
-                    focusSlot(idx - 1);
-                }
-            } else if (slot.value.length > 0) {
-                // Clear current slot but stay on it — the next Backspace then
-                // moves to the previous (canonical OTP UX).
-                event.preventDefault();
-                slot.value = '';
-                notifyChange();
-            }
-            return;
-        }
-
-        if (event.key === 'ArrowLeft' && idx > 0) {
-            event.preventDefault();
-            focusSlot(idx - 1);
-            return;
-        }
-
-        if (event.key === 'ArrowRight' && idx < slots.length - 1) {
-            event.preventDefault();
-            focusSlot(idx + 1);
-            return;
-        }
-    }
-
-    function handlePaste(event: ClipboardEvent): void {
-        const idx = findThisIndex(event.target);
-        if (idx === -1) return;
-        const data = event.clipboardData?.getData('text') ?? '';
-        if (!data) return;
-        event.preventDefault();
-
-        // Filter to pattern-matching characters; distribute starting at
-        // the focused slot.
-        const valid = Array.from(data).filter((ch) => pattern.test(ch));
-        if (valid.length === 0) return;
-
-        let cursor = idx;
-        for (const ch of valid) {
-            if (cursor >= slots.length) break;
-            const slot = slots[cursor];
-            if (slot) slot.value = ch;
-            cursor += 1;
-        }
-        notifyChange();
-
-        // Land focus on the slot after the last filled one (or the last
-        // slot if the paste filled to the end).
-        const landingIdx = Math.min(cursor, slots.length - 1);
-        focusSlot(landingIdx);
-    }
-
-    function handleFocus(event: FocusEvent): void {
-        if (!(event.target instanceof HTMLInputElement)) return;
-        // Select existing content so a typed digit overwrites it cleanly,
-        // matching Reka UI's "click any slot to retype" UX.
-        event.target.select();
-    }
-
-    slots.forEach((slot) => {
-        slot.addEventListener('input', handleInput);
-        slot.addEventListener('keydown', handleKeydown);
-        slot.addEventListener('paste', handlePaste);
-        slot.addEventListener('focus', handleFocus);
-    });
-
-    return function teardown(): void {
-        slots.forEach((slot) => {
-            slot.removeEventListener('input', handleInput);
-            slot.removeEventListener('keydown', handleKeydown);
-            slot.removeEventListener('paste', handlePaste);
-            slot.removeEventListener('focus', handleFocus);
-        });
-    };
-}