@umbra.ui/core 0.1.0

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

@@ -0,0 +1,764 @@
+# InputEmail
+
+A specialized email input component built with Vue 3 Composition API and TypeScript. The InputEmail component provides intelligent email validation, domain suggestions, typo detection, and visual feedback with smooth animations and accessibility features.
+
+## Installation/Import
+
+```typescript
+import { InputEmail } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for envelope, warning, and check icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const email = ref("");
+const isValid = ref(false);
+const suggestion = ref("");
+
+const handleEmailUpdate = (value: string) => {
+  console.log("Email:", value);
+  email.value = value;
+};
+
+const handleValidUpdate = (valid: boolean) => {
+  console.log("Is valid:", valid);
+  isValid.value = valid;
+};
+
+const handleSuggestionUpdate = (suggestedEmail: string) => {
+  console.log("Suggestion selected:", suggestedEmail);
+  suggestion.value = suggestedEmail;
+};
+</script>
+
+<template>
+  <div>
+    <InputEmail
+      v-model:value="email"
+      placeholder="name@example.com"
+      :showSuggestions="true"
+      :validateOnType="true"
+      @update:value="handleEmailUpdate"
+      @update:valid="handleValidUpdate"
+      @update:suggestion="handleSuggestionUpdate"
+    />
+
+    <div v-if="suggestion" class="suggestion-info">
+      <p>Selected suggestion: {{ suggestion }}</p>
+    </div>
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name         | Type                                                          | Required | Default              | Description                                     |
+| ----------------- | ------------------------------------------------------------- | -------- | -------------------- | ----------------------------------------------- |
+| `value`           | `string`                                                      | No       | `""`                 | The email address value                         |
+| `placeholder`     | `string`                                                      | No       | `"name@example.com"` | Placeholder text displayed when empty           |
+| `showSuggestions` | `boolean`                                                     | No       | `true`               | Whether to show email domain suggestions        |
+| `validateOnType`  | `boolean`                                                     | No       | `true`               | Whether to validate email while typing          |
+| `allowSubdomains` | `boolean`                                                     | No       | `true`               | Whether to allow subdomains in email validation |
+| `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 email value changes  |
+| `update:valid`      | `boolean`    | Emitted when validation state changes |
+| `update:suggestion` | `string`     | Emitted when a suggestion is selected |
+
+## Slots
+
+This component does not use slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## Features
+
+### Email Validation
+
+- **RFC 5322 Compliant**: Follows email address specification standards
+- **Domain Validation**: Validates domain structure and TLD requirements
+- **Length Limits**: Enforces local part (64 chars) and domain (253 chars) limits
+- **Character Restrictions**: Prevents invalid characters and consecutive dots
+- **TLD Validation**: Ensures top-level domain is at least 2 characters and letters only
+
+### Smart Suggestions
+
+- **Common Domains**: Suggests popular email providers (Gmail, Yahoo, Outlook, etc.)
+- **Typo Detection**: Detects and suggests corrections for common domain typos
+- **Keyboard Navigation**: Full keyboard support for suggestion selection
+- **Real-time Filtering**: Filters suggestions based on partial domain input
+
+### Typo Detection
+
+The component detects common typos in popular email domains:
+
+- `gmial.com` → `gmail.com`
+- `yahooo.com` → `yahoo.com`
+- `hotmial.com` → `hotmail.com`
+- `outloook.com` → `outlook.com`
+
+## CSS Customization
+
+The InputEmail 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 Email Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const email = ref("");
+</script>
+
+<template>
+  <div class="email-form">
+    <h3>Contact Information</h3>
+
+    <div class="form-group">
+      <label>Email Address</label>
+      <InputEmail
+        v-model:value="email"
+        placeholder="your.email@example.com"
+        :showSuggestions="true"
+      />
+    </div>
+  </div>
+</template>
+
+<style module>
+.email-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>
+```
+
+### Registration Form
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const formData = ref({
+  firstName: "",
+  lastName: "",
+  email: "",
+  emailValid: false,
+  password: "",
+  confirmPassword: "",
+});
+
+const canSubmit = computed(() => {
+  return (
+    formData.value.firstName &&
+    formData.value.lastName &&
+    formData.value.email &&
+    formData.value.emailValid &&
+    formData.value.password &&
+    formData.value.confirmPassword &&
+    formData.value.password === formData.value.confirmPassword
+  );
+});
+
+const handleSubmit = () => {
+  if (canSubmit.value) {
+    console.log("Registration data:", formData.value);
+    // Process registration logic here
+  }
+};
+</script>
+
+<template>
+  <div class="registration-form">
+    <h3>Create Account</h3>
+
+    <form @submit.prevent="handleSubmit">
+      <div class="form-row">
+        <div class="form-group">
+          <label>First Name</label>
+          <input
+            v-model="formData.firstName"
+            type="text"
+            placeholder="John"
+            required
+          />
+        </div>
+
+        <div class="form-group">
+          <label>Last Name</label>
+          <input
+            v-model="formData.lastName"
+            type="text"
+            placeholder="Doe"
+            required
+          />
+        </div>
+      </div>
+
+      <div class="form-group">
+        <label>Email Address</label>
+        <InputEmail
+          v-model:value="formData.email"
+          @update:valid="formData.emailValid = $event"
+          placeholder="john.doe@example.com"
+          :showSuggestions="true"
+          :validateOnType="true"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Password</label>
+        <input
+          v-model="formData.password"
+          type="password"
+          placeholder="Enter your password"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Confirm Password</label>
+        <input
+          v-model="formData.confirmPassword"
+          type="password"
+          placeholder="Confirm your password"
+          required
+        />
+      </div>
+
+      <button type="submit" :disabled="!canSubmit">Create Account</button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.registration-form {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.form-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+}
+
+.form-group {
+  margin-bottom: 1rem;
+}
+
+label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+input {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+}
+
+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 { InputEmail } from "@umbra-ui/core";
+
+const normalEmail = ref("");
+const disabledEmail = ref("user@example.com");
+const readonlyEmail = ref("admin@company.com");
+const errorEmail = ref("invalid-email");
+</script>
+
+<template>
+  <div class="states-example">
+    <h3>Email Input States</h3>
+
+    <div class="state-group">
+      <label>Normal State</label>
+      <InputEmail
+        v-model:value="normalEmail"
+        placeholder="Enter your email"
+        state="normal"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Disabled State</label>
+      <InputEmail v-model:value="disabledEmail" state="disabled" />
+    </div>
+
+    <div class="state-group">
+      <label>Readonly State</label>
+      <InputEmail v-model:value="readonlyEmail" state="readonly" />
+    </div>
+
+    <div class="state-group">
+      <label>Error State (Invalid Email)</label>
+      <InputEmail v-model:value="errorEmail" 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>
+```
+
+### Suggestion Features Demo
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const email = ref("");
+const selectedSuggestion = ref("");
+
+const testEmails = ref([
+  "user@gmial.com", // Typo: should suggest gmail.com
+  "test@yahooo.com", // Typo: should suggest yahoo.com
+  "admin@hotmial.com", // Typo: should suggest hotmail.com
+  "contact@outloook.com", // Typo: should suggest outlook.com
+]);
+
+const testEmail = (testEmail: string) => {
+  email.value = testEmail;
+};
+</script>
+
+<template>
+  <div class="suggestions-demo">
+    <h3>Email Suggestions & Typo Detection</h3>
+
+    <div class="demo-input">
+      <InputEmail
+        v-model:value="email"
+        @update:suggestion="selectedSuggestion = $event"
+        placeholder="Try typing with typos..."
+        :showSuggestions="true"
+        :validateOnType="true"
+      />
+
+      <div v-if="selectedSuggestion" class="suggestion-info">
+        <p><strong>Selected Suggestion:</strong> {{ selectedSuggestion }}</p>
+      </div>
+    </div>
+
+    <div class="test-emails">
+      <h4>Test Emails with Common Typos</h4>
+      <div class="test-buttons">
+        <button
+          v-for="testEmail in testEmails"
+          :key="testEmail"
+          @click="testEmail(testEmail)"
+          class="test-button"
+        >
+          {{ testEmail }}
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.suggestions-demo {
+  max-width: 600px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+}
+
+.demo-input {
+  margin-bottom: 2rem;
+}
+
+.suggestion-info {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #d4edda;
+  border-radius: 4px;
+  color: #155724;
+}
+
+.test-emails h4 {
+  margin-bottom: 1rem;
+  color: #333;
+}
+
+.test-buttons {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 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>
+```
+
+### Newsletter Signup
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const email = ref("");
+const isValid = ref(false);
+const isSubscribed = ref(false);
+
+const canSubscribe = computed(() => {
+  return email.value && isValid.value;
+});
+
+const handleSubscribe = () => {
+  if (canSubscribe.value) {
+    console.log("Subscribing:", email.value);
+    isSubscribed.value = true;
+    email.value = "";
+    isValid.value = false;
+  }
+};
+</script>
+
+<template>
+  <div class="newsletter-signup">
+    <h3>Stay Updated</h3>
+    <p>Subscribe to our newsletter for the latest updates and news.</p>
+
+    <div v-if="!isSubscribed" class="signup-form">
+      <InputEmail
+        v-model:value="email"
+        @update:valid="isValid = $event"
+        placeholder="your.email@example.com"
+        :showSuggestions="true"
+        :validateOnType="true"
+      />
+
+      <button
+        @click="handleSubscribe"
+        :disabled="!canSubscribe"
+        class="subscribe-button"
+      >
+        Subscribe
+      </button>
+    </div>
+
+    <div v-else class="success-message">
+      <p>✅ Thank you for subscribing! Check your email for confirmation.</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.newsletter-signup {
+  max-width: 400px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 8px;
+  text-align: center;
+}
+
+.newsletter-signup h3 {
+  margin-bottom: 0.5rem;
+  color: #333;
+}
+
+.newsletter-signup p {
+  margin-bottom: 1.5rem;
+  color: #666;
+}
+
+.signup-form {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.subscribe-button {
+  padding: 0.75rem;
+  background-color: #28a745;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 1rem;
+}
+
+.subscribe-button:disabled {
+  background-color: #ccc;
+  cursor: not-allowed;
+}
+
+.success-message {
+  padding: 1rem;
+  background-color: #d4edda;
+  border-radius: 4px;
+  color: #155724;
+}
+</style>
+```
+
+### Contact Form
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputEmail } from "@umbra-ui/core";
+
+const contactData = ref({
+  name: "",
+  email: "",
+  emailValid: false,
+  subject: "",
+  message: "",
+});
+
+const canSubmit = computed(() => {
+  return (
+    contactData.value.name &&
+    contactData.value.email &&
+    contactData.value.emailValid &&
+    contactData.value.subject &&
+    contactData.value.message
+  );
+});
+
+const handleSubmit = () => {
+  if (canSubmit.value) {
+    console.log("Contact form submitted:", contactData.value);
+    // Process contact form logic here
+  }
+};
+</script>
+
+<template>
+  <div class="contact-form">
+    <h3>Contact Us</h3>
+
+    <form @submit.prevent="handleSubmit">
+      <div class="form-group">
+        <label>Name</label>
+        <input
+          v-model="contactData.name"
+          type="text"
+          placeholder="Your full name"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Email</label>
+        <InputEmail
+          v-model:value="contactData.email"
+          @update:valid="contactData.emailValid = $event"
+          placeholder="your.email@example.com"
+          :showSuggestions="true"
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Subject</label>
+        <input
+          v-model="contactData.subject"
+          type="text"
+          placeholder="What's this about?"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Message</label>
+        <textarea
+          v-model="contactData.message"
+          placeholder="Tell us more..."
+          rows="5"
+          required
+        ></textarea>
+      </div>
+
+      <button type="submit" :disabled="!canSubmit">Send Message</button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.contact-form {
+  max-width: 500px;
+  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;
+}
+
+input,
+textarea {
+  width: 100%;
+  padding: 0.5rem;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 1rem;
+  font-family: inherit;
+}
+
+textarea {
+  resize: vertical;
+  min-height: 120px;
+}
+
+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>
+```
+
+## Notes
+
+- The component automatically converts input to lowercase for consistency
+- Email validation follows RFC 5322 standards with additional domain structure checks
+- Suggestions appear when the user types "@" and include common email providers
+- Typo detection works for popular email domains with automatic correction suggestions
+- The component includes smooth animations for suggestions dropdown and validation states
+- Keyboard navigation is fully supported (Arrow keys, Enter, Escape)
+- Paste operations automatically extract email addresses from common formats
+- The component prevents multiple "@" symbols and removes spaces automatically
+- Visual feedback includes envelope icon, validation checkmark, and error warning
+- The component is fully accessible with proper ARIA attributes and keyboard navigation
+- Input is optimized for mobile devices with proper input modes and font sizes
+- Validation can be configured to run on every keystroke or only when appropriate