@umbra.ui/core 0.1.0

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

@@ -0,0 +1,718 @@
+# StringCapture
+
+A popover-based text input component built with Vue 3 Composition API and TypeScript. The StringCapture component provides a modal-like interface for capturing text input with a floating popup, overlay, and integrated submit/cancel functionality.
+
+## Installation/Import
+
+```typescript
+import { StringCapture } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- @umbra-ui/core (for IconButton component)
+- @floating-ui/vue (for positioning)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture, Button } from "@umbra-ui/core";
+
+const capturedText = ref("");
+const isOpen = ref(false);
+
+const handleSubmit = (value: string) => {
+  console.log("Captured text:", value);
+  capturedText.value = value;
+};
+
+const handleCancel = () => {
+  console.log("Capture cancelled");
+};
+
+const openCapture = () => {
+  isOpen.value = true;
+};
+</script>
+
+<template>
+  <div>
+    <StringCapture
+      v-model="capturedText"
+      header-label="Enter Your Text"
+      placeholder="Type something..."
+      @submit="handleSubmit"
+      @cancel="handleCancel"
+    >
+      <Button @click="openCapture">
+        {{ capturedText || "Click to enter text" }}
+      </Button>
+    </StringCapture>
+  </div>
+</template>
+```
+
+## Props
+
+| Prop Name     | Type      | Required | Default           | Description                               |
+| ------------- | --------- | -------- | ----------------- | ----------------------------------------- |
+| `modelValue`  | `string`  | No       | `""`              | The captured text value                   |
+| `placeholder` | `string`  | No       | `"Enter text..."` | Placeholder text for the input field      |
+| `headerLabel` | `string`  | No       | `"Enter Text"`    | Label displayed in the popup header       |
+| `loading`     | `boolean` | No       | `false`           | Whether the component is in loading state |
+
+## Events
+
+| Event Name          | Payload Type | Description                               |
+| ------------------- | ------------ | ----------------------------------------- |
+| `update:modelValue` | `string`     | Emitted when the text value changes       |
+| `submit`            | `string`     | Emitted when the submit button is clicked |
+| `cancel`            | `void`       | Emitted when the capture is cancelled     |
+
+## Slots
+
+| Slot Name | Description                              |
+| --------- | ---------------------------------------- |
+| `default` | The trigger element that opens the popup |
+
+## Exposed Methods/Refs
+
+The StringCapture component exposes the following methods via template refs:
+
+| Method Name     | Parameters | Description                         |
+| --------------- | ---------- | ----------------------------------- |
+| `togglePopover` | `()`       | Toggles the popup open/closed state |
+
+### Example Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture } from "@umbra-ui/core";
+
+const stringCaptureRef = ref();
+
+const openCapture = () => {
+  stringCaptureRef.value?.togglePopover();
+};
+</script>
+
+<template>
+  <div>
+    <StringCapture ref="stringCaptureRef" v-model="capturedText">
+      <button @click="openCapture">Open Capture</button>
+    </StringCapture>
+  </div>
+</template>
+```
+
+## CSS Customization
+
+The StringCapture component uses CSS custom properties for theming and customization:
+
+### Popup Variables
+
+```css
+/* Popup Container */
+--stringcapture-popup-bg: var(--stringcapture-popup-background);
+--stringcapture-popup-border: var(--stringcapture-popup-border-color);
+--stringcapture-popup-shadow: var(--stringcapture-popup-shadow-color);
+--stringcapture-popup-inset-shadow: var(
+  --stringcapture-popup-inset-shadow-color
+);
+
+/* Header */
+--stringcapture-header-bg: var(--stringcapture-header-background);
+--stringcapture-header-border: var(--stringcapture-header-border-color);
+--stringcapture-header-text: var(--stringcapture-header-text-color);
+
+/* Input Container */
+--stringcapture-input-container-bg: var(
+  --stringcapture-input-container-background
+);
+
+/* Input Field */
+--stringcapture-input-text: var(--stringcapture-input-text-color);
+
+/* Overlay */
+--stringcapture-overlay-bg: var(--stringcapture-overlay-background);
+```
+
+## Key Features
+
+### Popup Interface
+
+- **Floating Popup**: Positioned using Floating UI for optimal placement
+- **Overlay Background**: Semi-transparent overlay that covers the entire screen
+- **Smooth Animations**: Fade-in/out animations for popup and overlay
+- **Responsive Positioning**: Automatically adjusts position based on available space
+
+### Input Management
+
+- **Auto-focus**: Input field automatically receives focus when opened
+- **Keyboard Navigation**: Enter to submit, Escape to cancel
+- **Submit Button**: Integrated submit button with visual feedback
+- **Input Validation**: Submit button is disabled when input is empty
+
+### User Experience
+
+- **Click Outside**: Clicking the overlay closes the popup
+- **Escape Key**: Pressing Escape cancels the capture
+- **Enter Key**: Pressing Enter submits the captured text
+- **Visual Feedback**: Submit button opacity changes based on input state
+
+### Accessibility
+
+- **Focus Management**: Proper focus handling for keyboard navigation
+- **ARIA Support**: Accessible popup interface
+- **Keyboard Navigation**: Full keyboard support
+- **Screen Reader Support**: Proper labeling and announcements
+
+## Examples
+
+### Basic String Capture
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture, Button } from "@umbra-ui/core";
+
+const capturedText = ref("");
+const isEditing = ref(false);
+
+const handleSubmit = (value: string) => {
+  console.log("Text captured:", value);
+  capturedText.value = value;
+  isEditing.value = false;
+};
+
+const handleCancel = () => {
+  console.log("Capture cancelled");
+  isEditing.value = false;
+};
+
+const startCapture = () => {
+  isEditing.value = true;
+};
+</script>
+
+<template>
+  <div class="basic-capture">
+    <h3>Basic String Capture</h3>
+
+    <StringCapture
+      v-model="capturedText"
+      header-label="Enter Your Name"
+      placeholder="Type your name..."
+      @submit="handleSubmit"
+      @cancel="handleCancel"
+    >
+      <Button @click="startCapture">
+        {{ capturedText || "Click to enter your name" }}
+      </Button>
+    </StringCapture>
+
+    <div v-if="capturedText" class="captured-text">
+      <p>
+        Captured: <strong>{{ capturedText }}</strong>
+      </p>
+    </div>
+  </div>
+</template>
+
+<style module>
+.basic-capture {
+  max-width: 400px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.captured-text {
+  margin-top: 1rem;
+  padding: 1rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+}
+
+.captured-text p {
+  margin: 0;
+  color: #666;
+}
+</style>
+```
+
+### Inline Text Editing
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture } from "@umbra-ui/core";
+
+const editableText = ref("Click to edit this text");
+const isEditing = ref(false);
+
+const handleSubmit = (value: string) => {
+  editableText.value = value;
+  isEditing.value = false;
+};
+
+const handleCancel = () => {
+  isEditing.value = false;
+};
+
+const startEdit = () => {
+  isEditing.value = true;
+};
+</script>
+
+<template>
+  <div class="inline-editing">
+    <h3>Inline Text Editing</h3>
+
+    <div class="editable-content">
+      <StringCapture
+        v-model="editableText"
+        header-label="Edit Text"
+        placeholder="Enter new text..."
+        @submit="handleSubmit"
+        @cancel="handleCancel"
+      >
+        <div
+          class="editable-text"
+          @click="startEdit"
+          :class="{ editing: isEditing }"
+        >
+          {{ editableText }}
+        </div>
+      </StringCapture>
+    </div>
+
+    <p class="instruction">Click on the text above to edit it</p>
+  </div>
+</template>
+
+<style module>
+.inline-editing {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.editable-content {
+  margin: 1rem 0;
+}
+
+.editable-text {
+  padding: 0.75rem;
+  border: 2px dashed #ddd;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  transition: all 0.2s;
+  background-color: #f8f9fa;
+}
+
+.editable-text:hover {
+  border-color: #007bff;
+  background-color: #e3f2fd;
+}
+
+.editable-text.editing {
+  border-color: #007bff;
+  background-color: #e3f2fd;
+}
+
+.instruction {
+  margin-top: 1rem;
+  color: #666;
+  font-size: 0.875rem;
+  font-style: italic;
+}
+</style>
+```
+
+### Form Integration
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { StringCapture, Button } from "@umbra-ui/core";
+
+interface FormData {
+  title: string;
+  description: string;
+  tags: string;
+}
+
+const formData = ref<FormData>({
+  title: "",
+  description: "",
+  tags: "",
+});
+
+const isFormValid = computed(() => {
+  return formData.value.title && formData.value.description;
+});
+
+const handleTitleSubmit = (value: string) => {
+  formData.value.title = value;
+};
+
+const handleDescriptionSubmit = (value: string) => {
+  formData.value.description = value;
+};
+
+const handleTagsSubmit = (value: string) => {
+  formData.value.tags = value;
+};
+
+const handleFormSubmit = () => {
+  if (isFormValid.value) {
+    console.log("Form submitted:", formData.value);
+    // Handle form submission
+  }
+};
+</script>
+
+<template>
+  <div class="form-integration">
+    <h3>Form Integration</h3>
+
+    <form @submit.prevent="handleFormSubmit">
+      <div class="form-group">
+        <label>Title</label>
+        <StringCapture
+          v-model="formData.title"
+          header-label="Enter Title"
+          placeholder="Enter project title..."
+          @submit="handleTitleSubmit"
+        >
+          <div class="form-field">
+            {{ formData.title || "Click to enter title" }}
+          </div>
+        </StringCapture>
+      </div>
+
+      <div class="form-group">
+        <label>Description</label>
+        <StringCapture
+          v-model="formData.description"
+          header-label="Enter Description"
+          placeholder="Enter project description..."
+          @submit="handleDescriptionSubmit"
+        >
+          <div class="form-field">
+            {{ formData.description || "Click to enter description" }}
+          </div>
+        </StringCapture>
+      </div>
+
+      <div class="form-group">
+        <label>Tags (Optional)</label>
+        <StringCapture
+          v-model="formData.tags"
+          header-label="Enter Tags"
+          placeholder="Enter tags separated by commas..."
+          @submit="handleTagsSubmit"
+        >
+          <div class="form-field">
+            {{ formData.tags || "Click to enter tags" }}
+          </div>
+        </StringCapture>
+      </div>
+
+      <Button type="submit" :disabled="!isFormValid" class="submit-button">
+        Create Project
+      </Button>
+    </form>
+  </div>
+</template>
+
+<style module>
+.form-integration {
+  max-width: 600px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.form-group {
+  margin-bottom: 1.5rem;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 0.5rem;
+  font-weight: 500;
+  color: #333;
+}
+
+.form-field {
+  padding: 0.75rem;
+  border: 1px solid #ddd;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  transition: border-color 0.2s;
+  background-color: #fff;
+  min-height: 2.5rem;
+  display: flex;
+  align-items: center;
+}
+
+.form-field:hover {
+  border-color: #007bff;
+}
+
+.submit-button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #007bff;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 1rem;
+  transition: background-color 0.2s;
+}
+
+.submit-button:hover:not(:disabled) {
+  background-color: #0056b3;
+}
+
+.submit-button:disabled {
+  background-color: #6c757d;
+  cursor: not-allowed;
+}
+</style>
+```
+
+### Quick Actions
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture, Button } from "@umbra-ui/core";
+
+const quickActions = ref<string[]>([]);
+const newAction = ref("");
+
+const handleAddAction = (value: string) => {
+  if (value.trim()) {
+    quickActions.value.push(value.trim());
+    newAction.value = "";
+  }
+};
+
+const removeAction = (index: number) => {
+  quickActions.value.splice(index, 1);
+};
+
+const clearAllActions = () => {
+  quickActions.value = [];
+};
+</script>
+
+<template>
+  <div class="quick-actions">
+    <h3>Quick Actions</h3>
+
+    <div class="actions-list">
+      <div
+        v-for="(action, index) in quickActions"
+        :key="index"
+        class="action-item"
+      >
+        <span>{{ action }}</span>
+        <button @click="removeAction(index)" class="remove-btn">×</button>
+      </div>
+    </div>
+
+    <div class="add-action">
+      <StringCapture
+        v-model="newAction"
+        header-label="Add Quick Action"
+        placeholder="Enter action name..."
+        @submit="handleAddAction"
+      >
+        <Button class="add-button"> + Add Action </Button>
+      </StringCapture>
+    </div>
+
+    <div v-if="quickActions.length > 0" class="actions-controls">
+      <Button @click="clearAllActions" class="clear-button"> Clear All </Button>
+    </div>
+  </div>
+</template>
+
+<style module>
+.quick-actions {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.actions-list {
+  margin: 1rem 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.action-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0.75rem;
+  background-color: #f8f9fa;
+  border-radius: 0.25rem;
+  border: 1px solid #e9ecef;
+}
+
+.remove-btn {
+  background: none;
+  border: none;
+  color: #dc3545;
+  cursor: pointer;
+  font-size: 1.25rem;
+  padding: 0.25rem;
+  border-radius: 0.25rem;
+  transition: background-color 0.2s;
+}
+
+.remove-btn:hover {
+  background-color: #f8d7da;
+}
+
+.add-action {
+  margin: 1rem 0;
+}
+
+.add-button {
+  width: 100%;
+  padding: 0.75rem;
+  background-color: #28a745;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 1rem;
+  transition: background-color 0.2s;
+}
+
+.add-button:hover {
+  background-color: #218838;
+}
+
+.actions-controls {
+  margin-top: 1rem;
+  text-align: center;
+}
+
+.clear-button {
+  padding: 0.5rem 1rem;
+  background-color: #dc3545;
+  color: white;
+  border: none;
+  border-radius: 0.25rem;
+  cursor: pointer;
+  font-size: 0.875rem;
+  transition: background-color 0.2s;
+}
+
+.clear-button:hover {
+  background-color: #c82333;
+}
+</style>
+```
+
+### Custom Styling
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { StringCapture, Button } from "@umbra-ui/core";
+
+const customText = ref("");
+
+const handleSubmit = (value: string) => {
+  customText.value = value;
+};
+</script>
+
+<template>
+  <div class="custom-styling">
+    <h3>Custom Styled String Capture</h3>
+
+    <StringCapture
+      v-model="customText"
+      header-label="Custom Styled Input"
+      placeholder="Enter text with custom styling..."
+      @submit="handleSubmit"
+    >
+      <Button class="custom-trigger">
+        {{ customText || "Custom Styled Button" }}
+      </Button>
+    </StringCapture>
+  </div>
+</template>
+
+<style module>
+.custom-styling {
+  max-width: 500px;
+  padding: 2rem;
+  border: 1px solid #e0e0e0;
+  border-radius: 0.5rem;
+}
+
+.custom-trigger {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  border: none;
+  border-radius: 0.5rem;
+  padding: 1rem 2rem;
+  font-size: 1rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: transform 0.2s, box-shadow 0.2s;
+  box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);
+}
+
+.custom-trigger:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px rgba(102, 126, 234, 0.4);
+}
+
+/* Custom CSS variables for theming */
+.custom-styling {
+  --stringcapture-popup-bg: #ffffff;
+  --stringcapture-popup-border: 2px solid #667eea;
+  --stringcapture-popup-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
+
+  --stringcapture-header-bg: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  --stringcapture-header-text: #ffffff;
+
+  --stringcapture-input-container-bg: #f8f9fa;
+  --stringcapture-input-text: #333333;
+
+  --stringcapture-overlay-bg: rgba(102, 126, 234, 0.3);
+}
+</style>
+```
+
+## Technical Notes
+
+- StringCapture provides a modal-like interface for text input with floating popup
+- Floating UI is used for precise positioning and responsive placement
+- The component uses Vue's Teleport to render the popup outside the component tree
+- Keyboard navigation includes Enter to submit and Escape to cancel
+- Click outside functionality closes the popup via overlay click
+- Smooth animations provide visual feedback for popup show/hide
+- CSS custom properties enable easy theming for light and dark modes
+- The component integrates with IconButton for the submit functionality
+- Focus management ensures proper keyboard navigation
+- TypeScript interfaces ensure type safety for props and events