@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/FileUpload/hooks/upload/useHandleDrop/createFileRejectionHelpers.ts

@@ -0,0 +1,273 @@
+import { UploadValidationContextType } from '../../../providers/UploadValidationProvider';
+import {
+    ContextAwareMessage,
+    DynamicMessageContext,
+    FileError,
+    FileRejection,
+    FileResource,
+    ValidationError,
+} from '../../../types/commonTypes';
+import { builtInErrorCodes } from '../../../utils/constants';
+import { createMessageContext } from '../../../utils/createMessageContext';
+import { resolveContextAwareMessage } from '../../../utils/messageUtils';
+
+// Type for tracking error groups
+export type ErrorGroup = {
+    count: number;
+    files: File[];
+    message: ContextAwareMessage<DynamicMessageContext>;
+};
+
+/**
+ * Creates helper functions for processing file rejections and formatting error messages
+ * @param validation Validation context containing message formatters and validation rules
+ * @returns Object with helper functions for processing file rejections
+ */
+export const createRejectionHelpers = (validation: UploadValidationContextType) => {
+    const { accept, formattedMaxSize, getValidationMessage, maxFiles, maxSize, strictValidation, validateFileCount } =
+        validation;
+
+    /**
+     * Ensures an error group exists for the given code, creating one if necessary
+     *
+     * @param errorGroups - Record of existing error groups indexed by error code
+     * @param code - The error code to get or create a group for
+     * @param message - Optional error message to use when creating a new group
+     * @returns The existing or newly created error group for the specified code
+     * @remarks
+     * - Error groups track files that failed with the same error code
+     * - Each group maintains a count of files, file references, and a shared message
+     * - New groups are initialized with empty arrays and zero counts
+     */
+    const getOrCreateErrorGroup = (
+        errorGroups: Record<string, ErrorGroup>,
+        code: string,
+        message?: ContextAwareMessage<DynamicMessageContext>
+    ): ErrorGroup => {
+        if (!(code in errorGroups)) {
+            errorGroups[code] = {
+                count: 0,
+                files: [],
+                message: message ?? '',
+            };
+        }
+        return errorGroups[code];
+    };
+
+    return {
+        /**
+         * Formats a human-readable error message for display based on error code and grouped files
+         *
+         * This function handles two types of validation errors:
+         *
+         * 1. System errors (built-in): For standard error codes like 'file-too-large' or 'too-many-files',
+         *    it uses the built-in message system with appropriate pluralization and formatting.
+         *
+         * 2. Custom validator errors: For custom error codes from user-defined validators,
+         *    it enriches the message with context about the rejected files (count, names, etc.).
+         *
+         * Used in two key scenarios:
+         * - Creating consolidated error messages for the UI (one message per error type)
+         * - Formatting individual file rejection messages for callbacks
+         *
+         * @param code - The error code identifying the validation failure
+         * @param error - The error object containing the message (string or function)
+         * @param errorGroups - Record of grouped errors with counts and file references
+         * @returns A formatted, human-readable error message ready for display
+         */
+        getFormattedErrorGroupMessage: (
+            code: string,
+            error: ValidationError,
+            errorGroups: Record<string, ErrorGroup>
+        ) => {
+            const isSystemError = builtInErrorCodes.includes(code);
+            const errorGroup = errorGroups[code];
+
+            // For system errors, use getValidationMessage directly
+            if (isSystemError) {
+                return getValidationMessage({
+                    code,
+                    count: errorGroup.count,
+                    messageType: 'drop',
+                });
+            }
+
+            // For custom errors, we need to provide context about the rejected files
+            const messageContext = createMessageContext({
+                accept,
+                code,
+                count: errorGroup.count,
+                dropFiles: errorGroup.files,
+                formattedMaxSize,
+                maxFiles,
+                maxSize,
+                messageType: 'drop',
+            });
+
+            // Resolve the message function with proper context containing all grouped files
+            return resolveContextAwareMessage(error.message, messageContext);
+        },
+
+        getOrCreateErrorGroup,
+
+        /**
+         * Handles file count limits and returns updated accepted/rejected files
+         *
+         * This function enforces the maxFiles constraint by calculating whether adding
+         * new files would exceed the configured limit.
+         *
+         * @param currentFiles - Existing files already uploaded or selected
+         * @param droppedAcceptedFiles - New files that passed initial type/size validation
+         * @param droppedRejectedFiles - New files that already failed validation for other reasons
+         * @returns Object containing the final accepted and rejected files after limit checks
+         * @remarks
+         * - Considers both existing files and newly dropped files when checking limits
+         * - Handles two validation modes:
+         *   1. Strict validation (strictValidation: true):
+         *      If adding any files would exceed the limit, ALL files are rejected
+         *   2. Partial upload (strictValidation: false):
+         *      Accepts files up to the remaining limit, rejecting only overflow files
+         * - Calculates remaining slots as (maxFiles - currentFiles.length)
+         * - When no maxFiles is defined, accepts all files (Infinity limit)
+         * - Adds appropriate error metadata to the rejected files for UI feedback
+         */
+        handleFileCountLimits: (
+            currentFiles: FileResource[],
+            droppedAcceptedFiles: File[],
+            droppedRejectedFiles: FileRejection[]
+        ) => {
+            let acceptedResult = droppedAcceptedFiles;
+            let rejectionsResult = [...droppedRejectedFiles];
+
+            // Check if the total number of files (including both accepted and rejected) would exceed the limit
+            // This ensures users see the maxFiles error even if some files are rejected for other reasons
+            const totalDroppedFiles = droppedAcceptedFiles.length + droppedRejectedFiles.length;
+            const wouldExceedLimit = !validateFileCount(currentFiles.length, totalDroppedFiles);
+            const remainingSlots = maxFiles ? maxFiles - currentFiles.length : Infinity;
+
+            if (wouldExceedLimit) {
+                // Calculate how many files exceed the limit, considering all dropped files
+                const overflowCount = currentFiles.length + totalDroppedFiles - (maxFiles ?? Infinity);
+                const errorCode = 'too-many-files';
+                const errorMessage = getValidationMessage({
+                    code: errorCode,
+                    count: overflowCount,
+                    messageType: 'drop',
+                });
+
+                const maxFilesError: FileError = {
+                    code: errorCode,
+                    message: errorMessage,
+                };
+
+                // Add the error to all files that exceed the limit
+                // Start with files that were already accepted (they passed other validations)
+                const fileCountRejections = acceptedResult.slice(remainingSlots).map((file) => ({
+                    errors: [maxFilesError],
+                    file,
+                }));
+
+                // Add these new rejections to the existing ones
+                rejectionsResult = [...rejectionsResult, ...fileCountRejections];
+
+                if (!strictValidation) {
+                    // In partial upload mode, only accept files up to the max file limit
+                    acceptedResult = acceptedResult.slice(0, remainingSlots);
+                } else {
+                    // In strict mode, reject all files if the total count exceeds the limit
+                    acceptedResult = [];
+                }
+            }
+
+            return { allAcceptedFiles: acceptedResult, allRejections: rejectionsResult };
+        },
+
+        /**
+         * Handles file size validation and returns updated accepted/rejected files
+         *
+         * This function checks if files exceed the maximum allowed size (maxSize)
+         * and updates accept/reject lists accordingly.
+         *
+         * @param acceptedFiles - Files that have passed previous validation steps
+         * @returns Object containing validated files and size-related rejections
+         * @remarks
+         * - Files exceeding maxSize are identified and grouped with a 'file-too-large' error
+         * - Handles two validation modes:
+         *   1. Strict validation (strictValidation: true):
+         *      If ANY file exceeds the size limit, ALL files are rejected
+         *   2. Partial upload (strictValidation: false):
+         *      Only oversized files are rejected, others proceed normally
+         * - When maxSize is undefined, all files pass size validation
+         * - Adds appropriate error metadata to rejected files for UI feedback
+         * - The returned object has separate lists for valid files and size rejections
+         */
+        handleFileSizeValidation: (acceptedFiles: File[]) => {
+            let validFiles = [...acceptedFiles];
+            let sizeRejections: FileRejection[] = [];
+
+            // Check for oversized files
+            const oversizedFiles = acceptedFiles.filter((file) => maxSize && file.size > maxSize);
+
+            if (oversizedFiles.length > 0) {
+                const errorCode = 'file-too-large';
+                const errorMessage = getValidationMessage({
+                    code: errorCode,
+                    count: oversizedFiles.length,
+                    messageType: 'drop',
+                });
+
+                const fileSizeError: FileError = {
+                    code: errorCode,
+                    message: errorMessage,
+                };
+
+                // Add to rejections
+                sizeRejections = oversizedFiles.map((file) => ({
+                    errors: [fileSizeError],
+                    file,
+                }));
+
+                if (!strictValidation) {
+                    // In partial upload mode, filter out oversized files
+                    validFiles = acceptedFiles.filter((file) => !maxSize || file.size <= maxSize);
+                } else {
+                    // In strict mode, reject all files if any are oversized
+                    validFiles = [];
+                }
+            }
+
+            return { sizeRejections, validFiles };
+        },
+
+        /**
+         * Processes file rejections and groups them by error code
+         *
+         * This function takes an array of file rejections and organizes them into
+         * error groups based on the error codes. Each group tracks a count of affected
+         * files and the file references.
+         *
+         * @param rejections - Array of file rejections to process
+         * @returns A record of error groups indexed by error code
+         * @remarks
+         * - Multiple files with the same error code are consolidated into a single group
+         * - A file can appear in multiple groups if it has multiple error codes
+         * - Each group tracks:
+         *   - count: Number of files affected by this error
+         *   - files: References to the affected files
+         *   - message: The error message (shared across the group)
+         * - Used for generating consolidated error messages and UI summaries
+         */
+        processRejections: (rejections: FileRejection[]): Record<string, ErrorGroup> => {
+            const groups: Record<string, ErrorGroup> = {};
+            rejections.forEach((rejection) => {
+                rejection.errors.forEach((error) => {
+                    const group = getOrCreateErrorGroup(groups, error.code, error.message);
+                    group.count++;
+                    group.files.push(rejection.file);
+                });
+            });
+
+            return groups;
+        },
+    };
+};

