@adamosuiteservices/ui 2.13.1 → 2.13.3

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

@@ -2,15 +2,19 @@
 
 ## 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.
+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. Soporta tanto carga de un solo archivo como múltiples archivos. Ideal para formularios que requieren subida de archivos con feedback inmediato al usuario.
 
 ## Características
 
 - ✅ Drag & Drop con feedback visual
+- ✅ Modo simple (un archivo) y múltiple (varios archivos)
 - ✅ 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
+- ✅ Vista previa del archivo/archivos seleccionados con tamaño
+- ✅ Botón para remover archivos individuales
+- ✅ Botón "Clear all" para modo múltiple
+- ✅ Posición configurable de archivos (arriba/abajo)
+- ✅ Límite de cantidad de archivos en modo múltiple
 - ✅ Etiquetas personalizables (i18n)
 - ✅ Estado de arrastre visual (borde y fondo cambian)
 - ✅ Integración con formularios React
@@ -25,6 +29,8 @@ import type { FileUploadProps, FileUploadLabels } from "@adamosuiteservices/ui/f
 
 ## Uso Básico
 
+### Un Solo Archivo
+
 ```tsx
 import { useState } from "react";
 import { FileUpload } from "@adamosuiteservices/ui/file-upload";
@@ -41,27 +47,245 @@ function MyForm() {
 }
 ```
 
+### Múltiples Archivos
+
+```tsx
+import { useState } from "react";
+import { FileUpload } from "@adamosuiteservices/ui/file-upload";
+
+function MyForm() {
+  const [files, setFiles] = useState<File[]>([]);
+
+  return (
+    <FileUpload
+      selectedFiles={files}
+      onFilesSelect={setFiles}
+      multiple
+    />
+  );
+}
+```
+
 **Configuración por defecto**:
 - Extensiones aceptadas: `.xls`, `.xlsx`, `.numbers`
 - Tamaño máximo: 50 MB
+- Máximo de archivos (modo múltiple): 10
+- Posición de archivos: `below`
 
 ## Props
 
-### selectedFile (requerido)
+### Modo Simple (Un Archivo)
+
+#### selectedFile
 
 ```tsx
-selectedFile: File | null
+selectedFile?: File | null
 ```
 
 Estado del archivo actualmente seleccionado. Usa `null` cuando no hay archivo.
 
-### onFileSelect (requerido)
+#### onFileSelect
+
+```tsx
+onFileSelect?: (file: File | null) => void
+```
+
+### Props Comunes
+
+#### acceptedExtensions
 
 ```tsx
-onFileSelect: (file: File | null) => void
+acceptedExtensions?: string[]
 ```
 
