@salesforce/webapp-template-feature-react-file-upload-experimental 1.90.1 → 1.90.2

package/README.md

@@ -1,266 +1,252 @@
-# Feature: File Upload
+# Feature: File Upload API
 
-File upload feature: use the **FileUpload** component as-is with out-of-the-box UI, or build a **custom UI** with the `useFileUpload` hook (custom trigger, drop zone, or both).
+File upload API package that provides programmatic APIs for uploading files to Salesforce with progress tracking and ContentVersion integration. This package serves as a **reference implementation** with APIs that allow you to **build your own custom UI**.
 
-## Exports
-
-### Components & Hooks
-
-- **FileUpload** – Component with OOTB drop zone, dialog, and progress. Props: `accept?`, `multiple?`, `recordId?`, `onUploadComplete?`, `onUploadError?`, `className?`, `dropZoneClassName?`, `formatHint?`, `maxFileSize?`.
-- **useFileUpload** – Headless hook for custom UIs. Returns `getInputProps`, `openFilePicker`, `fileItems`, `getDropZoneProps`, `cancelFile`, `reset`, etc.
-- **UseFileUploadOptions** – Type for the `useFileUpload` options.
-
-### API Functions
-
-- **createContentVersion** – Manually create a ContentVersion record from a contentBodyId.
-
-## Agent Configuration Guide
+## Package Purpose
 
-When implementing the FileUpload component, agents should prompt users for the following properties to configure the component appropriately:
+This package exposes APIs only - **no components or hooks are exported**. You can:
 
-### Required Information
+- Use the `upload()` API to handle the complete upload flow
+- Build your own custom UI with full control over the user experience
+- Track upload progress for each file in real-time
+- Optionally create ContentVersion records linked to Salesforce records
 
-1. **Multiple File Selection** (`multiple`):
-   - Prompt: "Should users be able to upload multiple files at once?"
-   - Type: Boolean (true/false)
-   - Default: false (single file only)
+The included components in the source code are for demonstration and testing purposes only.
 
-2. **Upload Context** (`recordId`):
-   - Prompt: "Do you want to link uploaded files to a specific Salesforce record?"
-   - Type: String (Salesforce record ID) or omit
-   - Note: If provided, creates ContentVersion and links to record immediately. If omitted, only returns `contentBodyId`.
-   - **Record Form Pattern**: If used in a record creation form where the record doesn't exist yet, omit `recordId` during upload, then use `createContentVersion` with the `contentBodyId` and the newly created record ID after form submission.
-
-3. **Completion Handler** (`onUploadComplete`):
-   - Prompt: "What should happen after files are successfully uploaded?"
-   - Type: Function that receives array of uploaded files
-   - Required properties to handle: `name`, `size`, `contentBodyId`, `contentVersionId`
+## Exports
 
-### Optional Configuration
+### API Functions
 
-4. **File Type Restrictions** (`accept`):
-   - Prompt: "What file types should be accepted? (e.g., 'image/_', '.pdf', 'image/_,.pdf')"
-   - Type: String (MIME types or file extensions)
-   - Default: All file types accepted
+- **upload** – Unified upload API that handles config, upload with progress tracking, and optionally creates ContentVersion records
+- **createContentVersion** – Manually create a ContentVersion record from a contentBodyId
+- **getCurrentUserId** – Get the current user's Salesforce ID
 
-5. **File Size Limit** (`maxFileSize`):
-   - Prompt: "What is the maximum file size in MB?"
-   - Type: Number (in megabytes)
-   - Default: 2048 MB (2 GB)
+### Types
 
-6. **User Guidance** (`formatHint`):
-   - Prompt: "What hint text should be displayed to users? (e.g., 'JPEG, PNG, PDF, up to 50MB')"
-   - Type: String
-   - Default: None
+- **UploadOptions** – Configuration options for the upload function
+- **FileUploadResult** – Result object containing file info and IDs
+- **FileUploadProgress** – Progress callback data for tracking upload status
+- **UploadStatus** – Upload status enum: "pending" | "uploading" | "processing" | "success" | "error"
 
-7. **Styling** (`dropZoneClassName`):
-   - Prompt: "Do you need custom CSS classes for the drop zone?"
-   - Type: String (CSS class names)
-   - Default: Standard styling
+## Usage Guide
 
-8. **Error Handling** (`onUploadError`):
-   - Prompt: "How should upload errors be handled?"
-   - Type: Function that receives error information
-   - Default: Standard error display
+### Basic Upload with Progress Tracking
 
-9. **Container Styling** (`className`):
-   - Prompt: "Do you need custom CSS classes for the container?"
-   - Type: String (CSS class names)
-   - Default: Standard styling
+Upload files to Salesforce with real-time progress tracking for each file:
 
