@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/FileUpload/testUtils/mockFilesAndImages.ts

@@ -0,0 +1,64 @@
+import { RemoteFile } from '../types';
+import { createMixedFilesAndImageUrls, createMockFiles, createMockRemoteFileImages } from './testUtils';
+
+//Basic document (.pdf) file
+export const mockPdfFile = new File(['test content'], 'sample-document.pdf', { type: 'application/pdf' });
+
+//Image URLs - Images from the contrast test to test darker images with card overlays
+export const mockDarkBlueImageUrl: RemoteFile = {
+    name: '(dark)-deep-blue.jpg',
+    type: 'image/jpeg',
+    url: '/contrast-test-images/(dark)-deep-blue.jpg',
+};
+
+export const mockColorfulImageUrl: RemoteFile = {
+    name: '(colorful)-flowers.jpg',
+    type: 'image/jpeg',
+    url: '/contrast-test-images/(colorful)-flowers.jpg',
+};
+
+export const mockNeutralImageUrl: RemoteFile = {
+    name: '(neutral)-train-on-bridge.jpg',
+    type: 'image/jpeg',
+    url: '/contrast-test-images/(neutral)-train-on-bridge.jpg',
+};
+
+export const mockFordMotorImageUrl: RemoteFile = {
+    name: 'ford-motor.webp',
+    type: 'image/webp',
+    url: '/contrast-test-images/ford-motor.webp',
+};
+
+// Non-image files
+export const mockNonImageFiles = [
+    new File(['test content'], 'document1.pdf', { type: 'application/pdf' }),
+    new File(['test content'], 'document2.pdf', { type: 'application/pdf' }),
+    new File(['test content'], 'document3.pdf', { type: 'application/pdf' }),
+    new File(['test content'], 'document4.pdf', { type: 'application/pdf' }),
+    new File(['test content'], 'spreadsheet.xlsx', {
+        type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    }),
+    new File(['test content'], 'maliciousVirus.txt', { type: 'text/plain' }),
+    new File(['test content'], 'embarrassingBlackmailInfo.pdf', { type: 'application/pdf' }),
+    new File(['test content'], 'SuperSafeWebsite.html', { type: 'text/html' }),
+];
+
+//Files and image URLs
+export const mockFilesAndImageUrls = [
+    new File(['test content'], 'tax-return.pdf', { type: 'application/pdf' }),
+    mockDarkBlueImageUrl,
+    mockColorfulImageUrl,
+    new File(['test content'], 'sample-invoice.pdf', { type: 'application/pdf' }),
+    mockNeutralImageUrl,
+    mockFordMotorImageUrl,
+];
+
+// Create mock data with the helper functions
+export const mock10Files = createMockFiles(10);
+export const mock500Files = createMockFiles(500);
+
+export const mock10ImageUrls = createMockRemoteFileImages(10);
+export const mock500ImageUrls = createMockRemoteFileImages(500);
+
+export const mock20FilesAndImageUrls = createMixedFilesAndImageUrls(10, 10);
+export const mock1kFilesAndImageUrls = createMixedFilesAndImageUrls(500, 500);

package/src/FileUpload/testUtils/testUtils.ts

