@adamosuiteservices/ui 2.18.0 → 2.18.2

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

@@ -4,6 +4,8 @@
 
 File upload component with **drag & drop** functionality, extension and size validation, preview of selected files, and visual drag area. Supports both single file and multiple file upload. Ideal for forms that require file uploads with immediate user feedback.
 
+> **Looking for server integration?** Check out [FileUploadV2](file-upload-v2.md) which includes automatic ID generation and metadata support for server-side file tracking.
+
 ## Features
 
 - ✅ Drag & drop with visual feedback
@@ -437,50 +439,13 @@ Position where selected files appear in multiple mode:
 />
 ```
 
-#### labels
-
-```tsx
-labels?: FileUploadLabels
-
-type FileUploadLabels = {
-  dragDrop?: string
-  selectFile?: string
-  fileRequirements?: string
-  filesSelected?: (count: number) => string
-}
-```
-
-Customizable labels for internationalization or specific texts.
-
-**Example**:
-
-````tsx
-<FileUpload
-  selectedFile={file}
-  onFileSelect={setFile}
-  labels={{
-    dragDrop: "Drag and drop your file here or",
-    selectFile: "Select the file",
-    fileRequirements: "Allowed files: .xls, .xlsx. Maximum size 50 MB."
-  }}
-/>
-
-// Multiple mode with custom counter
-<FileUpload
-  selectedFiles={files}
-  onFilesSelect={setFiles}
-  multiple
-  labels={{
-    filesSelected: (count) => `${count} document${count !== 1 ? "s" : ""} selected`
-  }}
-/>
-```Comunes
+## Examples
 
-### acceptedExtensions
+### With Field components
 
 ```tsx
 acceptedExtensions?: string[]
-````
+```
 
 Array of allowed file extensions. Default: `[".xls", ".xlsx", ".numbers"]`
 
@@ -508,87 +473,44 @@ Maximum file size in megabytes. Default: `50`
 <FileUpload selectedFile={file} onFileSelect={setFile} maxSizeInMB={10} />
 ```
 
-### labels
-
-```tsx
-labels?: FileUploadLabels
+## Examples
 
-type FileUploadLabels = {
-  dragDrop?: string
-  selectFile?: string
-  fileRequirements?: string
+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.`);
 }
-```
-
-Customizable labels for internationalization or specific texts.
-
-**Example**:
+};
 
-```tsx
+return (
+<FieldGroup className="adm:max-w-xl">
+<Field>
+<FieldLabel>Upload document (PDF or DOCX only, max 2MB)</FieldLabel>
 <FileUpload
-  selectedFile={file}
-  onFileSelect={setFile}
-  labels={{
-    dragDrop: "Drag and drop your file here or",
-    selectFile: "Select the file",
-    fileRequirements: "Allowed files: .xls, .xlsx. Maximum size 50 MB.",
-  }}
+selectedFile={file}
+onFileSelect={(newFile) => {
+setFile(newFile);
+if (newFile) setError("");
+}}
+onInvalidFile={handleInvalidFile}
+aria-invalid={!!error}
+acceptedExtensions={[".pdf", ".docx"]}
+maxSizeInMB={2}
 />
-```
-
-## Examples
-
-### With Field components
-
-```tsx
-import {
-  Field,
-  FieldLabel,
-  FieldDescription,
-  FieldError,
-  FieldGroup,
-} from "@adamosuiteservices/ui/field";
-import { FileUpload } from "@adamosuiteservices/ui/file-upload";
-
-function FileUploadForm() {
-  const [file, setFile] = useState<File | null>(null);
-  const [error, setError] = useState<string>("");
-
-  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.`);
-    }
-  };
-
-  return (
-    <FieldGroup className="adm:max-w-xl">
-      <Field>
-        <FieldLabel>Upload document (PDF or DOCX only, max 2MB)</FieldLabel>
-        <FileUpload
-          selectedFile={file}
-          onFileSelect={(newFile) => {
-            setFile(newFile);
-            if (newFile) setError("");
-          }}
-          onInvalidFile={handleInvalidFile}
-          aria-invalid={!!error}
-          acceptedExtensions={[".pdf", ".docx"]}
-          maxSizeInMB={2}
-        />
-        {error ? (
-          <FieldError>{error}</FieldError>
-        ) : (
-          <FieldDescription>
-            Supported formats: PDF, DOCX. Maximum 2MB.
-          </FieldDescription>
-        )}
-      </Field>
-    </FieldGroup>
-  );
+{error ? (
+<FieldError>{error}</FieldError>
+) : (
+<FieldDescription>
+Supported formats: PDF, DOCX. Maximum 2MB.
+</FieldDescription>
+)}
+</Field>
+</FieldGroup>
+);
 }