-### Example Agent Flow
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+async function handleUpload(files: File[]) {
+  const results = await upload({
+    files,
+    onProgress: (progress) => {
+      console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
+      // Update your UI with progress.status and progress.progress
+    },
+  });
 
-```
-Agent: "I'll help you set up the FileUpload component. Let me ask you a few questions:"
-
-1. "Should users be able to upload multiple files at once?" → User: "Yes"
-2. "Do you want to link uploaded files to a specific Salesforce record?" → User: "Yes, to an Account record"
-3. "What file types should be accepted?" → User: "Images and PDFs only"
-4. "What is the maximum file size in MB?" → User: "50 MB"
-5. "What hint text should be displayed to users?" → User: "JPEG, PNG, PDF, up to 50MB"
-6. "How should files be handled after upload?" → User: "Log them to console"
-
-Agent generates:
-<FileUpload
-  multiple
-  accept="image/*,.pdf"
-  recordId={accountId}
-  maxFileSize={50}
-  formatHint="JPEG, PNG, PDF, up to 50MB"
-  onUploadComplete={(files) => console.log("Uploaded:", files)}
-/>
+  console.log("Upload complete:", results);
+  // results[0].contentBodyId: "069..." (always available)
+  // results[0].contentVersionId: undefined (no record linked)
+}
 ```
 
-## Usage
+### Upload with Record Linking
 
-### Option 1: FileUpload component (OOTB UI)
-
-Use the component as-is for a ready-made drop zone, dialog, and progress display.
+Link uploaded files to a Salesforce record immediately by providing `recordId`:
 
 ```tsx
-import { FileUpload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-<FileUpload
-  multiple
-  accept="image/*,.pdf"
-  recordId={accountId} // Creates ContentVersion and links to this record
-  maxFileSize={50} // 50 MB limit
-  formatHint="JPEG, PNG, PDF, up to 50MB"
-  onUploadComplete={(files) => {
-    // files[0].contentBodyId: "069..."
-    // files[0].contentVersionId: "068..."
-    console.log("Uploaded:", files);
-  }}
-/>;
-```
-
-### Option 2: Upload file only (no ContentVersion)
-
-Omit `recordId` to only upload the file and get the `contentBodyId`:
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+async function uploadToRecord(files: File[], recordId: string) {
+  const results = await upload({
+    files,
+    recordId, // Links files to this record (Account, Opportunity, etc.)
+    onProgress: (progress) => {
+      // Track progress: pending → uploading → processing → success
+      updateUI(progress.fileName, progress.status, progress.progress);
+    },
+  });
 
-```tsx
-<FileUpload
-  multiple
-  onUploadComplete={(files) => {
-    // Only contentBodyId is returned, no ContentVersion created
-    console.log("Content Body ID:", files[0].contentBodyId);
-    console.log("Content Version ID:", files[0].contentVersionId); // undefined
-  }}
-/>
+  // Both contentBodyId and contentVersionId are available
+  console.log("Uploaded to record:", results);
+}
 ```
 
-### Option 3: Upload files before record exists (Record Form pattern)
+### Deferred Record Linking (Record Creation Pattern)
 
-When using FileUpload in a record creation form, omit `recordId` during upload, then create ContentVersion after the form is submitted and the record ID is available:
+**When creating a new record**: Upload files first without `recordId`, then link them after the record is created:
 
 ```tsx
 import {
-  FileUpload,
+  upload,
   createContentVersion,
 } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
 
-function CreateRecordForm() {
-  const [uploadedFiles, setUploadedFiles] = useState([]);
+async function createRecordWithFiles(formData: any, files: File[]) {
+  // Step 1: Upload files (no recordId yet)
+  const uploadResults = await upload({
+    files,
+    onProgress: (progress) => console.log(progress),
+  });
 
-  const handleFileUploadComplete = (files) => {
-    // Store contentBodyId for later use
-    setUploadedFiles(files);
-    console.log("Files uploaded, contentBodyIds stored:", files);
-  };
+  // Step 2: Create the record
+  const newRecordId = await createRecord(formData);
+
+  // Step 3: Link uploaded files to the new record
+  for (const file of uploadResults) {
+    const contentVersionId = await createContentVersion(
+      new File([""], file.fileName),
+      file.contentBodyId,
+      newRecordId,
+    );
+    console.log("ContentVersion created:", contentVersionId);
+  }
+}
+```
+
+### Cancel Upload
+
+Use an AbortController to cancel uploads:
 
-  const handleFormSubmit = async (formData) => {
-    // 1. Create the record first
-    const newRecordId = await createRecord(formData);
-
-    // 2. Now link uploaded files to the newly created record
-    for (const file of uploadedFiles) {
-      const contentVersionId = await createContentVersion(
-        new File([""], file.name),
-        file.contentBodyId,
-        newRecordId, // Use the newly created record ID
-      );
-      console.log("ContentVersion created:", contentVersionId);
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+function UploadComponent() {
+  const abortController = new AbortController();
+
+  const handleUpload = async (files: File[]) => {
+    try {
+      await upload({
+        files,
+        signal: abortController.signal,
+        onProgress: (progress) => console.log(progress),
+      });
+    } catch (error) {
+      console.error("Upload failed or cancelled:", error);
     }
   };
 
-  return (
-    <form onSubmit={handleFormSubmit}>
-      {/* Form fields */}
-      <input name="name" placeholder="Record Name" />
-
-      {/* File upload without recordId */}
-      <FileUpload multiple onUploadComplete={handleFileUploadComplete} />
+  const cancelUpload = () => {
+    abortController.abort();
+  };
 
-      <button type="submit">Create Record</button>
-    </form>
+  return (
+    <div>
+      <button onClick={() => handleUpload(selectedFiles)}>Upload</button>
+      <button onClick={cancelUpload}>Cancel</button>
+    </div>
   );
 }
 ```
 
-### Option 4: Manual ContentVersion creation
+## API Reference
 
-Upload file first, then manually create ContentVersion:
+### upload(options)
 
-```tsx
-import {
-  FileUpload,
-  createContentVersion,
-  getCurrentUserId,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+Unified upload API that handles the complete upload flow with progress tracking.
 
-function MyComponent() {
-  const handleComplete = async (files) => {
-    const userId = await getCurrentUserId();
-
-    for (const file of files) {
-      const contentVersionId = await createContentVersion(
-        new File([""], file.name),
-        file.contentBodyId,
-        userId,
-      );
-      console.log("Created ContentVersion:", contentVersionId);
-    }
-  };
+**Parameters:**
+
+```typescript
+interface UploadOptions {
+  /** Files to upload */
+  files: File[];
+
+  /**
+   * Record ID to link files to (FirstPublishLocationId).
+   * - If provided: Creates ContentVersion and links to this record
+   * - If null/undefined: Only uploads file, returns contentBodyId only
+   */
+  recordId?: string | null;
+
+  /** Callback for upload progress of each file */
+  onProgress?: (progress: FileUploadProgress) => void;
+
+  /** Optional abort signal to cancel all uploads */
+  signal?: AbortSignal;
+}
 
-  return <FileUpload onUploadComplete={handleComplete} />;
+interface FileUploadProgress {
+  fileName: string;
+  status: "pending" | "uploading" | "processing" | "success" | "error";
+  progress: number; // 0-100 for uploading, 0 for other states
+  error?: string;
 }
 ```
 
-### Option 5: Custom UI with your own trigger
+**Returns:** `Promise<FileUploadResult[]>`
 
-Use the `useFileUpload` hook to control when the file picker opens. Render a hidden input and your own button or action.
+```typescript
+interface FileUploadResult {
+  fileName: string;
+  size: number;
+  contentBodyId: string; // Always available
+  contentVersionId?: string; // Only if recordId was provided
+}
+```
+
+### createContentVersion(file, contentBodyId, recordId)
+
+Manually create a ContentVersion record from a previously uploaded file.
+
+**Parameters:**
+
+- `file` (File): The file object (used for metadata like name)
+- `contentBodyId` (string): The ContentBody ID from a previous upload
+- `recordId` (string): The record ID for FirstPublishLocationId
+
+**Returns:** `Promise<string | undefined>` - The ContentVersion ID if successful
 
 ```tsx
-import {
-  useFileUpload,
-  type UseFileUploadOptions,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+const contentVersionId = await createContentVersion(file, "069xx000000xxxx", "001xx000000yyyy");
+```
 
-function CustomUploadButton() {
-  const { getInputProps, openFilePicker } = useFileUpload({
-    multiple: true,
-    maxFileSize: 50, // 50 MB limit
-    onUploadComplete: (files) => console.log("Uploaded:", files),
-  });
+### getCurrentUserId()
 
-  return (
-    <>
-      <input {...getInputProps()} style={{ display: "none" }} />
-      <button type="button" onClick={openFilePicker}>
-        Upload files
-      </button>
-    </>
-  );
-}
+Get the current user's Salesforce ID.
+
+**Returns:** `Promise<string>` - The current user ID
+
+```tsx
+const userId = await getCurrentUserId();
 ```
 
-### Option 6: Custom UI with drop zone and progress
+## Building Your Own UI
 
-Build a custom drop zone and inline progress list (no dialog) using `getDropZoneProps` and `fileItems`:
+This package provides the backend APIs - you can build any UI you want. Here's a basic example:
 
 ```tsx
-import { useFileUpload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
-
-function MyUpload() {
-  const { fileItems, getInputProps, getDropZoneProps, reset } = useFileUpload({
-    multiple: true,
-    recordId: accountId,
-    maxFileSize: 100, // 100 MB limit
-    onUploadComplete: (files) => console.log("Uploaded files:", files),
-  });
+import {
+  upload,
+  type FileUploadProgress,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { useState } from "react";
 
-  const input = getInputProps();
-  const drop = getDropZoneProps();
+function CustomFileUpload({ recordId }: { recordId?: string }) {
+  const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());
+
+  const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(event.target.files || []);
+
+    await upload({
+      files,
+      recordId,
+      onProgress: (fileProgress) => {
+        setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
+      },
+    });
+  };
 
   return (
     <div>
-      <div {...drop}>
-        <input {...input} style={{ display: "none" }} />
-        Drop files here
-      </div>
-      {fileItems.map((item) => (
-        <div key={item.file.name}>
-          {item.file.name}: {item.state} {item.progress}%
+      <input type="file" multiple onChange={handleFileSelect} />
+
+      {Array.from(progress.entries()).map(([fileName, fileProgress]) => (
+        <div key={fileName}>
+          {fileName}: {fileProgress.status} - {fileProgress.progress}%
+          {fileProgress.error && <span>Error: {fileProgress.error}</span>}
         </div>
       ))}
     </div>
@@ -268,38 +254,78 @@ function MyUpload() {
 }
 ```
 
-## API Reference
+## Agent/Vibe Integration Guide
 
-### createContentVersion(file, contentBodyId, recordId)
+When building file upload functionality with an AI agent like Vibe, follow this pattern:
 
-Manually create a ContentVersion record from a previously uploaded file.
+### 1. Ask User for Record Context
 
-**Parameters:**
+```
+Agent: "Do you want to link uploaded files to a specific record, or upload them first and link later?"
 
-- `file` (File): The file object (used for metadata like name)
-- `contentBodyId` (string): The ContentBody ID from a previous upload
-- `recordId` (string): The record ID for FirstPublishLocationId (ex: Salesforce record id to attach file)
+Options:
+A) Link to existing record (provide recordId)
+B) Upload only (link later with createContentVersion)
+C) Link to current user
+```
 
-**Returns:** `Promise<string | undefined>` - The ContentVersion ID if successful
+### 2. Implement Based on Response
+
+**Option A: Link to existing record**
 
 ```tsx
-const contentVersionId = await createContentVersion(file, "069xx000000xxxx", "005xx000000yyyy");
+await upload({ files, recordId: "001xx000000yyyy" });
 ```
 
-## Dependencies
+**Option B: Upload only, link later**
+
+```tsx
+const results = await upload({ files }); // No recordId
+// Later: await createContentVersion(file, results[0].contentBodyId, newRecordId);
+```
+
+**Option C: Link to current user**
 
-This feature depends on:
+```tsx
+const userId = await getCurrentUserId();
+await upload({ files, recordId: userId });
+```
+
+### 3. Track Progress in Your UI
+
+Always provide progress feedback to users:
+
+```tsx
+onProgress: (progress) => {
+  // Update your UI based on:
+  // - progress.fileName
+  // - progress.status (pending, uploading, processing, success, error)
+  // - progress.progress (0-100)
+  // - progress.error (if status is 'error')
+};
+```
+
+## Reference Implementation
+
+This package includes a reference implementation with UI components for demonstration purposes. The components are located in `src/features/fileupload/` and include:
+
+- FileUpload component with drop zone and progress dialog
+- useFileUpload hook for custom implementations
+- Test pages showing various usage patterns
+
+These are **not exported** from the package but can be viewed as examples of how to build your own UI using the APIs.
+
+## Dependencies
 
-- **base-react-app** (built-in) – UI components (Button, Dialog, etc.) via shadcn are included in the base React app.
 - **@salesforce/webapp-experimental** – For API client and Salesforce integration
+- **@salesforce/sdk-data** – For data SDK integration
 
-## Build & Testing
+## Testing
 
-You can test the extension of the base app and the components via the following:
+Test the reference implementation locally:
 
 ```bash
-npx nx build
-npx nx start
+npx nx dev @salesforce/webapp-template-feature-react-file-upload-experimental
 ```
 
-Open the app and navigate to the **Upload Test** page to test the FileUpload component with manual ContentVersion creation.
+Open the app and navigate to the test pages to see the APIs in action.

package/dist/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.90.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.90.1...v1.90.2) (2026-03-11)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.90.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.90.0...v1.90.1) (2026-03-11)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-file-upload/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.90.1",
-    "@salesforce/webapp-experimental": "^1.90.1",
+    "@salesforce/sdk-data": "^1.90.2",
+    "@salesforce/webapp-experimental": "^1.90.2",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-form": "^1.28.4",
     "class-variance-authority": "^0.7.1",
@@ -40,7 +40,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.90.1",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.90.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",