@adamosuiteservices/ui 2.17.1 → 2.18.1

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
@@ -86,6 +88,58 @@ State of the currently selected file. Use `null` when there is no file.
 onFileSelect?: (file: File | null) => void
 ```
 
+Callback invoked when the user selects or removes a file. Receives the new file or `null` when removed.
+
+#### onFileAdd
+
+```tsx
+onFileAdd?: (file: File) => void
+```
+
+Callback invoked when a new file is added (via drag & drop or file selection). Receives the added file. This fires in addition to `onFileSelect`.
+
+**Use case**: Track file additions for logging, analytics, or triggering immediate upload.
+
+**Example**:
+
+```tsx
+const handleFileAdd = (file: File) => {
+  console.log("File added:", file.name);
+  // Optionally start upload immediately
+  uploadFile(file);
+};
+
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  onFileAdd={handleFileAdd}
+/>;
+```
+
+#### onFileRemove
+
+```tsx
+onFileRemove?: (file: File) => void
+```
+
+Callback invoked when a file is removed. Receives the removed file. This fires in addition to `onFileSelect`.
+
+**Use case**: Track file removals, call API to delete from server, or update analytics.
+
+**Example**:
+
+```tsx
+const handleFileRemove = (file: File) => {
+  console.log("File removed:", file.name);
+};
+
+<FileUpload
+  selectedFile={file}
+  onFileSelect={setFile}
+  onFileRemove={handleFileRemove}
+/>;
+```
+
 ### Common props
 
 #### acceptedExtensions
@@ -289,6 +343,64 @@ onFilesSelect?: (files: File[]) => void
 
 Callback invoked when the user selects, adds, or removes files.
 
+#### onFilesAdd
+
+```tsx
+onFilesAdd?: (files: File[]) => void
+```
+
+Callback invoked when new files are added (via drag & drop or file selection). Receives the array of added files. This fires in addition to `onFilesSelect`.
+
+**Use case**: Track file additions, start batch upload, or update UI state.
+
+**Example**:
+
+```tsx
+const handleFilesAdd = (files: File[]) => {
+  console.log(
+    `${files.length} file(s) added:`,
+    files.map((f) => f.name),
+  );
+  // Start batch upload
+  files.forEach(uploadFile);
+};
+
+<FileUpload
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  onFilesAdd={handleFilesAdd}
+  multiple
+/>;
+```
+
+#### onFilesRemove
+
+```tsx
+onFilesRemove?: (files: File[]) => void
+```
+
+Callback invoked when files are removed (individually or via "Clear all"). Receives the array of removed files. This fires in addition to `onFilesSelect`.
+
+**Use case**: Track file removals, call API to delete from server, or clean up resources.
+
+**Example**:
+
+```tsx
+const handleFilesRemove = (files: File[]) => {
+  console.log(
+    `${files.length} file(s) removed:`,
+    files.map((f) => f.name),
+  );
+};
+
+<FileUpload
+  selectedFiles={files}
+  onFilesSelect={setFiles}
+  onFilesRemove={handleFilesRemove}
+  multiple
+/>;
+```
+
 #### multiple
 
 ```tsx
