@evolve.ui/core-components 1.0.0

package/hooks-D4sJ62Xl.mjs

@@ -0,0 +1,607 @@
+import { formatFileSize } from "./utils/formatFileSize.mjs";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { capitalize } from "es-toolkit";
+//#region src/FileUpload/utils/constants.ts
+const builtInErrorCodes = [
+	"file-invalid-type",
+	"file-too-large",
+	"too-many-files"
+];
+const ACCEPTED_MIME_TYPES = {
+	documents: [
+		"application/pdf",
+		"application/msword",
+		"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+		"application/vnd.ms-excel",
+		"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	],
+	images: [
+		"image/jpeg",
+		"image/png",
+		"image/gif",
+		"image/webp"
+	],
+	pdfs: ["application/pdf"]
+};
+const DRAG_MESSAGES = {
+	default: "Invalid file",
+	partialUpload: {
+		"file-invalid-type": ({ fileCount = 1, filePluralizationText }) => `${fileCount} ${filePluralizationText} ${fileCount > 1 ? "have" : "has"} an invalid file type`,
+		"file-too-large": ({ formattedMaxSize }) => `One or more files are too large. (${formattedMaxSize} limit)`,
+		"too-many-files": ({ fileCount, filePluralizationText }) => `${fileCount} ${filePluralizationText} will exceed the file limit`
+	},
+	singleFileUpload: {
+		"file-invalid-type": "File type not supported",
+		"file-too-large": ({ formattedMaxSize }) => `File must be smaller than ${formattedMaxSize}`,
+		"too-many-files": ({ filePluralizationText, maxFiles }) => `You can only upload ${maxFiles} ${filePluralizationText}`
+	},
+	strictUpload: {
+		"file-invalid-type": "One or more files have an invalid file type",
+		"file-too-large": ({ formattedMaxSize }) => `One or more files are too large. (${formattedMaxSize} limit)`,
+		"too-many-files": ({ maxFiles, maxFilesPluralizationText }) => `You can only upload ${maxFiles} ${maxFilesPluralizationText}`
+	}
+};
+const DROP_MESSAGES = {
+	default: "Invalid file",
+	partialUpload: {
+		"file-invalid-type": ({ acceptedFileExtensions, fileCount = 1, filePluralizationText }) => `Failed to add ${fileCount} ${filePluralizationText} due to invalid file type. Please upload only ${acceptedFileExtensions} files.`,
+		"file-too-large": ({ fileCount = 1, filePluralizationText, formattedMaxSize }) => `${fileCount} ${filePluralizationText} ${fileCount > 1 ? "are" : "is"} too large. Please upload files smaller than ${formattedMaxSize}.`,
+		"too-many-files": ({ fileCount, filePluralizationText, maxFiles }) => `You've reached the ${maxFiles} file limit. ${fileCount} ${filePluralizationText} could not be added.`
+	},
+	singleFileUpload: {
+		"file-invalid-type": ({ acceptedFileExtensions }) => `File type not supported. Please upload only ${acceptedFileExtensions} files.`,
+		"file-too-large": ({ formattedMaxSize }) => `File is too large. Please upload files smaller than ${formattedMaxSize}.`,
+		"too-many-files": ({ filePluralizationText, maxFiles }) => `${capitalize(filePluralizationText ?? "files")} not added. You can only upload ${maxFiles} in total`
+	},
+	strictUpload: {
+		"file-invalid-type": ({ acceptedFileExtensions }) => `One or more files have an invalid file type. Please upload only ${acceptedFileExtensions} files.`,
+		"file-too-large": ({ formattedMaxSize }) => `One or more files are too large. Please upload files smaller than ${formattedMaxSize}.`,
+		"too-many-files": ({ filePluralizationText, maxFiles, maxFilesPluralizationText }) => `${capitalize(filePluralizationText ?? "files")} not added - maximum of ${maxFiles} ${maxFilesPluralizationText} allowed.`
+	}
+};
+//#endregion
+//#region src/FileUpload/utils/getFileExtensionsFromAcceptedTypes.ts
+const MIME_TYPE_TO_EXTENSION = {
+	"application/msword": ".doc",
+	"application/pdf": ".pdf",
+	"application/vnd.ms-excel": ".xls",
+	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+	"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+	"image/gif": ".gif",
+	"image/jpeg": ".jpeg",
+	"image/jpg": ".jpg",
+	"image/png": ".png",
+	"image/webp": ".webp"
+};
+/**
+* Converts a MIME type to its corresponding file extension
+* @param mimeType The MIME type to convert (e.g., 'image/jpeg', 'application/pdf')
+* @returns The corresponding file extension with leading dot (e.g., '.jpeg', '.pdf')
+*          or an empty string if the MIME type is invalid or incomplete
+*/
+const getMimeTypeExtension = (mimeType) => {
+	if (MIME_TYPE_TO_EXTENSION[mimeType]) return MIME_TYPE_TO_EXTENSION[mimeType];
+	const parts = mimeType.split("/");
+	if (parts.length === 2 && parts[1] && !parts[1].includes(".")) return `.${parts[1]}`;
+	return "";
+};
+/**
+* Converts file type restrictions into a comma-separated list of file extensions
+* @param accept - Optional file type restrictions, can be either:
+*   - A preset category from CommonFileTypes (e.g., 'images', 'pdfs', 'documents')
+*   - An array of specific file extensions (e.g., ['.jpg', '.png', '.pdf'])
+*   - An array of MIME types (e.g., ['image/jpeg', 'image/png', 'application/pdf'])
+*   - A mixed array of both extensions and MIME types
+* @returns A comma-separated string of file extensions with leading dots (e.g., '.jpg, .png, .pdf')
+*          or an empty string if no valid extensions are found or accept is undefined
+* @example
+* // Returns '.jpeg, .png, .gif, .webp, .jpg'
+* getFileExtensionsFromAcceptedTypes('images')
+*
+* // Returns '.jpg, .png, .pdf'
+* getFileExtensionsFromAcceptedTypes(['.jpg', 'image/png', 'application/pdf'])
+*/
+const getFileExtensionsFromAcceptedTypes = (accept) => {
+	if (!accept) return "";
+	if (typeof accept === "string") return ACCEPTED_MIME_TYPES[accept].map(getMimeTypeExtension).join(", ");
+	return accept.filter(Boolean).map((type) => type.startsWith(".") ? type : getMimeTypeExtension(type)).filter((ext) => ext.length > 1).join(", ");
+};
+//#endregion
+//#region src/FileUpload/utils/getFilePluralizationText.ts
+const getBaseText = (accept) => {
+	if (accept === "images") return "image";
+	if (Array.isArray(accept)) return accept.every((type) => type.startsWith("image/")) ? "image" : "file";
+	return "file";
+};
+const pluralize = (count, word, hideCount, capitalizeWord) => {
+	const text = `${word}${count === 1 ? "" : "s"}`;
+	const finalText = capitalizeWord ? capitalize(text) : text;
+	return hideCount ? finalText : `${count} ${finalText}`;
+};
+/**
+* Generates a formatted text string for file type descriptions with proper pluralization and capitalization
+* @param props Configuration object for text formatting
+* @param props.accept - Optional file type(s) to determine if text should say "file" or "image"
+* @param props.capitalize - Optional flag to capitalize the first letter of the output
+* @param props.count - Optional number to determine pluralization (e.g., "1 file" vs "2 files")
+* @param props.hideCount - Optional flag to exclude the count from the output (e.g., "files" instead of "2 files")
+* @returns Formatted string describing file(s) or image(s)
+* @example
+* // Returns "2 files"
+* getFilePluralizationText({ count: 2 })
+*
+* // Returns "1 image"
+* getFilePluralizationText({ accept: 'images', count: 1 })
+*
+* // Returns "Files"
+* getFilePluralizationText({ capitalize: true, hideCount: true })
+*
+* // Returns "Image"
+* getFilePluralizationText({ accept: 'images', capitalize: true })
+*/
+const getFilePluralizationText = ({ accept, capitalize: capitalizeWord, count, hideCount } = {}) => {
+	const baseText = getBaseText(accept);
+	if (count === void 0) {
+		if (capitalizeWord) return capitalize(baseText);
+		return baseText;
+	}
+	return pluralize(count, baseText, hideCount, capitalizeWord);
+};
+//#endregion
+//#region src/FileUpload/utils/createMessageContext.ts
+/**
+* Creates a base message context with properties common to both drag and drop events
+*/
+const createBaseMessageContext = ({ accept, code, count, formattedMaxSize, maxFiles, maxSize }) => {
+	const acceptedFileExtensions = getFileExtensionsFromAcceptedTypes(accept);
+	const filePluralizationText = getFilePluralizationText({
+		accept,
+		count,
+		hideCount: true
+	});
+	const maxFilesPluralizationText = getFilePluralizationText({
+		accept,
+		count: maxFiles,
+		hideCount: true
+	});
+	return {
+		acceptedFileExtensions,
+		errorCode: code,
+		...count !== void 0 && { fileCount: count },
+		filePluralizationText,
+		formattedMaxSize,
+		maxFiles,
+		maxFilesPluralizationText,
+		maxSizeBytes: maxSize
+	};
+};
+/**
+* Creates a message context for drag events
+*/
+const createDragMessageContext = ({ accept, code, count, formattedMaxSize, items, maxFiles, maxSize }) => {
+	return {
+		...createBaseMessageContext({
+			accept,
+			code,
+			count,
+			formattedMaxSize,
+			maxFiles,
+			maxSize
+		}),
+		...items && { draggedItems: items },
+		eventType: "drag"
+	};
+};
+/**
+* Creates a message context for drop events
+*/
+const createDropMessageContext = ({ accept, code, count, files, formattedMaxSize, maxFiles, maxSize }) => {
+	const baseContext = createBaseMessageContext({
+		accept,
+		code,
+		count,
+		formattedMaxSize,
+		maxFiles,
+		maxSize
+	});
+	const rejectedFileList = files?.map((f) => f.name).join(", ") ?? "";
+	return {
+		...baseContext,
+		eventType: "drop",
+		rejectedFileList,
+		...files && { rejectedFiles: files }
+	};
+};
+/**
+* Unified function to create the appropriate message context based on the message type
+*
+* @param params Common parameters for both context types
+* @param params.messageType The type of message context to create ('drag' or 'drop')
+* @param params.dragItems Optional DataTransferItemList for drag events
+* @param params.dropFiles Optional File[] for drop events (only newly dropped files can be rejected)
+* @returns The appropriate message context based on the message type
+*/
+const createMessageContext = ({ accept, code, count, dragItems, dropFiles, formattedMaxSize, maxFiles, maxSize, messageType = "drop" }) => {
+	const baseParams = {
+		accept,
+		code,
+		count,
+		formattedMaxSize,
+		maxFiles,
+		maxSize
+	};
+	if (messageType === "drag") return createDragMessageContext({
+		...baseParams,
+		items: dragItems
+	});
+	return createDropMessageContext({
+		...baseParams,
+		files: dropFiles
+	});
+};
+//#endregion
+//#region src/FileUpload/utils/messageUtils.ts
+/**
+* Processes any type of message into a string
+* @param message - A string, function that returns a string, or undefined
+* @param context - The context object to pass to the message function (optional)
+* @param defaultMessage - Optional fallback message used when the primary message is undefined
+*                         or when the primary message is a function but context is undefined
+* @returns A string message. If a function message is provided, its result is converted to a string.
+*          Returns an empty string if no valid message can be resolved.
+*/
+const resolveContextAwareMessage = (message, context, defaultMessage) => {
+	if (!message) {
+		if (defaultMessage) return resolveContextAwareMessage(defaultMessage, context);
+		return "";
+	}
+	if (typeof message === "function") {
+		if (context) return String(message(context));
+		if (defaultMessage) return resolveContextAwareMessage(defaultMessage, context);
+		return "";
+	}
+	return message;
+};
+//#endregion
+//#region src/FileUpload/hooks/validation/useValidationMessages.ts
+const getMessageSet = (messages, isSingleFileUpload, strictValidation) => {
+	if (isSingleFileUpload) return messages.singleFileUpload;
+	if (strictValidation) return messages.strictUpload;
+	return messages.partialUpload;
+};
+/**
+* Hook that manages validation message generation for file uploads
+* @param props Configuration object
+* @param props.accept - Optional array of accepted file types or CommonFileTypes
+* @param props.maxFiles - Optional maximum number of files allowed
+* @param props.maxSize - Optional maximum file size in bytes
+* @param props.strictValidation - Optional flag for strict validation mode
+* @returns Object containing:
+*   - formattedMaxSize: Human-readable maximum file size (e.g., "5 MB")
+*   - getValidationMessage: Function to get validation messages based on error codes and context
+* @remarks
+* - Handles both drag and drop validation messages
+* - Supports custom error messages
+* - Formats file size limits in human-readable format
+* - Handles pluralization for file count messages
+*/
+const useValidationMessages = ({ accept, maxFiles, maxSize, strictValidation }) => {
+	const formattedMaxSize = maxSize ? formatFileSize(maxSize) : void 0;
+	const isSingleFileUpload = maxFiles === 1;
+	return {
+		formattedMaxSize,
+		getValidationMessage: useCallback(({ code, count = 1, message: customMessage, messageType = "drop" }) => {
+			const messages = messageType === "drag" ? DRAG_MESSAGES : DROP_MESSAGES;
+			const messageContext = createMessageContext({
+				accept,
+				code,
+				count,
+				formattedMaxSize,
+				maxFiles,
+				maxSize,
+				messageType
+			});
+			if (customMessage) return resolveContextAwareMessage(customMessage, messageContext);
+			const message = getMessageSet(messages, isSingleFileUpload, strictValidation)[code];
+			return resolveContextAwareMessage(message, messageContext, messages.default);
+		}, [
+			formattedMaxSize,
+			isSingleFileUpload,
+			maxFiles,
+			accept,
+			strictValidation,
+			maxSize
+		])
+	};
+};
+//#endregion
+//#region src/FileUpload/hooks/validation/useValidationState.ts
+/**
+* Hook that manages validation state for file upload operations
+* @param initialError - Optional initial validation error to display
+* @param getValidationMessage - Function to get validation messages
+* @returns Object containing:
+*   - dragValidationErrors: Validation errors during drag operations
+*   - dropValidationErrors: Validation errors during drop operations
+*   - fileRejections: Rejected files
+*   - setDragValidation: Update drag validation state
+*   - setDropValidation: Update drop validation state
+*   - clearDragValidation: Reset drag validation state
+*   - clearDropValidation: Reset drop validation state
+*   - clearAllValidation: Reset both validation states
+* @remarks
+* - Maintains separate validation states for drag and drop operations
+* - Provides methods to update and clear validation states
+* - Supports initial error state for immediate feedback
+* - Uses memoized clear functions to prevent unnecessary rerenders
+* - Handles message processing internally
+*/
+const useValidationState = (initialError, getValidationMessage) => {
+	const [dragValidationError, setDragValidationErrorState] = useState(null);
+	const [dropValidationErrors, setDropValidationErrorsState] = useState(initialError ? [initialError] : []);
+	const [fileRejections, setFileRejections] = useState([]);
+	const clearDragValidation = useCallback(() => {
+		setDragValidationErrorState(null);
+	}, []);
+	const clearDropValidation = useCallback(() => {
+		setDropValidationErrorsState([]);
+	}, []);
+	const clearAllValidation = useCallback(() => {
+		clearDragValidation();
+		clearDropValidation();
+		setFileRejections([]);
+	}, [clearDragValidation, clearDropValidation]);
+	const setDragValidationError = useCallback((errorOrCode, count) => {
+		if (errorOrCode === null) {
+			setDragValidationErrorState(null);
+			return;
+		}
+		if (typeof errorOrCode === "string") if (getValidationMessage) {
+			const message = getValidationMessage({
+				code: errorOrCode,
+				count,
+				messageType: "drag"
+			});
+			setDragValidationErrorState({
+				code: errorOrCode,
+				message
+			});
+		} else setDragValidationErrorState({
+			code: errorOrCode,
+			message: `Error: ${errorOrCode}`
+		});
+		else setDragValidationErrorState(errorOrCode);
+	}, [getValidationMessage]);
+	const setDropValidationErrors = useCallback((errorsOrCodes, count) => {
+		if (!Array.isArray(errorsOrCodes)) {
+			const errorOrCode = errorsOrCodes;
+			if (typeof errorOrCode === "string") if (getValidationMessage) {
+				const message = getValidationMessage({
+					code: errorOrCode,
+					count,
+					messageType: "drop"
+				});
+				setDropValidationErrorsState([{
+					code: errorOrCode,
+					message
+				}]);
+			} else setDropValidationErrorsState([{
+				code: errorOrCode,
+				message: `Error: ${errorOrCode}`
+			}]);
+			else setDropValidationErrorsState([errorOrCode]);
+			return;
+		}
+		const processedErrors = errorsOrCodes.map((errorOrCode) => {
+			if (typeof errorOrCode === "string") {
+				if (getValidationMessage) return {
+					code: errorOrCode,
+					message: getValidationMessage({
+						code: errorOrCode,
+						count,
+						messageType: "drop"
+					})
+				};
+				return {
+					code: errorOrCode,
+					message: `Error: ${errorOrCode}`
+				};
+			}
+			return errorOrCode;
+		});
+		setDropValidationErrorsState(processedErrors);
+	}, [getValidationMessage]);
+	useEffect(() => {
+		setDropValidationErrorsState(initialError ? [initialError] : []);
+	}, [initialError]);
+	return {
+		clearAllValidation,
+		clearDragValidation,
+		clearDropValidation,
+		dragValidationError,
+		dropValidationErrors,
+		fileRejections,
+		setDragValidationError,
+		setDropValidationErrors,
+		setFileRejections
+	};
+};
+//#endregion
+//#region src/FileUpload/hooks/validation/useFileValidationLogic.ts
+/**
+* Hook that implements core file validation logic and state management
+*
+* This hook serves as the foundation for file validation throughout the upload system.
+* It combines validation state management with validation logic functions, allowing
+* for comprehensive file validation with customizable rules.
+*
+* @param config - Optional validation configuration object containing:
+*   - accept: Optional array of accepted file types or preset categories
+*   - error: Custom error object to override default validation errors
+*   - maxFiles: Maximum number of files allowed (1 for single file upload)
+*   - maxSize: Maximum file size in bytes
+*   - strictValidation: When true, all files are rejected if any fail validation
+*   - validator: Custom validation function for additional rules
+*
+* @returns An object containing:
+*   - Validation state (dragValidationError, dropValidationErrors)
+*   - State management methods (clearDragValidation, clearDropValidation, etc.)
+*   - formattedMaxSize: Human-readable size limit (e.g., "5 MB")
+*   - getValidationMessage: Function to generate context-aware error messages
+*   - Validation methods:
+*     - validateFileType: Checks if a file type is allowed
+*     - validateFileSize: Checks if a file is within size limits
+*     - validateFileCount: Checks if adding files would exceed limit
+*     - validateCustomRules: Applies custom validation function if provided
+*/
+const useFileValidationLogic = (config) => {
+	const { accept, error, maxFiles, maxSize, strictValidation, validator } = config ?? {};
+	const { formattedMaxSize, getValidationMessage } = useValidationMessages({
+		...config,
+		accept
+	});
+	const validationState = useValidationState(error, getValidationMessage);
+	const validateFileType = useCallback((fileType, mimeTypes) => {
+		if (!mimeTypes) return true;
+		return Object.keys(mimeTypes).includes(fileType);
+	}, []);
+	const validateFileSize = useCallback((fileSize) => {
+		if (!maxSize) return true;
+		return fileSize <= maxSize;
+	}, [maxSize]);
+	const validateFileCount = useCallback((currentCount, newCount) => {
+		if (!maxFiles) return true;
+		return currentCount + newCount <= maxFiles;
+	}, [maxFiles]);
+	const validateCustomRules = useCallback((file) => {
+		if (!validator) return null;
+		const validationResult = validator(file);
+		if (!validationResult || validationResult.length === 0) return null;
+		return validationResult;
+	}, [validator]);
+	return {
+		...validationState,
+		formattedMaxSize,
+		getValidationMessage,
+		maxFiles,
+		maxSize,
+		strictValidation,
+		validateCustomRules,
+		validateFileCount,
+		validateFileSize,
+		validateFileType
+	};
+};
+//#endregion
+//#region src/FileUpload/providers/UploadValidationProvider.tsx
+const UploadValidationContext = createContext(void 0);
+const UploadValidationProvider = ({ accept, children, error, maxFiles, maxSize, strictValidation, validator }) => {
+	const validation = useFileValidationLogic({
+		accept,
+		error,
+		maxFiles,
+		maxSize,
+		strictValidation,
+		validator
+	});
+	const [fileRejections, setFileRejections] = useState([]);
+	const value = useMemo(() => ({
+		...validation,
+		accept,
+		fileRejections,
+		maxFiles,
+		maxSize,
+		setFileRejections,
+		strictValidation
+	}), [
+		validation,
+		accept,
+		maxFiles,
+		maxSize,
+		strictValidation,
+		fileRejections
+	]);
+	return /* @__PURE__ */ jsx(UploadValidationContext.Provider, {
+		value,
+		children
+	});
+};
+UploadValidationProvider.displayName = "UploadValidationProvider";
+/**
+* Hook to access the upload validation context
+*
+* Provides access to validation state, error handling, and validation methods
+* for file upload components.
+*
+* @returns The UploadValidationContextType object with validation state and methods
+* @throws Error if used outside of an UploadValidationProvider
+*
+* @example
+* ```tsx
+* const validation = useValidationContext();
+*
+* // Validate file type
+* const isValidType = validation.validateFileType(file.type);
+*
+* // Set validation error
+* if (!isValidType) {
+*   validation.setDragValidationError({
+*     code: 'invalid-file-type',
+*     message: 'File type not supported'
+*   });
+* }
+* ```
+*/
+const useValidationContext = () => {
+	const context = useContext(UploadValidationContext);
+	if (!context) throw new Error("useValidationContext must be used within UploadValidationProvider");
+	return context;
+};
+//#endregion
+//#region src/FileUpload/hooks/validation/useFileValidation.ts
+/**
+* Hook that provides file validation functionality by either using a shared validation context
+* or falling back to local validation logic
+* @param config - Optional validation configuration for file constraints (size, type, etc.)
+* @returns Validation context containing validation state and useful validation methods
+* @remarks
+* - If used within an UploadValidationProvider, returns the shared validation context
+* - Otherwise, creates a local validation context using useFileValidationLogic
+* - This allows components to work with or without a shared validation context
+*/
+const useFileValidation = (config) => {
+	const validationContext = useContext(UploadValidationContext);
+	const localValidation = useFileValidationLogic(config);
+	return validationContext ?? localValidation;
+};
+//#endregion
+//#region src/FileUpload/hooks/filePreview/useImageFilePreviewUrl.ts
+/**
+* Hook to manage file preview URLs with proper cleanup
+* @param file - File to preview
+* @returns Preview URL for image files, undefined for non-image files
+*/
+const useImageFilePreviewUrl = (file) => {
+	const [previewUrl, setPreviewUrl] = useState();
+	useEffect(() => {
+		if (!file) return;
+		if ("url" in file && file.url) {
+			setPreviewUrl(file.url);
+			return;
+		}
+		const fileObj = file;
+		if (!fileObj.type.startsWith("image/")) return;
+		if (previewUrl) URL.revokeObjectURL(previewUrl);
+		const url = URL.createObjectURL(fileObj);
+		setPreviewUrl(url);
+		return () => {
+			if (url) URL.revokeObjectURL(url);
+		};
+	}, [file]);
+	return previewUrl;
+};
+//#endregion
+export { useValidationContext as a, getFilePluralizationText as c, builtInErrorCodes as d, UploadValidationProvider as i, getFileExtensionsFromAcceptedTypes as l, useFileValidation as n, resolveContextAwareMessage as o, UploadValidationContext as r, createMessageContext as s, useImageFilePreviewUrl as t, ACCEPTED_MIME_TYPES as u };
+
+//# sourceMappingURL=hooks-D4sJ62Xl.mjs.map