🧰 AlpuraUploadFileDropComponent – Guía de uso

Componente de zona de carga (drag & drop + selector de archivo) con validación estricta opcional. Permite recibir archivos desde la interacción de clic o arrastrar/soltar, soporta carga de un único archivo o múltiples archivos y expone eventos para manejar archivos válidos, inválidos y eliminación de archivos.

---

📁 Importación

import { AlpuraUploadFileDropComponent } from '@alpura/commons';

---

🎛️ Inputs

Input	Tipo	Default	Descripción
accept	string	".xlsx,.xls"	Cadena para el atributo accept del <input type="file">. Se usa también para listar formatos soportados.
disabled	boolean	false	Desactiva la zona de carga e impide interacción (clic/teclado/drag&drop).
iconName	string	"cloud_upload"	Nombre del ícono de Material que se muestra en la zona.
uploadText	string	"Arrastra tu archivo aquí o haz clic para seleccionar"	Texto guía principal mostrado en la zona.
hint	string	""	Opcional. HTML permitido como ayuda. Si está vacío, se muestran los formatos derivados de accept.
strictAccept	boolean	true	Valida estrictamente contra accept. Si es false, se acepta cualquier archivo.
showFormats	boolean	true	Muestra automáticamente los formatos permitidos debajo de la zona. Solo aplica cuando hint está vacío.
showFileStatus	boolean	false	Muestra el recuadro de estado con el nombre del archivo cargado y un botón para eliminarlo.
canUploadMultiFiles	boolean	false	Habilita la carga de múltiples archivos. Cada archivo se procesa y emite de forma individual.
loadingDelay	number	1200	Tiempo mínimo en milisegundos que se muestra la animación de carga.
extraMimes	string[]	["application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel"]	Lista adicional de tipos MIME permitidos como complemento de accept.

---

📤 Outputs

Output	Parámetros	Descripción
file	File	Se emite cuando se selecciona o suelta un archivo válido.
fileInvalid	{ reason: InvalidReason, file?: File, message: string }	Se emite cuando un archivo es rechazado. Incluye el motivo y el mensaje de error.
fileCleared	{ fileName?: string, index?: number }	Se emite cuando el usuario elimina un archivo cargado. En modo múltiple incluye el índice.

InvalidReason

Valor	Descripción
empty_file	No se seleccionó ningún archivo.
extension_not_allowed	La extensión del archivo no está permitida.
mime_not_allowed	El tipo MIME del archivo no está permitido.

---

💻 Ejemplos de uso

1) Configuración por defecto (xlsx/xls)

<alpura-upload-file-drop
  (file)="onFilePicked($event)"
  (fileInvalid)="onUploadInvalid($event)"
>
</alpura-upload-file-drop>

2) Con validación estricta en HTML

<alpura-upload-file-drop
  [accept]="'.xlsx,.xls'"
  [strictAccept]="true"
  [iconName]="'cloud_upload'"
  [uploadText]="'Arrastra tu archivo o haz clic'"
  [hint]="'<em>Solo archivos .xlsx o .xls. Tamaño recomendado &lt; 10 MB.</em>'"
  (file)="onFilePicked($event)"
  (fileInvalid)="onUploadInvalid($event)"
>
</alpura-upload-file-drop>

3) Carga múltiple de archivos con estado visible

Activa canUploadMultiFiles y showFileStatus para permitir que el usuario suba varios archivos y vea la lista con opción de eliminar cada uno.

<alpura-upload-file-drop
  [accept]="'.xlsx,.xls'"
  [canUploadMultiFiles]="true"
  [showFileStatus]="true"
  [uploadText]="'Arrastra tus archivos o haz clic para seleccionarlos'"
  (file)="onFilePicked($event)"
  (fileInvalid)="onUploadInvalid($event)"
  (fileCleared)="onFileCleared($event)"
>
</alpura-upload-file-drop>

TypeScript

onFilePicked(file: File): void {
  // Inicia la carga real
}

onUploadInvalid(e: { reason: 'empty_file' | 'extension_not_allowed' | 'mime_not_allowed'; file?: File; message: string }): void {
  console.warn(`Archivo inválido: ${e.message}`);
}

onFileCleared(e: { fileName?: string; index?: number }): void {
  // En modo múltiple, `index` indica qué archivo se eliminó
  console.log(`Archivo eliminado: ${e.fileName} (índice: ${e.index})`);
}

---

🧠 Comportamiento

• Soporta clic, teclado (Enter / Espacio) y arrastrar/soltar.
• Si strictAccept es true, valida por extensión, tipo MIME y extraMimes; los archivos que no pasen disparan fileInvalid.
• Si disabled es true, se bloquea cualquier interacción.
• Si showFormats es true y hint está vacío, muestra automáticamente la lista de formatos derivada de accept.
• Si showFileStatus es true, muestra el nombre del archivo cargado con un botón para eliminarlo.

📂 Modo múltiple (canUploadMultiFiles: true)

• El input acepta el atributo multiple, permitiendo seleccionar varios archivos a la vez.
• Cada archivo se procesa y valida de forma individual.
• Cada archivo válido emite su propio evento file.
• Se mantiene una lista interna (fileNames) con el estado de carga (loading: boolean) por archivo.
• Al eliminar un archivo se emite fileCleared con { fileName, index }.
• Los archivos inválidos dentro de una selección múltiple también disparan fileInvalid individualmente.

---

🚀 Resultado esperado

Escenario	Evento emitido
Archivo válido seleccionado	file → File
Archivo con extensión no permitida	fileInvalid → { reason: 'extension_not_allowed', file, message }
Archivo vacío	fileInvalid → { reason: 'empty_file', message }
Tipo MIME no permitido	fileInvalid → { reason: 'mime_not_allowed', file, message }
Usuario elimina un archivo	fileCleared → { fileName, index? }

---

📬 Soporte

Para dudas o mantenimiento del componente AlpuraUploadFileDropComponent, contactar al equipo de arquitectura.