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

package/src/force-app/main/default/webapplications/feature-react-file-upload/src/features/fileupload/components/FileUploadDropZone.tsx

@@ -0,0 +1,90 @@
+import { LABELS } from "../utils/labels";
+
+import { ImageIcon } from "./FileUploadIcons";
+
+export interface FileUploadDropZoneProps {
+	/** Props for the hidden file input (ref, type, accept, multiple, onChange) */
+	inputProps: {
+		ref: React.RefObject<HTMLInputElement | null>;
+		type: "file";
+		accept?: string;
+		multiple: boolean;
+		onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+	};
+	/** Props for the drop zone (onClick, onDragOver, onDragLeave, onDrop, onKeyDown) */
+	dropZoneProps: {
+		onClick: () => void;
+		onDragOver: (e: React.DragEvent) => void;
+		onDragLeave: (e: React.DragEvent) => void;
+		onDrop: (e: React.DragEvent) => void;
+		onKeyDown: (e: React.KeyboardEvent) => void;
+	};
+	/** Whether the user is currently dragging over the drop zone */
+	isDragging: boolean;
+	/** Optional format hint (e.g. "JPEG, PNG, PDF, and MP4 formats, up to 50MB"). Defaults to LABELS.formatHint. */
+	formatHint?: string;
+	/** Optional CSS class for the drop zone (e.g. "h-full" for flex layouts) */
+	className?: string;
+}
+
+const DROP_ZONE_BASE_CLASSES =
+	"mb-2 flex cursor-pointer flex-col items-center justify-center gap-2 rounded-lg border-2 border-dashed bg-white px-6 pt-4 pb-8 transition-colors";
+const DROP_ZONE_DRAGGING_CLASSES = "border-blue-500 bg-blue-50";
+const DROP_ZONE_IDLE_CLASSES = "border-gray-300 hover:border-gray-400 hover:bg-gray-50";
+
+/**
+ * Drop zone for file selection. Renders a dashed border area with document icon,
+ * primary instruction text, and format hint. Accepts click and drag-and-drop.
+ * Uses a hidden file input; props come from useFileUpload.
+ */
+export function FileUploadDropZone({
+	inputProps,
+	dropZoneProps,
+	isDragging,
+	formatHint = LABELS.formatHint,
+	className = "",
+}: FileUploadDropZoneProps) {
+	const dropZoneClassName = [
+		DROP_ZONE_BASE_CLASSES,
+		isDragging ? DROP_ZONE_DRAGGING_CLASSES : DROP_ZONE_IDLE_CLASSES,
+		className,
+	]
+		.filter(Boolean)
+		.join(" ");
+
+	return (
+		<div
+			role="button"
+			tabIndex={0}
+			onClick={dropZoneProps.onClick}
+			onDragOver={dropZoneProps.onDragOver}
+			onDragLeave={dropZoneProps.onDragLeave}
+			onDrop={dropZoneProps.onDrop}
+			onKeyDown={dropZoneProps.onKeyDown}
+			className={dropZoneClassName}
+			aria-label={LABELS.dropZone}
+			data-testid="file-upload-drop-zone"
+		>
+			<input
+				id="file-upload-input-id"
+				ref={inputProps.ref}
+				type="file"
+				accept={inputProps.accept}
+				multiple={inputProps.multiple}
+				onChange={inputProps.onChange}
+				className="sr-only"
+				aria-hidden
+			/>
+			<span
+				className="inline-flex h-12 w-12 shrink-0 items-center justify-center text-gray-500"
+				aria-hidden
+			>
+				<ImageIcon size="lg" />
+			</span>
+			<p className="text-center text-sm font-medium text-gray-900">
+				{isDragging ? LABELS.dropFilesHere : LABELS.chooseFileOrDrop}
+			</p>
+			<p className="text-center text-xs text-gray-500">{formatHint}</p>
+		</div>
+	);
+}

package/src/force-app/main/default/webapplications/feature-react-file-upload/src/features/fileupload/components/FileUploadFileItem.tsx

