@evolve.ui/core-components 1.0.1 → 1.1.0

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

@@ -0,0 +1,92 @@
+import { useCallback } from 'react';
+
+import { formatFileSize } from '../../../utils/formatFileSize';
+import { CommonFileTypes, ValidationMessageParams } from '../../types/commonTypes';
+import { DRAG_MESSAGES, DROP_MESSAGES } from '../../utils/constants';
+import { createMessageContext } from '../../utils/createMessageContext';
+import { resolveContextAwareMessage } from '../../utils/messageUtils';
+
+const getMessageSet = (
+    messages: typeof DRAG_MESSAGES | typeof DROP_MESSAGES,
+    isSingleFileUpload: boolean,
+    strictValidation?: boolean
+) => {
+    // Determine which message set to use
+    if (isSingleFileUpload) {
+        return messages.singleFileUpload;
+    }
+
+    if (strictValidation) {
+        return messages.strictUpload;
+    }
+
+    return messages.partialUpload;
+};
+
+type UseValidationMessagesProps = {
+    /** Optional array of accepted file types */
+    accept?: CommonFileTypes | string[];
+    /** Maximum allowed file size in bytes (Unrestricted by default) */
+    maxFiles?: number;
+    /** Maximum number of files (1 for single file, undefined for unlimited) */
+    maxSize?: number;
+    /** Whether to use strict validation */
+    strictValidation?: boolean;
+};
+
+/**
+ * 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
+ */
+export const useValidationMessages = ({ accept, maxFiles, maxSize, strictValidation }: UseValidationMessagesProps) => {
+    const formattedMaxSize = maxSize ? formatFileSize(maxSize) : undefined;
+    const isSingleFileUpload = maxFiles === 1;
+
+    const getValidationMessage = useCallback(
+        ({ code, count = 1, message: customMessage, messageType = 'drop' }: ValidationMessageParams): string => {
+            const messages = messageType === 'drag' ? DRAG_MESSAGES : DROP_MESSAGES;
+
+            // Create the appropriate context based on message type
+            const messageContext = createMessageContext({
+                accept,
+                code,
+                count,
+                formattedMaxSize,
+                maxFiles,
+                maxSize,
+                messageType,
+            });
+
+            // If we have a custom message, use it
+            if (customMessage) {
+                return resolveContextAwareMessage(customMessage, messageContext);
+            }
+
+            // Otherwise use built-in messages
+            const messageSet = getMessageSet(messages, isSingleFileUpload, strictValidation);
+            // @ts-expect-error - we know the code exists in messageSet
+            const message = messageSet[code];
+
+            // Use the message or fall back to default
+            return resolveContextAwareMessage(message, messageContext, messages.default);
+        },
+        [formattedMaxSize, isSingleFileUpload, maxFiles, accept, strictValidation, maxSize]
+    );
+
+    return {
+        formattedMaxSize,
+        getValidationMessage,
+    };
+};

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