-```
+
+````
 
 ### Estado Deshabilitado
 
@@ -633,7 +555,7 @@ function DisabledWithFileExample() {
     </FieldGroup>
   );
 }
-```
+````
 
 ### Inside fieldset disabled
 
@@ -992,269 +914,97 @@ const handleInvalidFile = (file: File, reason: "extension" | "size") => {
 - Dragging a new file replaces the previous one
 - Using the input also replaces the file
 
-### Normal state vs dragging
+### Multiple mode (`selectedFiles` + `onFilesSelect`)
 
-```tsx
-// Normal
-border-input bg-background
+- Allows multiple files up to `maxFiles` limit
+- Files can be displayed above or below the drop area (`filesPosition`)
+- Each file has its own remove button
+- A "Clear all" button appears when there are 2+ files
 
-// Dragging
-border-primary
-```
+### Visual styling details
 
-### Selected file card
+**Drag & drop area:**
+
+- Padding: `p-6` (24px)
+- Border radius: `rounded-2xl` (16px)
+- Border: `border-2 border-dashed`
+- Normal state: `border-input bg-background`
+- Dragging: `border-primary`
+- Transitions: `transition-colors`
+
+**Selected file card:**
 
 - Padding: `p-6` (24px)
 - Border radius: `rounded-2xl` (16px)
 - Background: `bg-muted`
 - Border: `border-input`
 - Horizontal gap: `gap-4` (16px)
-- Icon on `bg-primary-50` background with `rounded-xl` and `p-2.5`
-
-```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",
-  }}
-/>;
-```
-
-### With form integration
-
-```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);
+- Icon: `text-primary` on `bg-primary/15` background
 
-    try {
-      const response = await fetch("/api/upload", {
-        method: "POST",
-        body: formData
-      });
-
-### Remove button
+**Remove button:**
 
 - Variant: `destructive-medium`
 - Icon: `delete` from Material Symbols
 - Icon color: `text-destructive`
 
-### Clear all button (multiple mode)
+**Clear all button (multiple mode):**
 
 - Variant: `ghost`
 - Size: `sm`
 - Appears only when there are 2+ files
-      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>
-  );
-}
-```
-
-## Visual states
-
-### Without selected file
-
-The component shows:
-
-- Drag & drop area with dashed border
-- Document icon on light blue background
-- Instructional text and link to select file
-- File requirements (extensions and size)
-
-### During drag over
-
-When the user drags a file over the area:
-
-- Border changes to `border-primary-500`
-- Background changes to `bg-primary-50`
-- Smooth transition with `transition-colors`
-
-### With selected file
-
-The component shows:
-
-- Card with `bg-neutral-100` background
-- Document icon on white background
-- File name (with truncate if long)
-- File size in MB
-- Destructive button to remove the file
-
-## Validation
-
-The component automatically validates:
-
-1. **Extension**: Only accepts files with extensions in `acceptedExtensions`
-2. **Size**: Rejects files larger than `maxSizeInMB`
-
-If a file does not meet these validations, it is not selected and `onFileSelect` is not invoked.
-
-## Base styles
-
-### Drag & drop area
-
-- Padding: `p-6` (24px)
-- Border radius: `rounded-2xl` (16px)
-- Border: `border-2 border-dashed`
-- Gap between elements: `gap-6` (24px)
-- Transitions: `transition-colors`
-
-### Normal state vs dragging
-
-```tsx
-// Normal
-border-neutral-300 bg-neutral-50
-
-// Dragging
-border-primary-500 bg-primary-50
-```
-
-### Selected file card
-
-- Padding: `p-6` (24px)
-- Border radius: `rounded-2xl` (16px)
-- Background: `bg-neutral-100`
-- Horizontal gap: `gap-4` (16px)
-- Icon on white background with `rounded-xl` and `p-2.5`
-
-### Remove button
-
-- Variant: `destructive-medium`
-- Icon: `delete` from Material Symbols
-- Icon color: `text-destructive-500`
 
 ## Accessibility
 
 - Hidden file input with `className="adm:hidden"`
-- Label properly associated with `htmlFor="file-upload"`
+- Label properly associated via auto-generated ID or custom `input.id`
 - Link button uses `asChild` for semantic behavior
 - Typography with `muted` color for secondary text
+- Supports `aria-invalid` for form validation feedback
+- Supports `aria-disabled` and `disabled` for accessibility
+- Automatically detects and respects `<fieldset disabled>`
 
 ## TypeScript types
 
-````typescript
-export type FileUploadLabels = {
-  dragDrop?: string
-  selectFile?: string
-  fileRequirements?: string
-  filesSelected?: (count: number) => string
-};
-
-export type FileUploadProps = ComponentProps<"div"> & Readonly<{
-  // Simple mode
-  selectedFile?: File | null
-  onFileSelect?: (file: File | null) => void
-
-  // Multiple mode
-  selectedFiles?: File[]
-  onFilesSelect?: (files: File[]) => void
-  multiple?: boolean
-  maxFiles?: number
-  filesPosition?: "above" | "below"
-
-  // Validation
-  onInvalidFile?: (file: File, reason: "extension" | "size") => void
-  invalid?: boolean
-  "aria-invalid"?: boolean
-
-  // States
-  disabled?: boolean
-
-  // Common
-  acceptedExtensions?: string[]
-  maxSizeInMB?: number
-  labels?: FileUploadLabels
-  input?: ComponentProps<"input">
-}>
-### FormData for upload
-
-```tsx
-// Un archivo
-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();
-};
-
-// Múltiples archivos
-const uploadFiles = async (files: File[]) => {
-  const formData = new FormData();
-  files.forEach((file, index) => {
-    formData.append(`file${index}`, file);
-  });
-
-  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
-
-// 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
-```
-
-## TypeScript types (duplicate)
-
 ```typescript
 export type FileUploadLabels = {
   dragDrop?: string;
   selectFile?: string;
   fileRequirements?: string;
+  filesSelected?: (count: number) => string;
 };
 
 export type FileUploadProps = ComponentProps<"div"> &
   Readonly<{
-    selectedFile: File | null;
-    onFileSelect: (file: File | null) => void;
+    // Simple mode
+    selectedFile?: File | null;
+    onFileSelect?: (file: File | null) => void;
+
+    // Multiple mode
+    selectedFiles?: File[];
+    onFilesSelect?: (files: File[]) => void;
+    multiple?: boolean;
+    maxFiles?: number;
+    filesPosition?: "above" | "below";
+
+    // Callbacks
+    onFileAdd?: (file: File) => void;
+    onFileRemove?: (file: File) => void;
+    onFilesAdd?: (files: File[]) => void;
+    onFilesRemove?: (files: File[]) => void;
+
+    // Validation
+    onInvalidFile?: (file: File, reason: "extension" | "size") => void;
+    invalid?: boolean;
+    "aria-invalid"?: boolean;
+
+    // States
+    disabled?: boolean;
+
+    // Common
     acceptedExtensions?: string[];
     maxSizeInMB?: number;
     labels?: FileUploadLabels;
+    input?: ComponentProps<"input">;
   }>;
 ```
 
@@ -1263,6 +1013,7 @@ export type FileUploadProps = ComponentProps<"div"> &
 ### FormData for upload
 
 ```tsx
+// Single file
 const uploadFile = async (file: File) => {
   const formData = new FormData();
   formData.append("file", file);
@@ -1280,6 +1031,21 @@ const uploadFile = async (file: File) => {
 
   return response.json();
 };
+
+// Multiple files
+const uploadFiles = async (files: File[]) => {
+  const formData = new FormData();
+  files.forEach((file, index) => {
+    formData.append(`file${index}`, file);
+  });
+
+  const response = await fetch("/api/upload-multiple", {
+    method: "POST",
+    body: formData,
+  });
+
+  return response.json();
+};
 ```
 
 ### With progress tracking
@@ -1310,73 +1076,69 @@ const uploadWithProgress = async (file: File) => {
 };
 ```
 
-## Comparison with Input type="file"
-
-| 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)     |
-| aria-invalid          | ⚠️ Manual                | ✅ Integrado              |
-| Fieldset disabled     | ⚠️ Native but no styles  | ✅ Automatically detected |
-| Disabled files        | ❌ Not supported         | ✅ Full visual feedback   |
+## Best practices
 
-## Notes
-
-- The component uses native browser `File` API
-- Validation is client-side only - always validate on the server as well
-- In simple mode, drag & drop accepts one file at a time
-- In multiple mode, multiple files can be dragged simultaneously
-- Files are not stored automatically - handle upload with callbacks
-- The component is fully controlled - the parent manages file state
-- The file input is reusable: after selecting, it resets to allow selecting the same file again
-- **Automatic ID generation**: If no `id` is provided in the `input` prop, one is automatically generated with format `file-upload-{random}` to ensure accessibility
-- **Automatic fieldset detection**: The component detects when it is inside a `<fieldset disabled>` using MutationObserver and disables itself automatically
-- **Selected files and disabled**: When the component is disabled, selected files are visually shown as disabled and cannot be removed
-- Use with Field components (`Field`, `FieldLabel`, `FieldError`, etc.) for a better form experience
+### ✅ Do
 
 ```tsx
-<FileUpload
-  selectedFile={file}
-  onFileSelect={setFile}
-  className="adm:max-w-2xl adm:mx-auto"
-/>
+// Validate on server-side as well
+// Always check that file is not null before upload
+
+// Use specific extensions for security
+acceptedExtensions={[".pdf", ".docx", ".xlsx"]}
+
+// Set reasonable size limits
+maxSizeInMB={10}
+
+// Provide descriptive labels for context
+labels={{
+  dragDrop: "Drag and drop your invoice here or",
+  selectFile: "Select invoice"
+}}
 ```
 
-### With additional wrapper
+### ❌ Don't
 
 ```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>
+// Don't skip server-side validation
+// Always verify file is not null
+
+// Don't use overly permissive extensions (security risk)
+acceptedExtensions={[".*"]}
+
+// Don't set excessive size limits without justification
+maxSizeInMB={10000} // 10GB is excessive
+
+// Don't use generic labels when context is specific
+labels={{ selectFile: "Select file" }} // Not descriptive enough
 ```
 
-## Comparison with Input type="file"
+## Comparison with FileUploadV2
+
+| Feature             | FileUpload                           | FileUploadV2                                       |
+| ------------------- | ------------------------------------ | -------------------------------------------------- |
+| File type           | `File` (plain browser File object)   | `FileWithMetadata` (with required ID)              |
+| Status tracking     | ❌ No                                | ✅ Yes (idle, uploading, success, error, deleting) |
+| Unique IDs          | ❌ No                                | ✅ Yes (auto-generated)                            |
+| Custom ID generator | ❌ No                                | ✅ Yes (generateId prop)                           |
+| Metadata support    | ❌ No                                | ✅ Yes (metadata property)                         |
+| Server integration  | ⚠️ Manual only                       | ✅ Built-in with IDs and status                    |
+| Use case            | Simple forms without status tracking | Server integration with file tracking              |
+| Complexity          | ⚡ Simple                            | 🔧 Advanced                                        |
 
-| Feature              | Native file input        | FileUpload                |
-| -------------------- | ------------------------ | ------------------------- |
-| Drag & Drop          | ❌ No                    | ✅ Yes                    |
-| Visual validation    | ❌ No                    | ✅ Yes                    |
-| File preview         | ❌ No                    | ✅ Yes with name and size |
-| Validated extensions | ⚠️ Only accept attribute | ✅ With visual feedback   |
-| Validated size       | ❌ Only on backend       | ✅ Client and server      |
-| Consistent UX        | ❌ Varies by browser     | ✅ Consistent             |
-| Customizable labels  | ❌ No                    | ✅ Yes (i18n friendly)    |
+> **Need status tracking and metadata?** Use [FileUploadV2](file-upload-v2.md) for server-side file tracking with built-in unique identifiers and status management.
 
 ## Notes
 
-- The component uses native browser `File` API
-- Validation is client-side only - always validate on the server as well
-- Drag & drop only works with one file at a time
-- Files are not stored automatically - handle upload with `onFileSelect`
+- The component uses native browser `File` API (plain File objects without modifications)
+- Validation is client-side only - **always validate on the server as well**
+- In simple mode, drag & drop accepts one file at a time
+- In multiple mode, multiple files can be dragged simultaneously
+- Files are not stored automatically - handle upload with callbacks
 - The component is fully controlled - the parent manages file state
+- The file input is reusable: after selecting, it resets to allow selecting the same file again
+- **No status tracking**: FileUpload works with plain File objects - use [FileUploadV2](file-upload-v2.md) if you need status tracking
+- **Automatic ID generation**: If no `id` is provided in the `input` prop, one is automatically generated with format `file-upload-{random}` to ensure accessibility
+- **Automatic fieldset detection**: The component detects when it is inside a `<fieldset disabled>` using MutationObserver and disables itself automatically
+- **Selected files and disabled**: When the component is disabled, selected files are visually shown as disabled and cannot be removed
+- Use with Field components (`Field`, `FieldLabel`, `FieldError`, etc.) for a better form experience

package/llm.txt

@@ -32,7 +32,7 @@ Before creating ANY component, verify it doesn't exist here. For implementation
 - **Label** [`docs/components/ui/label.md`] - `@adamosuiteservices/ui/label`
 - **Input Group** [`docs/components/ui/input-group.md`] - `@adamosuiteservices/ui/input-group`
 - **File Upload** [`docs/components/ui/file-upload.md`] - `@adamosuiteservices/ui/file-upload` ⚠️ Simple file upload
-- **File Upload V2** [`docs/components/ui/file-upload-v2.md`] - `@adamosuiteservices/ui/file-upload` ⚠️ With IDs for server integration
+- **File Upload V2** [`docs/components/ui/file-upload-v2.md`] - `@adamosuiteservices/ui/file-upload-v2` ⚠️ With unique IDs and metadata for server integration
 
 ### Overlay Components (8)
 - **Dialog** [`docs/components/ui/dialog.md`] - `@adamosuiteservices/ui/dialog` (modal)
@@ -90,9 +90,9 @@ Before creating ANY component, verify it doesn't exist here. For implementation
 1. ❌ Creating components that already exist (check list above first!)
 2. ❌ Using barrel imports: `import { X } from "@adamosuiteservices/ui"`
 3. ❌ Using `adm:` prefix in user code
-5. ❌ Using FileUploadV2 for simple forms (use FileUpload instead)
-6. ❌ Using FileUpload when you need server-side file tracking (use FileUploadV2)
-4. ❌ Not consulting component documentation before implementation
+4. ❌ Using FileUploadV2 when you don't need unique IDs or metadata (use FileUpload instead)
+5. ❌ Using FileUpload without status when you need server-side tracking (use FileUploadV2 with IDs)
+6. ❌ Not consulting component documentation before implementation
 
 ## 📚 Documentation Structure