package/src/FileUpload/hooks/upload/useHandleDrop/useHandleDrop.ts

@@ -0,0 +1,153 @@
+import { useCallback } from 'react';
+
+import { UploadValidationContextType } from '../../../providers/UploadValidationProvider';
+import { FileRejection, FileResource } from '../../../types/commonTypes';
+import { createRejectionHelpers } from './createFileRejectionHelpers';
+
+/**
+ * Hook that handles file validation and processing when files are dropped
+ * @param props Object containing:
+ *   - files: Currently selected files in the uploader
+ *   - onDrop: Optional callback triggered for both accepted and rejected files
+ *   - onDropAccepted: Optional callback triggered only for accepted files
+ *   - onDropRejected: Optional callback triggered only for rejected files
+ *   - setFiles: Function to update the files state with newly accepted files
+ *   - validation: Validation context (from either provider or local validation)
+ * @returns Callback function for handling file drop events from react-dropzone
+ * @remarks
+ * - Performs validation in a specific sequence: file types → file sizes → file count
+ * - Groups and formats error messages for consistent UI display
+ * - Handles strict vs. partial validation modes differently:
+ *   - Strict: Rejects all files if any would be invalid
+ *   - Partial: Accepts valid files while rejecting invalid ones
+ * - Updates file state only for valid files
+ * - Clears validation state on completely successful drops
+ * - Calls appropriate callbacks with processed files
+ * - Sets validation errors in the validation context for UI display
+ */
+
+export type UseHandleDropProps = {
+    /** Current files in the upload area */
+    files: FileResource[];
+    /** Callback when files are dropped */
+    onDrop?: (acceptedFiles: File[], rejectedFiles: FileRejection[]) => void;
+    /** Callback when files are accepted */
+    onDropAccepted?: (acceptedFiles: File[]) => void;
+    /** Callback when files are rejected */
+    onDropRejected?: (rejectedFiles: FileRejection[]) => void;
+    /** Function to update the files state */
+    setFiles: (files: FileResource[]) => void;
+    /** Validation context */
+    validation: UploadValidationContextType;
+};
+
+export const useHandleDrop = ({
+    files,
+    onDrop,
+    onDropAccepted,
+    onDropRejected,
+    setFiles,
+    validation,
+}: UseHandleDropProps) => {
+    const { clearAllValidation, setDropValidationErrors, setFileRejections, strictValidation } = validation;
+
+    return useCallback(
+        (acceptedFiles: File[], rejectedFiles: FileRejection[]) => {
+            const {
+                getFormattedErrorGroupMessage,
+                handleFileCountLimits,
+                handleFileSizeValidation,
+                processRejections,
+            } = createRejectionHelpers(validation);
+
+            // Step 1: Validate file sizes
+            // Note: acceptedFiles have already passed type validation by react-dropzone
+            const { sizeRejections, validFiles } = handleFileSizeValidation(acceptedFiles);
+
+            // Filter out only File objects from current files for validation
+            // This is needed because FileResource can include RemoteFile objects
+            const currentFileObjects = files.filter((file): file is File => file instanceof File);
+
+            // Step 2: Handle file count limits with all validated files
+            // This combines all rejections from previous validation steps, including custom validator errors
+            const { allAcceptedFiles, allRejections } = handleFileCountLimits(currentFileObjects, validFiles, [
+                ...rejectedFiles, // Already includes custom validation errors
+                ...sizeRejections,
+            ]);
+
+            // Step 3: Process all rejections and group by error code
+            // This creates a dictionary of error groups for better UI presentation
+            // Message functions are preserved at this stage for proper grouping
+            const errorGroups = processRejections(allRejections);
+
+            // Step 4: Extract errors for UI display, now resolving messages with proper context
+            // We need one error message per error type for the UI
+            const errors = Object.entries(errorGroups).map(([code]) => ({
+                code,
+                message: getFormattedErrorGroupMessage(code, { code, message: errorGroups[code].message }, errorGroups),
+            }));
+
+            // Step 5: Format rejections for callbacks - maintain file-to-errors relationship
+            // These preserve the connection between each file and its specific rejection reasons
+            const processedRejections = allRejections.map((rejection) => ({
+                errors: rejection.errors.map((error) => ({
+                    code: error.code,
+                    message: getFormattedErrorGroupMessage(error.code, error, errorGroups),
+                })),
+                file: rejection.file,
+            }));
+
+            const hasRejections = processedRejections.length > 0;
+
+            // Step 6: Handle strict validation - reject all files if there are any rejections
+            if (strictValidation && hasRejections) {
+                // In strict mode, even valid files are rejected if any file has issues
+                const strictRejections = [
+                    ...processedRejections,
+                    ...allAcceptedFiles.map((file) => ({
+                        errors,
+                        file,
+                    })),
+                ];
+
+                setFileRejections(strictRejections);
+                setDropValidationErrors(errors);
+                onDropRejected?.(strictRejections);
+                onDrop?.([], strictRejections);
+                return;
+            }
+
+            // Step 7: Handle partial upload mode (OR no rejections)
+            setFileRejections(processedRejections);
+            setDropValidationErrors(errors);
+            onDropRejected?.(processedRejections);
+
+            // Step 8: Handle successful file uploads
+            if (allAcceptedFiles.length > 0) {
+                if (!hasRejections) {
+                    // Clear validation only if there are no rejections
+                    clearAllValidation();
+                }
+                // Update file state with new files (as FileResource[])
+                const newFileResources: FileResource[] = [...files, ...allAcceptedFiles];
+                setFiles(newFileResources);
+                onDropAccepted?.(allAcceptedFiles);
+            }
+
+            // Always call onDrop with both sets of files
+            onDrop?.(allAcceptedFiles, processedRejections);
+        },
+        [
+            files,
+            clearAllValidation,
+            setDropValidationErrors,
+            setFiles,
+            onDrop,
+            onDropAccepted,
+            onDropRejected,
+            setFileRejections,
+            strictValidation,
+            validation,
+        ]
+    );
+};

