@salesforce/webapp-template-feature-react-file-upload-experimental 1.55.0

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/hooks/useFileUpload.ts

@@ -0,0 +1,299 @@
+/**
+ * Hook: useFileUpload
+ *
+ * Manages file upload state and logic: config fetch, upload to URL, ContentVersion creation.
+ * Separates upload logic from UI. Use for custom upload UIs or with the FileUpload component.
+ *
+ * @param options - Upload options (accept, multiple, recordId, onUploadComplete, onUploadError)
+ * @returns Object containing fileItems, allDone, cancelFile, getInputProps, getDropZoneProps, openFilePicker, isDragging, reset
+ *
+ * @remarks
+ * Coordinates: (1) getUploadConfig for token/URL, (2) uploadToUrl for file body, (3) createContentVersion
+ * for record creation. Supports cancel, progress tracking, and sequential multi-file uploads.
+ */
+import * as React from "react";
+import { flushSync } from "react-dom";
+import {
+	getUploadConfig,
+	uploadToUrl,
+	createContentVersion,
+	getCurrentUserId,
+} from "../api/fileUpload";
+import type { FileUploadItem, UploadedFile, UploadState } from "../types/fileUpload";
+import { isFileTooLarge, MAX_FILE_SIZE_BYTES, formatFileSize } from "../utils/fileUploadUtils";
+import { LABELS } from "../utils/labels";
+
+export interface UseFileUploadOptions {
+	/** MIME types or file extensions to accept (e.g. image/*, .pdf). Omit for all files. */
+	accept?: string;
+	/** Whether to allow multiple file selection. Default: false */
+	multiple?: boolean;
+	/** Record Id for FirstPublishLocationId (e.g. Account, Opportunity). When provided, files are linked to this record. Otherwise, current user Id is used. */
+	recordId?: string;
+	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, and contentVersionId. */
+	onUploadComplete?: (files: UploadedFile[]) => void;
+	/** Called when an upload fails. Receives the file and error message. */
+	onUploadError?: (file: File, error: string) => void;
+}
+
+function updateItem(
+	items: FileUploadItem[],
+	fileName: string,
+	update: Partial<FileUploadItem>,
+): FileUploadItem[] {
+	return items.map((item) => (item.file.name === fileName ? { ...item, ...update } : item));
+}
+
+interface UseFileUploadReturn {
+	fileItems: FileUploadItem[];
+	allDone: boolean;
+	cancelFile: (fileName: string) => void;
+	getInputProps: () => {
+		ref: React.RefObject<HTMLInputElement | null>;
+		type: "file";
+		accept?: string;
+		multiple: boolean;
+		onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+	};
+	getDropZoneProps: () => {
+		onClick: () => void;
+		onDragOver: (e: React.DragEvent) => void;
+		onDragLeave: (e: React.DragEvent) => void;
+		onDrop: (e: React.DragEvent) => void;
+		onKeyDown: (e: React.KeyboardEvent) => void;
+	};
+	/** Programmatically open the native file picker. Use with a custom trigger (e.g. button). */
+	openFilePicker: () => void;
+	isDragging: boolean;
+	reset: () => void;
+}
+
+export function useFileUpload(options: UseFileUploadOptions = {}): UseFileUploadReturn {
+	const { accept, multiple = false, recordId, onUploadComplete, onUploadError } = options;
+
+	const [fileItems, setFileItems] = React.useState<FileUploadItem[]>([]);
+	const [isDragging, setIsDragging] = React.useState(false);
+	const inputRef = React.useRef<HTMLInputElement>(null);
+	const cancelledFilesRef = React.useRef<Set<string>>(new Set());
+	const currentAbortControllerRef = React.useRef<AbortController | null>(null);
+	const currentFileNameRef = React.useRef<string | null>(null);
+
+	const cancelFile = React.useCallback((fileName: string) => {
+		cancelledFilesRef.current.add(fileName);
+		if (currentFileNameRef.current === fileName && currentAbortControllerRef.current) {
+			currentAbortControllerRef.current.abort();
+		}
+	}, []);
+
+	React.useEffect(() => {
+		return () => {
+			currentAbortControllerRef.current?.abort();
+		};
+	}, []);
+
+	const handleChange = React.useCallback(
+		async (e: React.ChangeEvent<HTMLInputElement>) => {
+			const files = e.target.files ? Array.from(e.target.files) : [];
+			if (files.length === 0) return;
+
+			const maxSizeLabel = formatFileSize(MAX_FILE_SIZE_BYTES);
+			const errorMessage = LABELS.fileTooLarge(maxSizeLabel);
+
+			const items: FileUploadItem[] = files.map((file) => {
+				if (isFileTooLarge(file)) {
+					onUploadError?.(file, errorMessage);
+					return {
+						file,
+						state: "error" as UploadState,
+						progress: 0,
+						error: errorMessage,
+					};
+				}
+				return {
+					file,
+					state: "loading_config" as UploadState,
+					progress: 0,
+				};
+			});
+			setFileItems(items);
+			cancelledFilesRef.current.clear();
+
+			const itemsToUpload = items.filter((item) => item.state !== "error");
+			if (itemsToUpload.length === 0) {
+				e.target.value = "";
+				return;
+			}
+
+			let config: Awaited<ReturnType<typeof getUploadConfig>> | null = null;
+			let publishLocationId: string | null = null;
+			const uploadedFiles: UploadedFile[] = [];
+
+			for (const item of itemsToUpload) {
+				const { file } = item;
+
+				if (cancelledFilesRef.current.has(file.name)) {
+					setFileItems((prev) => updateItem(prev, file.name, { state: "cancelled", progress: 0 }));
+					continue;
+				}
+
+				try {
+					if (!config) {
+						config = await getUploadConfig();
+					}
+					setFileItems((prev) => updateItem(prev, file.name, { state: "loading_config" }));
+
+					if (cancelledFilesRef.current.has(file.name)) {
+						setFileItems((prev) =>
+							updateItem(prev, file.name, { state: "cancelled", progress: 0 }),
+						);
+						continue;
+					}
+
+					const abortController = new AbortController();
+					currentAbortControllerRef.current = abortController;
+					currentFileNameRef.current = file.name;
+
+					setFileItems((prev) => updateItem(prev, file.name, { state: "uploading", progress: 0 }));
+					const contentBodyId = await uploadToUrl(
+						file,
+						config.token,
+						config.uploadUrl,
+						(percent) => {
+							setFileItems((prev) => updateItem(prev, file.name, { progress: percent }));
+						},
+						abortController.signal,
+					);
+
+					currentAbortControllerRef.current = null;
+					currentFileNameRef.current = null;
+
+					if (cancelledFilesRef.current.has(file.name)) {
+						continue;
+					}
+
+					if (!publishLocationId) {
+						publishLocationId = recordId ?? (await getCurrentUserId());
+					}
+					setFileItems((prev) =>
+						updateItem(prev, file.name, { state: "creating_record", progress: 100 }),
+					);
+					const contentVersionId = await createContentVersion(
+						file,
+						contentBodyId,
+						publishLocationId,
+					);
+
+					flushSync(() => {
+						setFileItems((prev) =>
+							updateItem(prev, file.name, {
+								state: "success",
+								progress: 100,
+								contentVersionId,
+							}),
+						);
+					});
+					uploadedFiles.push({
+						name: file.name,
+						size: file.size,
+						contentVersionId,
+					});
+				} catch (err) {
+					currentAbortControllerRef.current = null;
+					currentFileNameRef.current = null;
+					const message = err instanceof Error ? err.message : String(err);
+					const isCancelled =
+						message === "Upload aborted" || cancelledFilesRef.current.has(file.name);
+					setFileItems((prev) =>
+						updateItem(prev, file.name, {
+							state: isCancelled ? "cancelled" : "error",
+							error: isCancelled ? undefined : message,
+						}),
+					);
+					if (!isCancelled) {
+						onUploadError?.(file, message);
+					}
+					// Continue with remaining files; do not return early
+				}
+			}
+
+			if (uploadedFiles.length > 0) {
+				onUploadComplete?.(uploadedFiles);
+			}
+
+			e.target.value = "";
+		},
+		[recordId, onUploadComplete, onUploadError],
+	);
+
+	const handleDragOver = React.useCallback((e: React.DragEvent) => {
+		e.preventDefault();
+		e.stopPropagation();
+		setIsDragging(true);
+	}, []);
+
+	const handleDragLeave = React.useCallback((e: React.DragEvent) => {
+		e.preventDefault();
+		e.stopPropagation();
+		setIsDragging(false);
+	}, []);
+
+	const handleDrop = React.useCallback(
+		(e: React.DragEvent) => {
+			e.preventDefault();
+			e.stopPropagation();
+			setIsDragging(false);
+			const files = e.dataTransfer.files ? Array.from(e.dataTransfer.files) : [];
+			if (files.length > 0 && inputRef.current) {
+				const dt = new DataTransfer();
+				files.forEach((f) => dt.items.add(f));
+				inputRef.current.files = dt.files;
+				handleChange({ target: inputRef.current } as React.ChangeEvent<HTMLInputElement>);
+			}
+		},
+		[handleChange],
+	);
+
+	const handleClick = React.useCallback(() => {
+		inputRef.current?.click();
+	}, []);
+
+	const handleKeyDown = React.useCallback((e: React.KeyboardEvent) => {
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			inputRef.current?.click();
+		}
+	}, []);
+
+	const reset = React.useCallback(() => {
+		setFileItems([]);
+	}, []);
+
+	const allDone =
+		fileItems.length > 0 &&
+		fileItems.every(
+			(item) => item.state === "success" || item.state === "error" || item.state === "cancelled",
+		);
+
+	return {
+		fileItems,
+		allDone,
+		isDragging,
+		reset,
+		cancelFile,
+		openFilePicker: handleClick,
+		getInputProps: () => ({
+			ref: inputRef,
+			type: "file" as const,
+			accept,
+			multiple,
+			onChange: handleChange,
+		}),
+		getDropZoneProps: () => ({
+			onClick: handleClick,
+			onDragOver: handleDragOver,
+			onDragLeave: handleDragLeave,
+			onDrop: handleDrop,
+			onKeyDown: handleKeyDown,
+		}),
+	};
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/hooks/useFileUploadDialog.ts

