@umbra.ui/core 0.1.0

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

@@ -0,0 +1,636 @@
+# InputCard
+
+A specialized credit card number input component built with Vue 3 Composition API and TypeScript. The InputCard component provides automatic formatting, card type detection, validation using the Luhn algorithm, and visual feedback with card brand icons.
+
+## Installation/Import
+
+```typescript
+import { InputCard } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for card and validation icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const cardNumber = ref("");
+const formattedCardNumber = ref("");
+const cardType = ref("");
+const isValid = ref(false);
+
+const handleCardUpdate = (value: string) => {
+  console.log("Raw card number:", value);
+  cardNumber.value = value;
+};
+
+const handleFormattedUpdate = (formatted: string) => {
+  console.log("Formatted card number:", formatted);
+  formattedCardNumber.value = formatted;
+};
+
+const handleCardTypeUpdate = (type: string) => {
+  console.log("Card type:", type);
+  cardType.value = type;
+};
+
+const handleValidUpdate = (valid: boolean) => {
+  console.log("Is valid:", valid);
+  isValid.value = valid;
+};
+</script>
+
+<template>
+  <div>
+    <InputCard
+      v-model:value="cardNumber"
+      placeholder="4242 4242 4242 4242"
+      :showCardType="true"
+      @update:value="handleCardUpdate"
+      @update:formatted="handleFormattedUpdate"
+      @update:cardType="handleCardTypeUpdate"
+      @update:valid="handleValidUpdate"
+    />
+
+    <div v-if="cardType" class="card-info">
+      <p>Card Type: {{ cardType }}</p>
+      <p>Valid: {{ isValid ? "Yes" : "No" }}</p>
+    </div>
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name      | Type                                                          | Required | Default                 | Description                                 |
+| -------------- | ------------------------------------------------------------- | -------- | ----------------------- | ------------------------------------------- |
+| `value`        | `string`                                                      | No       | `""`                    | The raw card number (digits only)           |
+| `placeholder`  | `string`                                                      | No       | `"4242 4242 4242 4242"` | Placeholder text displayed when empty       |
+| `showCardType` | `boolean`                                                     | No       | `true`                  | Whether to show the detected card type icon |
+| `state`        | `"normal" \| "active" \| "disabled" \| "readonly" \| "error"` | No       | `"normal"`              | Current state of the input field            |
+
+## Events
+
+| Event Name         | Payload Type | Description                                                                       |
+| ------------------ | ------------ | --------------------------------------------------------------------------------- |
+| `update:value`     | `string`     | Emitted when the card number changes, returns raw digits only                     |
+| `update:formatted` | `string`     | Emitted when the card number changes, returns formatted display value             |
+| `update:cardType`  | `string`     | Emitted when the card type is detected, returns card brand name                   |
+| `update:valid`     | `boolean`    | Emitted when validation state changes, returns true if card is complete and valid |
+
+## Slots
+
+This component does not use slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## Supported Card Types
+
+The component automatically detects and supports the following card types:
+
+- **Visa**: 4xxx (16 or 19 digits)
+- **Mastercard**: 5[1-5]xxx or 2[2-7]xxx (16 digits)
+- **American Express**: 3[47]xxx (15 digits)
+- **Discover**: 6011xxx, 65xxx, or 64[4-9]xxx (16 digits)
+- **Diners Club**: 36xxx, 38xxx, or 30[0-5]xxx (14 digits)
+- **JCB**: 35xxx (16 digits)
+
+## CSS Customization
+
+The InputCard component uses CSS custom properties for theming. It inherits from the general input theme:
+
+```css
+/* Input colors */
+--input-background-normal: #ffffff;
+--input-background-filled: #f8f9fa;
+--input-text-empty: #6c757d;
+--input-text-filled: #212529;
+--input-border: #ced4da;
+--input-border-filled: #80bdff;
+--input-focus-border: #007bff;
+--input-placeholder: #6c757d;
+--input-placeholder-filled: #adb5bd;
+
+/* State-specific colors */
+--input-disabled-bg: #e9ecef;
+--input-disabled-text: #6c757d;
+--input-disabled-border: #ced4da;
+--input-disabled-placeholder: #adb5bd;
+
+--input-readonly-bg: #f8f9fa;
+--input-readonly-text: #495057;
+--input-readonly-border: #ced4da;
+--input-readonly-placeholder: #6c757d;
+
+--input-error-bg: #f8d7da;
+--input-error-text: #721c24;
+--input-error-border: #dc3545;
+--input-text-error: #dc3545;
+```
+
+## Examples
+
+### Basic Card Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const cardNumber = ref("");
+</script>
+
+<template>
+  <div class="card-form">
+    <h3>Payment Information</h3>
+
+    <div class="form-group">
+      <label>Card Number</label>
+      <InputCard
+        v-model:value="cardNumber"
+        placeholder="1234 5678 9012 3456"
+        :showCardType="true"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.card-form {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Complete Payment Form
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const paymentData = ref({
+  cardNumber: "",
+  cardType: "",
+  isValid: false,
+  expiryMonth: "",
+  expiryYear: "",
+  cvv: "",
+  cardholderName: "",
+});
+
+const canSubmit = computed(() => {
+  return (
+    paymentData.value.isValid &&
+    paymentData.value.expiryMonth &&
+    paymentData.value.expiryYear &&
+    paymentData.value.cvv &&
+    paymentData.value.cardholderName
+  );
+});
+
+const handleSubmit = () => {
+  if (canSubmit.value) {
+    console.log("Processing payment:", paymentData.value);
+    // Process payment logic here
+  }
+};
+</script>
+
+<template>
+  <div class="payment-form">
+    <h3>Complete Payment</h3>
+
+    <form @submit.prevent="handleSubmit">
+      <div class="form-group">
+        <label>Card Number</label>
+        <InputCard
+          v-model:value="paymentData.cardNumber"
+          @update:cardType="paymentData.cardType = $event"
+          @update:valid="paymentData.isValid = $event"
+          placeholder="1234 5678 9012 3456"
+        />
+        <p v-if="paymentData.cardType" class="card-type">
+          Detected: {{ paymentData.cardType }}
+        </p>
+      </div>
+
+      <div class="form-row">
+        <div class="form-group">
+          <label>Expiry Month</label>
+          <select v-model="paymentData.expiryMonth" required>
+            <option value="">Month</option>
+            <option
+              v-for="month in 12"
+              :key="month"
+              :value="month.toString().padStart(2, '0')"
+            >
+              {{ month.toString().padStart(2, "0") }}
+            </option>
+          </select>
+        </div>
+
+        <div class="form-group">
+          <label>Expiry Year</label>
+          <select v-model="paymentData.expiryYear" required>
+            <option value="">Year</option>
+            <option
+              v-for="year in 10"
+              :key="year"
+              :value="(new Date().getFullYear() + year).toString()"
+            >
+              {{ new Date().getFullYear() + year }}
+            </option>
+          </select>
+        </div>
+
+        <div class="form-group">
+          <label>CVV</label>
+          <input
+            v-model="paymentData.cvv"
+            type="text"
+            placeholder="123"
+            maxlength="4"
+            pattern="[0-9]*"
+            inputmode="numeric"
+            required
+          />
+        </div>
+      </div>
+
+      <div class="form-group">
+        <label>Cardholder Name</label>
+        <input
+          v-model="paymentData.cardholderName"
+          type="text"
+          placeholder="John Doe"
+          required
+        />
+      </div>
+
+      <button type="submit" :disabled="!canSubmit">Process Payment</button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.payment-form {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+.form-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+  gap: 1rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+input,
+select {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+
+.card-type {
+  margin-top: 0.25rem;
+  font-size: 0.9rem;
+  color: #666;
+}
+
+button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+
+button:disabled {
+  background-color: #ccc;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Different States
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const normalCard = ref("");
+const disabledCard = ref("4242424242424242");
+const readonlyCard = ref("5555555555554444");
+const errorCard = ref("1234567890123456"); // Invalid card
+</script>
+
+<template>
+  <div class="states-example">
+    <h3>Input States</h3>
+
+    <div class="state-group">
+      <label>Normal State</label>
+      <InputCard
+        v-model:value="normalCard"
+        placeholder="Enter card number"
+        state="normal"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Disabled State</label>
+      <InputCard v-model:value="disabledCard" state="disabled" />
+    </div>
+
+    <div class="state-group">
+      <label>Readonly State</label>
+      <InputCard v-model:value="readonlyCard" state="readonly" />
+    </div>
+
+    <div class="state-group">
+      <label>Error State (Invalid Card)</label>
+      <InputCard v-model:value="errorCard" state="normal" />
+    </div>
+  </div>
+</template>
+
+<style module>
+.states-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.state-group {
+  margin-bottom: 1.5rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Card Type Detection Demo
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const testCards = ref([
+  { name: "Visa", number: "4111111111111111" },
+  { name: "Mastercard", number: "5555555555554444" },
+  { name: "American Express", number: "378282246310005" },
+  { name: "Discover", number: "6011111111111117" },
+  { name: "Diners Club", number: "30569309025904" },
+  { name: "JCB", number: "3530111333300000" },
+]);
+
+const currentCard = ref("");
+const detectedType = ref("");
+const isValid = ref(false);
+
+const testCard = (cardNumber: string) => {
+  currentCard.value = cardNumber;
+};
+</script>
+
+<template>
+  <div class="detection-demo">
+    <h3>Card Type Detection</h3>
+
+    <div class="demo-input">
+      <InputCard
+        v-model:value="currentCard"
+        @update:cardType="detectedType = $event"
+        @update:valid="isValid = $event"
+        placeholder="Enter or test a card number"
+      />
+
+      <div v-if="detectedType || isValid !== null" class="detection-info">
+        <p><strong>Detected Type:</strong> {{ detectedType || "Unknown" }}</p>
+        <p><strong>Valid:</strong> {{ isValid ? "Yes" : "No" }}</p>
+      </div>
+    </div>
+
+    <div class="test-cards">
+      <h4>Test Cards</h4>
+      <div class="card-buttons">
+        <button
+          v-for="card in testCards"
+          :key="card.name"
+          @click="testCard(card.number)"
+          class="test-button"
+        >
+          {{ card.name }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.detection-demo {
+  max-width: 600px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.demo-input {
+  margin-bottom: 2rem;
+}
+
+.detection-info {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 4px;
+}
+
+.detection-info p {
+  margin: 0.25rem 0;
+}
+
+.test-cards h4 {
+  margin-bottom: 1rem;
+  color: #333;
+}
+
+.card-buttons {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(120px, 1fr));
+  gap: 0.5rem;
+}
+
+.test-button {
+  padding: 0.5rem;
+  background-color: #6c757d;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 0.9rem;
+}
+
+.test-button:hover {
+  background-color: #5a6268;
+}
+</style>
+```
+
+### Validation Feedback
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputCard } from "@umbra-ui/core";
+
+const cardNumber = ref("");
+const isValid = ref(false);
+const isComplete = ref(false);
+
+const validationMessage = computed(() => {
+  if (!isComplete.value) {
+    return "Enter your card number";
+  }
+  if (!isValid.value) {
+    return "Please enter a valid card number";
+  }
+  return "Card number is valid";
+});
+
+const validationClass = computed(() => {
+  if (!isComplete.value) return "neutral";
+  return isValid.value ? "valid" : "invalid";
+});
+</script>
+
+<template>
+  <div class="validation-example">
+    <h3>Validation Feedback</h3>
+
+    <div class="form-group">
+      <label>Card Number</label>
+      <InputCard
+        v-model:value="cardNumber"
+        @update:valid="
+          (valid) => {
+            isValid = valid;
+            isComplete = cardNumber.length > 0;
+          }
+        "
+        placeholder="1234 5678 9012 3456"
+      />
+
+      <div :class="['validation-message', validationClass]">
+        {{ validationMessage }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.validation-example {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.validation-message {
+  margin-top: 0.5rem;
+  padding: 0.5rem;
+  border-radius: 4px;
+  font-size: 0.9rem;
+}
+
+.validation-message.neutral {
+  background-color: #e9ecef;
+  color: #6c757d;
+}
+
+.validation-message.valid {
+  background-color: #d4edda;
+  color: #155724;
+}
+
+.validation-message.invalid {
+  background-color: #f8d7da;
+  color: #721c24;
+}
+</style>
+```
+
+## Notes
+
+- The component automatically formats card numbers with appropriate spacing based on the detected card type
+- Card validation uses the Luhn algorithm for accurate validation
+- The component prevents non-numeric input and enforces maximum length limits per card type
+- Card type detection happens in real-time as the user types
+- The component includes smooth animations for card type icons and error states
+- Visual feedback includes card brand icons and validation error indicators
+- The component supports paste operations with automatic formatting
+- All major credit card types are supported with their specific formatting rules
+- The component is fully accessible with proper ARIA attributes and keyboard navigation
+- Error states are automatically triggered when a complete but invalid card number is entered
+- The component includes responsive design considerations for mobile devices
+- Input is restricted to numeric characters only with proper input mode settings