@umbra.ui/core 0.1.0

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

@@ -0,0 +1,636 @@
+# InputPhone
+
+A specialized phone number input component built with Vue 3 Composition API and TypeScript. The InputPhone component provides automatic phone number formatting, country detection, validation, and visual feedback with smooth animations and accessibility features.
+
+## Installation/Import
+
+```typescript
+import { InputPhone } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for phone, warning, and check icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+const phoneNumber = ref("");
+
+const handlePhoneUpdate = (value: string) => {
+  console.log("Phone:", value);
+  phoneNumber.value = value;
+};
+
+const handleFormattedUpdate = (formatted: string) => {
+  console.log("Formatted:", formatted);
+};
+
+const handleValidUpdate = (isValid: boolean) => {
+  console.log("Valid:", isValid);
+};
+</script>
+
+<template>
+  <div>
+    <InputPhone
+      v-model:value="phoneNumber"
+      @update:formatted="handleFormattedUpdate"
+      @update:valid="handleValidUpdate"
+      placeholder="Enter phone number"
+      default-country="US"
+      :allow-international="true"
+      :show-country-code="true"
+    />
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name            | Type                                                          | Required | Default                | Description                                  |
+| -------------------- | ------------------------------------------------------------- | -------- | ---------------------- | -------------------------------------------- |
+| `value`              | `string`                                                      | No       | `""`                   | The phone number value                       |
+| `placeholder`        | `string`                                                      | No       | `"Enter phone number"` | Placeholder text displayed when empty        |
+| `defaultCountry`     | `string`                                                      | No       | `"US"`                 | ISO country code for default formatting      |
+| `allowInternational` | `boolean`                                                     | No       | `true`                 | Whether to allow international phone numbers |
+| `showCountryCode`    | `boolean`                                                     | No       | `true`                 | Whether to show country code when detected   |
+| `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 phone number value changes     |
+| `update:formatted` | `string`     | Emitted when the formatted phone number changes |
+| `update:valid`     | `boolean`    | Emitted when the validation state changes       |
+
+## Slots
+
+This component does not provide any slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## CSS Customization
+
+The InputPhone component uses CSS custom properties for theming and customization:
+
+### Input Container Variables
+
+```css
+--input-border: 1px solid var(--input-border-color);
+--input-border-radius: 0.588rem;
+--input-focus-border: var(--input-focus-color);
+--input-background-normal: var(--input-bg-normal);
+--input-background-filled: var(--input-bg-filled);
+--input-border-filled: var(--input-border-filled-color);
+--input-text-empty: var(--input-text-empty-color);
+--input-text-filled: var(--input-text-filled-color);
+--input-placeholder: var(--input-placeholder-color);
+--input-placeholder-filled: var(--input-placeholder-filled-color);
+```
+
+### State-Specific Variables
+
+```css
+/* Disabled State */
+--input-disabled-bg: var(--input-disabled-background);
+--input-disabled-text: var(--input-disabled-text-color);
+--input-disabled-border: var(--input-disabled-border-color);
+--input-disabled-placeholder: var(--input-disabled-placeholder-color);
+
+/* Readonly State */
+--input-readonly-bg: var(--input-readonly-background);
+--input-readonly-text: var(--input-readonly-text-color);
+--input-readonly-border: var(--input-readonly-border-color);
+--input-readonly-placeholder: var(--input-readonly-placeholder-color);
+
+/* Error State */
+--input-error-bg: var(--input-error-background);
+--input-error-text: var(--input-error-text-color);
+--input-error-border: var(--input-error-border-color);
+--input-text-error: var(--input-error-text-color);
+```
+
+## Key Features
+
+### Automatic Formatting
+
+- **Country Detection**: Automatically detects country from phone number patterns
+- **Real-time Formatting**: Formats phone numbers as the user types
+- **Multiple Formats**: Supports US, UK, and international phone number formats
+- **Smart Cursor Positioning**: Maintains proper cursor position during formatting
+
+### Validation
+
+- **Real-time Validation**: Validates phone numbers based on country-specific rules
+- **Visual Feedback**: Shows validation state with icons and error messages
+- **Digit Limits**: Enforces country-specific digit limits (US: 10/11, UK: 11/12, International: 7-15)
+- **E.164 Compliance**: Follows international E.164 standard for phone numbers
+
+### User Experience
+
+- **Input Restrictions**: Only allows digits and formatting characters
+- **Paste Support**: Handles pasted phone numbers with proper formatting
+- **Keyboard Navigation**: Supports standard keyboard navigation and editing
+- **Responsive Design**: Adapts to different screen sizes with proper font scaling
+
+### Supported Countries
+
+- **US**: `(555) 123-4567` or `+1 (555) 123-4567`
+- **UK**: `20 1234 5678` or `+44 20 1234 5678`
+- **International**: Generic formatting with country codes
+
+## Examples
+
+### Basic Phone Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+const phone = ref("");
+</script>
+
+<template>
+  <div class="phone-form">
+    <h3>Contact Information</h3>
+
+    <div class="form-group">
+      <label>Phone Number</label>
+      <InputPhone
+        v-model:value="phone"
+        placeholder="Enter your phone number"
+        default-country="US"
+      />
+    </div>
+
+    <div class="phone-display">
+      <p>Entered: {{ phone }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.phone-form {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+}
+
+.phone-display {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f5f5f5;
+  border-radius: 0.25rem;
+}
+</style>
+```
+
+### International Phone Numbers
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+const internationalPhone = ref("");
+const isValid = ref(false);
+const formatted = ref("");
+
+const handleValidUpdate = (valid: boolean) => {
+  isValid.value = valid;
+};
+
+const handleFormattedUpdate = (formattedValue: string) => {
+  formatted.value = formattedValue;
+};
+</script>
+
+<template>
+  <div class="international-example">
+    <h3>International Phone Numbers</h3>
+
+    <div class="form-group">
+      <label>Phone Number (Any Country)</label>
+      <InputPhone
+        v-model:value="internationalPhone"
+        @update:valid="handleValidUpdate"
+        @update:formatted="handleFormattedUpdate"
+        placeholder="Enter international phone number"
+        default-country="US"
+        :allow-international="true"
+        :show-country-code="true"
+      />
+    </div>
+
+    <div class="validation-status">
+      <div class="status-item">
+        <strong>Valid:</strong>
+        <span :class="{ valid: isValid, invalid: !isValid }">
+          {{ isValid ? "Yes" : "No" }}
+        </span>
+      </div>
+      <div class="status-item"><strong>Formatted:</strong> {{ formatted }}</div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.international-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+}
+
+.validation-status {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.status-item {
+  margin-bottom: 0.5rem;
+}
+
+.valid {
+  color: #28a745;
+  font-weight: 500;
+}
+
+.invalid {
+  color: #dc3545;
+  font-weight: 500;
+}
+</style>
+```
+
+### Contact Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+interface ContactForm {
+  name: string;
+  email: string;
+  phone: string;
+  message: string;
+}
+
+const form = ref<ContactForm>({
+  name: "",
+  email: "",
+  phone: "",
+  message: "",
+});
+
+const phoneValid = ref(false);
+
+const isFormValid = computed(() => {
+  return (
+    form.value.name &&
+    form.value.email &&
+    form.value.phone &&
+    phoneValid.value &&
+    form.value.message
+  );
+});
+
+const handlePhoneValid = (valid: boolean) => {
+  phoneValid.value = valid;
+};
+
+const handleSubmit = () => {
+  if (isFormValid.value) {
+    console.log("Form submitted:", form.value);
+    // Handle form submission
+  }
+};
+</script>
+
+<template>
+  <div class="contact-form">
+    <h3>Contact Us</h3>
+
+    <form @submit.prevent="handleSubmit">
+      <div class="form-group">
+        <label>Name *</label>
+        <input
+          v-model="form.name"
+          type="text"
+          placeholder="Your name"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Email *</label>
+        <input
+          v-model="form.email"
+          type="email"
+          placeholder="your@email.com"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Phone Number *</label>
+        <InputPhone
+          v-model:value="form.phone"
+          @update:valid="handlePhoneValid"
+          placeholder="Enter your phone number"
+          default-country="US"
+        />
+        <div v-if="form.phone && !phoneValid" class="error-message">
+          Please enter a valid phone number
+        </div>
+      </div>
+
+      <div class="form-group">
+        <label>Message *</label>
+        <textarea
+          v-model="form.message"
+          placeholder="Your message"
+          rows="4"
+          required
+        ></textarea>
+      </div>
+
+      <button type="submit" :disabled="!isFormValid" class="submit-button">
+        Send Message
+      </button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.contact-form {
+  max-width: 600px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  background-color: #fff;
+}
+
+.form-group {
+  margin-bottom: 1.5rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.form-group input,
+.form-group textarea {
+  width: 100%;
+  padding: 0.75rem;
+  border: 1px solid #ddd;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+}
+
+.form-group input:focus,
+.form-group textarea:focus {
+  outline: none;
+  border-color: #007bff;
+  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
+}
+
+.error-message {
+  color: #dc3545;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+.submit-button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  cursor: pointer;
+  transition: background-color 0.2s;
+}
+
+.submit-button:hover:not(:disabled) {
+  background-color: #0056b3;
+}
+
+.submit-button:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Different States
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+const normalPhone = ref("");
+const disabledPhone = ref("(555) 123-4567");
+const readonlyPhone = ref("+1 (555) 987-6543");
+const errorPhone = ref("123");
+</script>
+
+<template>
+  <div class="states-example">
+    <h3>Input States</h3>
+
+    <div class="state-group">
+      <label>Normal State</label>
+      <InputPhone
+        v-model:value="normalPhone"
+        placeholder="Enter phone number"
+        state="normal"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Disabled State</label>
+      <InputPhone v-model:value="disabledPhone" state="disabled" />
+    </div>
+
+    <div class="state-group">
+      <label>Readonly State</label>
+      <InputPhone v-model:value="readonlyPhone" state="readonly" />
+    </div>
+
+    <div class="state-group">
+      <label>Error State (Invalid Number)</label>
+      <InputPhone
+        v-model:value="errorPhone"
+        placeholder="Enter valid phone number"
+        state="normal"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.states-example {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.state-group {
+  margin-bottom: 1.5rem;
+}
+
+.state-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+</style>
+```
+
+### Country-Specific Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputPhone } from "@umbra-ui/core";
+
+const usPhone = ref("");
+const ukPhone = ref("");
+const internationalPhone = ref("");
+
+const handleUSPhone = (value: string) => {
+  usPhone.value = value;
+};
+
+const handleUKPhone = (value: string) => {
+  ukPhone.value = value;
+};
+
+const handleInternationalPhone = (value: string) => {
+  internationalPhone.value = value;
+};
+</script>
+
+<template>
+  <div class="country-examples">
+    <h3>Country-Specific Formatting</h3>
+
+    <div class="country-group">
+      <h4>United States</h4>
+      <InputPhone
+        v-model:value="usPhone"
+        @update:value="handleUSPhone"
+        placeholder="Enter US phone number"
+        default-country="US"
+        :show-country-code="true"
+      />
+      <p class="format-info">Format: (555) 123-4567 or +1 (555) 123-4567</p>
+    </div>
+
+    <div class="country-group">
+      <h4>United Kingdom</h4>
+      <InputPhone
+        v-model:value="ukPhone"
+        @update:value="handleUKPhone"
+        placeholder="Enter UK phone number"
+        default-country="GB"
+        :show-country-code="true"
+      />
+      <p class="format-info">Format: 20 1234 5678 or +44 20 1234 5678</p>
+    </div>
+
+    <div class="country-group">
+      <h4>International</h4>
+      <InputPhone
+        v-model:value="internationalPhone"
+        @update:value="handleInternationalPhone"
+        placeholder="Enter international phone number"
+        default-country="US"
+        :allow-international="true"
+        :show-country-code="true"
+      />
+      <p class="format-info">Format: +[country code] [number]</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.country-examples {
+  max-width: 600px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.country-group {
+  margin-bottom: 2rem;
+  padding: 1rem;
+  border: 1px solid #f0f0f0;
+  border-radius: 0.25rem;
+}
+
+.country-group h4 {
+  margin: 0 0 1rem 0;
+  color: #333;
+}
+
+.format-info {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: #666;
+  font-style: italic;
+}
+</style>
+```
+
+## Technical Notes
+
+- Phone number validation follows country-specific rules and E.164 international standard
+- Automatic formatting preserves cursor position during input
+- Supports paste operations with proper formatting and validation
+- Input restrictions prevent non-digit characters except formatting symbols
+- Responsive design prevents zoom on mobile devices with proper font sizing
+- Error states are automatically triggered for invalid phone numbers
+- Country detection works for US, UK, and generic international formats