@@ -0,0 +1,111 @@
+import { RemoteFile } from '../types';
+
+// Array of all available image files in the card and contrast-test-images directories
+const availableImages = [
+    // Card images
+    '/card/arne_wahl.jpg',
+    '/card/arne_wahl_2.png',
+    '/card/art_deco.jpg',
+    '/card/art_deco_2.png',
+    '/card/donghia.jpg',
+    '/card/donghia_2.png',
+    '/card/maximilian.jpg',
+    '/card/maximilian_2.png',
+    '/card/milo.jpg',
+    '/card/milo_2.png',
+    '/card/modern.png',
+    '/card/modern_2.png',
+    '/card/scalamandre.jpg',
+    '/card/scalamandre_2.png',
+    '/card/scandinavian.jpg',
+    '/card/scandinavian_2.png',
+    '/card/schriever.jpg',
+    '/card/schriever_2.png',
+    '/card/walnut_full.jpg',
+    '/card/walnut_full_2.png',
+    // Contrast test images
+    '/contrast-test-images/(neutral)-train-on-bridge.jpg',
+    '/contrast-test-images/ford-motor.webp',
+    '/contrast-test-images/(colorful)-flowers.jpg',
+    '/contrast-test-images/(dark)-deep-blue.jpg',
+];
+
+// Function to get a random image from the available images
+export const getRandomImage = () => {
+    const randomIndex = Math.floor(Math.random() * availableImages.length);
+    return availableImages[randomIndex];
+};
+
+// Function to create a RemoteFile object from an image URL
+export const createRemoteFileFromUrl = (url: string, index?: number): RemoteFile => {
+    const urlPart = url.split('/').pop();
+    const filename = urlPart && urlPart.length > 0 ? urlPart : `image-${index ?? 0}`;
+    const extension = filename.split('.').pop()?.toLowerCase();
+
+    // Determine MIME type based on extension
+    let type = 'image/jpeg'; // default
+    if (extension === 'png') {
+        type = 'image/png';
+    }
+    if (extension === 'webp') {
+        type = 'image/webp';
+    }
+    if (extension === 'gif') {
+        type = 'image/gif';
+    }
+
+    return {
+        name: filename,
+        type,
+        url,
+    };
+};
+
+export const createTestFile = (name: string, type: string, sizeInBytes = 1024): File => {
+    // Create content with the specified size
+    const content = Array(Math.ceil(sizeInBytes / 10))
+        .fill('test content')
+        .join('');
+
+    // Create the File object with basic properties
+    const file = new File([content], name, {
+        lastModified: Date.now(),
+        type,
+    });
+
+    // Override the size property to match the requested size
+    // This is needed because the actual content might not match exactly
+    Object.defineProperty(file, 'size', { value: sizeInBytes });
+
+    return file;
+};
+
+// Shuffle an array using Fisher-Yates algorithm
+export const shuffleArray = <T>(array: T[]): T[] => {
+    const shuffled = [...array];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+};
+
+// Helper functions to create mock data
+export const createMockFiles = (count: number): File[] => {
+    return Array.from({ length: count }, (_, index) =>
+        createTestFile(`file-${index}.pdf`, 'application/pdf', 1024 * (index + 1))
+    );
+};
+
+export const createMockRemoteFileImages = (count: number): RemoteFile[] => {
+    return Array.from({ length: count }, (_, index) => {
+        const randomUrl = getRandomImage();
+        return createRemoteFileFromUrl(randomUrl, index);
+    });
+};
+
+export const createMixedFilesAndImageUrls = (fileCount: number, imageUrlCount: number) => {
+    const files = createMockFiles(fileCount);
+    const imageUrls = createMockRemoteFileImages(imageUrlCount);
+    return [...files, ...imageUrls];
+};

package/src/FileUpload/types/commonTypes.ts

