@umbra.ui/core 0.1.0

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

@@ -0,0 +1,844 @@
+# InputText
+
+A versatile text input component built with Vue 3 Composition API and TypeScript. The InputText component provides a clean, accessible text input with multiple states, size variants, and visual feedback with smooth animations and proper theming support.
+
+## Installation/Import
+
+```typescript
+import { InputText } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/icons (for ripple animation and lock icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+const text = ref("");
+
+const handleTextUpdate = (value: string) => {
+  console.log("Text:", value);
+  text.value = value;
+};
+</script>
+
+<template>
+  <div>
+    <InputText
+      v-model:value="text"
+      placeholder="Enter your text"
+      state="normal"
+      size="normal"
+    />
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name     | Type                                                          | Required | Default        | Description                           |
+| ------------- | ------------------------------------------------------------- | -------- | -------------- | ------------------------------------- |
+| `value`       | `string`                                                      | No       | `""`           | The text value                        |
+| `placeholder` | `string`                                                      | No       | `"Enter text"` | Placeholder text displayed when empty |
+| `state`       | `"normal" \| "active" \| "disabled" \| "readonly" \| "error"` | No       | `"normal"`     | Current state of the input field      |
+| `size`        | `"compact" \| "normal"`                                       | No       | `"normal"`     | Size variant of the input field       |
+
+## Events
+
+| Event Name     | Payload Type | Description                         |
+| -------------- | ------------ | ----------------------------------- |
+| `update:value` | `string`     | Emitted when the text value changes |
+
+## Slots
+
+This component does not provide any slots.
+
+## Exposed Methods/Refs
+
+This component does not expose any methods or refs.
+
+## CSS Customization
+
+The InputText 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);
+```
+
+## Key Features
+
+### Input States
+
+- **Normal**: Standard input state with clean styling
+- **Active**: Shows animated ripple icon for active state
+- **Disabled**: Non-interactive state with muted appearance
+- **Readonly**: Read-only state with lock icon
+- **Error**: Error state with error message display
+
+### Size Variants
+
+- **Normal**: Standard padding and spacing
+- **Compact**: Reduced padding for space-constrained layouts
+
+### Visual Feedback
+
+- **Dynamic Background**: Background color changes based on input state
+- **Focus States**: Clear focus indication with border color changes
+- **Icon Indicators**: Contextual icons for different states
+- **Error Messages**: Built-in error message display
+
+### Accessibility
+
+- **Keyboard Navigation**: Full keyboard support
+- **Screen Reader Support**: Proper ARIA attributes
+- **Focus Management**: Clear focus indicators
+- **Responsive Design**: Mobile-friendly with proper font scaling
+
+## Examples
+
+### Basic Text Input
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+const text = ref("");
+</script>
+
+<template>
+  <div class="text-form">
+    <h3>Basic Text Input</h3>
+
+    <div class="form-group">
+      <label>Name</label>
+      <InputText
+        v-model:value="text"
+        placeholder="Enter your name"
+        state="normal"
+        size="normal"
+      />
+    </div>
+
+    <div class="text-display">
+      <p>Entered: {{ text }}</p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.text-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;
+}
+
+.text-display {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f5f5f5;
+  border-radius: 0.25rem;
+}
+</style>
+```
+
+### Different States
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+const normalText = ref("");
+const activeText = ref("Active state");
+const disabledText = ref("Disabled text");
+const readonlyText = ref("Readonly text");
+const errorText = ref("Error text");
+</script>
+
+<template>
+  <div class="states-example">
+    <h3>Input States</h3>
+
+    <div class="state-group">
+      <label>Normal State</label>
+      <InputText
+        v-model:value="normalText"
+        placeholder="Enter text"
+        state="normal"
+        size="normal"
+      />
+    </div>
+
+    <div class="state-group">
+      <label>Active State</label>
+      <InputText v-model:value="activeText" state="active" size="normal" />
+    </div>
+
+    <div class="state-group">
+      <label>Disabled State</label>
+      <InputText v-model:value="disabledText" state="disabled" size="normal" />
+    </div>
+
+    <div class="state-group">
+      <label>Readonly State</label>
+      <InputText v-model:value="readonlyText" state="readonly" size="normal" />
+    </div>
+
+    <div class="state-group">
+      <label>Error State</label>
+      <InputText
+        v-model:value="errorText"
+        placeholder="Enter valid text"
+        state="error"
+        size="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>
+```
+
+### Size Variants
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+const normalSize = ref("");
+const compactSize = ref("");
+</script>
+
+<template>
+  <div class="size-examples">
+    <h3>Size Variants</h3>
+
+    <div class="size-group">
+      <label>Normal Size</label>
+      <InputText
+        v-model:value="normalSize"
+        placeholder="Normal size input"
+        state="normal"
+        size="normal"
+      />
+      <p class="size-description">Standard padding and spacing</p>
+    </div>
+
+    <div class="size-group">
+      <label>Compact Size</label>
+      <InputText
+        v-model:value="compactSize"
+        placeholder="Compact size input"
+        state="normal"
+        size="compact"
+      />
+      <p class="size-description">
+        Reduced padding for space-constrained layouts
+      </p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.size-examples {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.size-group {
+  margin-bottom: 2rem;
+}
+
+.size-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.size-description {
+  margin-top: 0.5rem;
+  font-size: 0.875rem;
+  color: #666;
+  font-style: italic;
+}
+</style>
+```
+
+### Contact Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+interface ContactForm {
+  firstName: string;
+  lastName: string;
+  email: string;
+  subject: string;
+  message: string;
+}
+
+const form = ref<ContactForm>({
+  firstName: "",
+  lastName: "",
+  email: "",
+  subject: "",
+  message: "",
+});
+
+const isFormValid = computed(() => {
+  return (
+    form.value.firstName &&
+    form.value.lastName &&
+    form.value.email &&
+    form.value.subject &&
+    form.value.message
+  );
+});
+
+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-row">
+        <div class="form-group">
+          <label>First Name *</label>
+          <InputText
+            v-model:value="form.firstName"
+            placeholder="Enter first name"
+            state="normal"
+            size="normal"
+            required
+          />
+        </div>
+
+        <div class="form-group">
+          <label>Last Name *</label>
+          <InputText
+            v-model:value="form.lastName"
+            placeholder="Enter last name"
+            state="normal"
+            size="normal"
+            required
+          />
+        </div>
+      </div>
+
+      <div class="form-group">
+        <label>Email *</label>
+        <InputText
+          v-model:value="form.email"
+          placeholder="your@email.com"
+          state="normal"
+          size="normal"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Subject *</label>
+        <InputText
+          v-model:value="form.subject"
+          placeholder="Enter subject"
+          state="normal"
+          size="normal"
+          required
+        />
+      </div>
+
+      <div class="form-group">
+        <label>Message *</label>
+        <textarea
+          v-model="form.message"
+          placeholder="Enter 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-row {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+
+.form-group {
+  margin-bottom: 1.5rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.form-group textarea {
+  width: 100%;
+  padding: 0.75rem;
+  border: 1px solid #ddd;
+  border-radius: 0.25rem;
+  font-size: 1rem;
+  font-family: inherit;
+  resize: vertical;
+}
+
+.form-group textarea:focus {
+  outline: none;
+  border-color: #007bff;
+  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);
+}
+
+.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>
+```
+
+### Search Interface
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+const searchQuery = ref("");
+const searchResults = ref<string[]>([]);
+
+const isSearching = computed(() => {
+  return searchQuery.value.length > 0;
+});
+
+const handleSearch = () => {
+  if (searchQuery.value.trim()) {
+    // Simulate search results
+    searchResults.value = [
+      `Result 1 for "${searchQuery.value}"`,
+      `Result 2 for "${searchQuery.value}"`,
+      `Result 3 for "${searchQuery.value}"`,
+    ];
+  } else {
+    searchResults.value = [];
+  }
+};
+
+const clearSearch = () => {
+  searchQuery.value = "";
+  searchResults.value = [];
+};
+</script>
+
+<template>
+  <div class="search-interface">
+    <h3>Search Interface</h3>
+
+    <div class="search-container">
+      <div class="search-input-group">
+        <InputText
+          v-model:value="searchQuery"
+          placeholder="Search for something..."
+          state="normal"
+          size="normal"
+          @update:value="handleSearch"
+        />
+        <button
+          v-if="isSearching"
+          @click="clearSearch"
+          class="clear-button"
+          title="Clear search"
+        >
+          ×
+        </button>
+      </div>
+
+      <div v-if="searchResults.length > 0" class="search-results">
+        <h4>Search Results</h4>
+        <ul>
+          <li v-for="(result, index) in searchResults" :key="index">
+            {{ result }}
+          </li>
+        </ul>
+      </div>
+
+      <div v-else-if="isSearching" class="no-results">
+        <p>No results found for "{{ searchQuery }}"</p>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.search-interface {
+  max-width: 500px;
+  padding: 1.5rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.search-container {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.search-input-group {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.clear-button {
+  position: absolute;
+  right: 0.5rem;
+  width: 2rem;
+  height: 2rem;
+  border: none;
+  background: none;
+  cursor: pointer;
+  font-size: 1.5rem;
+  color: #666;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  transition: background-color 0.2s;
+}
+
+.clear-button:hover {
+  background-color: #f0f0f0;
+}
+
+.search-results {
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.search-results h4 {
+  margin: 0 0 0.5rem 0;
+  color: #333;
+}
+
+.search-results ul {
+  margin: 0;
+  padding-left: 1.5rem;
+}
+
+.search-results li {
+  margin-bottom: 0.25rem;
+  color: #666;
+}
+
+.no-results {
+  padding: 1rem;
+  text-align: center;
+  color: #666;
+  font-style: italic;
+}
+</style>
+```
+
+### Settings Panel
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { InputText } from "@umbra-ui/core";
+
+interface Settings {
+  username: string;
+  displayName: string;
+  organization: string;
+  department: string;
+}
+
+const settings = ref<Settings>({
+  username: "john.doe",
+  displayName: "John Doe",
+  organization: "Acme Corp",
+  department: "Engineering",
+});
+
+const hasChanges = computed(() => {
+  // Check if any settings have been modified
+  return Object.values(settings.value).some((value) => value.trim() !== "");
+});
+
+const handleSave = () => {
+  console.log("Settings saved:", settings.value);
+  // Handle settings save
+};
+
+const handleReset = () => {
+  settings.value = {
+    username: "john.doe",
+    displayName: "John Doe",
+    organization: "Acme Corp",
+    department: "Engineering",
+  };
+};
+</script>
+
+<template>
+  <div class="settings-panel">
+    <h3>User Settings</h3>
+
+    <form @submit.prevent="handleSave">
+      <div class="settings-grid">
+        <div class="setting-group">
+          <label>Username</label>
+          <InputText
+            v-model:value="settings.username"
+            placeholder="Enter username"
+            state="readonly"
+            size="normal"
+          />
+          <p class="setting-description">Username cannot be changed</p>
+        </div>
+
+        <div class="setting-group">
+          <label>Display Name</label>
+          <InputText
+            v-model:value="settings.displayName"
+            placeholder="Enter display name"
+            state="normal"
+            size="normal"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Organization</label>
+          <InputText
+            v-model:value="settings.organization"
+            placeholder="Enter organization"
+            state="normal"
+            size="normal"
+          />
+        </div>
+
+        <div class="setting-group">
+          <label>Department</label>
+          <InputText
+            v-model:value="settings.department"
+            placeholder="Enter department"
+            state="normal"
+            size="normal"
+          />
+        </div>
+      </div>
+
+      <div class="settings-actions">
+        <button type="button" @click="handleReset" class="reset-button">
+          Reset
+        </button>
+        <button type="submit" :disabled="!hasChanges" class="save-button">
+          Save Changes
+        </button>
+      </div>
+    </form>
+  </div>
+</template>
+
+<style module>
+.settings-panel {
+  max-width: 600px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+  background-color: #fff;
+}
+
+.settings-grid {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+  margin-bottom: 2rem;
+}
+
+.setting-group {
+  display: flex;
+  flex-direction: column;
+}
+
+.setting-group label {
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.setting-description {
+  margin-top: 0.25rem;
+  font-size: 0.875rem;
+  color: #666;
+  font-style: italic;
+}
+
+.settings-actions {
+  display: flex;
+  gap: 1rem;
+  justify-content: flex-end;
+}
+
+.reset-button {
+  padding: 0.75rem 1.5rem;
+  background-color: #6c757d;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 1rem;
+  transition: background-color 0.2s;
+}
+
+.reset-button:hover {
+  background-color: #5a6268;
+}
+
+.save-button {
+  padding: 0.75rem 1.5rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 1rem;
+  transition: background-color 0.2s;
+}
+
+.save-button:hover:not(:disabled) {
+  background-color: #0056b3;
+}
+
+.save-button:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+</style>
+```
+
+## Technical Notes
+
+- InputText provides a clean, accessible text input with multiple states and size variants
+- State management includes normal, active, disabled, readonly, and error states
+- Size variants include normal and compact for different layout needs
+- Visual feedback includes dynamic background colors, focus states, and contextual icons
+- Error states display built-in error messages below the input
+- Responsive design prevents zoom on mobile devices with proper font scaling
+- Full keyboard navigation and screen reader support
+- CSS custom properties enable easy theming and customization