@@ -597,6 +709,104 @@ function CustomInputPropsExample() {
 }
 ```
 
+### With callbacks for immediate upload
+
+```tsx
+import { useState } from "react";
+import { FileUpload } from "@adamosuiteservices/ui/file-upload";
+import { Typography } from "@adamosuiteservices/ui/typography";
+
+function ImmediateUploadExample() {
+  const [file, setFile] = useState<File | null>(null);
+  const [isUploading, setIsUploading] = useState(false);
+
+  const handleFileAdd = async (addedFile: File) => {
+    console.log("File added, starting upload:", addedFile.name);
+    setIsUploading(true);
+
+    try {
+      const formData = new FormData();
+      formData.append("file", addedFile);
+
+      const response = await fetch("/api/upload", {
+        method: "POST",
+        body: formData,
+      });
+
+      if (response.ok) {
+        console.log("Upload successful");
+      }
+    } catch (error) {
+      console.error("Upload failed:", error);
+    } finally {
+      setIsUploading(false);
+    }
+  };
+
+  const handleFileRemove = (removedFile: File) => {
+    console.log("File removed:", removedFile.name);
+  };
+
+  return (
+    <div className="adm:max-w-xl adm:space-y-4">
+      <FileUpload
+        selectedFile={file}
+        onFileSelect={setFile}
+        onFileAdd={handleFileAdd}
+        onFileRemove={handleFileRemove}
+      />
+      {isUploading && <Typography color="muted">Uploading...</Typography>}
+    </div>
+  );
+}
+```
+
+### Multiple files with callbacks
+
+```tsx
+import { useState } from "react";
+import { FileUpload } from "@adamosuiteservices/ui/file-upload";
+import { Typography } from "@adamosuiteservices/ui/typography";
+
+function MultipleFilesWithCallbacks() {
+  const [files, setFiles] = useState<File[]>([]);
+  const [eventLog, setEventLog] = useState<string[]>([]);
+
+  const handleFilesAdd = (addedFiles: File[]) => {
+    const message = `Added ${addedFiles.length} file(s): ${addedFiles.map((f) => f.name).join(", ")}`;
+    setEventLog((prev) => [...prev, message]);
+  };
+
+  const handleFilesRemove = (removedFiles: File[]) => {
+    const message = `Removed ${removedFiles.length} file(s): ${removedFiles.map((f) => f.name).join(", ")}`;
+    setEventLog((prev) => [...prev, message]);
+  };
+
+  return (
+    <div className="adm:max-w-xl adm:space-y-4">
+      <FileUpload
+        selectedFiles={files}
+        onFilesSelect={setFiles}
+        onFilesAdd={handleFilesAdd}
+        onFilesRemove={handleFilesRemove}
+        multiple
+      />
+
+      {eventLog.length > 0 && (
+        <div className="adm:space-y-2">
+          <Typography className="adm:font-medium">Event log:</Typography>
+          {eventLog.map((log, index) => (
+            <Typography key={index} color="muted" className="adm:text-sm">
+              {log}
+            </Typography>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
 ### Excel files (default)
 
 ````tsx

package/llm.txt

@@ -1,11 +1,11 @@
 # Adamo UI Component Library - LLM Context
 
-> **CRITICAL**: This is a COMPLETE React component library with 45+ components. DO NOT create components that already exist. ALWAYS check this file first and use existing components.
+> **CRITICAL**: This is a COMPLETE React component library with 46+ components. DO NOT create components that already exist. ALWAYS check this file first and use existing components.
 
 ## 🚨 MOST IMPORTANT RULES
 
 1. **NEVER create a component that already exists** - Check the component list below first
-   - Example: ❌ DON'T create `<input type="file">` ✅ DO use `<FileUpload>`
+   - Example: ❌ DON'T create `<input type="file">` ✅ DO use `<FileUpload>` or `<FileUploadV2>`
 
 2. **Use individual imports** - `import { Button } from "@adamosuiteservices/ui/button";`
 
@@ -13,11 +13,11 @@
 
 4. **Users NEVER use `adm:` prefix** - Only library internals use it
 
-## 📦 Available Components (45+)
+## 📦 Available Components (46+)
 
 Before creating ANY component, verify it doesn't exist here. For implementation details, props, and examples, see the linked documentation.
 
-### Form Components (14)
+### Form Components (15)
 - **Button** [`docs/components/ui/button.md`] - `@adamosuiteservices/ui/button`
 - **Button Group** [`docs/components/ui/button-group.md`] - `@adamosuiteservices/ui/button-group`
 - **Input** [`docs/components/ui/input.md`] - `@adamosuiteservices/ui/input`
@@ -31,7 +31,8 @@ Before creating ANY component, verify it doesn't exist here. For implementation
 - **Field** [`docs/components/ui/field.md`] - `@adamosuiteservices/ui/field` (form wrapper with label/error)
 - **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` ⚠️ USE THIS!
+- **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-v2` ⚠️ With IDs for server integration
 
 ### Overlay Components (8)
 - **Dialog** [`docs/components/ui/dialog.md`] - `@adamosuiteservices/ui/dialog` (modal)
@@ -89,6 +90,8 @@ 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
 
 ## 📚 Documentation Structure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "2.17.1",
+  "version": "2.18.1",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -118,6 +118,10 @@
       "types": "./dist/components/ui/file-upload/file-upload.d.ts",
       "import": "./dist/file-upload.js"
     },
+    "./file-upload-v2": {
+      "types": "./dist/components/ui/file-upload-v2/file-upload-v2.d.ts",
+      "import": "./dist/file-upload-v2.js"
+    },
     "./hover-card": {
       "types": "./dist/components/ui/hover-card/hover-card.d.ts",
       "import": "./dist/hover-card.js"