@@ -0,0 +1,267 @@
+import { type FileRejection as ReactDropzoneFileRejection } from 'react-dropzone';
+
+/**
+ * Possible error codes for file validation failures - these are the codes that are used in the validation messages.
+ * These are the codes used by React-Dropzone under the hood.
+ * @typedef {string} FileErrorCode
+ * @property {'file-invalid-type'} - File type not accepted
+ * @property {'file-too-large'} - File exceeds size limit
+ * @property {'too-many-files'} - Exceeds maximum file count
+ * @property {string} CustomError - Custom error message
+ */
+export type FileErrorCode = 'file-invalid-type' | 'file-too-large' | 'too-many-files' | string;
+
+export type RemoteFile = {
+    id?: string;
+    name: string;
+    type?: string;
+    url: string;
+};
+
+// FileResource is used to represent a file or a remote file
+export type FileResource = File | RemoteFile;
+
+/**
+ * Generic type for messages that can be either a string or a function that returns a string based on context
+ * This allows for dynamic messages that can incorporate data from the current validation context.
+ *
+ * @template T - The context type that will be passed to the message function
+ * @example
+ * // Static message
+ * const staticMessage: ContextAwareMessage<DynamicMessageContext> = "File type not supported";
+ *
+ * // Dynamic message that uses context
+ * const dynamicMessage: ContextAwareMessage<DynamicMessageContext> =
+ *   (context) => `File exceeds the ${context.formattedMaxSize} limit`;
+ */
+export type ContextAwareMessage<T> = string | ((context: T) => string) | undefined;
+
+/**
+ * Base context with common properties used by all message types
+ * Contains the shared information needed to generate validation messages
+ * for both drag and drop events.
+ *
+ * @property acceptedFileExtensions - Comma-separated list of accepted file extensions (e.g., '.jpg, .png')
+ * @property errorCode - The validation error code triggering this message
+ * @property fileCount - Number of files involved in the validation event
+ * @property filePluralizationText - Properly pluralized text for file type (e.g., "image" or "images")
+ * @property formattedMaxSize - Human-readable maximum file size (e.g., "5 MB")
+ * @property maxFiles - Maximum number of files allowed
+ * @property maxFilesPluralizationText - Properly pluralized text for max files (e.g., "file" or "files")
+ * @property maxSizeBytes - Maximum file size in bytes
+ */
+export type BaseDynamicMessageContext = {
+    acceptedFileExtensions?: string;
+    errorCode: string;
+    fileCount?: number;
+    filePluralizationText?: string;
+    formattedMaxSize?: string;
+    maxFiles?: number;
+    maxFilesPluralizationText?: string;
+    maxSizeBytes?: number;
+};
+
+/**
+ * Context for drag events with drag-specific properties
+ * Used to generate validation messages during file drag operations.
+ *
+ * @property draggedItems - The DataTransferItemList containing all items being dragged (not just rejected ones)
+ * @property eventType - Always 'drag' for drag events
+ */
+export type DragMessageContext = BaseDynamicMessageContext & {
+    draggedItems?: DataTransferItemList;
+    eventType: 'drag';
+};
+
+/**
+ * Context for drop events with drop-specific properties
+ * Used to generate validation messages after files have been dropped.
+ *
+ * @property eventType - Always 'drop' for drop events
+ * @property rejectedFileList - Comma-separated list of rejected file names
+ * @property rejectedFiles - Array of File objects that failed validation
+ */
+export type DropMessageContext = BaseDynamicMessageContext & {
+    eventType: 'drop';
+    rejectedFileList?: string;
+    rejectedFiles?: File[];
+};
+
+/**
+ * Guaranteed minimal properties available on all DynamicMessageContext variants.
+ * This type represents the contract for what you can ALWAYS safely destructure
+ * from any message context, regardless of whether it's a drag or drop event.
+ *
+ * Your custom validator message functions receive the full DynamicMessageContext,
+ * but you can safely destructure just these core properties for simple validators.
+ *
+ * @property fileCount - Number of files involved in the validation
+ * @property filePluralizationText - Properly pluralized text (e.g., "file" or "files")
+ *
+ * @example
+ * // Simple validator - only uses guaranteed properties
+ * const validator: FileValidator = (file) => {
+ *   if (invalid) {
+ *     return [{
+ *       code: 'custom-error',
+ *       message: ({ fileCount, filePluralizationText }) =>
+ *         `${fileCount} ${filePluralizationText} failed validation`
+ *     }];
+ *   }
+ *   return null;
+ * };
+ */
+export type ValidationMessageContext = {
+    fileCount: number;
+    filePluralizationText: string;
+};
+
+/**
+ * Context object provided to dynamic message functions in validators.
+ * This is a union of drag and drop contexts, representing what's actually passed at runtime.
+ *
+ * While the full context includes many optional properties (like formattedMaxSize, maxFiles, etc.),
+ * you can always safely destructure the core properties: fileCount and filePluralizationText
+ * (see ValidationMessageContext for the guaranteed minimal subset).
+ *
+ * Use isDragContext or isDropContext type guards to access event-specific properties safely.
+ */
+export type DynamicMessageContext = DragMessageContext | DropMessageContext;
+
+/**
+ * Type guard to check if a context is a drag context
+ * Use this before accessing drag-specific properties
+ *
+ * @param context - The message context to check
+ * @returns true if context is a drag context, false otherwise
+ */
+export const isDragContext = (context: DynamicMessageContext): context is DragMessageContext => {
+    return context.eventType === 'drag';
+};
+
+/**
+ * Type guard to check if a context is a drop context
+ * Use this before accessing drop-specific properties
+ *
+ * @param context - The message context to check
+ * @returns true if context is a drop context, false otherwise
+ */
+export const isDropContext = (context: DynamicMessageContext): context is DropMessageContext => {
+    return context.eventType === 'drop';
+};
+
+/**
+ * Parameters for generating validation messages
+ * Used to create appropriate error messages for different validation scenarios.
+ *
+ * @property code - The error code that triggered the validation failure
+ * @property count - Optional number of files that failed this specific validation
+ * @property message - Optional message string or function that generates a message based on context
+ * @property messageType - Optional string indicating the type of message ('drag' or 'drop')
+ */
+export type ValidationMessageParams = {
+    code: FileErrorCode;
+    count?: number;
+    message?: ContextAwareMessage<DynamicMessageContext>;
+    messageType?: 'drag' | 'drop';
+};
+
+/**
+ * Represents a file validation error that can include dynamic messaging
+ * Used during the validation process before messages are finalized.
+ * This type allows for context-aware messages that can be resolved
+ * at runtime based on the validation context.
+ *
+ * @property code - Error code identifying the type of validation failure
+ * @property message - Human-readable error message or function that generates one
+ * @remarks Used during validation process before messages are finalized
+ */
+export type DynamicFileError = {
+    code: FileErrorCode;
+    message: ContextAwareMessage<DynamicMessageContext>;
+};
+
+/**
+ * Structure for processed validation error responses
+ * The final form of validation errors after message resolution.
+ * Unlike DynamicFileError, FileError messages are always strings,
+ * as they have already been processed with context.
+ *
+ * @property code - Error code identifying the type of validation failure
+ * @property message - Human-readable error message
+ * @remarks Used for displaying validation results after message processing
+ */
+export type FileError = {
+    code: FileErrorCode;
+    message: string;
+};
+
+/**
+ * Union type for validation errors that can be either a FileError or a DynamicFileError
+ * This type allows for flexibility in handling different types of validation errors
+ * and provides a common interface for processing them
+ */
+export type ValidationError = FileError | DynamicFileError;
+
+/**
+ * Represents a file rejection from the upload process
+ * Re-exported from react-dropzone for convenience
+ *
+ * @property file - The rejected file
+ * @property errors - Array of errors associated with the rejected file
+ */
+export type FileRejection = ReactDropzoneFileRejection;
+
+/**
+ * Predefined categories of file types
+ * Used as a convenient shorthand for common file type groups
+ *
+ * @value 'images' - Common image formats (jpeg, png, gif, webp)
+ * @value 'pdfs' - PDF documents only
+ * @value 'documents' - Office and PDF documents (pdf, doc, docx, xls, xlsx)
+ */
+export type CommonFileTypes = 'images' | 'pdfs' | 'documents';
+
+/**
+ * Ensures numbers are greater than 0; used for validation parameters
+ * A type utility that prevents negative numbers or zero from being used
+ * in places where only positive numbers make sense (e.g., file size limits)
+ */
+export type PositiveNumber = number extends infer N
+    ? N extends number
+        ? N extends 0
+            ? never
+            : N extends -1
+              ? never
+              : number
+        : never
+    : never;
+
+/**
+ * Custom validation function for file uploads
+ * Implement this to create custom validation rules beyond the built-in ones
+ *
+ * @param file - File or DataTransferItem to validate
+ * @returns An array of ValidationError objects if validation fails, null if passes
+ */
+export type FileValidator = (file: File | DataTransferItem) => ValidationError[] | null;
+
+/**
+ * Configuration for file validation
+ * Used to set up validation rules and behavior for file uploads
+ *
+ * @property accept - Allowed file types (preset categories or MIME types/extensions)
+ * @property error - Optional custom error to display regardless of validation results
+ * @property maxFiles - Maximum number of files allowed
+ * @property maxSize - Maximum file size in bytes
+ * @property strictValidation - If true, rejects all files when any validation fails
+ * @property validator - Optional custom validation function
+ */
+export type ValidationConfig = {
+    accept?: CommonFileTypes | string[];
+    error?: FileError;
+    maxFiles?: number;
+    maxSize?: number;
+    strictValidation?: boolean;
+    validator?: FileValidator;
+};

