@adamosuiteservices/ui 2.17.0 → 2.18.0

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

@@ -86,6 +86,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 +341,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 +707,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` ⚠️ 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.0",
+  "version": "2.18.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",