@@ -0,0 +1,99 @@
+import { Button } from "../../../components/ui/__inherit__button";
+import { FileTypeIcon, IconImageClose, SuccessIcon } from "./FileUploadIcons";
+import {
+	formatFileSize,
+	getFileExtension,
+	getProgressWidth,
+	isUploading,
+} from "../utils/fileUploadUtils";
+import { LABELS } from "../utils/labels";
+import type { FileUploadItem } from "../types/fileUpload";
+
+export interface FileUploadFileItemProps {
+	/** The file item with upload state, progress, and optional error */
+	item: FileUploadItem;
+	/** Called when the user cancels an in-progress upload */
+	onCancel: (fileName: string) => void;
+}
+
+/**
+ * Renders a single file upload item with file type icon, name, size, progress bar,
+ * cancel button (when uploading), and status icon (success, error, or cancelled).
+ */
+export function FileUploadFileItem({ item, onCancel }: FileUploadFileItemProps) {
+	const extension = getFileExtension(item.file.name);
+	const progressWidth = getProgressWidth(item.state, item.progress);
+
+	return (
+		<li
+			className="grid min-w-0 grid-cols-[auto_minmax(0,4fr)_minmax(0,5fr)] items-center gap-2 rounded-lg border border-gray-200 bg-gray-100 p-2"
+			data-testid="file-upload-item"
+		>
+			<FileTypeIcon extension={extension} />
+			<div className="min-w-0 overflow-hidden">
+				<p
+					className="truncate text-sm font-medium text-gray-900"
+					title={item.file.name}
+					aria-label={LABELS.fileName(item.file.name)}
+				>
+					{item.file.name}
+				</p>
+				<p
+					className="truncate text-xs text-gray-600"
+					aria-label={LABELS.fileSize(formatFileSize(item.file.size))}
+				>
+					{formatFileSize(item.file.size)}
+				</p>
+			</div>
+			<div className="flex min-w-0 items-center gap-1.5">
+				<div
+					className="h-1.5 min-w-0 flex-1 overflow-hidden rounded-full bg-gray-200"
+					role="progressbar"
+					aria-label={LABELS.uploadProgress(item.file.name)}
+					aria-valuenow={progressWidth}
+					aria-valuemin={0}
+					aria-valuemax={100}
+				>
+					<div
+						className="h-full bg-blue-600 transition-all duration-300"
+						style={{ width: `${progressWidth}%` }}
+					/>
+				</div>
+				{isUploading(item.state) && (
+					<Button
+						type="button"
+						variant="ghost"
+						size="icon"
+						className="h-7 w-7 shrink-0 text-gray-600 hover:text-red-600"
+						onClick={() => onCancel(item.file.name)}
+						aria-label={LABELS.cancelUpload(item.file.name)}
+					>
+						<IconImageClose fill="rgb(116, 116, 116)" />
+					</Button>
+				)}
+				{renderStatusIcon(item.state)}
+				{item.state === "error" && item.error && <p className="sr-only">{item.error}</p>}
+			</div>
+		</li>
+	);
+}
+
+function renderStatusIcon(state: FileUploadItem["state"]): React.ReactNode {
+	if (isUploading(state)) return null;
+	if (state === "success") return <SuccessIcon fill="rgb(46, 132, 74)" />;
+	if (state === "cancelled") {
+		return (
+			<span className="shrink-0 text-xs text-gray-500" aria-label={LABELS.cancelled}>
+				{LABELS.cancelled}
+			</span>
+		);
+	}
+	return (
+		<span
+			className="inline-flex h-4 w-4 shrink-0 items-center justify-center text-red-600"
+			aria-label={LABELS.uploadFailed}
+		>
+			×
+		</span>
+	);
+}

package/src/force-app/main/default/webapplications/feature-react-file-upload/src/features/fileupload/components/FileUploadIcons.tsx

