@adamosuiteservices/ui 2.17.1 → 2.18.1

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

@@ -0,0 +1,1116 @@
+# File Upload V2 Component
+
+## Description
+
+Enhanced file upload component with **unique file identification**, **metadata support**, and **server integration** capabilities. Built on the FileUpload component foundation, FileUploadV2 adds automatic ID generation for each file, making it ideal for scenarios requiring server-side file tracking, asynchronous uploads, and delete operations.
+
+> **Need a simpler version?** Check out [FileUpload](file-upload.md) for basic file upload without IDs or server integration features.
+
+## Features
+
+- ✅ All features from FileUpload component
+- ✅ Automatic unique ID generation for each file
+- ✅ Custom ID generator support
+- ✅ Metadata support for storing additional file information
+- ✅ Server-side file tracking with IDs
+- ✅ Pre-loaded files with server IDs
+- ✅ Callbacks with file references for API integration
+- ✅ Full TypeScript with FileWithMetadata type
+- ✅ Perfect for async upload/delete operations
+
+## When to use
+
+Use **FileUploadV2** when you need:
+
+- Server-side file tracking with unique identifiers
+- Asynchronous file uploads with progress tracking
+- Delete operations requiring file IDs
+- Pre-loading existing files from server
+- Storing metadata alongside files
+- Complex file management workflows
+
+Use **FileUpload** (original) when you need:
+
+- Simple file selection without server integration
+- One-time form submission with files
+- No need for file identification or tracking
+
+## Import
+
+```typescript
+import { FileUploadV2 } from "@adamosuiteservices/ui/file-upload-v2";
+import type {
+  FileUploadV2Props,
+  FileWithMetadata,
+  FileUploadV2Labels,
+} from "@adamosuiteservices/ui/file-upload-v2";
+```
+
+## Basic usage
+
+### Single file with automatic IDs
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+
+function MyForm() {
+  const [file, setFile] = useState<FileWithMetadata | null>(null);
+
+  return <FileUploadV2 selectedFile={file} onFileSelect={setFile} />;
+}
+```
+
+### Multiple files with automatic IDs
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+
+function MyForm() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+
+  return (
+    <FileUploadV2 selectedFiles={files} onFilesSelect={setFiles} multiple />
+  );
+}
+```
+
+### With server files (pre-loaded)
+
+```tsx
+import { useState, useEffect } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+
+function MyForm() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+
+  useEffect(() => {
+    // Load existing files from server
+    const serverFiles: FileWithMetadata[] = [
+      {
+        id: "server-file-123",
+        file: new File(["content"], "report.xlsx", {
+          type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        }),
+        metadata: {
+          uploadedAt: "2024-01-15T10:30:00Z",
+          uploadedBy: "user@example.com",
+          serverUrl: "https://api.example.com/files/server-file-123",
+        },
+      },
+    ];
+    setFiles(serverFiles);
+  }, []);
+
+  return (
+    <FileUploadV2 selectedFiles={files} onFilesSelect={setFiles} multiple />
+  );
+}
+```
+
+## Props
+
+### FileWithMetadata type
+
+```tsx
+type FileWithMetadata = {
+  id: string;
+  file: File;
+  metadata?: Record<string, unknown>;
+};
+```
+
+- **id**: Unique identifier for the file (auto-generated or provided)
+- **file**: Native browser File object
+- **metadata**: Optional additional data (upload timestamp, server URL, etc.)
+
+### Simple mode (single file)
+
+#### selectedFile
+
+```tsx
+selectedFile?: FileWithMetadata | null
+```
+
+State of the currently selected file with ID and metadata. Use `null` when there is no file.
+
+#### onFileSelect
+
+```tsx
+onFileSelect?: (file: FileWithMetadata | null) => void
+```
+
+Callback invoked when the user selects or removes a file. Receives the file with ID and metadata, or `null` when removed.
+
+#### onFileAdd
+
+```tsx
+onFileAdd?: (file: FileWithMetadata) => void
+```
+
+Callback invoked when a new file is added. Receives the file with auto-generated ID. This fires in addition to `onFileSelect`.
+
+**Use case**: Start upload immediately when file is added.
+
+**Example**:
+
+```tsx
+const handleFileAdd = async (fileWithMetadata: FileWithMetadata) => {
+  console.log("File added with ID:", fileWithMetadata.id);
+
+  const formData = new FormData();
+  formData.append("file", fileWithMetadata.file);
+  formData.append("fileId", fileWithMetadata.id);
+
+  await fetch("/api/upload", {
+    method: "POST",
+    body: formData,
+  });
+};
+
+<FileUploadV2
+  selectedFile={file}
+  onFileSelect={setFile}
+  onFileAdd={handleFileAdd}
+/>;
+```
+
+#### onFileRemove
+
+```tsx
+onFileRemove?: (file: FileWithMetadata) => void
+```
+
+Callback invoked when a file is removed. Receives the file with its ID, enabling server-side deletion.
+
+**Use case**: Call API to delete file from server using the file ID.
+
+**Example**:
+
+```tsx
+const handleFileRemove = async (fileWithMetadata: FileWithMetadata) => {
+  console.log("File removed with ID:", fileWithMetadata.id);
+
+  // Only delete from server if it has been uploaded
+  if (fileWithMetadata.metadata?.serverUrl) {
+    await fetch(`/api/files/${fileWithMetadata.id}`, {
+      method: "DELETE",
+    });
+  }
+};
+
+<FileUploadV2
+  selectedFile={file}
+  onFileSelect={setFile}
+  onFileRemove={handleFileRemove}
+/>;
+```
+
+### Multiple mode
+
+#### selectedFiles
+
+```tsx
+selectedFiles?: FileWithMetadata[]
+```
+
+Array of selected files with IDs and metadata.
+
+#### onFilesSelect
+
+```tsx
+onFilesSelect?: (files: FileWithMetadata[]) => void
+```
+
+Callback invoked when the user selects, adds, or removes files.
+
+#### onFilesAdd
+
+```tsx
+onFilesAdd?: (files: FileWithMetadata[]) => void
+```
+
+Callback invoked when new files are added. Receives array of files with auto-generated IDs. This fires in addition to `onFilesSelect`.
+
+**Example**:
+
+```tsx
+const handleFilesAdd = async (filesWithMetadata: FileWithMetadata[]) => {
+  console.log(
+    "Files added:",
+    filesWithMetadata.map((f) => f.id),
+  );
+
+  // Upload each file
+  await Promise.all(
+    filesWithMetadata.map(async (fwm) => {
+      const formData = new FormData();
+      formData.append("file", fwm.file);
+      formData.append("fileId", fwm.id);
+
+      return fetch("/api/upload", {
+        method: "POST",
+        body: formData,
+      });
+    }),
+  );
+};
+
+<FileUploadV2
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  onFilesAdd={handleFilesAdd}
+  multiple
+/>;
+```
+
+#### onFilesRemove
+
+```tsx
+onFilesRemove?: (files: FileWithMetadata[]) => void
+```
+
+Callback invoked when files are removed. Receives array of removed files with their IDs.
+
+**Example**:
+
+```tsx
+const handleFilesRemove = async (removedFiles: FileWithMetadata[]) => {
+  console.log(
+    "Files removed:",
+    removedFiles.map((f) => f.id),
+  );
+
+  // Delete from server
+  await Promise.all(
+    removedFiles
+      .filter((f) => f.metadata?.serverUrl)
+      .map((f) => fetch(`/api/files/${f.id}`, { method: "DELETE" })),
+  );
+};
+
+<FileUploadV2
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  onFilesRemove={handleFilesRemove}
+  multiple
+/>;
+```
+
+#### multiple
+
+```tsx
+multiple?: boolean
+```
+
+Enables multiple file mode. Default: `false`
+
+#### maxFiles
+
+```tsx
+maxFiles?: number
+```
+
+Maximum number of files allowed in multiple mode. Default: `10`
+
+#### filesPosition
+
+```tsx
+filesPosition?: "above" | "below"
+```
+
+Position where selected files appear in multiple mode. Default: `"below"`
+
+### ID generation
+
+#### generateId
+
+```tsx
+generateId?: (file: File) => string
+```
+
+Custom function to generate unique IDs for files. If not provided, uses default generator.
+
+**Default generator format**: `{timestamp}-{random}-{filename}`
+
+Example: `1704892800000-x7k2p9q3m-report.xlsx`
+
+**Use case**: Use custom ID format for integration with existing systems.
+
+**Example**:
+
+```tsx
+const customIdGenerator = (file: File) => {
+  return `custom-${Date.now()}-${file.name}`;
+};
+
+<FileUploadV2
+  selectedFile={file}
+  onFileSelect={setFile}
+  generateId={customIdGenerator}
+/>;
+```
+
+**Example with UUID**:
+
+```tsx
+import { v4 as uuidv4 } from "uuid";
+
+<FileUploadV2
+  selectedFile={file}
+  onFileSelect={setFile}
+  generateId={(file) => uuidv4()}
+/>;
+```
+
+### Common props
+
+All props from the original FileUpload component are supported:
+
+#### acceptedExtensions
+
+```tsx
+acceptedExtensions?: string[]
+```
+
+Array of allowed file extensions. Default: `[".xls", ".xlsx", ".numbers"]`
+
+#### maxSizeInMB
+
+```tsx
+maxSizeInMB?: number
+```
+
+Maximum file size in megabytes. Default: `50`
+
+#### labels
+
+```tsx
+labels?: FileUploadV2Labels
+
+type FileUploadV2Labels = {
+  dragDrop?: string
+  selectFile?: string
+  fileRequirements?: string
+  filesSelected?: (count: number) => string
+}
+```
+
+Customizable labels for internationalization.
+
+#### aria-invalid / invalid
+
+```tsx
+"aria-invalid"?: boolean
+invalid?: boolean
+```
+
+Marks the component as invalid. Default: `false`
+
+#### disabled
+
+```tsx
+disabled?: boolean
+```
+
+Disables the component. Default: `false`
+
+#### input
+
+```tsx
+input?: ComponentProps<"input">
+```
+
+Custom props for the internal `<input type="file">` element.
+
+#### onInvalidFile
+
+```tsx
+onInvalidFile?: (file: FileWithMetadata, reason: "extension" | "size") => void
+```
+
+Callback invoked when a file does not pass validation.
+
+## Examples
+
+### With Field components
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+} from "@adamosuiteservices/ui/field";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+
+function FileUploadForm() {
+  const [file, setFile] = useState<FileWithMetadata | null>(null);
+  const [error, setError] = useState<string>("");
+
+  const handleInvalidFile = (
+    file: FileWithMetadata,
+    reason: "extension" | "size",
+  ) => {
+    if (reason === "extension") {
+      setError(`File "${file.file.name}" has an invalid extension.`);
+    } else if (reason === "size") {
+      setError(`File "${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>
+        <FileUploadV2
+          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>
+  );
+}
+```
+
+### With API integration (async upload)
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+import { Button } from "@adamosuiteservices/ui/button";
+import { Typography } from "@adamosuiteservices/ui/typography";
+
+function AsyncUploadExample() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+  const [uploadStatus, setUploadStatus] = useState<
+    Record<string, "uploading" | "success" | "error">
+  >({});
+
+  const handleFilesAdd = async (addedFiles: FileWithMetadata[]) => {
+    // Mark files as uploading
+    const newStatus = { ...uploadStatus };
+    addedFiles.forEach((f) => {
+      newStatus[f.id] = "uploading";
+    });
+    setUploadStatus(newStatus);
+
+    // Upload each file
+    await Promise.all(
+      addedFiles.map(async (fileWithMetadata) => {
+        try {
+          const formData = new FormData();
+          formData.append("file", fileWithMetadata.file);
+          formData.append("fileId", fileWithMetadata.id);
+
+          const response = await fetch("/api/upload", {
+            method: "POST",
+            body: formData,
+          });
+
+          if (response.ok) {
+            const data = await response.json();
+
+            // Update file with server metadata
+            setFiles((prev) =>
+              prev.map((f) =>
+                f.id === fileWithMetadata.id
+                  ? {
+                      ...f,
+                      metadata: {
+                        ...f.metadata,
+                        serverUrl: data.url,
+                        uploadedAt: new Date().toISOString(),
+                      },
+                    }
+                  : f,
+              ),
+            );
+
+            setUploadStatus((prev) => ({
+              ...prev,
+              [fileWithMetadata.id]: "success",
+            }));
+          } else {
+            setUploadStatus((prev) => ({
+              ...prev,
+              [fileWithMetadata.id]: "error",
+            }));
+          }
+        } catch (error) {
+          console.error("Upload failed:", error);
+          setUploadStatus((prev) => ({
+            ...prev,
+            [fileWithMetadata.id]: "error",
+          }));
+        }
+      }),
+    );
+  };
+
+  const handleFilesRemove = async (removedFiles: FileWithMetadata[]) => {
+    // Delete from server if they were uploaded
+    await Promise.all(
+      removedFiles
+        .filter((f) => f.metadata?.serverUrl)
+        .map(async (f) => {
+          try {
+            await fetch(`/api/files/${f.id}`, { method: "DELETE" });
+          } catch (error) {
+            console.error("Delete failed:", error);
+          }
+        }),
+    );
+
+    // Clean up upload status
+    setUploadStatus((prev) => {
+      const newStatus = { ...prev };
+      removedFiles.forEach((f) => delete newStatus[f.id]);
+      return newStatus;
+    });
+  };
+
+  return (
+    <div className="adm:max-w-xl adm:space-y-4">
+      <FileUploadV2
+        selectedFiles={files}
+        onFilesSelect={setFiles}
+        onFilesAdd={handleFilesAdd}
+        onFilesRemove={handleFilesRemove}
+        multiple
+      />
+
+      {files.length > 0 && (
+        <div className="adm:space-y-2">
+          <Typography className="adm:font-medium">Upload status:</Typography>
+          {files.map((f) => (
+            <div key={f.id} className="adm:flex adm:items-center adm:gap-2">
+              <Typography className="adm:text-sm">{f.file.name}</Typography>
+              <Typography
+                className="adm:text-sm"
+                color={
+                  uploadStatus[f.id] === "success"
+                    ? "success"
+                    : uploadStatus[f.id] === "error"
+                      ? "destructive"
+                      : "muted"
+                }
+              >
+                {uploadStatus[f.id] === "uploading" && "Uploading..."}
+                {uploadStatus[f.id] === "success" && "✓ Uploaded"}
+                {uploadStatus[f.id] === "error" && "✗ Failed"}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### With pre-loaded server files
+
+```tsx
+import { useState, useEffect } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+
+function PreloadedFilesExample() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+
+  useEffect(() => {
+    // Simulate fetching files from server
+    const loadServerFiles = async () => {
+      const response = await fetch("/api/files");
+      const serverFiles = await response.json();
+
+      // Convert server files to FileWithMetadata
+      const filesWithMetadata: FileWithMetadata[] = serverFiles.map(
+        (sf: any) => ({
+          id: sf.id,
+          file: new File([""], sf.name, { type: sf.mimeType }),
+          metadata: {
+            serverUrl: sf.url,
+            uploadedAt: sf.uploadedAt,
+            size: sf.size,
+          },
+        }),
+      );
+
+      setFiles(filesWithMetadata);
+    };
+
+    loadServerFiles();
+  }, []);
+
+  const handleFilesRemove = async (removedFiles: FileWithMetadata[]) => {
+    // Delete from server
+    await Promise.all(
+      removedFiles.map((f) =>
+        fetch(`/api/files/${f.id}`, { method: "DELETE" }),
+      ),
+    );
+  };
+
+  return (
+    <FileUploadV2
+      selectedFiles={files}
+      onFilesSelect={setFiles}
+      onFilesRemove={handleFilesRemove}
+      multiple
+      className="adm:max-w-xl"
+    />
+  );
+}
+```
+
+### With custom ID generator
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+import { v4 as uuidv4 } from "uuid";
+
+function CustomIdExample() {
+  const [file, setFile] = useState<FileWithMetadata | null>(null);
+
+  // Use UUID for file IDs
+  const generateUUID = () => uuidv4();
+
+  return (
+    <FileUploadV2
+      selectedFile={file}
+      onFileSelect={setFile}
+      generateId={generateUUID}
+      className="adm:max-w-xl"
+    />
+  );
+}
+```
+
+### With form integration and validation
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+import { Field, FieldLabel, FieldError } from "@adamosuiteservices/ui/field";
+import { Button } from "@adamosuiteservices/ui/button";
+
+function FormIntegrationExample() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+  const [error, setError] = useState<string>("");
+  const [uploadedFileIds, setUploadedFileIds] = useState<string[]>([]);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (files.length === 0) {
+      setError("Please select at least one file");
+      return;
+    }
+
+    setError("");
+
+    // Upload files that haven't been uploaded yet
+    const filesToUpload = files.filter((f) => !uploadedFileIds.includes(f.id));
+
+    if (filesToUpload.length > 0) {
+      try {
+        await Promise.all(
+          filesToUpload.map(async (f) => {
+            const formData = new FormData();
+            formData.append("file", f.file);
+            formData.append("fileId", f.id);
+
+            await fetch("/api/upload", {
+              method: "POST",
+              body: formData,
+            });
+          }),
+        );
+
+        setUploadedFileIds((prev) => [
+          ...prev,
+          ...filesToUpload.map((f) => f.id),
+        ]);
+        alert("Files uploaded successfully!");
+      } catch (error) {
+        setError("Upload failed. Please try again.");
+      }
+    } else {
+      alert("All files already uploaded!");
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="adm:max-w-xl adm:space-y-4">
+      <Field>
+        <FieldLabel>Upload documents</FieldLabel>
+        <FileUploadV2
+          selectedFiles={files}
+          onFilesSelect={(newFiles) => {
+            setFiles(newFiles);
+            setError("");
+          }}
+          aria-invalid={!!error}
+          multiple
+        />
+        {error && <FieldError>{error}</FieldError>}
+      </Field>
+
+      <Button type="submit">Submit form</Button>
+    </form>
+  );
+}
+```
+
+### With event tracking
+
+```tsx
+import { useState } from "react";
+import {
+  FileUploadV2,
+  FileWithMetadata,
+} from "@adamosuiteservices/ui/file-upload-v2";
+import { Typography } from "@adamosuiteservices/ui/typography";
+
+function EventTrackingExample() {
+  const [files, setFiles] = useState<FileWithMetadata[]>([]);
+  const [events, setEvents] = useState<string[]>([]);
+
+  const logEvent = (message: string) => {
+    setEvents((prev) => [
+      ...prev,
+      `[${new Date().toLocaleTimeString()}] ${message}`,
+    ]);
+  };
+
+  const handleFilesAdd = (addedFiles: FileWithMetadata[]) => {
+    logEvent(
+      `Added ${addedFiles.length} file(s): ${addedFiles.map((f) => `${f.file.name} (ID: ${f.id})`).join(", ")}`,
+    );
+  };
+
+  const handleFilesRemove = (removedFiles: FileWithMetadata[]) => {
+    logEvent(
+      `Removed ${removedFiles.length} file(s): ${removedFiles.map((f) => `${f.file.name} (ID: ${f.id})`).join(", ")}`,
+    );
+  };
+
+  return (
+    <div className="adm:max-w-xl adm:space-y-4">
+      <FileUploadV2
+        selectedFiles={files}
+        onFilesSelect={setFiles}
+        onFilesAdd={handleFilesAdd}
+        onFilesRemove={handleFilesRemove}
+        multiple
+      />
+
+      {events.length > 0 && (
+        <div className="adm:space-y-2">
+          <Typography className="adm:font-medium">Event log:</Typography>
+          <div className="adm:max-h-40 adm:overflow-y-auto adm:rounded-lg adm:border adm:bg-muted adm:p-3">
+            {events.map((event, index) => (
+              <Typography
+                key={index}
+                className="adm:text-sm adm:font-mono"
+                color="muted"
+              >
+                {event}
+              </Typography>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Comparison with FileUpload
+
+| Feature                | FileUpload (original) | FileUploadV2           |
+| ---------------------- | --------------------- | ---------------------- |
+| File type              | `File`                | `FileWithMetadata`     |
+| Unique IDs             | ❌ No                 | ✅ Yes (auto)          |
+| Custom ID generator    | ❌ No                 | ✅ Yes (generateId)    |
+| Metadata support       | ❌ No                 | ✅ Yes (optional)      |
+| Server integration     | ⚠️ Manual             | ✅ Built-in with IDs   |
+| Pre-loaded files       | ⚠️ No IDs             | ✅ With server IDs     |
+| Delete API calls       | ⚠️ No file reference  | ✅ Uses file.id        |
+| Async upload tracking  | ⚠️ Manual tracking    | ✅ Track by file.id    |
+| Callbacks with IDs     | ❌ No                 | ✅ Yes                 |
+| Use case               | Simple forms          | Server integration     |
+| Backward compatibility | ✅ Original           | ❌ Different file type |
+
+## TypeScript types
+
+```typescript
+export type FileWithMetadata = {
+  id: string;
+  file: File;
+  metadata?: Record<string, unknown>;
+};
+
+export type FileUploadV2Labels = {
+  dragDrop?: string;
+  selectFile?: string;
+  fileRequirements?: string;
+  filesSelected?: (count: number) => string;
+};
+
+export type FileUploadV2Props = ComponentProps<"div"> &
+  Readonly<{
+    // Simple mode
+    selectedFile?: FileWithMetadata | null;
+    onFileSelect?: (file: FileWithMetadata | null) => void;
+
+    // Multiple mode
+    selectedFiles?: FileWithMetadata[];
+    onFilesSelect?: (files: FileWithMetadata[]) => void;
+    multiple?: boolean;
+    maxFiles?: number;
+    filesPosition?: "above" | "below";
+
+    // Callbacks
+    onFileAdd?: (file: FileWithMetadata) => void;
+    onFileRemove?: (file: FileWithMetadata) => void;
+    onFilesAdd?: (files: FileWithMetadata[]) => void;
+    onFilesRemove?: (files: FileWithMetadata[]) => void;
+
+    // ID generation
+    generateId?: (file: File) => string;
+
+    // Validation
+    onInvalidFile?: (
+      file: FileWithMetadata,
+      reason: "extension" | "size",
+    ) => void;
+    invalid?: boolean;
+    "aria-invalid"?: boolean;
+
+    // States
+    disabled?: boolean;
+
+    // Common
+    acceptedExtensions?: string[];
+    maxSizeInMB?: number;
+    labels?: FileUploadV2Labels;
+    input?: ComponentProps<"input">;
+  }>;
+```
+
+## Default ID generation
+
+The default ID generator creates unique IDs using the following format:
+
+```typescript
+const defaultGenerateId = (file: File) => {
+  return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}-${file.name}`;
+};
+```
+
+**Format**: `{timestamp}-{random}-{filename}`
+
+**Example**: `1704892800000-x7k2p9q3m-report.xlsx`
+
+**Components**:
+
+- **timestamp**: Current timestamp in milliseconds
+- **random**: Random alphanumeric string (9 characters)
+- **filename**: Original file name
+
+This ensures uniqueness even when uploading the same file multiple times.
+
+## Backend integration
+
+### Upload with file ID
+
+```tsx
+const uploadFile = async (fileWithMetadata: FileWithMetadata) => {
+  const formData = new FormData();
+  formData.append("file", fileWithMetadata.file);
+  formData.append("fileId", fileWithMetadata.id);
+  formData.append(
+    "metadata",
+    JSON.stringify({
+      uploadedAt: new Date().toISOString(),
+      originalName: fileWithMetadata.file.name,
+    }),
+  );
+
+  const response = await fetch("/api/upload", {
+    method: "POST",
+    body: formData,
+  });
+
+  return response.json();
+};
+```
+
+### Delete from server
+
+```tsx
+const deleteFile = async (fileWithMetadata: FileWithMetadata) => {
+  await fetch(`/api/files/${fileWithMetadata.id}`, {
+    method: "DELETE",
+  });
+};
+```
+
+### Update file metadata after upload
+
+```tsx
+const handleFileAdd = async (fileWithMetadata: FileWithMetadata) => {
+  const response = await uploadFile(fileWithMetadata);
+
+  // Update file with server metadata
+  setFiles((prev) =>
+    prev.map((f) =>
+      f.id === fileWithMetadata.id
+        ? {
+            ...f,
+            metadata: {
+              serverUrl: response.url,
+              uploadedAt: response.uploadedAt,
+            },
+          }
+        : f,
+    ),
+  );
+};
+```
+
+## Best practices
+
+### Do
+
+```tsx
+// Use FileUploadV2 when you need server-side tracking
+<FileUploadV2 selectedFile={file} onFileSelect={setFile} />;
+
+// Always handle file removal for uploaded files
+const handleFileRemove = async (file: FileWithMetadata) => {
+  if (file.metadata?.serverUrl) {
+    await deleteFromServer(file.id);
+  }
+};
+
+// Store server metadata after successful upload
+const handleFileAdd = async (file: FileWithMetadata) => {
+  const response = await uploadFile(file);
+  updateFileMetadata(file.id, { serverUrl: response.url });
+};
+
+// Use custom ID generator for specific requirements
+<FileUploadV2
+  selectedFile={file}
+  onFileSelect={setFile}
+  generateId={(file) => uuidv4()}
+/>;
+```
+
+### Don't
+
+```tsx
+// Don't use FileUploadV2 for simple forms without server integration
+// Use FileUpload instead
+<FileUploadV2 selectedFile={file} onFileSelect={setFile} /> // Overkill
+
+// Don't modify file.id after creation
+file.id = "new-id"; // ❌ IDs should be immutable
+
+// Don't forget to clean up server files on remove
+const handleFileRemove = (file: FileWithMetadata) => {
+  // ❌ Missing server deletion
+  console.log("Removed:", file.id);
+};
+
+// Don't store sensitive data in metadata (it's client-side)
+metadata: {
+  password: "secret123", // ❌ Insecure
+  apiKey: "key", // ❌ Insecure
+}
+```
+
+## Notes
+
+- The component uses the same UI as FileUpload but works with `FileWithMetadata` instead of `File`
+- IDs are generated automatically when files are added (drag & drop or file selection)
+- IDs are guaranteed unique within the component instance
+- For server integration, use the file ID to track uploads and deletions
+- Metadata is optional and can store any additional information
+- Pre-loaded files from server should include their server-assigned IDs
+- The component is fully controlled - the parent manages file state
+- Use `generateId` prop for custom ID generation strategies
+- All validation features from FileUpload are preserved
+
+## Migration from FileUpload
+
+If you're using FileUpload and need file IDs:
+
+**Before** (FileUpload):
+
+```tsx
+const [files, setFiles] = useState<File[]>([]);
+
+<FileUpload selectedFiles={files} onFilesSelect={setFiles} multiple />;
+```
+
+**After** (FileUploadV2):
+
+```tsx
+const [files, setFiles] = useState<FileWithMetadata[]>([]);
+
+<FileUploadV2 selectedFiles={files} onFilesSelect={setFiles} multiple />;
+```
+
+**Key changes**:
+
+1. Change type from `File[]` to `FileWithMetadata[]`
+2. Update component from `FileUpload` to `FileUploadV2`
+3. Access the native File object via `fileWithMetadata.file`
+4. Use `fileWithMetadata.id` for server operations
+5. Store server data in `fileWithMetadata.metadata`
+