@@ -0,0 +1,171 @@
+import { useCallback, useEffect, useState } from 'react';
+
+import { FileError, FileErrorCode, FileRejection } from '../../types';
+
+/**
+ * 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
+ */
+export const useValidationState = (
+    initialError?: FileError,
+    getValidationMessage?: (params: { code: FileErrorCode; count?: number; messageType: 'drag' | 'drop' }) => string
+) => {
+    // Single error for drag (since we show one at a time during drag)
+    const [dragValidationError, setDragValidationErrorState] = useState<FileError | null>(null);
+
+    // Array of errors for drop (since multiple files can have different errors)
+    const [dropValidationErrors, setDropValidationErrorsState] = useState<FileError[]>(
+        initialError ? [initialError] : []
+    );
+
+    const [fileRejections, setFileRejections] = useState<FileRejection[]>([]);
+
+    const clearDragValidation = useCallback(() => {
+        setDragValidationErrorState(null);
+    }, []);
+
+    const clearDropValidation = useCallback(() => {
+        setDropValidationErrorsState([]);
+    }, []);
+
+    const clearAllValidation = useCallback(() => {
+        clearDragValidation();
+        clearDropValidation();
+        setFileRejections([]);
+    }, [clearDragValidation, clearDropValidation]);
+
+    // Enhanced setters that handle message processing
+    const setDragValidationError = useCallback(
+        (errorOrCode: FileError | FileErrorCode | null, count?: number) => {
+            if (errorOrCode === null) {
+                setDragValidationErrorState(null);
+                return;
+            }
+
+            // If we're given just a code, get the message from getValidationMessage
+            if (typeof errorOrCode === 'string') {
+                if (getValidationMessage) {
+                    const message = getValidationMessage({
+                        code: errorOrCode,
+                        count,
+                        messageType: 'drag',
+                    });
+                    setDragValidationErrorState({
+                        code: errorOrCode,
+                        message,
+                    });
+                } else {
+                    // Fallback if getValidationMessage is not provided
+                    setDragValidationErrorState({
+                        code: errorOrCode,
+                        message: `Error: ${errorOrCode}`,
+                    });
+                }
+            } else {
+                // If we're given a complete error object, use it directly
+                setDragValidationErrorState(errorOrCode);
+            }
+        },
+        [getValidationMessage]
+    );
+
+    const setDropValidationErrors = useCallback(
+        (errorsOrCodes: Array<FileError | FileErrorCode> | FileError | FileErrorCode, count?: number) => {
+            // Handle single error/code case
+            if (!Array.isArray(errorsOrCodes)) {
+                const errorOrCode = errorsOrCodes;
+
+                // If we're given just a code, get the message from getValidationMessage
+                if (typeof errorOrCode === 'string') {
+                    if (getValidationMessage) {
+                        const message = getValidationMessage({
+                            code: errorOrCode,
+                            count,
+                            messageType: 'drop',
+                        });
+                        setDropValidationErrorsState([
+                            {
+                                code: errorOrCode,
+                                message,
+                            },
+                        ]);
+                    } else {
+                        // Fallback if getValidationMessage is not provided
+                        setDropValidationErrorsState([
+                            {
+                                code: errorOrCode,
+                                message: `Error: ${errorOrCode}`,
+                            },
+                        ]);
+                    }
+                } else {
+                    // If we're given a complete error object, use it directly
+                    setDropValidationErrorsState([errorOrCode]);
+                }
+                return;
+            }
+
+            // Handle array case
+            const processedErrors = errorsOrCodes.map((errorOrCode) => {
+                // If we're given just a code, get the message from getValidationMessage
+                if (typeof errorOrCode === 'string') {
+                    if (getValidationMessage) {
+                        const message = getValidationMessage({
+                            code: errorOrCode,
+                            count,
+                            messageType: 'drop',
+                        });
+                        return {
+                            code: errorOrCode,
+                            message,
+                        };
+                    }
+                    // Fallback if getValidationMessage is not provided
+                    return {
+                        code: errorOrCode,
+                        message: `Error: ${errorOrCode}`,
+                    };
+                }
+                // If we're given a complete error object, use it directly
+                return errorOrCode;
+            });
+
+            setDropValidationErrorsState(processedErrors);
+        },
+        [getValidationMessage]
+    );
+
+    // Effect to synchronize drop errors if the initialError prop changes post-mount.
+    // Uses the raw state setter and only depends on initialError to avoid performance issues.
+    useEffect(() => {
+        setDropValidationErrorsState(initialError ? [initialError] : []);
+    }, [initialError]);
+
+    return {
+        clearAllValidation,
+        clearDragValidation,
+        clearDropValidation,
+        dragValidationError,
+        dropValidationErrors,
+        fileRejections,
+        setDragValidationError,
+        setDropValidationErrors,
+        setFileRejections,
+    };
+};

