react-dropzone 19.0.1 → 19.1.0

package/dist/index.d.cts

@@ -14,6 +14,12 @@ interface FileError {
   message: string;
   code: ErrorCode | string;
 }
+/**
+ * What a custom `validator` returns: a single error, a list of errors, or `null` when the file
+ * passes. A validator may return the result directly (synchronous) or wrapped in a `Promise`
+ * (asynchronous, e.g. reading image dimensions or calling an external service).
+ */
+type ValidatorResult = FileError | readonly FileError[] | null;
 declare enum ErrorCode {
   FileInvalidType = "file-invalid-type",
   FileTooLarge = "file-too-large",
@@ -48,7 +54,18 @@ type DropzoneOptions = Pick<React.HTMLProps<HTMLElement>, SharedProps> & {
   onFileDialogCancel?: () => void;
   onFileDialogOpen?: () => void;
   onError?: (err: Error) => void;
-  validator?: <T extends File>(file: T) => FileError | readonly FileError[] | null;
+  /**
+   * Custom validation, run once per file on drop/selection. Return `null` to accept the file, or a
+   * {@link FileError} (or array of them) to reject it. May be `async` (return a `Promise`) to support
+   * checks that can't run synchronously - e.g. reading image dimensions, inspecting file contents,
+   * or calling an external service. While an async validator is pending, {@link DropzoneState.isProcessing}
+   * is `true`, and `onDrop`/`onDropAccepted`/`onDropRejected` fire only once it settles. If the
+   * validator throws or rejects, `onError` is called and the drop is discarded.
+   *
+   * Note: the validator never runs during a drag (a `DataTransferItem` has no name/size), so a
+   * validator-configured dropzone is `isDragUnknown` until drop.
+   */
+  validator?: <T extends File>(file: T) => ValidatorResult | Promise<ValidatorResult>;
   /**
    * Override the message of any rejection error (built-in or custom). Called once per error;
    * receives the error and the file it belongs to and returns the message to use. Return
@@ -70,6 +87,14 @@ type DropzoneState = DropzoneRef & {
   isDragUnknown: boolean;
   isDragGlobal: boolean;
   isFileDialogActive: boolean;
+  /**
+   * `true` while a drop/selection is being processed asynchronously - i.e. while `getFilesFromEvent`
+   * reads the files and/or an async {@link DropzoneOptions.validator} runs. Spans the whole pipeline,
+   * from when files start being read until validation settles. When both are synchronous (the default
+   * `getFilesFromEvent` with no/async-free validator) the work resolves within a microtask, so it's
+   * only observable for genuinely async work. Use it to show a spinner or disable UI while processing.
+   */
+  isProcessing: boolean;
   acceptedFiles: readonly FileWithPath[];
   fileRejections: readonly FileRejection[];
   rootRef: React.RefObject<HTMLElement>;
@@ -120,5 +145,5 @@ declare const Dropzone: React.ForwardRefExoticComponent<DropzoneProps & React.Re
  */
 declare function useDropzone(props?: DropzoneOptions): DropzoneState;
 //#endregion
-export { type Accept, DropEvent, DropzoneInputProps, DropzoneOptions, DropzoneProps, DropzoneRef, DropzoneRootProps, DropzoneState, ErrorCode, type FileError, FileRejection, type FileWithPath, Dropzone as default, useDropzone };
+export { type Accept, DropEvent, DropzoneInputProps, DropzoneOptions, DropzoneProps, DropzoneRef, DropzoneRootProps, DropzoneState, ErrorCode, type FileError, FileRejection, type FileWithPath, type ValidatorResult, Dropzone as default, useDropzone };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -14,6 +14,12 @@ interface FileError {
   message: string;
   code: ErrorCode | string;
 }
+/**
+ * What a custom `validator` returns: a single error, a list of errors, or `null` when the file
+ * passes. A validator may return the result directly (synchronous) or wrapped in a `Promise`
+ * (asynchronous, e.g. reading image dimensions or calling an external service).
+ */
+type ValidatorResult = FileError | readonly FileError[] | null;
 declare enum ErrorCode {
   FileInvalidType = "file-invalid-type",
   FileTooLarge = "file-too-large",
@@ -48,7 +54,18 @@ type DropzoneOptions = Pick<React.HTMLProps<HTMLElement>, SharedProps> & {
   onFileDialogCancel?: () => void;
   onFileDialogOpen?: () => void;
   onError?: (err: Error) => void;
-  validator?: <T extends File>(file: T) => FileError | readonly FileError[] | null;
+  /**
+   * Custom validation, run once per file on drop/selection. Return `null` to accept the file, or a
+   * {@link FileError} (or array of them) to reject it. May be `async` (return a `Promise`) to support
+   * checks that can't run synchronously - e.g. reading image dimensions, inspecting file contents,
+   * or calling an external service. While an async validator is pending, {@link DropzoneState.isProcessing}
+   * is `true`, and `onDrop`/`onDropAccepted`/`onDropRejected` fire only once it settles. If the
+   * validator throws or rejects, `onError` is called and the drop is discarded.
+   *
+   * Note: the validator never runs during a drag (a `DataTransferItem` has no name/size), so a
+   * validator-configured dropzone is `isDragUnknown` until drop.
+   */
+  validator?: <T extends File>(file: T) => ValidatorResult | Promise<ValidatorResult>;
   /**
    * Override the message of any rejection error (built-in or custom). Called once per error;
    * receives the error and the file it belongs to and returns the message to use. Return
@@ -70,6 +87,14 @@ type DropzoneState = DropzoneRef & {
   isDragUnknown: boolean;
   isDragGlobal: boolean;
   isFileDialogActive: boolean;
+  /**
+   * `true` while a drop/selection is being processed asynchronously - i.e. while `getFilesFromEvent`
+   * reads the files and/or an async {@link DropzoneOptions.validator} runs. Spans the whole pipeline,
+   * from when files start being read until validation settles. When both are synchronous (the default
+   * `getFilesFromEvent` with no/async-free validator) the work resolves within a microtask, so it's
+   * only observable for genuinely async work. Use it to show a spinner or disable UI while processing.
+   */
+  isProcessing: boolean;
   acceptedFiles: readonly FileWithPath[];
   fileRejections: readonly FileRejection[];
   rootRef: React.RefObject<HTMLElement>;
@@ -120,5 +145,5 @@ declare const Dropzone: React.ForwardRefExoticComponent<DropzoneProps & React.Re
  */
 declare function useDropzone(props?: DropzoneOptions): DropzoneState;
 //#endregion
-export { type Accept, DropEvent, DropzoneInputProps, DropzoneOptions, DropzoneProps, DropzoneRef, DropzoneRootProps, DropzoneState, ErrorCode, type FileError, FileRejection, type FileWithPath, Dropzone as default, useDropzone };
+export { type Accept, DropEvent, DropzoneInputProps, DropzoneOptions, DropzoneProps, DropzoneRef, DropzoneRootProps, DropzoneState, ErrorCode, type FileError, FileRejection, type FileWithPath, type ValidatorResult, Dropzone as default, useDropzone };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -97,6 +97,13 @@ function isDefined(value) {
 	return value !== void 0 && value !== null;
 }
 /**
+* Check if a value is thenable (Promise-like), used to tell a synchronous validator result from an
+* asynchronous one.
+*/
+function isThenable(value) {
+	return value != null && typeof value.then === "function";
+}
+/**
 * Classify a set of dragged files for the `isDragAccept`/`isDragReject`/`isDragUnknown` states.
 *
 * During `dragenter`/`dragover` the browser only exposes `DataTransferItem`s, which carry a MIME
@@ -129,7 +136,10 @@ function isPropagationStopped(event) {
 }
 function isEvtWithFiles(event) {
 	if (!event.dataTransfer) return !!event.target && !!event.target.files;
-	return Array.prototype.some.call(event.dataTransfer.types, (type) => type === "Files" || type === "application/x-moz-file");
+	return Array.prototype.some.call(event.dataTransfer.types, (type) => type === "Files" || type === "application/x-moz-file") || Array.prototype.some.call(event.dataTransfer.items ?? [], isKindFile);
+}
+function isKindFile(item) {
+	return typeof item === "object" && item !== null && item.kind === "file";
 }
 function onDocumentDragOver(event) {
 	event.preventDefault();
@@ -278,6 +288,7 @@ const initialState = {
 	isDragReject: false,
 	isDragUnknown: false,
 	isDragGlobal: false,
+	isProcessing: false,
 	acceptedFiles: [],
 	fileRejections: []
 };
@@ -311,6 +322,23 @@ function useDropzone(props = {}) {
 	const inputRef = useRef(null);
 	const [state, dispatch] = useReducer(reducer, initialState);
 	const { isFocused, isFileDialogActive } = state;
+	const processingAbortRef = useRef(null);
+	const beginProcessing = useCallback(() => {
+		processingAbortRef.current?.abort();
+		const controller = new AbortController();
+		processingAbortRef.current = controller;
+		dispatch({
+			type: "setProcessing",
+			isProcessing: true
+		});
+		return controller.signal;
+	}, []);
+	const endProcessing = useCallback((signal) => {
+		if (!signal.aborted) dispatch({
+			type: "setProcessing",
+			isProcessing: false
+		});
+	}, []);
 	const fsAccessApiWorksRef = useRef(typeof window !== "undefined" && window.isSecureContext && useFsAccessApi && canUseFileSystemAccessAPI());
 	const onWindowFocus = () => {
 		if (!fsAccessApiWorksRef.current && isFileDialogActive) setTimeout(() => {
@@ -476,42 +504,72 @@ function useDropzone(props = {}) {
 		onDragLeave,
 		noDragEventsBubbling
 	]);
-	const setFiles = useCallback((files, event) => {
-		const acceptedFiles = [];
-		const fileRejections = [];
+	const setFiles = useCallback(async (files, event, signal) => {
 		const localizeError = (error, file) => getErrorMessage ? {
 			...error,
 			message: getErrorMessage(error, file)
 		} : error;
-		files.forEach((file) => {
-			const [accepted, acceptError] = fileAccepted(file, inputAcceptAttr);
-			const [sizeMatch, sizeError] = fileMatchSize(file, minSize, maxSize);
-			const customErrors = validator ? validator(file) : null;
-			if (accepted && sizeMatch && !customErrors) acceptedFiles.push(file);
-			else {
-				let errors = [acceptError, sizeError];
-				if (customErrors) errors = errors.concat(customErrors);
+		const commit = (results) => {
+			const acceptedFiles = [];
+			const fileRejections = [];
+			results.forEach(({ file, accepted, acceptError, sizeMatch, sizeError, customErrors }) => {
+				if (accepted && sizeMatch && !customErrors) acceptedFiles.push(file);
+				else {
+					let errors = [acceptError, sizeError];
+					if (customErrors) errors = errors.concat(customErrors);
+					fileRejections.push({
+						file,
+						errors: errors.filter((e) => e != null).map((error) => localizeError(error, file))
+					});
+				}
+			});
+			const acceptedFilesLimit = multiple ? maxFiles >= 1 ? maxFiles : Number.POSITIVE_INFINITY : 1;
+			if (acceptedFiles.length > acceptedFilesLimit) acceptedFiles.splice(acceptedFilesLimit).forEach((file) => {
 				fileRejections.push({
 					file,
-					errors: errors.filter((e) => e != null).map((error) => localizeError(error, file))
+					errors: [localizeError(TOO_MANY_FILES_REJECTION, file)]
 				});
-			}
-		});
-		const acceptedFilesLimit = multiple ? maxFiles >= 1 ? maxFiles : Number.POSITIVE_INFINITY : 1;
-		if (acceptedFiles.length > acceptedFilesLimit) acceptedFiles.splice(acceptedFilesLimit).forEach((file) => {
-			fileRejections.push({
-				file,
-				errors: [localizeError(TOO_MANY_FILES_REJECTION, file)]
 			});
+			dispatch({
+				acceptedFiles,
+				fileRejections,
+				type: "setFiles"
+			});
+			if (onDrop) onDrop(acceptedFiles, fileRejections, event);
+			if (fileRejections.length > 0 && onDropRejected) onDropRejected(fileRejections, event);
+			if (acceptedFiles.length > 0 && onDropAccepted) onDropAccepted(acceptedFiles, event);
+		};
+		const pending = files.map((file) => {
+			const [accepted, acceptError] = fileAccepted(file, inputAcceptAttr);
+			const [sizeMatch, sizeError] = fileMatchSize(file, minSize, maxSize);
+			return {
+				file,
+				accepted,
+				acceptError,
+				sizeMatch,
+				sizeError,
+				customErrors: validator ? validator(file) : null
+			};
 		});
-		dispatch({
-			acceptedFiles,
-			fileRejections,
-			type: "setFiles"
-		});
-		if (onDrop) onDrop(acceptedFiles, fileRejections, event);
-		if (fileRejections.length > 0 && onDropRejected) onDropRejected(fileRejections, event);
-		if (acceptedFiles.length > 0 && onDropAccepted) onDropAccepted(acceptedFiles, event);
+		if (!pending.some(({ customErrors }) => isThenable(customErrors))) {
+			commit(pending);
+			return;
+		}
+		let results;
+		try {
+			results = await Promise.all(pending.map(async ({ customErrors, ...rest }) => ({
+				...rest,
+				customErrors: await customErrors
+			})));
+		} catch (e) {
+			if (!signal.aborted) {
+				endProcessing(signal);
+				onErrCb(e);
+			}
+			return;
+		}
+		if (signal.aborted) return;
+		commit(results);
 	}, [
 		dispatch,
 		multiple,
@@ -523,23 +581,39 @@ function useDropzone(props = {}) {
 		onDropAccepted,
 		onDropRejected,
 		validator,
-		getErrorMessage
+		getErrorMessage,
+		onErrCb,
+		endProcessing
 	]);
 	const onDropCb = useCallback((event) => {
 		event.preventDefault();
 		event.persist?.();
 		stopPropagation(event);
 		dragTargetsRef.current = [];
-		if (isEvtWithFiles(event)) Promise.resolve(getFilesFromEvent(event)).then((files) => {
-			if (isPropagationStopped(event) && !noDragEventsBubbling) return;
-			setFiles(files, event);
-		}).catch((e) => onErrCb(e));
 		dispatch({ type: "reset" });
+		if (isEvtWithFiles(event)) {
+			const signal = beginProcessing();
+			Promise.resolve(getFilesFromEvent(event)).then((files) => {
+				if (signal.aborted) return;
+				if (isPropagationStopped(event) && !noDragEventsBubbling) {
+					endProcessing(signal);
+					return;
+				}
+				return setFiles(files, event, signal);
+			}).catch((e) => {
+				if (!signal.aborted) {
+					endProcessing(signal);
+					onErrCb(e);
+				}
+			});
+		}
 	}, [
 		getFilesFromEvent,
 		setFiles,
 		onErrCb,
-		noDragEventsBubbling
+		noDragEventsBubbling,
+		beginProcessing,
+		endProcessing
 	]);
 	const openFileDialog = useCallback(() => {
 		if (fsAccessApiWorksRef.current) {
@@ -549,10 +623,16 @@ function useDropzone(props = {}) {
 				multiple,
 				types: pickerTypes
 			};
-			window.showOpenFilePicker(opts).then((handles) => getFilesFromEvent(handles)).then((files) => {
-				setFiles(files, null);
+			let signal;
+			window.showOpenFilePicker(opts).then((handles) => {
+				signal = beginProcessing();
+				return getFilesFromEvent(handles);
+			}).then((files) => {
 				dispatch({ type: "closeDialog" });
+				if (signal.aborted) return;
+				return setFiles(files, null, signal);
 			}).catch((e) => {
+				if (signal) endProcessing(signal);
 				if (isAbort(e)) {
 					onFileDialogCancelCb(e);
 					dispatch({ type: "closeDialog" });
@@ -580,7 +660,9 @@ function useDropzone(props = {}) {
 		setFiles,
 		onErrCb,
 		pickerTypes,
-		multiple
+		multiple,
+		beginProcessing,
+		endProcessing
 	]);
 	const onKeyDownCb = useCallback((event) => {
 		if (!rootRef.current?.isEqualNode(event.target)) return;
@@ -707,10 +789,15 @@ function reducer(state, action) {
 			isDragReject: action.isDragReject,
 			isDragUnknown: action.isDragUnknown
 		};
+		case "setProcessing": return {
+			...state,
+			isProcessing: action.isProcessing
+		};
 		case "setFiles": return {
 			...state,
 			acceptedFiles: action.acceptedFiles,
 			fileRejections: action.fileRejections,
+			isProcessing: false,
 			isDragReject: false,
 			isDragUnknown: false
 		};