@evolve.ui/core-components 1.0.1 → 1.2.0

package/src/FileUpload/utils/constants.ts

@@ -0,0 +1,79 @@
+import { capitalize } from 'es-toolkit';
+
+import { CommonFileTypes, DynamicMessageContext, FileErrorCode } from '../types/commonTypes';
+
+export const builtInErrorCodes: FileErrorCode[] = ['file-invalid-type', 'file-too-large', 'too-many-files'];
+
+export const ACCEPTED_MIME_TYPES: Record<CommonFileTypes, string[]> = {
+    documents: [
+        'application/pdf',
+        'application/msword',
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document', // .docx
+        'application/vnd.ms-excel',
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', // .xlsx
+    ],
+    images: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+    pdfs: ['application/pdf'],
+};
+
+// Messages shown during drag (preventative)
+//DRAG MESSAGE RULES: Be short and concise. Don't use periods.
+export const DRAG_MESSAGES = {
+    default: 'Invalid file',
+    partialUpload: {
+        'file-invalid-type': ({ fileCount = 1, filePluralizationText }: DynamicMessageContext) =>
+            `${fileCount} ${filePluralizationText} ${fileCount > 1 ? 'have' : 'has'} an invalid file type`,
+        'file-too-large': ({ formattedMaxSize }: DynamicMessageContext) =>
+            `One or more files are too large. (${formattedMaxSize} limit)`,
+        'too-many-files': ({ fileCount, filePluralizationText }: DynamicMessageContext) =>
+            `${fileCount} ${filePluralizationText} will exceed the file limit`,
+    },
+    singleFileUpload: {
+        'file-invalid-type': 'File type not supported',
+        'file-too-large': ({ formattedMaxSize }: DynamicMessageContext) =>
+            `File must be smaller than ${formattedMaxSize}`,
+        'too-many-files': ({ filePluralizationText, maxFiles }: DynamicMessageContext) =>
+            `You can only upload ${maxFiles} ${filePluralizationText}`,
+    },
+    strictUpload: {
+        'file-invalid-type': 'One or more files have an invalid file type',
+        'file-too-large': ({ formattedMaxSize }: DynamicMessageContext) =>
+            `One or more files are too large. (${formattedMaxSize} limit)`,
+        'too-many-files': ({ maxFiles, maxFilesPluralizationText }: DynamicMessageContext) =>
+            `You can only upload ${maxFiles} ${maxFilesPluralizationText}`,
+    },
+};
+
+// Messages shown after drop (error state)
+//DROP MESSAGE RULES: Guide the user on what went wrong and what they can do to move forward.
+export const DROP_MESSAGES = {
+    default: 'Invalid file',
+    partialUpload: {
+        'file-invalid-type': ({
+            acceptedFileExtensions,
+            fileCount = 1,
+            filePluralizationText,
+        }: DynamicMessageContext) =>
+            `Failed to add ${fileCount} ${filePluralizationText} due to invalid file type. Please upload only ${acceptedFileExtensions} files.`,
+        'file-too-large': ({ fileCount = 1, filePluralizationText, formattedMaxSize }: DynamicMessageContext) =>
+            `${fileCount} ${filePluralizationText} ${fileCount > 1 ? 'are' : 'is'} too large. Please upload files smaller than ${formattedMaxSize}.`,
+        'too-many-files': ({ fileCount, filePluralizationText, maxFiles }: DynamicMessageContext) =>
+            `You've reached the ${maxFiles} file limit. ${fileCount} ${filePluralizationText} could not be added.`,
+    },
+    singleFileUpload: {
+        'file-invalid-type': ({ acceptedFileExtensions }: DynamicMessageContext) =>
+            `File type not supported. Please upload only ${acceptedFileExtensions} files.`,
+        'file-too-large': ({ formattedMaxSize }: DynamicMessageContext) =>
+            `File is too large. Please upload files smaller than ${formattedMaxSize}.`,
+        'too-many-files': ({ filePluralizationText, maxFiles }: DynamicMessageContext) =>
+            `${capitalize(filePluralizationText ?? 'files')} not added. You can only upload ${maxFiles} in total`,
+    },
+    strictUpload: {
+        'file-invalid-type': ({ acceptedFileExtensions }: DynamicMessageContext) =>
+            `One or more files have an invalid file type. Please upload only ${acceptedFileExtensions} files.`,
+        'file-too-large': ({ formattedMaxSize }: DynamicMessageContext) =>
+            `One or more files are too large. Please upload files smaller than ${formattedMaxSize}.`,
+        'too-many-files': ({ filePluralizationText, maxFiles, maxFilesPluralizationText }: DynamicMessageContext) =>
+            `${capitalize(filePluralizationText ?? 'files')} not added - maximum of ${maxFiles} ${maxFilesPluralizationText} allowed.`,
+    },
+};