package/src/FileUpload/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @package @evolve.ui/core-components/fileUpload
+ * File upload system with drag-and-drop support, previews, and validation
+ *
+ * @module
+ * Components:
+ * - FileUpload: Complete file upload solution with dropzone and preview list
+ * - FileDropzone: Drag-and-drop upload zone with validation feedback
+ * - FilePreviewList: Grid or list display of uploaded files with previews
+ * - FileCard: Versatile file representation that adapts between grid and list design formats
+ * - ListFileCard: A visual representation of a file in a list card design
+ * - GridFileCard: A visual representation of a file in a grid card design
+ *
+ * Providers:
+ * - FileUploadProvider: Manages file state and upload callbacks, with context for shared validation
+ * - UploadValidationProvider: Handles shared validation logic
+ *
+ * Hooks:
+ * - useFileValidation: File validation (optional UploadValidationProvider integration)
+ *
+ */
+
+// Hooks
+export { useFileValidation } from './hooks';
+
+// Components
+export { FileUpload } from './components/FileUpload/FileUpload';
+export { FileDropzoneOverlay } from './components/FileDropzoneOverlay/FileDropzoneOverlay';
+export { FileUploadCanvas } from './components/FileUploadCanvas/FileUploadCanvas';
+export { FileDropzone } from './components/FileDropzone/FileDropzone';
+export { FilePreviewList } from './components/FilePreviewList/FilePreviewList';
+export { FileCard } from './components/FileCard/FileCard';
+export { ListFileCard } from './components/ListFileCard/ListFileCard';
+export { GridFileCard } from './components/GridFileCard/GridFileCard';
+
+// Providers
+export { useValidationContext, UploadValidationProvider } from './providers/UploadValidationProvider';
+export { useFileUploadContext, FileUploadProvider } from './providers/FileUploadProvider';
+
+// Contexts
+export { FileUploadContext } from './providers/FileUploadProvider';
+export { UploadValidationContext } from './providers/UploadValidationProvider';
+
+// Utils
+export { getFileExtensionsFromAcceptedTypes } from './utils/getFileExtensionsFromAcceptedTypes';
+export { getFilePluralizationText } from './utils/getFilePluralizationText';
+
+// Types
+export type { OverlayStyleOptions } from './types/sharedTypes';
+export type { ValidationError } from './types';
+export type {
+    FileCardAction,
+    FileProgressCircleConfig,
+    FileStatusConfig,
+    FileStatusIcon,
+    FileStatusIconConfig,
+} from './components/types';

package/src/FileUpload/providers/FileUploadProvider.tsx

