@umbra.ui/core 0.1.0

package/src/components/pickers/FilePicker/README.md

@@ -0,0 +1,1542 @@
+# FilePicker
+
+A comprehensive file picker component built with Vue 3 Composition API and TypeScript. The FilePicker provides an intuitive drag-and-drop interface for file selection with support for file validation, directory traversal, multiple file handling, and smooth animations using GSAP.
+
+## Installation/Import
+
+```typescript
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError, DropState } from "@umbra-ui/core";
+```
+
+**Dependencies:**
+
+- Vue 3.x
+- GSAP (for animations)
+- @umbra-ui/icons (for icons)
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const selectedFiles = ref<File[]>([]);
+const fileErrors = ref<FileError[]>([]);
+
+const handleFilesUpdate = (files: File[]) => {
+  console.log("Files updated:", files);
+  selectedFiles.value = files;
+};
+
+const handleFileDrop = (files: File[]) => {
+  console.log("New files dropped:", files);
+};
+
+const handleFileErrors = (errors: FileError[]) => {
+  console.log("File errors:", errors);
+  fileErrors.value = errors;
+};
+</script>
+
+<template>
+  <div class="app">
+    <h2>Upload Files</h2>
+
+    <FilePicker
+      v-model:files="selectedFiles"
+      accept="image/*,.pdf,.doc,.docx"
+      :max-size="5 * 1024 * 1024"
+      :max-files="10"
+      @update:files="handleFilesUpdate"
+      @drop="handleFileDrop"
+      @error="handleFileErrors"
+    />
+
+    <div v-if="selectedFiles.length > 0" class="file-list">
+      <h3>Selected Files ({{ selectedFiles.length }})</h3>
+      <div v-for="file in selectedFiles" :key="file.name" class="file-item">
+        <span class="file-name">{{ file.name }}</span>
+        <span class="file-size">{{ formatFileSize(file.size) }}</span>
+      </div>
+    </div>
+
+    <div v-if="fileErrors.length > 0" class="error-list">
+      <h3>Errors</h3>
+      <div v-for="error in fileErrors" :key="error.file" class="error-item">
+        <strong>{{ error.file }}:</strong> {{ error.error }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.app {
+  padding: 24px;
+  max-width: 600px;
+}
+
+.file-list {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 8px;
+}
+
+.file-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 0;
+  border-bottom: 1px solid #e9ecef;
+}
+
+.file-item:last-child {
+  border-bottom: none;
+}
+
+.file-name {
+  font-weight: 500;
+  color: #495057;
+}
+
+.file-size {
+  color: #6c757d;
+  font-size: 14px;
+}
+
+.error-list {
+  margin-top: 20px;
+  padding: 16px;
+  background: #f8d7da;
+  border-radius: 8px;
+  border: 1px solid #f5c6cb;
+}
+
+.error-item {
+  color: #721c24;
+  margin-bottom: 8px;
+}
+
+.error-item:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Props
+
+| Prop Name     | Type                 | Required | Default    | Description                                          |
+| ------------- | -------------------- | -------- | ---------- | ---------------------------------------------------- |
+| `accept`      | `string \| string[]` | No       | `"*/*"`    | Accepted file types (MIME types or extensions)       |
+| `multiple`    | `boolean`            | No       | `true`     | Whether to allow multiple file selection             |
+| `disabled`    | `boolean`            | No       | `false`    | Whether the picker is disabled                       |
+| `maxSize`     | `number`             | No       | `Infinity` | Maximum file size in bytes                           |
+| `maxFiles`    | `number`             | No       | `Infinity` | Maximum number of files allowed                      |
+| `recursive`   | `boolean`            | No       | `true`     | Whether to traverse directories recursively          |
+| `appendFiles` | `boolean`            | No       | `true`     | Whether to append new files or replace existing ones |
+
+## Events
+
+| Event Name     | Payload Type  | Description                                     |
+| -------------- | ------------- | ----------------------------------------------- |
+| `update:files` | `File[]`      | Emitted when the files list is updated          |
+| `error`        | `FileError[]` | Emitted when file validation errors occur       |
+| `drop`         | `File[]`      | Emitted when files are dropped (only new files) |
+
+## FileError Interface
+
+```typescript
+interface FileError {
+  file: string;
+  error: string;
+}
+```
+
+### FileError Properties
+
+| Property | Type     | Description                            |
+| -------- | -------- | -------------------------------------- |
+| `file`   | `string` | Name of the file that caused the error |
+| `error`  | `string` | Description of the error               |
+
+## DropState Interface
+
+```typescript
+interface DropState {
+  isDragging: boolean;
+  isProcessing: boolean;
+  dragCount: number;
+}
+```
+
+### DropState Properties
+
+| Property       | Type      | Description                                                  |
+| -------------- | --------- | ------------------------------------------------------------ |
+| `isDragging`   | `boolean` | Whether files are currently being dragged over the drop zone |
+| `isProcessing` | `boolean` | Whether files are currently being processed                  |
+| `dragCount`    | `number`  | Number of drag enter/leave events (for nested elements)      |
+
+## Exposed Methods
+
+| Method           | Parameters | Description                                    |
+| ---------------- | ---------- | ---------------------------------------------- |
+| `openFileDialog` | None       | Opens the native file selection dialog         |
+| `clearFiles`     | None       | Clears all selected files                      |
+| `files`          | None       | Reactive reference to the current files array  |
+| `errors`         | None       | Reactive reference to the current errors array |
+
+## CSS Customization
+
+### Layout Variables
+
+```css
+.file-picker {
+  --filepicker-container-bg: #ffffff;
+  --filepicker-container-border: #d1d5db;
+  --filepicker-container-hover-bg: #f9fafb;
+  --filepicker-container-hover-border: #9ca3af;
+  --filepicker-container-active-bg: #e5e7eb;
+  --filepicker-container-active-border: #0090ff;
+  --filepicker-container-active-text: #000000;
+  --filepicker-overlay-bg: rgba(255, 255, 255, 0.9);
+  --filepicker-overlay-text: #000000;
+  --filepicker-spinner-border: #d1d5db;
+  --filepicker-spinner-border-top: #6366f1;
+  --filepicker-disabled-opacity: 0.5;
+  --filepicker-icon-color: #6b7280;
+  --filepicker-title-color: #374151;
+  --filepicker-subtitle-color: #6b7280;
+  --filepicker-processing-bg: rgba(255, 255, 255, 0.8);
+}
+```
+
+### Container Styling
+
+```css
+.file-picker .container {
+  position: relative;
+  width: 100%;
+  min-height: 200px;
+  border: 1px dashed var(--filepicker-container-border);
+  border-radius: 0.706rem;
+  background-color: var(--filepicker-container-bg);
+  transition: all 0.2s ease;
+  overflow: hidden;
+}
+```
+
+### Overlay Styling
+
+```css
+.file-picker .overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--filepicker-overlay-bg);
+  backdrop-filter: blur(4px);
+  opacity: 0;
+  scale: 0.95;
+  pointer-events: none;
+}
+```
+
+## Examples
+
+### Image Uploader
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const images = ref<File[]>([]);
+const errors = ref<FileError[]>([]);
+
+const totalSize = computed(() => {
+  return images.value.reduce((total, file) => total + file.size, 0);
+});
+
+const formatFileSize = (bytes: number): string => {
+  if (bytes === 0) return "0 Bytes";
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+};
+
+const handleImagesUpdate = (files: File[]) => {
+  images.value = files;
+  console.log("Images updated:", files);
+};
+
+const handleImageErrors = (fileErrors: FileError[]) => {
+  errors.value = fileErrors;
+  console.log("Image errors:", fileErrors);
+};
+
+const removeImage = (index: number) => {
+  images.value.splice(index, 1);
+};
+
+const clearAllImages = () => {
+  images.value = [];
+  errors.value = [];
+};
+</script>
+
+<template>
+  <div class="image-uploader">
+    <div class="uploader-header">
+      <h3>Image Gallery</h3>
+      <p>Upload your images (max 5MB each, 10 images total)</p>
+    </div>
+
+    <FilePicker
+      v-model:files="images"
+      accept="image/*"
+      :max-size="5 * 1024 * 1024"
+      :max-files="10"
+      @update:files="handleImagesUpdate"
+      @error="handleImageErrors"
+    >
+      <div class="custom-content">
+        <div class="upload-icon">📸</div>
+        <div class="upload-text">
+          <h4>Drop images here or click to browse</h4>
+          <p>Supports JPG, PNG, GIF, WebP</p>
+        </div>
+      </div>
+    </FilePicker>
+
+    <div v-if="images.length > 0" class="image-gallery">
+      <div class="gallery-header">
+        <h4>Uploaded Images ({{ images.length }})</h4>
+        <div class="gallery-stats">
+          <span>Total size: {{ formatFileSize(totalSize) }}</span>
+          <button @click="clearAllImages" class="clear-btn">Clear All</button>
+        </div>
+      </div>
+
+      <div class="image-grid">
+        <div
+          v-for="(image, index) in images"
+          :key="image.name"
+          class="image-item"
+        >
+          <div class="image-preview">
+            <img
+              :src="URL.createObjectURL(image)"
+              :alt="image.name"
+              class="preview-img"
+            />
+            <button @click="removeImage(index)" class="remove-btn">×</button>
+          </div>
+          <div class="image-info">
+            <p class="image-name">{{ image.name }}</p>
+            <p class="image-size">{{ formatFileSize(image.size) }}</p>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div v-if="errors.length > 0" class="error-section">
+      <h4>Upload Errors</h4>
+      <div v-for="error in errors" :key="error.file" class="error-item">
+        <strong>{{ error.file }}:</strong> {{ error.error }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.image-uploader {
+  padding: 24px;
+  max-width: 800px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.uploader-header {
+  margin-bottom: 24px;
+}
+
+.uploader-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.uploader-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+}
+
+.upload-icon {
+  font-size: 48px;
+}
+
+.upload-text h4 {
+  font-size: 18px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.upload-text p {
+  color: #718096;
+  margin: 0;
+}
+
+.image-gallery {
+  margin-top: 32px;
+}
+
+.gallery-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 20px;
+}
+
+.gallery-header h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0;
+}
+
+.gallery-stats {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.gallery-stats span {
+  color: #6b7280;
+  font-size: 14px;
+}
+
+.clear-btn {
+  padding: 6px 12px;
+  background: #ef4444;
+  color: white;
+  border: none;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.clear-btn:hover {
+  background: #dc2626;
+}
+
+.image-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 16px;
+}
+
+.image-item {
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  overflow: hidden;
+  background: #f9fafb;
+}
+
+.image-preview {
+  position: relative;
+  aspect-ratio: 1;
+  overflow: hidden;
+}
+
+.preview-img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.remove-btn {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 24px;
+  height: 24px;
+  background: rgba(239, 68, 68, 0.9);
+  color: white;
+  border: none;
+  border-radius: 50%;
+  font-size: 16px;
+  font-weight: bold;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.2s ease;
+}
+
+.remove-btn:hover {
+  background: rgba(220, 38, 38, 0.9);
+}
+
+.image-info {
+  padding: 12px;
+}
+
+.image-name {
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin: 0 0 4px 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.image-size {
+  font-size: 12px;
+  color: #6b7280;
+  margin: 0;
+}
+
+.error-section {
+  margin-top: 24px;
+  padding: 16px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 8px;
+}
+
+.error-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #dc2626;
+  margin: 0 0 12px 0;
+}
+
+.error-item {
+  color: #991b1b;
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+
+.error-item:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+### Document Uploader
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const documents = ref<File[]>([]);
+const errors = ref<FileError[]>([]);
+
+const acceptedTypes = [
+  "application/pdf",
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "text/plain",
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".txt",
+];
+
+const formatFileSize = (bytes: number): string => {
+  if (bytes === 0) return "0 Bytes";
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+};
+
+const getFileIcon = (file: File) => {
+  if (file.type.includes("pdf")) return "📄";
+  if (file.type.includes("word")) return "📝";
+  if (file.type.includes("text")) return "📃";
+  return "📁";
+};
+
+const handleDocumentsUpdate = (files: File[]) => {
+  documents.value = files;
+  console.log("Documents updated:", files);
+};
+
+const handleDocumentErrors = (fileErrors: FileError[]) => {
+  errors.value = fileErrors;
+  console.log("Document errors:", fileErrors);
+};
+
+const removeDocument = (index: number) => {
+  documents.value.splice(index, 1);
+};
+</script>
+
+<template>
+  <div class="document-uploader">
+    <div class="uploader-header">
+      <h3>Document Upload</h3>
+      <p>Upload your documents (PDF, Word, Text files)</p>
+    </div>
+
+    <FilePicker
+      v-model:files="documents"
+      :accept="acceptedTypes"
+      :max-size="10 * 1024 * 1024"
+      :max-files="5"
+      :multiple="true"
+      @update:files="handleDocumentsUpdate"
+      @error="handleDocumentErrors"
+    >
+      <div class="custom-content">
+        <div class="upload-icon">📁</div>
+        <div class="upload-text">
+          <h4>Drop documents here or click to browse</h4>
+          <p>Supports PDF, DOC, DOCX, TXT (max 10MB each)</p>
+        </div>
+      </div>
+    </FilePicker>
+
+    <div v-if="documents.length > 0" class="document-list">
+      <h4>Uploaded Documents ({{ documents.length }})</h4>
+      <div class="document-items">
+        <div
+          v-for="(document, index) in documents"
+          :key="document.name"
+          class="document-item"
+        >
+          <div class="document-icon">{{ getFileIcon(document) }}</div>
+          <div class="document-info">
+            <p class="document-name">{{ document.name }}</p>
+            <p class="document-details">
+              {{ formatFileSize(document.size) }} • {{ document.type }}
+            </p>
+          </div>
+          <button @click="removeDocument(index)" class="remove-btn">×</button>
+        </div>
+      </div>
+    </div>
+
+    <div v-if="errors.length > 0" class="error-section">
+      <h4>Upload Errors</h4>
+      <div v-for="error in errors" :key="error.file" class="error-item">
+        <strong>{{ error.file }}:</strong> {{ error.error }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.document-uploader {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.uploader-header {
+  margin-bottom: 24px;
+}
+
+.uploader-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.uploader-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+}
+
+.upload-icon {
+  font-size: 48px;
+}
+
+.upload-text h4 {
+  font-size: 18px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.upload-text p {
+  color: #718096;
+  margin: 0;
+}
+
+.document-list {
+  margin-top: 32px;
+}
+
+.document-list h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.document-items {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.document-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 16px;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+}
+
+.document-icon {
+  font-size: 24px;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #e5e7eb;
+  border-radius: 8px;
+}
+
+.document-info {
+  flex: 1;
+}
+
+.document-name {
+  font-size: 14px;
+  font-weight: 500;
+  color: #374151;
+  margin: 0 0 4px 0;
+}
+
+.document-details {
+  font-size: 12px;
+  color: #6b7280;
+  margin: 0;
+}
+
+.remove-btn {
+  width: 24px;
+  height: 24px;
+  background: #ef4444;
+  color: white;
+  border: none;
+  border-radius: 50%;
+  font-size: 16px;
+  font-weight: bold;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background 0.2s ease;
+}
+
+.remove-btn:hover {
+  background: #dc2626;
+}
+
+.error-section {
+  margin-top: 24px;
+  padding: 16px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 8px;
+}
+
+.error-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #dc2626;
+  margin: 0 0 12px 0;
+}
+
+.error-item {
+  color: #991b1b;
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+
+.error-item:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+### Single File Upload
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const selectedFile = ref<File | null>(null);
+const errors = ref<FileError[]>([]);
+
+const formatFileSize = (bytes: number): string => {
+  if (bytes === 0) return "0 Bytes";
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+};
+
+const handleFileUpdate = (files: File[]) => {
+  selectedFile.value = files[0] || null;
+  console.log("File updated:", selectedFile.value);
+};
+
+const handleFileErrors = (fileErrors: FileError[]) => {
+  errors.value = fileErrors;
+  console.log("File errors:", fileErrors);
+};
+
+const clearFile = () => {
+  selectedFile.value = null;
+  errors.value = [];
+};
+</script>
+
+<template>
+  <div class="single-file-uploader">
+    <div class="uploader-header">
+      <h3>Single File Upload</h3>
+      <p>Upload one file at a time</p>
+    </div>
+
+    <FilePicker
+      v-model:files="selectedFile ? [selectedFile] : []"
+      accept="*/*"
+      :max-size="50 * 1024 * 1024"
+      :max-files="1"
+      :multiple="false"
+      :append-files="false"
+      @update:files="handleFileUpdate"
+      @error="handleFileErrors"
+    >
+      <div class="custom-content">
+        <div class="upload-icon">📎</div>
+        <div class="upload-text">
+          <h4>Drop a file here or click to browse</h4>
+          <p>Any file type, max 50MB</p>
+        </div>
+      </div>
+    </FilePicker>
+
+    <div v-if="selectedFile" class="file-preview">
+      <h4>Selected File</h4>
+      <div class="file-card">
+        <div class="file-icon">📄</div>
+        <div class="file-details">
+          <p class="file-name">{{ selectedFile.name }}</p>
+          <p class="file-info">
+            {{ formatFileSize(selectedFile.size) }} •
+            {{ selectedFile.type || "Unknown type" }}
+          </p>
+          <p class="file-date">
+            Last modified:
+            {{ new Date(selectedFile.lastModified).toLocaleDateString() }}
+          </p>
+        </div>
+        <button @click="clearFile" class="clear-btn">Clear</button>
+      </div>
+    </div>
+
+    <div v-if="errors.length > 0" class="error-section">
+      <h4>Upload Error</h4>
+      <div v-for="error in errors" :key="error.file" class="error-item">
+        <strong>{{ error.file }}:</strong> {{ error.error }}
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.single-file-uploader {
+  padding: 24px;
+  max-width: 500px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.uploader-header {
+  margin-bottom: 24px;
+}
+
+.uploader-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.uploader-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+}
+
+.upload-icon {
+  font-size: 48px;
+}
+
+.upload-text h4 {
+  font-size: 18px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.upload-text p {
+  color: #718096;
+  margin: 0;
+}
+
+.file-preview {
+  margin-top: 32px;
+}
+
+.file-preview h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.file-card {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding: 20px;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+}
+
+.file-icon {
+  font-size: 32px;
+  width: 60px;
+  height: 60px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #e5e7eb;
+  border-radius: 12px;
+}
+
+.file-details {
+  flex: 1;
+}
+
+.file-name {
+  font-size: 16px;
+  font-weight: 600;
+  color: #374151;
+  margin: 0 0 8px 0;
+}
+
+.file-info {
+  font-size: 14px;
+  color: #6b7280;
+  margin: 0 0 4px 0;
+}
+
+.file-date {
+  font-size: 12px;
+  color: #9ca3af;
+  margin: 0;
+}
+
+.clear-btn {
+  padding: 8px 16px;
+  background: #ef4444;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.clear-btn:hover {
+  background: #dc2626;
+}
+
+.error-section {
+  margin-top: 24px;
+  padding: 16px;
+  background: #fef2f2;
+  border: 1px solid #fecaca;
+  border-radius: 8px;
+}
+
+.error-section h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #dc2626;
+  margin: 0 0 12px 0;
+}
+
+.error-item {
+  color: #991b1b;
+  margin-bottom: 8px;
+  font-size: 14px;
+}
+
+.error-item:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+### Custom Overlay
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const files = ref<File[]>([]);
+const errors = ref<FileError[]>([]);
+
+const handleFilesUpdate = (newFiles: File[]) => {
+  files.value = newFiles;
+  console.log("Files updated:", newFiles);
+};
+
+const handleFileErrors = (fileErrors: FileError[]) => {
+  errors.value = fileErrors;
+  console.log("File errors:", fileErrors);
+};
+</script>
+
+<template>
+  <div class="custom-overlay-uploader">
+    <div class="uploader-header">
+      <h3>Custom Overlay Uploader</h3>
+      <p>Drag and drop with custom overlay animation</p>
+    </div>
+
+    <FilePicker
+      v-model:files="files"
+      accept="image/*,video/*"
+      :max-size="100 * 1024 * 1024"
+      :max-files="20"
+      @update:files="handleFilesUpdate"
+      @error="handleFileErrors"
+    >
+      <div class="custom-content">
+        <div class="upload-icon">🎬</div>
+        <div class="upload-text">
+          <h4>Drop media files here</h4>
+          <p>Images and videos up to 100MB each</p>
+        </div>
+      </div>
+
+      <template #overlay>
+        <div class="custom-overlay">
+          <div class="overlay-icon">⬇️</div>
+          <div class="overlay-text">
+            <h4>Release to upload</h4>
+            <p>Drop your files now</p>
+          </div>
+        </div>
+      </template>
+
+      <template #processing>
+        <div class="custom-processing">
+          <div class="processing-spinner"></div>
+          <p>Processing files...</p>
+        </div>
+      </template>
+    </FilePicker>
+
+    <div v-if="files.length > 0" class="files-summary">
+      <h4>Uploaded Files ({{ files.length }})</h4>
+      <div class="files-grid">
+        <div v-for="file in files" :key="file.name" class="file-item">
+          <div class="file-icon">
+            {{ file.type.startsWith("image/") ? "🖼️" : "🎥" }}
+          </div>
+          <div class="file-info">
+            <p class="file-name">{{ file.name }}</p>
+            <p class="file-size">
+              {{ (file.size / 1024 / 1024).toFixed(2) }} MB
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style module>
+.custom-overlay-uploader {
+  padding: 24px;
+  max-width: 700px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.uploader-header {
+  margin-bottom: 24px;
+}
+
+.uploader-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.uploader-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+}
+
+.upload-icon {
+  font-size: 48px;
+}
+
+.upload-text h4 {
+  font-size: 18px;
+  font-weight: 600;
+  color: #2d3748;
+  margin: 0 0 8px 0;
+}
+
+.upload-text p {
+  color: #718096;
+  margin: 0;
+}
+
+.custom-overlay {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+  background: rgba(59, 130, 246, 0.1);
+  border: 2px dashed #3b82f6;
+  border-radius: 12px;
+  padding: 40px;
+  margin: 20px;
+}
+
+.overlay-icon {
+  font-size: 48px;
+  animation: bounce 1s infinite;
+}
+
+.overlay-text h4 {
+  font-size: 20px;
+  font-weight: 600;
+  color: #1e40af;
+  margin: 0 0 8px 0;
+}
+
+.overlay-text p {
+  color: #3b82f6;
+  margin: 0;
+}
+
+@keyframes bounce {
+  0%,
+  20%,
+  50%,
+  80%,
+  100% {
+    transform: translateY(0);
+  }
+  40% {
+    transform: translateY(-10px);
+  }
+  60% {
+    transform: translateY(-5px);
+  }
+}
+
+.custom-processing {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 16px;
+  text-align: center;
+}
+
+.processing-spinner {
+  width: 40px;
+  height: 40px;
+  border: 4px solid #e5e7eb;
+  border-top-color: #3b82f6;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.custom-processing p {
+  color: #6b7280;
+  font-weight: 500;
+  margin: 0;
+}
+
+.files-summary {
+  margin-top: 32px;
+}
+
+.files-summary h4 {
+  font-size: 18px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 16px 0;
+}
+
+.files-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+  gap: 12px;
+}
+
+.file-item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  padding: 16px;
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  text-align: center;
+}
+
+.file-icon {
+  font-size: 24px;
+}
+
+.file-info {
+  width: 100%;
+}
+
+.file-name {
+  font-size: 12px;
+  font-weight: 500;
+  color: #374151;
+  margin: 0 0 4px 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-size {
+  font-size: 11px;
+  color: #6b7280;
+  margin: 0;
+}
+</style>
+```
+
+## Advanced Usage
+
+### Programmatic Control
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+import type { FileError } from "@umbra-ui/core";
+
+const filePickerRef = ref<InstanceType<typeof FilePicker>>();
+const files = ref<File[]>([]);
+const errors = ref<FileError[]>([]);
+
+const handleFilesUpdate = (newFiles: File[]) => {
+  files.value = newFiles;
+};
+
+const handleFileErrors = (fileErrors: FileError[]) => {
+  errors.value = fileErrors;
+};
+
+const openFileDialog = () => {
+  filePickerRef.value?.openFileDialog();
+};
+
+const clearAllFiles = () => {
+  filePickerRef.value?.clearFiles();
+};
+
+const getCurrentFiles = () => {
+  return filePickerRef.value?.files || [];
+};
+
+const getCurrentErrors = () => {
+  return filePickerRef.value?.errors || [];
+};
+</script>
+
+<template>
+  <div class="programmatic-control">
+    <div class="control-header">
+      <h3>Programmatic Control</h3>
+      <p>Control the file picker programmatically</p>
+    </div>
+
+    <div class="control-buttons">
+      <button @click="openFileDialog" class="control-btn">
+        Open File Dialog
+      </button>
+      <button @click="clearAllFiles" class="control-btn">
+        Clear All Files
+      </button>
+      <button @click="getCurrentFiles" class="control-btn">
+        Get Current Files
+      </button>
+      <button @click="getCurrentErrors" class="control-btn">
+        Get Current Errors
+      </button>
+    </div>
+
+    <FilePicker
+      ref="filePickerRef"
+      v-model:files="files"
+      accept="*/*"
+      :max-size="10 * 1024 * 1024"
+      :max-files="5"
+      @update:files="handleFilesUpdate"
+      @error="handleFileErrors"
+    />
+
+    <div v-if="files.length > 0" class="files-info">
+      <h4>Current Files ({{ files.length }})</h4>
+      <ul>
+        <li v-for="file in files" :key="file.name">
+          {{ file.name }} ({{ (file.size / 1024).toFixed(2) }} KB)
+        </li>
+      </ul>
+    </div>
+
+    <div v-if="errors.length > 0" class="errors-info">
+      <h4>Current Errors ({{ errors.length }})</h4>
+      <ul>
+        <li v-for="error in errors" :key="error.file">
+          {{ error.file }}: {{ error.error }}
+        </li>
+      </ul>
+    </div>
+  </div>
+</template>
+
+<style module>
+.programmatic-control {
+  padding: 24px;
+  max-width: 600px;
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.control-header {
+  margin-bottom: 24px;
+}
+
+.control-header h3 {
+  font-size: 24px;
+  font-weight: 600;
+  color: #1a202c;
+  margin: 0 0 8px 0;
+}
+
+.control-header p {
+  color: #718096;
+  margin: 0;
+}
+
+.control-buttons {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-bottom: 24px;
+}
+
+.control-btn {
+  padding: 8px 16px;
+  background: #3b82f6;
+  color: white;
+  border: none;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.2s ease;
+}
+
+.control-btn:hover {
+  background: #2563eb;
+}
+
+.files-info,
+.errors-info {
+  margin-top: 24px;
+  padding: 16px;
+  background: #f9fafb;
+  border-radius: 8px;
+}
+
+.files-info h4,
+.errors-info h4 {
+  font-size: 16px;
+  font-weight: 500;
+  color: #2d3748;
+  margin: 0 0 12px 0;
+}
+
+.files-info ul,
+.errors-info ul {
+  margin: 0;
+  padding-left: 20px;
+}
+
+.files-info li,
+.errors-info li {
+  color: #4a5568;
+  margin-bottom: 4px;
+}
+
+.files-info li:last-child,
+.errors-info li:last-child {
+  margin-bottom: 0;
+}
+</style>
+```
+
+## Performance Considerations
+
+- **GSAP Animations**: Smooth drag-and-drop animations with optimized performance
+- **File Processing**: Asynchronous file processing with proper error handling
+- **Memory Management**: Efficient file handling with proper cleanup
+- **Directory Traversal**: Recursive directory processing with depth control
+- **Validation**: Client-side validation before file processing
+
+## Accessibility
+
+- **Keyboard Navigation**: Support for keyboard interaction
+- **Screen Reader Support**: Proper ARIA labels and semantic structure
+- **Focus Management**: Focus is properly managed during interactions
+- **Drag and Drop**: Accessible drag-and-drop with proper feedback
+- **Error Reporting**: Clear error messages for validation failures
+
+## Browser Support
+
+- **Modern Browsers**: Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
+- **Mobile Browsers**: iOS Safari 14+, Chrome Mobile 88+
+- **File API**: Requires File API support for drag-and-drop
+- **Directory API**: Requires File System Access API for directory traversal
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Files not uploading**: Check file size limits and accepted types
+2. **Drag and drop not working**: Ensure proper event handling and browser support
+3. **Directory traversal issues**: Verify File System Access API support
+4. **Animation not smooth**: Check GSAP installation and configuration
+
+### Debug Mode
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from "vue";
+import { FilePicker } from "@umbra-ui/core";
+
+const files = ref<File[]>([]);
+const errors = ref<FileError[]>([]);
+
+// Watch for changes
+watch(files, (newFiles) => {
+  console.log("Files changed:", newFiles);
+});
+
+watch(errors, (newErrors) => {
+  console.log("Errors changed:", newErrors);
+});
+</script>
+```
+
+## Migration Guide
+
+### From v1 to v2
+
+- `v-model` prop is now `v-model:files`
+- Event names have been updated to use kebab-case
+- File validation system has been improved
+- GSAP integration has been enhanced
+
+### Breaking Changes
+
+- Removed `value` prop in favor of `v-model:files`
+- Changed event names from camelCase to kebab-case
+- Updated file prop to use File[] array instead of single File
+- Modified CSS class naming convention