package/src/FileUpload/utils/createMessageContext.ts

@@ -0,0 +1,180 @@
+import {
+    BaseDynamicMessageContext,
+    CommonFileTypes,
+    DragMessageContext,
+    DropMessageContext,
+    DynamicMessageContext,
+} from '../types/commonTypes';
+import { getFileExtensionsFromAcceptedTypes } from './getFileExtensionsFromAcceptedTypes';
+import { getFilePluralizationText } from './getFilePluralizationText';
+
+/**
+ * Creates a base message context with properties common to both drag and drop events
+ */
+export const createBaseMessageContext = ({
+    accept,
+    code,
+    count,
+    formattedMaxSize,
+    maxFiles,
+    maxSize,
+}: {
+    accept?: CommonFileTypes | string[];
+    code: string;
+    count?: number;
+    formattedMaxSize?: string;
+    maxFiles?: number;
+    maxSize?: number;
+}): BaseDynamicMessageContext => {
+    const acceptedFileExtensions = getFileExtensionsFromAcceptedTypes(accept);
+
+    const filePluralizationText = getFilePluralizationText({
+        accept,
+        count,
+        hideCount: true,
+    });
+
+    const maxFilesPluralizationText = getFilePluralizationText({
+        accept,
+        count: maxFiles,
+        hideCount: true,
+    });
+
+    return {
+        acceptedFileExtensions,
+        errorCode: code,
+        ...(count !== undefined && { fileCount: count }),
+        filePluralizationText,
+        formattedMaxSize,
+        maxFiles,
+        maxFilesPluralizationText,
+        maxSizeBytes: maxSize,
+    };
+};
+
+/**
+ * Creates a message context for drag events
+ */
+export const createDragMessageContext = ({
+    accept,
+    code,
+    count,
+    formattedMaxSize,
+    items,
+    maxFiles,
+    maxSize,
+}: {
+    accept?: CommonFileTypes | string[];
+    code: string;
+    count?: number;
+    formattedMaxSize?: string;
+    items?: DataTransferItemList;
+    maxFiles?: number;
+    maxSize?: number;
+}): DragMessageContext => {
+    const baseContext = createBaseMessageContext({
+        accept,
+        code,
+        count,
+        formattedMaxSize,
+        maxFiles,
+        maxSize,
+    });
+
+    return {
+        ...baseContext,
+        ...(items && { draggedItems: items }),
+        eventType: 'drag',
+    };
+};
+
+/**
+ * Creates a message context for drop events
+ */
+export const createDropMessageContext = ({
+    accept,
+    code,
+    count,
+    files,
+    formattedMaxSize,
+    maxFiles,
+    maxSize,
+}: {
+    accept?: CommonFileTypes | string[];
+    code: string;
+    count?: number;
+    files?: File[];
+    formattedMaxSize?: string;
+    maxFiles?: number;
+    maxSize?: number;
+}): DropMessageContext => {
+    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
+ */
+export const createMessageContext = ({
+    accept,
+    code,
+    count,
+    dragItems,
+    dropFiles,
+    formattedMaxSize,
+    maxFiles,
+    maxSize,
+    messageType = 'drop',
+}: {
+    accept?: CommonFileTypes | string[];
+    code: string;
+    count?: number;
+    dragItems?: DataTransferItemList;
+    dropFiles?: File[];
+    formattedMaxSize?: string;
+    maxFiles?: number;
+    maxSize?: number;
+    messageType?: 'drag' | 'drop';
+}): DynamicMessageContext => {
+    const baseParams = {
+        accept,
+        code,
+        count,
+        formattedMaxSize,
+        maxFiles,
+        maxSize,
+    };
+
+    if (messageType === 'drag') {
+        return createDragMessageContext({
+            ...baseParams,
+            items: dragItems,
+        });
+    }
+
+    return createDropMessageContext({
+        ...baseParams,
+        files: dropFiles,
+    });
+};

package/src/FileUpload/utils/getFileExtensionsFromAcceptedTypes.ts

@@ -0,0 +1,73 @@
+import { CommonFileTypes } from '../types/commonTypes';
+import { ACCEPTED_MIME_TYPES } from './constants';
+
+// Map of MIME types to their corresponding file extensions
+const MIME_TYPE_TO_EXTENSION: Record<string, string> = {
+    '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
+ */
+export const getMimeTypeExtension = (mimeType: string): string => {
+    // If we have a direct mapping, use it
+    if (MIME_TYPE_TO_EXTENSION[mimeType]) {
+        return MIME_TYPE_TO_EXTENSION[mimeType];
+    }
+
+    // For simple MIME types, extract the subtype
+    const parts = mimeType.split('/');
+    if (parts.length === 2 && parts[1] && !parts[1].includes('.')) {
+        return `.${parts[1]}`;
+    }
+
+    // Return empty string for incomplete MIME types
+    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'])
+ */
+export const getFileExtensionsFromAcceptedTypes = (accept?: CommonFileTypes | string[]) => {
+    if (!accept) {
+        return '';
+    }
+
+    // If it's a CommonFileTypes string (e.g., 'images')
+    if (typeof accept === 'string') {
+        const mimeTypes = ACCEPTED_MIME_TYPES[accept as CommonFileTypes];
+        return mimeTypes.map(getMimeTypeExtension).join(', ');
+    }
+
+    // If it's an array of extensions/mime types
+    return accept
+        .filter(Boolean) // Remove empty strings and falsy values
+        .map((type) => (type.startsWith('.') ? type : getMimeTypeExtension(type))) // Convert MIME types to extensions
+        .filter((ext) => ext.length > 1) // Remove single-character extensions
+        .join(', ');
+};

package/src/FileUpload/utils/getFilePluralizationText.ts

@@ -0,0 +1,68 @@
+import { capitalize } from 'es-toolkit';
+
+import { CommonFileTypes } from '../types/commonTypes';
+
+type GetFilePluralizationTextProps = {
+    accept?: CommonFileTypes | string[];
+    capitalize?: boolean;
+    count?: number;
+    hideCount?: boolean;
+};
+
+const getBaseText = (accept?: CommonFileTypes | string[]): 'image' | 'file' => {
+    if (accept === 'images') {
+        return 'image';
+    }
+
+    if (Array.isArray(accept)) {
+        const isImageOnly = accept.every((type) => type.startsWith('image/'));
+        return isImageOnly ? 'image' : 'file';
+    }
+
+    return 'file';
+};
+
+const pluralize = (count: number, word: string, hideCount?: boolean, capitalizeWord?: boolean) => {
+    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 })
+ */
+export const getFilePluralizationText = ({
+    accept,
+    capitalize: capitalizeWord,
+    count,
+    hideCount,
+}: GetFilePluralizationTextProps = {}) => {
+    const baseText = getBaseText(accept);
+
+    if (count === undefined) {
+        if (capitalizeWord) {
+            return capitalize(baseText);
+        }
+        return baseText;
+    }
+
+    return pluralize(count, baseText, hideCount, capitalizeWord);
+};

package/src/FileUpload/utils/getMimeTypes.ts

@@ -0,0 +1,26 @@
+import { CommonFileTypes } from '../types/commonTypes';
+import { ACCEPTED_MIME_TYPES } from './constants';
+
+/**
+ * Utility function that converts file type restrictions into MIME type format for react-dropzone
+ * @param accept - Optional file type restrictions, can be either:
+ *   - A preset category from CommonFileTypes (e.g., 'images', 'pdfs', 'documents')
+ *   - An array of specific MIME types (e.g., ['image/jpeg', 'image/png'])
+ * @returns Object mapping MIME types to empty arrays for react-dropzone's accept prop
+ * @remarks
+ * - Returns undefined when no restrictions are provided (accepts all file types)
+ * - Handles both preset categories and custom MIME type arrays
+ * - Formats MIME types to match react-dropzone's expected structure
+ */
+
+export const getMimeTypes = (accept?: CommonFileTypes | string[]) => {
+    if (!accept) {
+        return undefined; // No restrictions
+    }
+
+    if (Array.isArray(accept)) {
+        return accept.reduce((acc, curr) => ({ ...acc, [curr]: [] }), {}); // Custom MIME types
+    }
+
+    return ACCEPTED_MIME_TYPES[accept].reduce((acc, curr) => ({ ...acc, [curr]: [] }), {}); // Preset category
+};

package/src/FileUpload/utils/messageUtils.ts

@@ -0,0 +1,41 @@
+import { ContextAwareMessage } from '../types/commonTypes';
+
+/**
+ * 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.
+ */
+export const resolveContextAwareMessage = <T>(
+    message: ContextAwareMessage<T> | undefined,
+    context?: T,
+    defaultMessage?: ContextAwareMessage<T>
+): string => {
+    // Handle undefined message
+    if (!message) {
+        // Use default message if provided
+        if (defaultMessage) {
+            return resolveContextAwareMessage(defaultMessage, context);
+        }
+        return '';
+    }
+
+    // Handle function message
+    if (typeof message === 'function') {
+        // Ensure we have a context to pass to the function
+        if (context) {
+            return String(message(context));
+        }
+        // If no context but we have a default, use it
+        if (defaultMessage) {
+            return resolveContextAwareMessage(defaultMessage, context);
+        }
+        return '';
+    }
+
+    // Handle string message
+    return message;
+};

package/src/FileUpload/utils/styles.ts

@@ -0,0 +1,68 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { FileError } from '../types';
+
+type DropzoneState = {
+    disableDragValidation: boolean;
+    disabled: boolean;
+    isDragActive: boolean;
+    validationError?: FileError | null;
+};
+
+export const getUploadZoneStyles = ({
+    disabled,
+    disableDragValidation,
+    isDragActive,
+    validationError,
+}: DropzoneState) => {
+    const isInvalid = Boolean(validationError);
+    const isErrorState = disableDragValidation ? false : isInvalid;
+    const isDefaultState = !isDragActive && !isErrorState;
+    const isDraggedOver = isDragActive && (disableDragValidation || !isInvalid);
+    const isDefaultAppearance = isDefaultState && !disabled;
+
+    return cn(
+        // Layout & Container
+        [
+            'relative',
+            'flex flex-col',
+            'h-full w-full',
+            'items-center justify-center',
+            'rounded-container',
+            'outline-dashed outline-1 -outline-offset-1',
+            'p-sm',
+            'transition-colors',
+            'hover:bg-background-hover hover:outline-border-hover', // Hover (when not dragging)
+        ],
+
+        // Focus & Interactive Base
+        ['hui-focus-visible-outline'],
+
+        // Interactive States
+        {
+            // Disabled
+            'cursor-not-allowed bg-background-disabled outline-border-disabled hover:bg-background-disabled hover:outline-border-disabled':
+                disabled,
+
+            // Enabled
+            'cursor-pointer active:bg-background-pressed active:outline active:outline-4 active:outline-focus-primary':
+                !disabled,
+
+            // Drag Active (only when not disabled)
+            'outline outline-4 outline-offset-0 outline-focus-primary': isDragActive && !disabled,
+        },
+
+        // Visual States
+        {
+            // Error (only when not disabled)
+            'bg-background-critical-light outline-dashed outline-1 -outline-offset-1 outline-border-critical':
+                isErrorState && !disabled,
+
+            // Drag Over
+            'bg-background-hover': isDraggedOver && !isErrorState && !disabled,
+
+            // Default
+            'bg-background-primary outline-border-secondary': isDefaultAppearance,
+        }
+    );
+};