package/src/FileUpload/hooks/upload/useUploadAvailability/useUploadAvailability.ts

@@ -0,0 +1,44 @@
+import { FileResource } from '../../../types/commonTypes';
+
+/**
+ * Hook that determines if file uploads are currently available/disabled
+ * @param props Object containing:
+ *   - disabled: Optional flag to manually disable uploads
+ *   - files: Currently selected files
+ *   - maxFiles: Optional maximum number of files allowed
+ * @returns Object containing:
+ *   - hasReachedFileLimit: Whether max file count has been reached
+ *   - isDisabled: Whether uploads are currently disabled
+ * @remarks
+ * - Combines both manual disable state and file limit restrictions
+ * - Used to prevent uploads when either condition is met
+ */
+export type UploadAvailabilityParams = {
+    /** Whether the upload is disabled */
+    disabled?: boolean;
+    /** Current files in the upload area */
+    files: FileResource[];
+    /** Maximum number of files allowed */
+    maxFiles?: number;
+};
+
+type UploadAvailability = {
+    hasReachedFileLimit: boolean;
+    isDisabled: boolean;
+};
+
+export const useUploadAvailability = ({
+    disabled = false,
+    files,
+    maxFiles,
+}: UploadAvailabilityParams): UploadAvailability => {
+    // Calculate if we've reached the file limit
+    const hasReachedFileLimit = maxFiles !== undefined && files.length >= maxFiles;
+    // Consider both local and provider disabled states
+    const isDisabled = disabled || hasReachedFileLimit;
+
+    return {
+        hasReachedFileLimit,
+        isDisabled,
+    };
+};