@@ -0,0 +1,90 @@
+import symbolsUrl from "../assets/symbols.svg?url";
+
+const IMAGE_EXTENSIONS = new Set([
+	"jpg",
+	"jpeg",
+	"png",
+	"gif",
+	"webp",
+	"svg",
+	"bmp",
+	"ico",
+	"tiff",
+	"tif",
+]);
+
+/**
+ * Renders a file-type icon based on extension. Uses symbols.svg: "unknown" for
+ * no extension, "image" for image types, or the extension (e.g. pdf) for others.
+ */
+export function FileTypeIcon({ extension }: { extension: string }) {
+	/** Symbol ID in symbols.svg: unknown (no ext), image (image types), or extension (e.g. pdf). */
+	const ext = extension.toLowerCase();
+	const symbolId = extension === "FILE" ? "unknown" : IMAGE_EXTENSIONS.has(ext) ? "image" : ext;
+	return (
+		<span
+			className="inline-flex h-8 w-8 shrink-0 items-center justify-center"
+			aria-hidden
+			title={extension}
+		>
+			<svg className="h-full w-full" aria-hidden>
+				<use href={`${symbolsUrl}#${symbolId}`} />
+			</svg>
+		</span>
+	);
+}
+
+import iconImageCloseSvg from "../assets/icon-image-close.svg?raw";
+import successSvg from "../assets/success.svg?raw";
+import imageSvg from "../assets/image.svg?raw";
+
+/** Props for icon components (close, success, image) */
+export interface IconProps {
+	size?: "sm" | "md" | "lg";
+	fill?: string;
+}
+
+const sizeClass = (size: IconProps["size"]) =>
+	size === "sm" ? "h-4 w-4" : size === "lg" ? "h-12 w-12" : "h-6 w-6";
+
+/**
+ * Close icon (circle with X). Renders from icon-image-close.svg.
+ */
+export function IconImageClose({ size = "md", fill = "currentColor" }: IconProps) {
+	return (
+		<span
+			className={`inline-flex ${sizeClass(size)} shrink-0 items-center justify-center`}
+			style={{ color: fill }}
+			aria-hidden
+			dangerouslySetInnerHTML={{ __html: iconImageCloseSvg }}
+		/>
+	);
+}
+
+/**
+ * Success icon (circle with checkmark). Renders from success.svg.
+ */
+export function SuccessIcon({ size = "md", fill = "currentColor" }: IconProps) {
+	return (
+		<span
+			className={`inline-flex ${sizeClass(size)} shrink-0 items-center justify-center`}
+			style={{ color: fill }}
+			aria-hidden
+			dangerouslySetInnerHTML={{ __html: successSvg }}
+		/>
+	);
+}
+
+/**
+ * Image icon (picture frame). Renders from image.svg. Used for drop zone.
+ */
+export function ImageIcon({ size = "lg", fill = "currentColor" }: IconProps) {
+	return (
+		<span
+			className={`inline-flex ${sizeClass(size)} shrink-0 items-center justify-center`}
+			style={{ color: fill }}
+			aria-hidden
+			dangerouslySetInnerHTML={{ __html: imageSvg }}
+		/>
+	);
+}

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

@@ -0,0 +1,312 @@
+/**
+ * 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 } from "../api/fileUpload";
+import type { FileUploadItem, UploadedFile, UploadState } from "../types/fileUpload";
+import {
+	isFileTooLarge,
+	MAX_FILE_SIZE_BYTES,
+	bytesFromMB,
+	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 and ContentVersion is created. When null/undefined, only uploads file and returns contentBodyId without creating ContentVersion. */
+	recordId?: string;
+	/** Called when uploads complete. Receives array of successfully uploaded files with name, size, contentBodyId, and contentVersionId (if ContentVersion was created). */
+	onUploadComplete?: (files: UploadedFile[]) => void;
+	/** Called when an upload fails. Receives the file and error message. */
+	onUploadError?: (file: File, error: string) => void;
+	/** Maximum file size in MB. Files exceeding this limit are rejected with an error. Omit for default (2 GB). */
+	maxFileSize?: number;
+}
+
+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,
+		maxFileSize,
+	} = options;
+
+	const maxBytes = maxFileSize != null ? bytesFromMB(maxFileSize) : MAX_FILE_SIZE_BYTES;
+
+	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(maxBytes);
+			const errorMessage = LABELS.fileTooLarge(maxSizeLabel);
+
+			const items: FileUploadItem[] = files.map((file) => {
+				if (isFileTooLarge(file, maxBytes)) {
+					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;
+					}
+
+					// Only create ContentVersion if recordId is provided
+					let contentVersionId: string | undefined;
+					if (recordId) {
+						if (!publishLocationId) {
+							publishLocationId = recordId;
+						}
+						setFileItems((prev) =>
+							updateItem(prev, file.name, { state: "creating_record", progress: 100 }),
+						);
+						contentVersionId = await createContentVersion(file, contentBodyId, publishLocationId);
+					}
+
+					flushSync(() => {
+						setFileItems((prev) =>
+							updateItem(prev, file.name, {
+								state: "success",
+								progress: 100,
+								contentBodyId,
+								contentVersionId,
+							}),
+						);
+					});
+					uploadedFiles.push({
+						name: file.name,
+						size: file.size,
+						contentBodyId,
+						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, maxBytes],
+	);
+
+	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/src/force-app/main/default/webapplications/feature-react-file-upload/src/features/fileupload/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 };
+}