@@ -0,0 +1,70 @@
+/**
+ * Hook: useFileUploadDialog
+ *
+ * Manages file upload dialog state: open/close and list of successfully uploaded file names.
+ * Powers the FileUpload component internally. Opens dialog when fileItems has items; on close,
+ * captures success names for display and resets upload state.
+ *
+ * Not exported from the package. Use the FileUpload component for file upload UIs.
+ *
+ * @param options - Dialog options (fileItems, reset)
+ * @returns Object containing dialogOpen, uploadedFileNames, handleOpenChange
+ *
+ * @remarks
+ * Coordinates with useFileUpload: opens when fileItems.length > 0, on close calls reset and
+ * accumulates successfully uploaded file names for the summary list below the drop zone.
+ *
+ * @example
+ * ```tsx
+ * const { dialogOpen, uploadedFileNames, handleOpenChange } = useFileUploadDialog({
+ *   fileItems,
+ *   reset,
+ * });
+ * ```
+ */
+import * as React from "react";
+import type { FileUploadItem } from "../types/fileUpload";
+
+interface UseFileUploadDialogOptions {
+	fileItems: FileUploadItem[];
+	reset: () => void;
+}
+
+interface UseFileUploadDialogReturn {
+	dialogOpen: boolean;
+	uploadedFileNames: string[];
+	handleOpenChange: (open: boolean) => void;
+}
+
+export function useFileUploadDialog({
+	fileItems,
+	reset,
+}: UseFileUploadDialogOptions): UseFileUploadDialogReturn {
+	const [dialogOpen, setDialogOpen] = React.useState(false);
+	const [uploadedFileNames, setUploadedFileNames] = React.useState<string[]>([]);
+
+	React.useEffect(() => {
+		if (fileItems.length > 0) {
+			setDialogOpen(true);
+			setUploadedFileNames([]);
+		}
+	}, [fileItems.length]);
+
+	const handleOpenChange = React.useCallback(
+		(open: boolean) => {
+			if (!open) {
+				const successNames = fileItems
+					.filter((item) => item.state === "success")
+					.map((item) => item.file.name);
+				if (successNames.length > 0) {
+					setUploadedFileNames((prev) => [...prev, ...successNames]);
+				}
+				reset();
+			}
+			setDialogOpen(open);
+		},
+		[fileItems, reset],
+	);
+
+	return { dialogOpen, uploadedFileNames, handleOpenChange };
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * feature-react-file-upload – File upload component
+ *
+ * Provides a React file upload experience with drag-and-drop, progress tracking,
+ * and Salesforce ContentVersion integration. Supports single or multiple files,
+ * optional record linking (FirstPublishLocationId), and custom accept filters.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * File upload component. Renders a drop zone for selecting files, a modal dialog
+ * showing upload progress, and a list of successfully uploaded files. Supports
+ * click-to-select and drag-and-drop.
+ *
+ * @example
+ * ```tsx
+ * <FileUpload
+ *   accept="image/*"
+ *   multiple
+ *   recordId={accountId}
+ *   onUploadComplete={(files) => console.log('Uploaded:', files)}
+ * />
+ * ```
+ */
+export { FileUpload } from "./components/FileUpload";
+
+/**
+ * Props for the FileUpload component.
+ *
+ * @see FileUpload
+ */
+export type { FileUploadProps } from "./components/FileUpload";
+
+/**
+ * Hook that manages file upload state and logic: config fetch, upload to URL,
+ * and ContentVersion creation. Use for custom upload UIs or with the FileUpload
+ * component. Returns fileItems, getInputProps, getDropZoneProps, and helpers
+ * for progress, cancel, and reset.
+ *
+ * @example
+ * ```tsx
+ * const { fileItems, getDropZoneProps, openFilePicker } = useFileUpload({
+ *   accept: '.pdf',
+ *   onUploadComplete: (files) => handleComplete(files),
+ * });
+ * ```
+ */
+export { useFileUpload } from "./hooks/useFileUpload";
+
+/**
+ * Options for the useFileUpload hook.
+ *
+ * @see useFileUpload
+ */
+export type { UseFileUploadOptions } from "./hooks/useFileUpload";

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/navigationMenu.tsx

@@ -0,0 +1,80 @@
+import { Link, useLocation } from 'react-router';
+import { getAllRoutes } from './router-utils';
+import { useState } from 'react';
+
+export default function NavigationMenu() {
+  const [isOpen, setIsOpen] = useState(false);
+  const location = useLocation();
+
+  const isActive = (path: string) => location.pathname === path;
+
+  const toggleMenu = () => setIsOpen(!isOpen);
+
+  const navigationRoutes: { path: string; label: string }[] = getAllRoutes()
+    .filter(
+      route =>
+        route.handle?.showInNavigation === true &&
+        route.fullPath !== undefined &&
+        route.handle?.label !== undefined
+    )
+    .map(
+      route =>
+        ({
+          path: route.fullPath,
+          label: route.handle?.label,
+        }) as { path: string; label: string }
+    );
+
+  return (
+    <nav className="bg-white border-b border-gray-200">
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+        <div className="flex justify-between items-center h-16">
+          <Link to="/" className="text-xl font-semibold text-gray-900">
+            React App
+          </Link>
+          <button
+            onClick={toggleMenu}
+            className="p-2 rounded-md text-gray-700 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-blue-500"
+            aria-label="Toggle menu"
+          >
+            <div className="w-6 h-6 flex flex-col justify-center space-y-1.5">
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${
+                  isOpen ? 'rotate-45 translate-y-2' : ''
+                }`}
+              />
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${isOpen ? 'opacity-0' : ''}`}
+              />
+              <span
+                className={`block h-0.5 w-6 bg-current transition-all ${
+                  isOpen ? '-rotate-45 -translate-y-2' : ''
+                }`}
+              />
+            </div>
+          </button>
+        </div>
+        {isOpen && (
+          <div className="pb-4">
+            <div className="flex flex-col space-y-2">
+              {navigationRoutes.map(item => (
+                <Link
+                  key={item.path}
+                  to={item.path}
+                  onClick={() => setIsOpen(false)}
+                  className={`px-3 py-2 rounded-md text-sm font-medium transition-colors ${
+                    isActive(item.path)
+                      ? 'bg-blue-100 text-blue-700'
+                      : 'text-gray-700 hover:bg-gray-100'
+                  }`}
+                >
+                  {item.label}
+                </Link>
+              ))}
+            </div>
+          </div>
+        )}
+      </div>
+    </nav>
+  );
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/pages/Home.tsx

@@ -0,0 +1,25 @@
+import { FileUpload } from "../components/FileUpload";
+
+/**
+ * Home page for testing the file-upload feature standalone.
+ * Renders FileUpload for dialog-based file upload with progress.
+ */
+export default function Home() {
+	return (
+		<div className="max-w-2xl mx-auto px-4 sm:px-6 lg:px-8 py-12 space-y-16">
+			<section>
+				<h2 className="text-2xl font-bold text-gray-900 mb-2">File Upload (Dialog + Progress)</h2>
+				<p className="text-gray-600 mb-8">
+					Choose files to open a dialog showing upload status with progress bar for each file.
+				</p>
+				<FileUpload
+					multiple
+					onUploadComplete={(files) => {
+						// eslint-disable-next-line no-console
+						console.log("Uploaded files:", files);
+					}}
+				/>
+			</section>
+		</div>
+	);
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/pages/NotFound.tsx

@@ -0,0 +1,18 @@
+import { Link } from 'react-router';
+
+export default function NotFound() {
+  return (
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold text-gray-900 mb-4">404</h1>
+        <p className="text-lg text-gray-600 mb-8">Page not found</p>
+        <Link
+          to="/"
+          className="inline-block px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors"
+        >
+          Go to Home
+        </Link>
+      </div>
+    </div>
+  );
+}

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/router-utils.tsx

@@ -0,0 +1,35 @@
+import type { RouteObject } from 'react-router';
+import { routes } from './routes';
+
+export type RouteWithFullPath = RouteObject & { fullPath: string };
+
+const flatMapRoutes = (
+  route: RouteObject,
+  parentPath: string = ''
+): RouteWithFullPath[] => {
+  let fullPath: string;
+
+  if (route.index) {
+    fullPath = parentPath || '/';
+  } else if (route.path) {
+    if (route.path.startsWith('/')) {
+      fullPath = route.path;
+    } else {
+      fullPath =
+        parentPath === '/' ? `/${route.path}` : `${parentPath}/${route.path}`;
+    }
+  } else {
+    fullPath = parentPath;
+  }
+
+  const routeWithPath = { ...route, fullPath };
+
+  const childRoutes =
+    route.children?.flatMap(child => flatMapRoutes(child, fullPath)) || [];
+
+  return [routeWithPath, ...childRoutes];
+};
+
+export const getAllRoutes = (): RouteWithFullPath[] => {
+  return routes.flatMap(route => flatMapRoutes(route));
+};

package/dist/force-app/main/default/webapplications/feature-react-file-upload/src/routes.tsx

@@ -0,0 +1,22 @@
+import type { RouteObject } from 'react-router';
+import AppLayout from './appLayout';
+import Home from './pages/Home';
+import NotFound from './pages/NotFound';
+
+export const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <AppLayout />,
+    children: [
+      {
+        index: true,
+        element: <Home />,
+        handle: { showInNavigation: true, label: "Home" }
+      },
+      {
+        path: '*',
+        element: <NotFound />
+      }
+    ]
+  }
+];