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

package/src/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/src/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/src/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/src/force-app/main/default/webapplications/feature-react-file-upload/src/routes.tsx

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

package/src/force-app/main/default/webapplications/feature-react-file-upload/src/types/fileUpload.ts

@@ -0,0 +1,26 @@
+/**
+ * File upload type definitions.
+ */
+
+export type UploadState =
+	| "idle"
+	| "loading_config"
+	| "uploading"
+	| "creating_record"
+	| "success"
+	| "error"
+	| "cancelled";
+
+export interface FileUploadItem {
+	file: File;
+	state: UploadState;
+	progress: number;
+	error?: string;
+	contentVersionId?: string;
+}
+
+export interface UploadedFile {
+	name: string;
+	size: number;
+	contentVersionId?: string;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * File upload utility functions.
+ */
+
+import type { UploadState } from "../types/fileUpload";
+
+/** Maximum allowed file size: 2 GB */
+export const MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024 * 1024;
+
+export function isFileTooLarge(file: File): boolean {
+	return file.size > MAX_FILE_SIZE_BYTES;
+}
+
+const UPLOADING_STATES: UploadState[] = ["loading_config", "uploading", "creating_record"];
+
+export function isUploading(state: UploadState): boolean {
+	return UPLOADING_STATES.includes(state);
+}
+
+export function formatFileSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+export function getFileExtension(name: string): string {
+	const lastDot = name.lastIndexOf(".");
+	return lastDot > 0 ? name.slice(lastDot + 1).toUpperCase() : "FILE";
+}
+
+export function formatUploadSummary(successCount: number, totalCount: number): string {
+	const noun = totalCount === 1 ? "file" : "files";
+	if (totalCount === 1) {
+		return successCount === 1 ? "1 of 1 file uploaded" : "1 file uploading";
+	}
+	return `${successCount} of ${totalCount} ${noun} uploaded`;
+}
+
+export function getProgressWidth(state: UploadState, progress: number): number {
+	if (state === "success") return 100;
+	if (state === "error" || state === "cancelled") return 0;
+	return progress;
+}

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

@@ -0,0 +1,21 @@
+/** User-visible text and accessibility labels. */
+export const LABELS = {
+	attach: "Attach",
+	uploadFiles: "Upload Files",
+	dropFilesHere: "Drop files here",
+	orDropFiles: "Or drop files",
+	uploadFilesDialogTitle: "Upload Files",
+	done: "Done",
+	cancelled: "Cancelled",
+	dropZone: "Upload files by clicking or dragging files here",
+	cancelUpload: (fileName: string) => `Cancel upload of ${fileName}`,
+	uploadComplete: "Upload complete",
+	uploadFailed: "Upload failed",
+	uploadStatus: "Upload status",
+	uploadedFiles: "Uploaded files",
+	uploadProgress: (fileName: string) => `Upload progress for ${fileName}`,
+	fileName: (name: string) => `File name: ${name}`,
+	fileSize: (size: string) => `File size: ${size}`,
+	fileTooLarge: (maxSize: string) => `File exceeds maximum size of ${maxSize}`,
+	doneButton: "Close dialog and finish upload",
+} as const;

package/src/force-app/main/default/webapplications/feature-react-file-upload/vite.config.ts

@@ -0,0 +1,43 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "path";
+import { resolve } from "path";
+import tailwindcss from "@tailwindcss/vite";
+import salesforce from "@salesforce/vite-plugin-webapp-experimental";
+
+export default defineConfig(({ mode }) => {
+	return {
+		plugins: [tailwindcss(), react(), salesforce({ debug: true })],
+
+		build: {
+			outDir: resolve(__dirname, "dist"),
+			assetsDir: "assets",
+			sourcemap: false,
+		},
+
+		resolve: {
+			dedupe: ["react", "react-dom"],
+			alias: {
+				react: path.resolve(__dirname, "node_modules/react"),
+				"react-dom": path.resolve(__dirname, "node_modules/react-dom"),
+				"@": path.resolve(__dirname, "./src"),
+				"@api": path.resolve(__dirname, "./src/api"),
+				"@components": path.resolve(__dirname, "./src/components"),
+				"@utils": path.resolve(__dirname, "./src/utils"),
+				"@styles": path.resolve(__dirname, "./src/styles"),
+				"@assets": path.resolve(__dirname, "./src/assets"),
+			},
+		},
+
+		test: {
+			root: resolve(__dirname),
+			environment: "jsdom",
+			include: [
+				"src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}",
+				"src/**/__tests__/**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}",
+			],
+			testTimeout: 10000,
+			globals: true,
+		},
+	};
+});