-Callback invocado cuando el usuario selecciona o remueve un archivo.
+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
+  filesSelected?: (count: number) => 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."
+  }}
+/>
+```
+
+#### invalid
+
+```tsx
+invalid?: boolean
+```
+
+Marca el componente como inválido, aplicando estilos destructivos. Por defecto: `false`
+
+**Ejemplo**:
+```tsx
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  invalid={!!errorMessage}
+/>
+```
+
+#### onInvalidFile
+
+```tsx
+onInvalidFile?: (file: File, reason: "extension" | "size") => void
+```
+
+Callback invocado cuando un archivo no pasa la validación. Recibe el archivo y el motivo del rechazo.
+
+**Ejemplo**:
+```tsx
+const handleInvalidFile = (file: File, reason: "extension" | "size") => {
+  if (reason === "extension") {
+    setError(`File "${file.name}" has an invalid extension.`);
+  } else if (reason === "size") {
+    setError(`File "${file.name}" exceeds the maximum size limit.`);
+  }
+};
+
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  onInvalidFile={handleInvalidFile}
+  invalid={!!error}
+/>
+```
+
+### Modo Múltiple
+
+#### selectedFiles
+
+```tsx
+selectedFiles?: File[]
+```
+
+Array de archivos seleccionados.
+
+#### onFilesSelect
+
+```tsx
+onFilesSelect?: (files: File[]) => void
+```
+
+Callback invocado cuando el usuario selecciona, agrega o remueve archivos.
+
+#### multiple
+
+```tsx
+multiple?: boolean
+```
+
+Habilita el modo de múltiples archivos. Por defecto: `false`
+
+#### maxFiles
+
+```tsx
+maxFiles?: number
+```
+
+Número máximo de archivos permitidos en modo múltiple. Por defecto: `10`
+
+#### filesPosition
+
+```tsx
+filesPosition?: "above" | "below"
+```
+
+Posición donde aparecen los archivos seleccionados en modo múltiple:
+- `"above"` - Archivos arriba del área de drag & drop
+- `"below"` - Archivos debajo del área de drag & drop (por defecto)
+
+**Ejemplo**:
+```tsx
+<FileUpload
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  multiple
+  filesPosition="above"
+/>
+```
+
+#### labels
+
+```tsx
+labels?: FileUploadLabels
+
+type FileUploadLabels = {
+  dragDrop?: string
+  selectFile?: string
+  fileRequirements?: string
+  filesSelected?: (count: number) => 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."
+  }}
+/>
+
+// Modo múltiple con contador personalizado
+<FileUpload
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  multiple
+  labels={{
+    filesSelected: (count) => `${count} documento${count !== 1 ? "s" : ""} seleccionado${count !== 1 ? "s" : ""}`
+  }}
+/>
+```Comunes
 
 ### acceptedExtensions
 
@@ -133,35 +357,110 @@ const [file, setFile] = useState<File | null>(null);
 
 <FileUpload
   selectedFile={file}
-  onFileSelect={setFile}
+### Múltiples Archivos
+
+```tsx
+const [files, setFiles] = useState<File[]>([]);
+
+<FileUpload
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  multiple
+  maxFiles={5}
+  labels={{
+    dragDrop: "Drag and drop your files here or",
+    selectFile: "Select files"
+  }}
 />
 ```
 
-### Imágenes
+### Múltiples Imágenes
 
 ```tsx
-const [image, setImage] = useState<File | null>(null);
+const [images, setImages] = useState<File[]>([]);
 
 <FileUpload
-  selectedFile={image}
-  onFileSelect={setImage}
+  selectedFiles={images}
+  onFilesSelect={setImages}
+  multiple
   acceptedExtensions={[".jpg", ".jpeg", ".png", ".gif", ".webp"]}
   maxSizeInMB={5}
+  maxFiles={10}
   labels={{
-    dragDrop: "Drag and drop your image here or",
-    selectFile: "Select an image",
-    fileRequirements: "Supported formats: JPG, PNG, GIF, WebP. Max 5MB."
+    dragDrop: "Drag and drop your images here or",
+    selectFile: "Select images",
+    fileRequirements: "Supported formats: JPG, PNG, GIF, WebP. Max 5MB each. Up to 10 images.",
+    filesSelected: (count) => `${count} image${count !== 1 ? "s" : ""} selected`
   }}
 />
 ```
 
-### Documentos PDF
+### Archivos Arriba del Área de Drop
 
 ```tsx
-const [document, setDocument] = useState<File | null>(null);
+const [files, setFiles] = useState<File[]>([]);
 
 <FileUpload
-  selectedFile={document}
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  multiple
+  filesPosition="above"
+  acceptedExtensions={[".pdf"]}
+  maxSizeInMB={10}
+/>
+```
+/>
+```
+
+### Imágenes
+
+```tsx
+const [image, setImage] = useState<File | null>(null);
+
+## Estados Visuales
+
+### Modo Simple
+
+#### 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)
+
+#### Con Archivo Seleccionado
+
+El área de drag & drop se oculta y muestra:
+- Tarjeta con fondo `bg-muted` y borde
+- Icono de documento en fondo `bg-primary-50`
+- Nombre del archivo (con truncate si es largo)
+- Tamaño del archivo en MB
+- Botón destructivo para remover el archivo
+
+### Modo Múltiple
+
+#### Sin Archivos
+
+Solo se muestra el área de drag & drop.
+
+### Durante Drag Over
+
+Cuando el usuario arrastra archivos sobre el área:
+- Borde cambia a `border-primary`
+- Transición suave con `transition-colors`
+
+### Estado Inválido
+
+Cuando `invalid={true}`:
+- Borde: `border-destructive`
+- Fondo: `bg-destructive/5`
+- Icono de documento: `text-destructive` con fondo `bg-destructive/10`
+- Texto de requisitos: `text-destructive`
+- Contador de archivos: `text-destructive`
+- Tarjetas de archivos: borde y fondo con colores destructivos
+
+## Validacióne={document}
   onFileSelect={setDocument}
   acceptedExtensions={[".pdf"]}
   maxSizeInMB={20}
@@ -171,22 +470,83 @@ const [document, setDocument] = useState<File | null>(null);
     fileRequirements: "Only PDF files. Maximum 20 MB."
   }}
 />
-```
+## 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`
+3. **Cantidad** (modo múltiple): Limita a `maxFiles` cantidad de archivos
 