@@ -0,0 +1,219 @@
+import { createContext, useContext, useState } from 'react';
+
+import { FileResource } from '../types';
+import { CommonFileTypes, FileError, FileRejection, FileValidator } from '../types/commonTypes';
+import { UploadValidationProvider } from './UploadValidationProvider';
+
+/**
+ * Context type for the FileUploadProvider
+ * Contains both file state management and callback handlers for file operations.
+ * This context makes file upload state and operations available to all child components.
+ *
+ * @property disabled - Whether the file upload functionality is disabled
+ * @property files - Array of currently selected/uploaded files
+ * @property onDrop - Callback triggered when files are dropped, with both accepted and rejected files
+ * @property onDropAccepted - Callback triggered when files pass validation
+ * @property onDropRejected - Callback triggered when files fail validation
+ * @property onFileDelete - Callback triggered when a file is deleted from the preview
+ * @property setFiles - State setter function to update the files array
+ */
+export type FileUploadContextType = {
+    disabled: boolean;
+    files: FileResource[];
+    onDrop?: (acceptedFiles: File[], rejectedFiles: FileRejection[]) => void;
+    onDropAccepted?: (files: File[]) => void;
+    onDropRejected?: (rejectedFiles: FileRejection[]) => void;
+    onFileDelete?: (fileResource: FileResource) => void;
+    setFiles: (files: FileResource[] | ((prev: FileResource[]) => FileResource[])) => void;
+};
+
+/**
+ * React context for file upload state and operations
+ * Used by the useFileUploadContext hook
+ */
+export const FileUploadContext = createContext<FileUploadContextType | undefined>(undefined);
+
+/**
+ * Configuration props for the FileUploadProvider
+ * These props control both file upload behavior and validation rules.
+ * Many of these properties are passed to the underlying ValidationProvider.
+ */
+export type FileUploadProviderConfigProps = {
+    /**
+     * Allowed file types - either preset categories ('images', 'pdfs', 'documents')
+     * or an array of MIME types/extensions (e.g., ['image/jpeg', '.png'])
+     */
+    accept?: CommonFileTypes | string[];
+
+    /**
+     * Whether the upload is disabled
+     * When true, prevents any interaction with the upload components
+     */
+    disabled?: boolean;
+
+    /**
+     * Error object to display custom validation errors
+     * Overrides any validation errors with this custom error
+     */
+    error?: FileError;
+
+    /**
+     * Initial files to populate the uploader with
+     * These files will be present when the component first mounts
+     */
+    initialFiles?: FileResource[];
+
+    /**
+     * Maximum number of files allowed
+     * Set to 1 for single file upload, undefined for unlimited
+     */
+    maxFiles?: number;
+
+    /**
+     * Maximum allowed file size in bytes
+     * Example: 5 * 1024 * 1024 for 5MB
+     */
+    maxSize?: number;
+
+    /**
+     * Callback when files are dropped (regardless of validation result)
+     * Provides both accepted and rejected files for handling
+     */
+    onDrop?: (acceptedFiles: File[], rejectedFiles: FileRejection[]) => void;
+
+    /**
+     * Callback when files pass validation and are accepted
+     * Useful for immediately processing valid files
+     */
+    onDropAccepted?: (files: File[]) => void;
+
+    /**
+     * Callback when files fail validation
+     * Provides detailed rejection reasons for each file
+     */
+    onDropRejected?: (rejectedFiles: FileRejection[]) => void;
+
+    /**
+     * Callback when user clicks delete button on a file preview
+     * Used to remove files from state or external storage
+     */
+    onFileDelete?: (fileResource: FileResource) => void;
+
+    /**
+     * When true, if any file fails validation, all files are rejected
+     * When false (default), valid files are accepted even if others are rejected
+     */
+    strictValidation?: boolean;
+
+    /**
+     * Custom validator function for additional validation rules
+     * Allows you to implement validation beyond the built-in type/size checks
+     */
+    validator?: FileValidator;
+};
+
+/**
+ * Props for the FileUploadProvider component
+ * Extends the config props with React children
+ */
+type FileUploadProviderProps = FileUploadProviderConfigProps & {
+    /** React children */
+    children: React.ReactNode;
+};
+
+/**
+ * Provider component for file upload functionality
+ *
+ * This provider manages both file state and validation rules:
+ * 1. Maintains file state (selected/uploaded files)
+ * 2. Provides context for drag/drop operations and file management
+ * 3. Wraps children with validation context for enforcing file rules
+ *
+ * While FileDropzone and FilePreviewList can function as standalone components,
+ * using this provider offers coordinated state management when using multiple
+ * file upload components together.
+ *
+ * @example
+ * ```tsx
+ * <FileUploadProvider
+ *   accept="images"
+ *   maxFiles={5}
+ *   maxSize={2 * 1024 * 1024}
+ *   onDropAccepted={(files) => console.log('Accepted:', files)}
+ * >
+ *   <FileDropzone />
+ *   <FilePreviewList />
+ * </FileUploadProvider>
+ * ```
+ */
+export const FileUploadProvider = ({
+    accept,
+    children,
+    disabled = false,
+    error,
+    initialFiles = [],
+    maxFiles,
+    maxSize,
+    onDrop,
+    onDropAccepted,
+    onDropRejected,
+    onFileDelete,
+    strictValidation,
+    validator,
+}: FileUploadProviderProps) => {
+    const [files, setFiles] = useState<FileResource[]>(initialFiles);
+
+    const value = {
+        accept,
+        disabled,
+        files,
+        onDrop,
+        onDropAccepted,
+        onDropRejected,
+        onFileDelete,
+        setFiles,
+    };
+
+    return (
+        <UploadValidationProvider
+            accept={accept}
+            error={error}
+            maxFiles={maxFiles}
+            maxSize={maxSize}
+            strictValidation={strictValidation}
+            validator={validator}
+        >
+            <FileUploadContext.Provider value={value}>{children}</FileUploadContext.Provider>
+        </UploadValidationProvider>
+    );
+};
+
+FileUploadProvider.displayName = 'FileUploadProvider';
+
+/**
+ * Hook to access the file upload context
+ *
+ * Provides access to the current files array and operations for
+ * managing file uploads within the FileUploadProvider.
+ *
+ * @throws Error if used outside of a FileUploadProvider
+ * @returns The FileUploadContextType object with files array and handlers
+ *
+ * @example
+ * ```tsx
+ * const { files, setFiles, onFileDelete } = useFileUploadContext();
+ *
+ * // Remove a file
+ * const handleDelete = (fileToDelete) => {
+ *   onFileDelete?.(fileToDelete);
+ *   setFiles(files.filter(file => file.name !== fileToDelete.name));
+ * };
+ * ```
+ */
+export const useFileUploadContext = () => {
+    const context = useContext<FileUploadContextType | undefined>(FileUploadContext);
+    if (!context) {
+        throw new Error('useFileUploadContext must be used within FileUploadProvider');
+    }
+    return context;
+};

package/src/FileUpload/providers/UploadValidationProvider.tsx