package/src/FileUpload/types/index.ts

@@ -0,0 +1,31 @@
+/**
+ * @package @evolve.ui/core-components/fileUpload/types
+ * Core type definitions for file upload functionality
+ *
+ * @typedef {number} PositiveNumber - Type representing numbers greater than 0
+ * @typedef {Function} FileValidator - Custom validation function for file uploads
+ * @typedef {Object} FileError - Structure for file validation error responses
+ * @typedef {Object} DynamicMessageContext - Context object for generating validation messages
+ * @typedef {Object} ValidationMessageContext - Guaranteed minimal properties on all message contexts
+ * @typedef {Object} FileResource - Type representing a file or a remote file
+ *
+ */
+export type {
+    PositiveNumber,
+    FileValidator,
+    FileError,
+    FileErrorCode,
+    FileRejection,
+    DynamicMessageContext,
+    ValidationMessageContext,
+    DynamicFileError,
+    ValidationError,
+    FileResource,
+    RemoteFile,
+} from './commonTypes';
+
+export { isDragContext, isDropContext } from './commonTypes';
+
+// Provider Context Types
+export type { FileUploadContextType } from '../providers/FileUploadProvider';
+export type { UploadValidationContextType } from '../providers/UploadValidationProvider';

package/src/FileUpload/types/sharedTypes.ts