package/src/FileUpload/hooks/validation/createDropzoneValidator.ts

@@ -0,0 +1,41 @@
+import { UploadValidationContextType } from '../../providers/UploadValidationProvider';
+
+/**
+ * Creates an optimized validator function for React-Dropzone that preserves
+ * function-based validation messages for later resolution
+ *
+ * @param validationContext - The validation context containing the custom validator
+ * @returns A validator function compatible with React-Dropzone
+ */
+export const createDropzoneValidator = (validationContext: UploadValidationContextType) => {
+    // Extract the custom validator function
+    const { validateCustomRules } = validationContext;
+
+    // Return undefined if no custom validator exists
+    if (typeof validateCustomRules !== 'function') {
+        return undefined;
+    }
+
+    // Return the actual validator function
+    return (file: File) => {
+        // Run the custom validator
+        const validationResult = validateCustomRules(file);
+
+        // If no errors, return null (valid)
+        if (!validationResult) {
+            return null;
+        }
+
+        // If no errors in array, return null
+        if (validationResult.length === 0) {
+            return null;
+        }
+
+        // Return errors with message functions preserved
+        // This allows for proper error grouping before message resolution
+        return validationResult.map((error) => ({
+            code: error.code,
+            message: error.message,
+        }));
+    };
+};

package/src/FileUpload/hooks/validation/useFileValidation.ts