-### CSV/Excel para Importación
+Si un archivo no cumple estas validaciones:
+- No se selecciona
+- Los callbacks `onFileSelect`/`onFilesSelect` no se invocan
+- El callback `onInvalidFile` se invoca (si está definido) con el archivo y el motivo
+
+### Ejemplo con Validación Completa
 
 ```tsx
-const [dataFile, setDataFile] = useState<File | null>(null);
+const [file, setFile] = useState<File | null>(null);
+const [error, setError] = useState<string>("");
+
+const handleInvalidFile = (file: File, reason: "extension" | "size") => {
+  if (reason === "extension") {
+    setError(`El archivo "${file.name}" tiene una extensión no permitida.`);
+  } else {
+    setError(`El archivo "${file.name}" excede el tamaño máximo.`);
+  }
+  // Auto-limpiar error después de 5 segundos
+  setTimeout(() => setError(""), 5000);
+};
 
 <FileUpload
-  selectedFile={dataFile}
-  onFileSelect={setDataFile}
-  acceptedExtensions={[".csv", ".xls", ".xlsx"]}
-  maxSizeInMB={30}
+  selectedFile={file}
+  onFileSelect={(newFile) => {
+    setFile(newFile);
+    setError(""); // Limpiar error al seleccionar archivo válido
+  }}
+  onInvalidFile={handleInvalidFile}
+  invalid={!!error}
+  acceptedExtensions={[".pdf", ".docx"]}
+  maxSizeInMB={2}
 />
+
+{error && (
+  <div className="adm:rounded-lg adm:border adm:border-destructive adm:bg-destructive/5 adm:p-4">
+    <Typography color="destructive" className="adm:text-sm adm:font-medium">
+      {error}
+    </Typography>
+  </div>
+)}
+```
+
+## Comportamiento por Modo
+
+### Modo Simple (`selectedFile` + `onFileSelect`)
+
+- Solo permite un archivo a la vez
+- El área de drag & drop se reemplaza con la vista del archivo seleccionado
+- Arrastrar un nuevo archivo reemplaza el anterior
+- Usar el input también reemplaza el archivo
+
+### Estado Normal vs Dragging
+
+```tsx
+// Normal
+border-input bg-background
+
+// Dragging
+border-primary
 ```
 
-### Archivos Comprimidos
+### Tarjeta de Archivo Seleccionado
+
+- Padding: `p-6` (24px)
+- Border radius: `rounded-2xl` (16px)
+- Background: `bg-muted`
+- Border: `border-input`
+- Gap horizontal: `gap-4` (16px)
+- Icono en fondo `bg-primary-50` con `rounded-xl` y `p-2.5`
 
 ```tsx
 const [archive, setArchive] = useState<File | null>(null);
@@ -223,11 +583,17 @@ function UploadForm() {
         body: formData
       });
       
-      if (response.ok) {
-        alert("File uploaded successfully!");
-        setFile(null);
-      }
-    } catch (error) {
+### Botón de Remover
+
+- Variante: `destructive-medium`
+- Icono: `delete` de Material Symbols
+- Color del icono: `text-destructive`
+
+### Botón Clear All (Modo Múltiple)
+
+- Variante: `ghost`
+- Size: `sm`
+- Aparece solo cuando hay 2+ archivos
       console.error("Upload failed:", error);
     }
   };
@@ -321,33 +687,70 @@ border-primary-500 bg-primary-50
 - Label asociado correctamente con `htmlFor="file-upload"`
 - Botón de link usa `asChild` para comportamiento semántico
 - Typography con color `muted` para textos secundarios
+## Tipos TypeScript
 
-## Buenas Prácticas
+```typescript
+export type FileUploadLabels = {
+  dragDrop?: string
+  selectFile?: string
+  fileRequirements?: string
+  filesSelected?: (count: number) => string
+};
 