@@ -0,0 +1,159 @@
+import { createContext, useContext, useMemo, useState } from 'react';
+
+import { useFileValidationLogic } from '../hooks/validation/useFileValidationLogic';
+import {
+    CommonFileTypes,
+    FileError,
+    FileRejection,
+    FileValidator,
+    ValidationMessageParams,
+} from '../types/commonTypes';
+
+/**
+ * Provider component that shares file validation logic and state across components
+ * @param props Object containing:
+ *   - accept: Optional file type restrictions (MIME types or preset categories)
+ *   - children: React child components
+ *   - error: Optional custom validation error object
+ *   - maxFiles: Optional maximum number of files allowed (1 for single file, undefined for unlimited)
+ *   - maxSize: Optional maximum file size in bytes
+ *   - strictValidation: Optional boolean to enable strict validation
+ *   - validator: Optional custom validation function
+ * @returns Provider component with shared validation context
+ * @remarks
+ * - Components can access validation through useValidationContext hook
+ * - If no provider is present, components will fall back to local validation logic
+ * - Validation state is shared between drag and drop operations
+ * - Errors must be explicitly set using the provided setter methods (setDragValidationError, setDropValidationErrors)
+ */
+
+export type UploadValidationContextType = {
+    /** Accepted file types - either preset categories or an array of MIME types */
+    accept?: CommonFileTypes | string[];
+    /** Clears all validation errors (both drag and drop errors) */
+    clearAllValidation: () => void;
+    /** Clears drag-related validation errors */
+    clearDragValidation: () => void;
+    /** Clears drop-related validation errors */
+    clearDropValidation: () => void;
+    /** Current drag validation error or null if none */
+    dragValidationError: FileError | null;
+    /** Array of drop validation errors */
+    dropValidationErrors: FileError[];
+    /** Files that failed validation with their rejection reasons */
+    fileRejections: FileRejection[];
+    /** Human-readable maximum file size (e.g., "5 MB") */
+    formattedMaxSize: string | undefined;
+    /** Generates context-aware validation messages */
+    getValidationMessage: (params: ValidationMessageParams) => string;
+    /** Maximum number of files allowed (1 for single file upload) */
+    maxFiles?: number;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Sets the drag validation error */
+    setDragValidationError: (error: FileError | null) => void;
+    /** Sets the drop validation errors array */
+    setDropValidationErrors: (errors: FileError[]) => void;
+    /** Updates the file rejections array */
+    setFileRejections: (rejections: FileRejection[]) => void;
+    /** When true, all files are rejected if any fail validation */
+    strictValidation?: boolean;
+    /** Custom validation function for additional file checks */
+    validateCustomRules: FileValidator;
+    /** Validates if adding new files would exceed the maximum file count */
+    validateFileCount: (currentCount: number, newCount: number) => boolean;
+    /** Checks if a file size is within the allowed limit */
+    validateFileSize: (fileSize: number) => boolean;
+    /** Validates file type against accepted types */
+    validateFileType: (fileType: string, mimeTypes?: Record<string, string[]>) => boolean;
+};
+
+export const UploadValidationContext = createContext<UploadValidationContextType | undefined>(undefined);
+
+export type UploadValidationProviderProps = {
+    /** Optional array of accepted file types */
+    accept?: CommonFileTypes | string[];
+    /** React children */
+    children: React.ReactNode;
+    /** Error object to display custom validation errors */
+    error?: FileError;
+    /** Maximum number of files (1 for single file, undefined for unlimited) */
+    maxFiles?: number;
+    /** Maximum allowed file size in bytes (Unrestricted by default) */
+    maxSize?: number;
+    /** Enable strict validation */
+    strictValidation?: boolean;
+    /** Custom validator function */
+    validator?: FileValidator;
+};
+
+export const UploadValidationProvider = ({
+    accept,
+    children,
+    error,
+    maxFiles,
+    maxSize,
+    strictValidation,
+    validator,
+}: UploadValidationProviderProps) => {
+    const validation = useFileValidationLogic({
+        accept,
+        error,
+        maxFiles,
+        maxSize,
+        strictValidation,
+        validator,
+    });
+
+    const [fileRejections, setFileRejections] = useState<FileRejection[]>([]);
+
+    const value = useMemo(
+        () => ({
+            ...validation,
+            accept,
+            fileRejections,
+            maxFiles,
+            maxSize,
+            setFileRejections,
+            strictValidation,
+        }),
+        [validation, accept, maxFiles, maxSize, strictValidation, fileRejections]
+    );
+
+    return <UploadValidationContext.Provider value={value}>{children}</UploadValidationContext.Provider>;
+};
+
+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'
+ *   });
+ * }
+ * ```
+ */
+export const useValidationContext = () => {
+    const context = useContext<UploadValidationContextType | undefined>(UploadValidationContext);
+    if (!context) {
+        throw new Error('useValidationContext must be used within UploadValidationProvider');
+    }
+    return context;
+};