@@ -0,0 +1,25 @@
+import { useContext } from 'react';
+
+import { UploadValidationContext, UploadValidationContextType } from '../../providers/UploadValidationProvider';
+import { ValidationConfig } from '../../types/commonTypes';
+import { useFileValidationLogic } from './useFileValidationLogic';
+
+/**
+ * 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
+ */
+export const useFileValidation = (config?: ValidationConfig): UploadValidationContextType => {
+    const validationContext = useContext<UploadValidationContextType | undefined>(UploadValidationContext);
+
+    // Create local validation logic
+    const localValidation = useFileValidationLogic(config);
+
+    // Return the context if it exists, otherwise use local validation
+    return validationContext ?? localValidation;
+};

package/src/FileUpload/hooks/validation/useFileValidationLogic.ts

@@ -0,0 +1,107 @@
+import { useCallback } from 'react';
+
+import { ValidationConfig } from '../../types/commonTypes';
+import { useValidationMessages } from './useValidationMessages';
+import { useValidationState } from './useValidationState';
+
+/**
+ * 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
+ */
+export const useFileValidationLogic = (config?: ValidationConfig) => {
+    const { accept, error, maxFiles, maxSize, strictValidation, validator } = config ?? {};
+
+    // Get message formatting and validation message utilities
+    const { formattedMaxSize, getValidationMessage } = useValidationMessages({
+        ...config,
+        accept,
+    });
+
+    // Initialize validation state, optionally with custom error
+    const validationState = useValidationState(error, getValidationMessage);
+
+    // Validation methods
+    // Check if a file type is allowed given mimeTypes mapping
+    const validateFileType = useCallback((fileType: string, mimeTypes?: Record<string, string[]>) => {
+        if (!mimeTypes) {
+            return true;
+        }
+        return Object.keys(mimeTypes).includes(fileType);
+    }, []);
+
+    // Check if file size is within configured limit
+    const validateFileSize = useCallback(
+        (fileSize: number) => {
+            if (!maxSize) {
+                return true;
+            }
+            return fileSize <= maxSize;
+        },
+        [maxSize]
+    );
+
+    // Check if adding files would exceed maximum count
+    const validateFileCount = useCallback(
+        (currentCount: number, newCount: number) => {
+            if (!maxFiles) {
+                return true;
+            }
+            return currentCount + newCount <= maxFiles;
+        },
+        [maxFiles]
+    );
+
+    // Run custom validator function if provided
+    const validateCustomRules = useCallback(
+        (file: File | DataTransferItem) => {
+            if (!validator) {
+                return null;
+            }
+            const validationResult = validator(file);
+
+            // If validation result is null or empty array, return null
+            if (!validationResult || validationResult.length === 0) {
+                return null;
+            }
+
+            // Return the array of errors
+            return validationResult;
+        },
+        [validator]
+    );
+
+    return {
+        ...validationState,
+        formattedMaxSize,
+        getValidationMessage,
+        maxFiles,
+        maxSize,
+        strictValidation,
+        validateCustomRules,
+        validateFileCount,
+        validateFileSize,
+        validateFileType,
+    };
+};