@adamosuiteservices/ui 2.13.0 → 2.13.1

package/docs/components/ui/file-upload.md

@@ -0,0 +1,473 @@
+# File Upload Component
+
+## Descripción
+
+Componente de carga de archivos con funcionalidad **drag & drop**, validación de extensiones y tamaño, vista previa del archivo seleccionado y área de arrastre visual. Ideal para formularios que requieren subida de archivos con feedback inmediato al usuario.
+
+## Características
+
+- ✅ Drag & Drop con feedback visual
+- ✅ Validación de extensiones de archivo
+- ✅ Validación de tamaño máximo
+- ✅ Vista previa del archivo seleccionado con tamaño
+- ✅ Botón para remover archivo seleccionado
+- ✅ Etiquetas personalizables (i18n)
+- ✅ Estado de arrastre visual (borde y fondo cambian)
+- ✅ Integración con formularios React
+- ✅ TypeScript completo con tipos exportados
+
+## Importación
+
+```typescript
+import { FileUpload } from "@adamosuiteservices/ui/file-upload";
+import type { FileUploadProps, FileUploadLabels } from "@adamosuiteservices/ui/file-upload";
+```
+
+## Uso Básico
+
+```tsx
+import { useState } from "react";
+import { FileUpload } from "@adamosuiteservices/ui/file-upload";
+
+function MyForm() {
+  const [file, setFile] = useState<File | null>(null);
+
+  return (
+    <FileUpload
+      selectedFile={file}
+      onFileSelect={setFile}
+    />
+  );
+}
+```
+
+**Configuración por defecto**:
+- Extensiones aceptadas: `.xls`, `.xlsx`, `.numbers`
+- Tamaño máximo: 50 MB
+
+## Props
+
+### selectedFile (requerido)
+
+```tsx
+selectedFile: File | null
+```
+
+Estado del archivo actualmente seleccionado. Usa `null` cuando no hay archivo.
+
+### onFileSelect (requerido)
+
+```tsx
+onFileSelect: (file: File | null) => void
+```
+
+Callback invocado cuando el usuario selecciona o remueve un archivo.
+
+### acceptedExtensions
+
+```tsx
+acceptedExtensions?: string[]
+```
+
+Array de extensiones de archivo permitidas. Por defecto: `[".xls", ".xlsx", ".numbers"]`
+
+**Ejemplo**:
+```tsx
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  acceptedExtensions={[".pdf", ".doc", ".docx"]}
+/>
+```
+
+### maxSizeInMB
+
+```tsx
+maxSizeInMB?: number
+```
+
+Tamaño máximo del archivo en megabytes. Por defecto: `50`
+
+**Ejemplo**:
+```tsx
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  maxSizeInMB={10}
+/>
+```
+
+### labels
+
+```tsx
+labels?: FileUploadLabels
+
+type FileUploadLabels = {
+  dragDrop?: string
+  selectFile?: string
+  fileRequirements?: string
+}
+```
+
+Etiquetas personalizables para internacionalización o textos específicos.
+
+**Ejemplo**:
+```tsx
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  labels={{
+    dragDrop: "Arrastra y suelta tu archivo aquí o",
+    selectFile: "Selecciona el archivo",
+    fileRequirements: "Archivos permitidos: .xls, .xlsx. Tamaño máximo 50 MB."
+  }}
+/>
+```
+
+## Ejemplos
+
+### Archivos de Excel (Por Defecto)
+
+```tsx
+const [file, setFile] = useState<File | null>(null);
+
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+/>
+```
+
+### Imágenes
+
+```tsx
+const [image, setImage] = useState<File | null>(null);
+
+<FileUpload
+  selectedFile={image}
+  onFileSelect={setImage}
+  acceptedExtensions={[".jpg", ".jpeg", ".png", ".gif", ".webp"]}
+  maxSizeInMB={5}
+  labels={{
+    dragDrop: "Drag and drop your image here or",
+    selectFile: "Select an image",
+    fileRequirements: "Supported formats: JPG, PNG, GIF, WebP. Max 5MB."
+  }}
+/>
+```
+
+### Documentos PDF
+
+```tsx
+const [document, setDocument] = useState<File | null>(null);
+
+<FileUpload
+  selectedFile={document}
+  onFileSelect={setDocument}
+  acceptedExtensions={[".pdf"]}
+  maxSizeInMB={20}
+  labels={{
+    dragDrop: "Drag and drop your PDF here or",
+    selectFile: "Select PDF",
+    fileRequirements: "Only PDF files. Maximum 20 MB."
+  }}
+/>
+```
+
+### CSV/Excel para Importación
+
+```tsx
+const [dataFile, setDataFile] = useState<File | null>(null);
+
+<FileUpload
+  selectedFile={dataFile}
+  onFileSelect={setDataFile}
+  acceptedExtensions={[".csv", ".xls", ".xlsx"]}
+  maxSizeInMB={30}
+/>
+```
+
+### Archivos Comprimidos
+
+```tsx
+const [archive, setArchive] = useState<File | null>(null);
+
+<FileUpload
+  selectedFile={archive}
+  onFileSelect={setArchive}
+  acceptedExtensions={[".zip", ".rar", ".7z"]}
+  maxSizeInMB={500}
+  labels={{
+    dragDrop: "Drag and drop your archive here or",
+    selectFile: "Select the archive"
+  }}
+/>
+```
+
+### Con Integración en Formulario
+
+```tsx
+function UploadForm() {
+  const [file, setFile] = useState<File | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!file) return;
+
+    const formData = new FormData();
+    formData.append("file", file);
+
+    try {
+      const response = await fetch("/api/upload", {
+        method: "POST",
+        body: formData
+      });
+      
+      if (response.ok) {
+        alert("File uploaded successfully!");
+        setFile(null);
+      }
+    } catch (error) {
+      console.error("Upload failed:", error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <FileUpload
+        selectedFile={file}
+        onFileSelect={setFile}
+      />
+      <Button type="submit" disabled={!file}>
+        Upload File
+      </Button>
+    </form>
+  );
+}
+```
+
+## Estados Visuales
+
+### Sin Archivo Seleccionado
+
+El componente muestra:
+- Área de drag & drop con borde punteado
+- Icono de documento en fondo azul claro
+- Texto instructivo y link para seleccionar archivo
+- Requisitos del archivo (extensiones y tamaño)
+
+### Durante Drag Over
+
+Cuando el usuario arrastra un archivo sobre el área:
+- Borde cambia a `border-primary-500`
+- Fondo cambia a `bg-primary-50`
+- Transición suave con `transition-colors`
+
+### Con Archivo Seleccionado
+
+El componente muestra:
+- Tarjeta con fondo `bg-neutral-100`
+- Icono de documento en fondo blanco
+- Nombre del archivo (con truncate si es largo)
+- Tamaño del archivo en MB
+- Botón destructivo para remover el archivo
+
+## Validación
+
+El componente valida automáticamente:
+
+1. **Extensión**: Solo acepta archivos con extensiones en `acceptedExtensions`
+2. **Tamaño**: Rechaza archivos mayores a `maxSizeInMB`
+
+Si un archivo no cumple estas validaciones, no se selecciona y `onFileSelect` no se invoca.
+
+## Estilos Base
+
+### Área de Drag & Drop
+
+- Padding: `p-6` (24px)
+- Border radius: `rounded-2xl` (16px)
+- Border: `border-2 border-dashed`
+- Gap entre elementos: `gap-6` (24px)
+- Transiciones: `transition-colors`
+
+### Estado Normal vs Dragging
+
+```tsx
+// Normal
+border-neutral-300 bg-neutral-50
+
+// Dragging
+border-primary-500 bg-primary-50
+```
+
+### Tarjeta de Archivo Seleccionado
+
+- Padding: `p-6` (24px)
+- Border radius: `rounded-2xl` (16px)
+- Background: `bg-neutral-100`
+- Gap horizontal: `gap-4` (16px)
+- Icono en fondo blanco con `rounded-xl` y `p-2.5`
+
+### Botón de Remover
+
+- Variante: `destructive-medium`
+- Icono: `delete` de Material Symbols
+- Color del icono: `text-destructive-500`
+
+## Accesibilidad
+
+- Input file oculto con `className="adm:hidden"`
+- Label asociado correctamente con `htmlFor="file-upload"`
+- Botón de link usa `asChild` para comportamiento semántico
+- Typography con color `muted` para textos secundarios
+
+## Buenas Prácticas
+
+### ✅ Recomendado
+
+```tsx
+// Estado controlado con useState
+const [file, setFile] = useState<File | null>(null);
+
+// Validación de tamaño apropiada
+maxSizeInMB={10} // Para documentos comunes
+maxSizeInMB={5}  // Para imágenes
+maxSizeInMB={500} // Para archivos grandes (zip, videos)
+
+// Labels específicas y claras
+labels={{
+  dragDrop: "Drag and drop your invoice here or",
+  selectFile: "Select invoice",
+  fileRequirements: "PDF only. Max 10MB."
+}}
+
+// Reset después de upload exitoso
+onSuccess={() => setFile(null)}
+```
+
+### ❌ Evitar
+
+```tsx
+// No validar el archivo antes de hacer upload
+// Siempre verificar que file no sea null
+
+// Extensiones demasiado permisivas
+acceptedExtensions={[".*"]} // Inseguro
+
+// Tamaño excesivo sin justificación
+maxSizeInMB={10000} // 10GB es excesivo
+
+// Labels genéricas cuando el contexto es específico
+labels={{ selectFile: "Select file" }} // Poco descriptivo
+```
+
+## Tipos TypeScript
+
+```typescript
+export type FileUploadLabels = {
+  dragDrop?: string
+  selectFile?: string
+  fileRequirements?: string
+};
+
+export type FileUploadProps = ComponentProps<"div"> & Readonly<{
+  selectedFile: File | null
+  onFileSelect: (file: File | null) => void
+  acceptedExtensions?: string[]
+  maxSizeInMB?: number
+  labels?: FileUploadLabels
+}>;
+```
+
+## Integración con Backend
+
+### FormData para Upload
+
+```tsx
+const uploadFile = async (file: File) => {
+  const formData = new FormData();
+  formData.append("file", file);
+  formData.append("metadata", JSON.stringify({
+    uploadedAt: new Date().toISOString()
+  }));
+
+  const response = await fetch("/api/upload", {
+    method: "POST",
+    body: formData
+  });
+
+  return response.json();
+};
+```
+
+### Con Progress Tracking
+
+```tsx
+const [progress, setProgress] = useState(0);
+
+const uploadWithProgress = async (file: File) => {
+  const formData = new FormData();
+  formData.append("file", file);
+
+  const xhr = new XMLHttpRequest();
+
+  xhr.upload.addEventListener("progress", (e) => {
+    if (e.lengthComputable) {
+      setProgress((e.loaded / e.total) * 100);
+    }
+  });
+
+  xhr.open("POST", "/api/upload");
+  xhr.send(formData);
+};
+```
+
+## Personalización
+
+### Custom Styling
+
+```tsx
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  className="adm:max-w-2xl adm:mx-auto"
+/>
+```
+
+### Con Wrapper Adicional
+
+```tsx
+<div className="adm:space-y-4">
+  <Label>Upload your document</Label>
+  <FileUpload
+    selectedFile={file}
+    onFileSelect={setFile}
+  />
+  {file && (
+    <Typography color="success">
+      ✓ File ready to upload
+    </Typography>
+  )}
+</div>
+```
+
+## Comparación con Input type="file"
+
+| Característica | Input file nativo | FileUpload |
+|----------------|-------------------|------------|
+| Drag & Drop | ❌ No | ✅ Sí |
+| Validación visual | ❌ No | ✅ Sí |
+| Preview del archivo | ❌ No | ✅ Sí con nombre y tamaño |
+| Extensiones validadas | ⚠️ Solo accept attribute | ✅ Con feedback visual |
+| Tamaño validado | ❌ Solo en backend | ✅ Cliente y servidor |
+| UX consistente | ❌ Varía por browser | ✅ Consistente |
+| Labels customizables | ❌ No | ✅ Sí (i18n friendly) |
+
+## Notas
+
+- El componente usa `File` API nativa del browser
+- La validación es solo en cliente - siempre validar también en el servidor
+- El drag & drop solo funciona con un archivo a la vez
+- Los archivos no se almacenan automáticamente - manejar el upload con `onFileSelect`
+- El componente es completamente controlado - el padre maneja el estado del archivo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "2.13.0",
+  "version": "2.13.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",