@@ -0,0 +1,159 @@
+/**
+ * This file contains shared type definitions for the file upload system.
+ * It follows a composition pattern where complex component props are built
+ * from smaller, reusable type definitions.
+ */
+import { FilePreviewListProps } from '../components/FilePreviewList/FilePreviewList';
+import { PreviewStyle } from '../components/types';
+import { CommonFileTypes, FileError, FileRejection, FileResource, FileValidator } from './commonTypes';
+
+/**
+ * Core functionality props shared across file upload components.
+ * These handle the main file upload behaviors and callbacks.
+ */
+type CoreUploadProps = {
+    /** Whether to disable early drag validation feedback*/
+    disableDragValidation?: boolean;
+    /** Whether the upload is disabled */
+    disabled?: boolean;
+    /** Error object to display custom validation errors */
+    error?: FileError;
+    /** Whether to hide error messages in the UI */
+    hideErrors?: boolean;
+    /** Maximum number of files (1 for single file, undefined for unlimited) */
+    maxFiles?: number;
+    /** Maximum allowed file size in bytes (Unrestricted by default) */
+    maxSize?: number;
+    /** Callback when files are dropped */
+    onDrop?: (acceptedFiles: File[], rejectedFiles: FileRejection[]) => void;
+    /** Callback when files are accepted */
+    onDropAccepted?: (files: File[]) => void;
+    /** Called when files fail validation with detailed rejection reasons
+     * Use case: Show specific error messages for each rejected file
+     * Example: "file.pdf is too large" or "file.exe is not an allowed type"
+     */
+    onDropRejected?: (rejectedFiles: FileRejection[]) => void;
+    /** Called when user clicks delete button on a file preview
+     * Use case: Remove file from server/state, update UI
+     */
+    onFileDelete?: (fileResource: FileResource) => void;
+    /** Simple callback for file changes - alternative to granular callbacks */
+    onFilesChange?: (files: FileResource[]) => void;
+    /** Whether to show the debugger display - to review file rejections and more*/
+    showDebugger?: boolean;
+    /** Reject all files if any fail validation (strict mode) */
+    strictValidation?: boolean;
+};
+
+/**
+ * UI-specific props shared across file upload components.
+ * These control visual aspects and accessibility features.
+ */
+type UIProps = {
+    /** Custom styling for the file upload component */
+    className?: string;
+    /** Custom data-testid for the file upload component */
+    'data-testid'?: string;
+    /** Custom caption text displayed below the upload input */
+    helpText?: string;
+    /** Aligns the help text to the center, overriding the default left alignment */
+    helpTextAlignCenter?: boolean;
+    /** Whether to hide the help text */
+    hideHelpText?: boolean;
+    /** Custom label to show above the upload input */
+    labelText?: string;
+};
+
+/**
+ * Additional shared props that don't fit into core or UI categories.
+ * These handle file type restrictions and custom validation.
+ */
+type SharedUploadProps = {
+    /** Allowed file types - either preset categories or custom MIME types */
+    accept?: CommonFileTypes | string[];
+    /** Custom aria-label for the upload zone */
+    ariaLabel?: string;
+    /** Custom validator function for file validation - there are default validations for maxFiles and maxSize and accept (mime types) */
+    validator?: FileValidator;
+};
+
+/**
+ * Complete props for the FileDropzone component.
+ * Similar to FileUploadProps but with different component-specific options.
+ */
+export type FileDropzoneProps = CoreUploadProps &
+    UIProps &
+    SharedUploadProps & {
+        /** Array of accepted files - typically comes from external state or context
+         * (often used to display files in the preview list) */
+        files?: FileResource[];
+    };
+
+export type OverlayStyleOptions = {
+    /** Apply backdrop blur effect during drag. Default: false (opt-in for performance) */
+    blurOnDrag?: boolean;
+    /**
+     * Whether the overlay should fill the parent container's height.
+     * When true: Applies h-full to expand to parent height
+     * When false/undefined (default): Applies relative positioning for natural content flow
+     */
+    fillParent?: boolean;
+    /**
+     * Padding around the wrapped children (Tailwind spacing value).
+     * Default: undefined (no additional padding)
+     */
+    innerPadding?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+    /**
+     * Show outline borders (dashed when idle, thick blue when dragging).
+     * Default: true (important for visual feedback and accessibility)
+     */
+    showDashedBorder?: boolean;
+};
+
+export type FileDropzoneOverlayProps = Omit<FileDropzoneProps, 'helpTextAlignCenter' | 'hideErrors' | 'labelText'> & {
+    /** Content to wrap with the dropzone overlay - required for the component to have a visible drag area */
+    children: React.ReactNode;
+    /**
+     * Whether to disable clicking through the overlay to interact with wrapped children when not dragging files.
+     * When false (default): Overlay is transparent to clicks, allowing interaction with wrapped content.
+     * When true: Overlay captures all events like a normal file uploader (opens file picker on click).
+     */
+    disableClickThrough?: boolean;
+    /** Text to display in the overlay when actively dragging files over the component */
+    dragText?: string;
+    /** Custom icon to display in the overlay during drag. If not provided, shows smart default based on accepted file types and maxFiles. */
+    icon?: React.ReactNode;
+    /** Configuration for visual styling options during drag operations */
+    styleOptions?: OverlayStyleOptions;
+};
+
+// FilePreviewList specific props for within the FileUpload component (Omitted props are handled by context in FileUpload)
+type PreviewConfig = Omit<FilePreviewListProps, 'files' | 'onDelete' | 'previewStyle'>;
+
+// FileDropzone specific props for within the FileUpload component (Omitted props are handled by context in FileUpload)
+type DropzoneConfig = Omit<FileDropzoneProps, 'files'>;
+
+// Complete FileUpload component props
+export type FileUploadProps = DropzoneConfig & {
+    /** Whether to hide the file preview list */
+    hideFilePreview?: boolean;
+    /** Initial files to populate the uploader with when first mounted */
+    initialFiles?: FileResource[];
+    /** Enables more granular custom configuration for the file preview list. (See FilePreviewList for available props) */
+    previewConfig?: PreviewConfig;
+    /** Determines the view style for the file preview list */
+    previewStyle?: PreviewStyle;
+};
+
+// FileDropzoneOverlay specific props for within FileUploadCanvas (Omitted props are handled by context)
+type DropzoneOverlayConfig = Omit<FileDropzoneOverlayProps, 'children' | 'files'>;
+
+// Complete FileUploadCanvas component props
+export type FileUploadCanvasProps = DropzoneOverlayConfig & {
+    /** Initial files to populate the uploader with when first mounted */
+    initialFiles?: FileResource[];
+    /** Enables more granular custom configuration for the file preview list. (See FilePreviewList for available props) */
+    previewConfig?: PreviewConfig;
+    /** Determines the view style for the file preview list */
+    previewStyle?: PreviewStyle;
+};