-### ✅ Recomendado
+export type FileUploadProps = ComponentProps<"div"> & Readonly<{
+  // Modo simple
+  selectedFile?: File | null
+  onFileSelect?: (file: File | null) => void
+  
+  // Modo múltiple
+  selectedFiles?: File[]
+  onFilesSelect?: (files: File[]) => void
+  multiple?: boolean
+  maxFiles?: number
+  filesPosition?: "above" | "below"
+  
+  // Validación
+  onInvalidFile?: (file: File, reason: "extension" | "size") => void
+  invalid?: boolean
+  
+  // Común
+  acceptedExtensions?: string[]
+  maxSizeInMB?: number
+  labels?: FileUploadLabels
+### FormData para Upload
 
 ```tsx
-// Estado controlado con useState
-const [file, setFile] = useState<File | null>(null);
+// Un archivo
+const uploadFile = async (file: File) => {
+  const formData = new FormData();
+  formData.append("file", file);
+  formData.append("metadata", JSON.stringify({
+    uploadedAt: new Date().toISOString()
+  }));
 
-// Validación de tamaño apropiada
-maxSizeInMB={10} // Para documentos comunes
-maxSizeInMB={5}  // Para imágenes
-maxSizeInMB={500} // Para archivos grandes (zip, videos)
+  const response = await fetch("/api/upload", {
+    method: "POST",
+    body: formData
+  });
 
-// Labels específicas y claras
-labels={{
-  dragDrop: "Drag and drop your invoice here or",
-  selectFile: "Select invoice",
-  fileRequirements: "PDF only. Max 10MB."
-}}
+  return response.json();
+};
 
-// Reset después de upload exitoso
-onSuccess={() => setFile(null)}
-```
+// Múltiples archivos
+const uploadFiles = async (files: File[]) => {
+  const formData = new FormData();
+  files.forEach((file, index) => {
+    formData.append(`file${index}`, file);
+  });
 
-### ❌ Evitar
+  const response = await fetch("/api/upload-multiple", {
+    method: "POST",
+    body: formData
+  });
 
+  return response.json();
+};
+```
 ```tsx
 // No validar el archivo antes de hacer upload
 // Siempre verificar que file no sea null
@@ -408,25 +811,31 @@ 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);
-};
-```
+## Comparación con Input type="file"
 
-## Personalización
+| Característica | Input file nativo | FileUpload |
+|----------------|-------------------|------------|
+| Drag & Drop | ❌ No | ✅ Sí |
+| Modo múltiple | ⚠️ Básico | ✅ Completo con UI |
+| Validación visual | ❌ No | ✅ Sí |
+| Preview de archivos | ❌ No | ✅ Sí con nombre y tamaño |
+| Extensiones validadas | ⚠️ Solo accept attribute | ✅ Con feedback visual |
+| Tamaño validado | ❌ Solo en backend | ✅ Cliente y servidor |
+| Límite de archivos | ❌ No | ✅ Sí (maxFiles) |
+| Remover archivos | ❌ No | ✅ Individual y Clear all |
+| Posición de preview | ❌ No configurable | ✅ Arriba o abajo |
+| UX consistente | ❌ Varía por browser | ✅ Consistente |
+| Labels customizables | ❌ No | ✅ Sí (i18n friendly) |
 
-### Custom Styling
+## Notas
 
+- El componente usa `File` API nativa del browser
+- La validación es solo en cliente - siempre validar también en el servidor
+- En modo simple, el drag & drop acepta un archivo a la vez
+- En modo múltiple, se pueden arrastrar múltiples archivos simultáneamente
+- Los archivos no se almacenan automáticamente - manejar el upload con los callbacks
+- El componente es completamente controlado - el padre maneja el estado de los archivos
+- El input file es reutilizable: después de seleccionar, se resetea para permitir seleccionar el mismo archivo de nuevo
 ```tsx
 <FileUpload
   selectedFile={file}