@umbra.ui/core 0.1.0

package/src/components/inputs/OTP/README.md

@@ -0,0 +1,736 @@
+# OTP
+
+A One-Time Password (OTP) input component built with Vue 3 Composition API and TypeScript. The OTP component provides a secure, user-friendly interface for entering verification codes with automatic focus management, paste support, keyboard navigation, and accessibility features.
+
+## Installation/Import
+
+```typescript
+import { OTP } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+
+const handleOTPUpdate = (value: string) => {
+  console.log("OTP Code:", value);
+  otpCode.value = value;
+};
+
+const handleOTPComplete = (value: string) => {
+  console.log("OTP Complete:", value);
+  // Handle OTP verification
+};
+</script>
+
+<template>
+  <div>
+    <OTP
+      v-model="otpCode"
+      :length="6"
+      :auto-focus="true"
+      :auto-submit="true"
+      @complete="handleOTPComplete"
+    />
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name    | Type      | Required | Default | Description                                                |
+| ------------ | --------- | -------- | ------- | ---------------------------------------------------------- |
+| `modelValue` | `string`  | No       | `""`    | The OTP code value                                         |
+| `length`     | `number`  | No       | `6`     | Number of OTP digits                                       |
+| `disabled`   | `boolean` | No       | `false` | Whether the OTP input is disabled                          |
+| `error`      | `string`  | No       | `""`    | Error message to display                                   |
+| `loading`    | `boolean` | No       | `false` | Whether the OTP is in loading state                        |
+| `autoFocus`  | `boolean` | No       | `true`  | Whether to auto-focus the first input on mount             |
+| `autoSubmit` | `boolean` | No       | `true`  | Whether to emit complete event when all digits are entered |
+
+## Events
+
+| Event Name          | Payload Type | Description                                                 |
+| ------------------- | ------------ | ----------------------------------------------------------- |
+| `update:modelValue` | `string`     | Emitted when the OTP value changes                          |
+| `complete`          | `string`     | Emitted when all digits are entered (if autoSubmit is true) |
+| `change`            | `string`     | Emitted when the OTP value changes                          |
+| `focus`             | `void`       | Emitted when any input receives focus                       |
+| `blur`              | `void`       | Emitted when any input loses focus                          |
+
+## Slots
+
+This component does not provide any slots.
+
+## Exposed Methods/Refs
+
+The OTP component exposes the following methods via template refs:
+
+| Method Name | Parameters | Description                                       |
+| ----------- | ---------- | ------------------------------------------------- |
+| `focus`     | `()`       | Focuses the first input field                     |
+| `clear`     | `()`       | Clears all input fields and focuses the first one |
+
+### Example Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpRef = ref();
+
+const clearOTP = () => {
+  otpRef.value?.clear();
+};
+
+const focusOTP = () => {
+  otpRef.value?.focus();
+};
+</script>
+
+<template>
+  <div>
+    <OTP ref="otpRef" v-model="otpCode" />
+    <button @click="clearOTP">Clear</button>
+    <button @click="focusOTP">Focus</button>
+  </div>
+</template>
+```
+
+## CSS Customization
+
+The OTP component uses CSS custom properties for theming and customization:
+
+### OTP Pin Variables
+
+```css
+/* Pin Background Colors */
+--otp-pin-empty-bg: var(--otp-pin-empty-background);
+--otp-pin-filled-bg: var(--otp-pin-filled-background);
+
+/* Pin Text Colors */
+--otp-pin-empty-text: var(--otp-pin-empty-text-color);
+--otp-pin-filled-text: var(--otp-pin-filled-text-color);
+
+/* Pin Border Colors */
+--otp-pin-border: var(--otp-pin-border-color);
+--otp-filled-border: var(--otp-filled-border-color);
+
+/* Focus Colors */
+--otp-focus-border: var(--otp-focus-border-color);
+
+/* Error Colors */
+--otp-error-border: var(--otp-error-border-color);
+--otp-error-text: var(--otp-error-text-color);
+
+/* Loading Colors */
+--otp-loading-text: var(--otp-loading-text-color);
+```
+
+## Key Features
+
+### Input Management
+
+- **Automatic Focus**: Auto-focuses the first input on mount
+- **Smart Navigation**: Automatically moves to the next field when a digit is entered
+- **Backspace Handling**: Moves to the previous field when backspace is pressed on an empty field
+- **Arrow Key Navigation**: Left/right arrow keys move between fields
+- **Delete Key**: Clears all fields from the current position
+
+### Paste Support
+
+- **Paste Detection**: Automatically detects and handles pasted OTP codes
+- **Smart Distribution**: Distributes pasted digits across available fields
+- **Focus Management**: Focuses the next empty field after pasting
+
+### Validation & States
+
+- **Digit-Only Input**: Only accepts numeric digits (0-9)
+- **Error States**: Visual error indication with custom error messages
+- **Loading States**: Loading indicator with disabled interaction
+- **Disabled States**: Non-interactive state with visual feedback
+
+### Accessibility
+
+- **ARIA Labels**: Proper labeling for screen readers
+- **Keyboard Navigation**: Full keyboard support
+- **Focus Management**: Clear focus indicators
+- **Error Announcements**: Error messages are announced to screen readers
+
+## Examples
+
+### Basic OTP Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+const isComplete = ref(false);
+
+const handleOTPComplete = (value: string) => {
+  isComplete.value = true;
+  console.log("OTP Complete:", value);
+};
+
+const handleOTPChange = (value: string) => {
+  isComplete.value = false;
+  console.log("OTP Changed:", value);
+};
+</script>
+
+<template>
+  <div class="otp-form">
+    <h3>Enter Verification Code</h3>
+
+    <div class="otp-container">
+      <OTP
+        v-model="otpCode"
+        :length="6"
+        :auto-focus="true"
+        :auto-submit="true"
+        @complete="handleOTPComplete"
+        @change="handleOTPChange"
+      />
+    </div>
+
+    <div class="otp-status">
+      <p v-if="isComplete" class="success">Code entered successfully!</p>
+      <p v-else class="instruction">
+        Enter the 6-digit code sent to your phone
+      </p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.otp-form {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.otp-container {
+  margin: 2rem 0;
+}
+
+.otp-status {
+  margin-top: 1rem;
+}
+
+.success {
+  color: #28a745;
+  font-weight: 500;
+}
+
+.instruction {
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### OTP with Error Handling
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+const error = ref("");
+const isLoading = ref(false);
+const attempts = ref(0);
+
+const isComplete = computed(() => {
+  return otpCode.value.length === 6;
+});
+
+const handleOTPComplete = async (value: string) => {
+  isLoading.value = true;
+  error.value = "";
+
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    // Simulate verification failure
+    if (value !== "123456") {
+      attempts.value++;
+      error.value = `Invalid code. ${3 - attempts.value} attempts remaining.`;
+      otpCode.value = "";
+
+      if (attempts.value >= 3) {
+        error.value = "Too many attempts. Please request a new code.";
+      }
+    } else {
+      error.value = "";
+      console.log("Verification successful!");
+    }
+  } catch (err) {
+    error.value = "Verification failed. Please try again.";
+  } finally {
+    isLoading.value = false;
+  }
+};
+
+const handleOTPChange = () => {
+  error.value = "";
+};
+</script>
+
+<template>
+  <div class="otp-verification">
+    <h3>Verify Your Account</h3>
+
+    <div class="otp-container">
+      <OTP
+        v-model="otpCode"
+        :length="6"
+        :error="error"
+        :loading="isLoading"
+        :auto-focus="true"
+        :auto-submit="true"
+        @complete="handleOTPComplete"
+        @change="handleOTPChange"
+      />
+    </div>
+
+    <div class="verification-status">
+      <p v-if="isLoading" class="loading">Verifying code...</p>
+      <p v-else-if="error" class="error">{{ error }}</p>
+      <p v-else class="instruction">Enter the 6-digit verification code</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.otp-verification {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.otp-container {
+  margin: 2rem 0;
+}
+
+.verification-status {
+  margin-top: 1rem;
+  min-height: 1.5rem;
+}
+
+.loading {
+  color: #007bff;
+  font-weight: 500;
+}
+
+.error {
+  color: #dc3545;
+  font-weight: 500;
+}
+
+.instruction {
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### Custom Length OTP
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+const otpLength = ref(4);
+
+const handleOTPComplete = (value: string) => {
+  console.log(`${otpLength.value}-digit OTP Complete:`, value);
+};
+
+const changeLength = (length: number) => {
+  otpLength.value = length;
+  otpCode.value = "";
+};
+</script>
+
+<template>
+  <div class="custom-otp">
+    <h3>Custom Length OTP</h3>
+
+    <div class="length-selector">
+      <label>OTP Length:</label>
+      <div class="length-buttons">
+        <button
+          v-for="length in [4, 6, 8]"
+          :key="length"
+          @click="changeLength(length)"
+          :class="{ active: otpLength === length }"
+          class="length-btn"
+        >
+          {{ length }} digits
+        </button>
+      </div>
+    </div>
+
+    <div class="otp-container">
+      <OTP
+        v-model="otpCode"
+        :length="otpLength"
+        :auto-focus="true"
+        :auto-submit="true"
+        @complete="handleOTPComplete"
+      />
+    </div>
+
+    <div class="otp-info">
+      <p>Enter the {{ otpLength }}-digit code</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-otp {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.length-selector {
+  margin-bottom: 2rem;
+}
+
+.length-selector label {
+  display: block;
+  margin-bottom: 1rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.length-buttons {
+  display: flex;
+  gap: 0.5rem;
+  justify-content: center;
+}
+
+.length-btn {
+  padding: 0.5rem 1rem;
+  border: 1px solid #ddd;
+  background-color: #fff;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  transition: all 0.2s;
+}
+
+.length-btn:hover {
+  background-color: #f8f9fa;
+}
+
+.length-btn.active {
+  background-color: #007bff;
+  color: white;
+  border-color: #007bff;
+}
+
+.otp-container {
+  margin: 2rem 0;
+}
+
+.otp-info {
+  margin-top: 1rem;
+}
+
+.otp-info p {
+  color: #666;
+  font-size: 0.875rem;
+}
+</style>
+```
+
+### OTP with Resend Functionality
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+const isResending = ref(false);
+const resendCooldown = ref(0);
+const resendCount = ref(0);
+
+const canResend = computed(() => {
+  return resendCooldown.value === 0 && !isResending.value;
+});
+
+const handleOTPComplete = (value: string) => {
+  console.log("OTP Complete:", value);
+};
+
+const resendOTP = async () => {
+  if (!canResend.value) return;
+
+  isResending.value = true;
+  resendCount.value++;
+
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+    console.log("OTP resent successfully");
+
+    // Start cooldown
+    resendCooldown.value = 30;
+    const interval = setInterval(() => {
+      resendCooldown.value--;
+      if (resendCooldown.value === 0) {
+        clearInterval(interval);
+      }
+    }, 1000);
+  } catch (err) {
+    console.error("Failed to resend OTP");
+  } finally {
+    isResending.value = false;
+  }
+};
+</script>
+
+<template>
+  <div class="otp-with-resend">
+    <h3>Two-Factor Authentication</h3>
+
+    <div class="otp-container">
+      <OTP
+        v-model="otpCode"
+        :length="6"
+        :auto-focus="true"
+        :auto-submit="true"
+        @complete="handleOTPComplete"
+      />
+    </div>
+
+    <div class="resend-section">
+      <p class="instruction">Enter the 6-digit code sent to your phone</p>
+
+      <div class="resend-actions">
+        <button @click="resendOTP" :disabled="!canResend" class="resend-btn">
+          <span v-if="isResending">Sending...</span>
+          <span v-else-if="resendCooldown > 0"
+            >Resend in {{ resendCooldown }}s</span
+          >
+          <span v-else>Resend Code</span>
+        </button>
+
+        <p v-if="resendCount > 0" class="resend-count">
+          Resent {{ resendCount }} time{{ resendCount > 1 ? "s" : "" }}
+        </p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.otp-with-resend {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.otp-container {
+  margin: 2rem 0;
+}
+
+.resend-section {
+  margin-top: 1rem;
+}
+
+.instruction {
+  color: #666;
+  font-size: 0.875rem;
+  margin-bottom: 1rem;
+}
+
+.resend-actions {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+.resend-btn {
+  padding: 0.5rem 1rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 0.875rem;
+  transition: background-color 0.2s;
+}
+
+.resend-btn:hover:not(:disabled) {
+  background-color: #0056b3;
+}
+
+.resend-btn:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+
+.resend-count {
+  color: #666;
+  font-size: 0.75rem;
+  margin: 0;
+}
+</style>
+```
+
+### OTP with Manual Submit
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { OTP } from "@umbra-ui/core";
+
+const otpCode = ref("");
+const isVerifying = ref(false);
+const error = ref("");
+
+const isComplete = computed(() => {
+  return otpCode.value.length === 6;
+});
+
+const handleOTPChange = () => {
+  error.value = "";
+};
+
+const verifyOTP = async () => {
+  if (!isComplete.value) return;
+
+  isVerifying.value = true;
+  error.value = "";
+
+  try {
+    // Simulate API call
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+
+    if (otpCode.value === "123456") {
+      console.log("Verification successful!");
+    } else {
+      error.value = "Invalid verification code";
+    }
+  } catch (err) {
+    error.value = "Verification failed. Please try again.";
+  } finally {
+    isVerifying.value = false;
+  }
+};
+</script>
+
+<template>
+  <div class="manual-submit-otp">
+    <h3>Manual Submit OTP</h3>
+
+    <div class="otp-container">
+      <OTP
+        v-model="otpCode"
+        :length="6"
+        :error="error"
+        :auto-submit="false"
+        @change="handleOTPChange"
+      />
+    </div>
+
+    <div class="submit-section">
+      <button
+        @click="verifyOTP"
+        :disabled="!isComplete || isVerifying"
+        class="verify-btn"
+      >
+        <span v-if="isVerifying">Verifying...</span>
+        <span v-else>Verify Code</span>
+      </button>
+
+      <p v-if="error" class="error-message">{{ error }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.manual-submit-otp {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  text-align: center;
+}
+
+.otp-container {
+  margin: 2rem 0;
+}
+
+.submit-section {
+  margin-top: 1rem;
+}
+
+.verify-btn {
+  padding: 0.75rem 2rem;
+  background-color: #28a745;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 1rem;
+  transition: background-color 0.2s;
+}
+
+.verify-btn:hover:not(:disabled) {
+  background-color: #218838;
+}
+
+.verify-btn:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+
+.error-message {
+  color: #dc3545;
+  font-size: 0.875rem;
+  margin-top: 0.5rem;
+}
+</style>
+```
+
+## Technical Notes
+
+- OTP component provides secure, accessible input for verification codes
+- Automatic focus management moves between fields as digits are entered
+- Paste support automatically distributes pasted digits across fields
+- Keyboard navigation includes arrow keys, backspace, and delete functionality
+- Error states provide visual feedback with custom error messages
+- Loading states disable interaction during verification
+- Accessibility features include ARIA labels and screen reader support
+- Responsive design adapts to mobile devices with appropriate sizing
+- CSS custom properties enable easy theming for light and dark modes
+- Exposed methods allow programmatic control of focus and clearing