@evolve.ui/core-components 1.0.1 → 1.1.0

package/src/FileUpload/components/FileDropzoneOverlay/components/OverlayDropzoneContent.tsx

@@ -0,0 +1,146 @@
+import { useMemo } from 'react';
+
+import { FileArchive, FileCsv, FilePdf, Files, FileText, ImageSquare, ImagesSquare } from '../../../../Icons';
+import { UploadValidationContextType } from '../../../providers/UploadValidationProvider';
+import { CommonFileTypes } from '../../../types/commonTypes';
+import { OverlayDropzoneDragText } from './OverlayDropzoneDragText';
+
+type OverlayContentProps = {
+    accept?: CommonFileTypes | string[];
+    customIcon?: React.ReactNode;
+    dragText: string;
+    isDragActive: boolean;
+    maxFiles?: number;
+    validation: UploadValidationContextType;
+};
+
+export const OverlayDropzoneContent = ({
+    accept,
+    customIcon,
+    dragText,
+    isDragActive,
+    maxFiles,
+    validation,
+}: OverlayContentProps) => {
+    // Determine icon color based on validation state
+    const iconColor = validation.dragValidationError ? 'critical' : 'secondary';
+
+    // Determine which icon to show based on accept and maxFiles
+    const icon = useMemo(() => {
+        // 1. Custom icon takes precedence
+        if (customIcon) {
+            return customIcon;
+        }
+
+        const isSingleFile = maxFiles === 1;
+
+        // 2. Images
+        if (accept === 'images' || (Array.isArray(accept) && accept.some((type) => type.startsWith('image/')))) {
+            if (isSingleFile) {
+                return (
+                    <ImageSquare
+                        color={iconColor}
+                        size="lg"
+                        style="duotone"
+                    />
+                );
+            }
+            return (
+                <ImagesSquare
+                    color={iconColor}
+                    size="lg"
+                    style="duotone"
+                />
+            );
+        }
+
+        // 3. Documents
+        if (accept === 'documents') {
+            if (isSingleFile) {
+                return (
+                    <FileText
+                        color={iconColor}
+                        size="lg"
+                        style="duotone"
+                    />
+                );
+            }
+            return (
+                <Files
+                    color={iconColor}
+                    size="lg"
+                    style="duotone"
+                />
+            );
+        }
+
+        // 4. PDFs
+        if (accept === 'pdfs' || (Array.isArray(accept) && accept.some((type) => type === 'application/pdf'))) {
+            return (
+                <FilePdf
+                    color={iconColor}
+                    size="lg"
+                    style="duotone"
+                />
+            );
+        }
+
+        // 5. CSV files
+        if (
+            Array.isArray(accept) &&
+            accept.some((type) => type === 'text/csv' || type === '.csv' || type.includes('csv'))
+        ) {
+            return (
+                <FileCsv
+                    color={iconColor}
+                    size="lg"
+                    style="duotone"
+                />
+            );
+        }
+
+        // 6. Archive files (zip, rar, 7z, tar, gz, etc.)
+        if (
+            Array.isArray(accept) &&
+            accept.some(
+                (type) =>
+                    type.includes('zip') ||
+                    type.includes('rar') ||
+                    type.includes('7z') ||
+                    type.includes('tar') ||
+                    type.includes('gzip') ||
+                    type === 'application/x-zip-compressed' ||
+                    type === 'application/x-rar-compressed' ||
+                    type === 'application/x-7z-compressed'
+            )
+        ) {
+            return (
+                <FileArchive
+                    color={iconColor}
+                    size="lg"
+                    style="duotone"
+                />
+            );
+        }
+
+        // 7. Default: general files icon
+        return (
+            <Files
+                color={iconColor}
+                size="lg"
+                style="duotone"
+            />
+        );
+    }, [customIcon, accept, maxFiles, iconColor]);
+
+    return (
+        <div className="text-center">
+            <div className="mb-xs flex justify-center">{icon}</div>
+            <OverlayDropzoneDragText
+                dragText={dragText}
+                isDragActive={isDragActive}
+                validation={validation}
+            />
+        </div>
+    );
+};

package/src/FileUpload/components/FileDropzoneOverlay/components/OverlayDropzoneDragText.tsx

@@ -0,0 +1,42 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useMemo } from 'react';
+
+import { UploadValidationContextType } from '../../../providers/UploadValidationProvider';
+
+type OverlayDropzoneDragTextProps = {
+    dragText: string;
+    isDragActive: boolean;
+    validation: UploadValidationContextType;
+};
+
+export const OverlayDropzoneDragText = ({ dragText, isDragActive, validation }: OverlayDropzoneDragTextProps) => {
+    // Determine overlay text based on drag state and validation
+    const overlayText = useMemo(() => {
+        if (!isDragActive) {
+            return null;
+        }
+
+        // Show validation error if present
+        if (validation.dragValidationError?.message) {
+            return validation.dragValidationError.message;
+        }
+
+        // Show success message for valid drag
+        return dragText;
+    }, [isDragActive, validation.dragValidationError, dragText]);
+
+    if (!overlayText) {
+        return null;
+    }
+
+    return (
+        <div
+            className={cn(
+                'text-xl font-medium',
+                validation.dragValidationError ? 'text-text-critical' : 'text-blue-600'
+            )}
+        >
+            {overlayText}
+        </div>
+    );
+};

package/src/FileUpload/components/FileDropzoneOverlay/styles.ts

@@ -0,0 +1,79 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { FileError } from '../../types';
+import { OverlayStyleOptions } from '../../types/sharedTypes';
+
+type DropzoneState = {
+    disableClickThrough: boolean;
+    disableDragValidation: boolean;
+    disabled: boolean;
+    isDragActive: boolean;
+    styleOptions?: OverlayStyleOptions;
+    validationError?: FileError | null;
+};
+
+export const getUploadOverlayStyles = ({
+    disableClickThrough,
+    disabled,
+    disableDragValidation,
+    isDragActive,
+    styleOptions = {},
+    validationError,
+}: DropzoneState) => {
+    const { blurOnDrag = false, showDashedBorder = true } = styleOptions;
+
+    const isInvalid = Boolean(validationError);
+    const isErrorState = disableDragValidation ? false : isInvalid;
+    const isDraggedOver = isDragActive && (disableDragValidation || !isInvalid);
+
+    return cn(
+        // Layout & Container
+        [
+            'absolute inset-0',
+            'flex flex-col',
+            'h-full w-full',
+            'items-center justify-center',
+            'rounded-[var(--container-border-radius)]',
+            showDashedBorder && 'outline-dashed outline-1 -outline-offset-1',
+            'transition-colors',
+            disableClickThrough &&
+                'cursor-pointer group-hover/dropzone:bg-background-hover group-hover/dropzone:outline-border-hover',
+        ],
+
+        // Pointer Events Strategy:
+        // - Only apply pointer-events-none when click-through is not disabled
+        // - When disableClickThrough is true, the overlay captures all events
+        // - The parent container (with getRootProps) captures drag events
+        !disableClickThrough && 'pointer-events-none',
+
+        // Z-Index: Always on top to be visible when drag is active
+        'z-10',
+
+        // Focus & Interactive Base
+        ['hui-focus-visible-outline'],
+
+        // Interactive States
+        {
+            // Drag Active - thick blue outline when dragging
+            'outline outline-4 outline-offset-0 outline-focus-primary': isDragActive,
+        },
+
+        // Visual States
+        {
+            // Apply blur when enabled and dragging (success state)
+            'backdrop-blur-[2px]': blurOnDrag && isDraggedOver && !isErrorState && !disabled,
+
+            // Apply blur when enabled and dragging (error state)
+            'backdrop-blur-sm': blurOnDrag && isDragActive && isErrorState,
+
+            // Error (only when not disabled and dragging)
+            'bg-background-critical-light/50 outline-border-critical': isErrorState && !disabled && isDragActive,
+
+            // Drag Over - show background when dragging
+            'bg-background-hover bg-background-secondary/90': isDraggedOver && !isErrorState && !disabled,
+
+            // Default - transparent when not dragging
+            'bg-transparent outline-border-secondary': !isDragActive,
+        }
+    );
+};

package/src/FileUpload/components/FilePreviewList/FilePreviewList.tsx

@@ -0,0 +1,251 @@
+import { cn } from '@evolve.ui/theme-system';
+import { breakpoints } from '@evolve.ui/theme-system/themes/common';
+import { useCallback, useContext, useMemo, useState } from 'react';
+
+import { useWindowWidth } from '../../../providers';
+import { FileUploadContext, FileUploadContextType } from '../../providers/FileUploadProvider';
+import { FileResource } from '../../types/commonTypes';
+import { FileCard, FileCardProps } from '../FileCard/FileCard';
+/* eslint-disable curly */
+import { BaseFileCardStyle, FileStatusConfig, PreviewStyle } from '../types';
+import { FilePreviewVirtualizedList } from './virtualizerComponents/FilePreviewVirtualizedList/FilePreviewVirtualizedList';
+
+type ColsByBreakpoint = {
+    xs: number;
+} & { [key in 'sm' | 'md' | 'lg' | 'xl']?: number };
+
+export type FilePreviewListProps = {
+    /** Whether files in the list can be selected (or checked) */
+    bulkSelectionEnabled?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Number of columns to display at each breakpoint, allowing you to create a custom grid layout. (grid view only) */
+    colsByBreakpoint?: ColsByBreakpoint;
+    /** Test ID for the component */
+    'data-testid'?: string;
+    /** Whether files can be dragged and sorted */
+    draggable?: boolean;
+    /** Array of Files or RemoteFile Objects (typically with URLs) to display in the preview list */
+    files?: FileResource[];
+    /** Callback to configure status display (status, progress, error, icon, text) for each file */
+    getFileStatusConfig?: (file: FileResource, index: number) => FileStatusConfig | undefined;
+    /** Whether to hide the delete action on the file cards */
+    hideDeleteAction?: boolean;
+    /** Whether to hide the file names on the file cards */
+    hideFileNames?: boolean;
+    /** Whether to hide the file sizes on the file cards */
+    hideFileSizes?: boolean;
+    /** Whether to hide status messages on the file cards (error messages, "Pending", "Uploading", and custom statusText) */
+    hideFileStatuses?: boolean;
+    /** Called when user clicks delete button on a file preview */
+    onDelete?: (fileResource: FileResource) => void;
+    /** Called when user selects or deselects a file */
+    onSelect?: (fileResource: FileResource, isSelected: boolean) => void;
+    /** Determines the view style for the file preview list */
+    previewStyle?: PreviewStyle;
+    /** Whether to show delete button or other actions on hover (list view only) */
+    showActionsOnHover?: boolean;
+    /** Whether to use a virtualized list (Only used if previewStyle is list or compactList) */
+    virtualized?: boolean;
+};
+
+const VIEW_TO_CARD_STYLE: Record<PreviewStyle, BaseFileCardStyle> = {
+    compactList: 'compact',
+    grid: 'card',
+    list: 'contained',
+};
+
+export const FilePreviewList = ({
+    bulkSelectionEnabled = false,
+    className,
+    colsByBreakpoint = { lg: 5, md: 4, sm: 3, xl: 5, xs: 3 },
+    'data-testid': dataTestId = 'file-preview-list',
+    draggable = false,
+    files: filesProp,
+    getFileStatusConfig,
+    hideDeleteAction = false,
+    hideFileNames = false,
+    hideFileSizes = false,
+    hideFileStatuses = false,
+    onDelete,
+    onSelect,
+    previewStyle = 'list',
+    showActionsOnHover = false,
+    virtualized = false,
+}: FilePreviewListProps) => {
+    const uploadContext = useContext<FileUploadContextType | undefined>(FileUploadContext);
+    // Check if we're in a provider by checking if files exist in context
+
+    // Props should take precedence over context values (consistent with FileDropzone)
+    // If files are provided as props, use those. Otherwise, fallback to context if available.
+    const files = filesProp ?? uploadContext?.files ?? [];
+
+    const handleDeleteFile = useCallback(
+        (fileToDelete: FileResource) => {
+            if (uploadContext && !onDelete) {
+                // No onDelete handler, use automatic deletion from context state
+                const fileToDeleteId = getItemIdentifier(fileToDelete);
+                uploadContext.setFiles((prevFiles) =>
+                    prevFiles.filter((file) => getItemIdentifier(file) !== fileToDeleteId)
+                );
+            }
+            onDelete?.(fileToDelete);
+        },
+        [uploadContext, onDelete]
+    );
+
+    const width = useWindowWidth();
+    const [selectedFiles, setSelectedFiles] = useState<string[]>([]);
+
+    const { lgMinValue, mdMinValue, smMinValue, xlMinValue } = breakpoints;
+
+    const gridColumns = useMemo(() => {
+        let columns = colsByBreakpoint.xs;
+        // Start with mobile (xs) as default
+        // Override with larger breakpoints if they exist and width matches
+        if (width >= smMinValue && colsByBreakpoint.sm) columns = colsByBreakpoint.sm;
+        if (width >= mdMinValue && colsByBreakpoint.md) columns = colsByBreakpoint.md;
+        if (width >= lgMinValue && colsByBreakpoint.lg) columns = colsByBreakpoint.lg;
+        if (width >= xlMinValue && colsByBreakpoint.xl) columns = colsByBreakpoint.xl;
+        return columns;
+    }, [width, colsByBreakpoint, lgMinValue, mdMinValue, smMinValue, xlMinValue]);
+
+    const handleSelect = useCallback(
+        (file: FileResource, isSelected: boolean) => {
+            setSelectedFiles((prev) => {
+                const name = file.name; // Both File and RemoteFile have name property
+
+                if (isSelected) {
+                    return [...prev, name];
+                }
+                return prev.filter((n) => n !== name);
+            });
+            onSelect?.(file, isSelected);
+        },
+        [onSelect]
+    );
+
+    const containerClasses = cn(
+        // Grid layout
+        previewStyle === 'grid' && ['grid', gridColumns && `grid-cols-${gridColumns}`],
+        // List/Table layout - only include gap-xs if viewStyle is list
+        previewStyle !== 'grid' && ['flex flex-col', previewStyle === 'list' && 'gap-xs']
+    );
+
+    const cardStyle = VIEW_TO_CARD_STYLE[previewStyle];
+
+    // Determine if we should use the virtualized list based on previewStyle and virtualized prop
+    const shouldUseVirtualizedList = virtualized && (previewStyle === 'list' || previewStyle === 'compactList');
+
+    // Common props used by both rendering paths
+    const commonProps = {
+        bulkSelectionEnabled,
+        draggable,
+        hideDeleteAction,
+        hideFileNames,
+        hideFileSizes,
+        hideFileStatuses,
+        showActionsOnHover,
+    };
+
+    // Helper to get a unique identifier for a file or URL
+    const getItemIdentifier = (item: FileResource): string => {
+        if ('url' in item) {
+            // RemoteFile: id should be unique if provided, otherwise use url as fallback
+            return item.id ?? item.url;
+        }
+        // File: use traditional properties for uniqueness
+        return `${item.name}-${item.size}-${item.lastModified}`;
+    };
+
+    // Create shared FileCard props with common conditional logic
+    const createFileCardProps = useCallback(
+        (fileResource: FileResource, index: number): FileCardProps => {
+            const name = fileResource.name;
+
+            const isSelected = selectedFiles.includes(name);
+
+            // FileCards hide the delete button when onDelete is not provided,
+            // so we pass undefined when hideDeleteAction is true,
+            // otherwise we pass the handleDeleteFile function
+            const deleteHandler = hideDeleteAction ? undefined : handleDeleteFile;
+
+            // Get status configuration from callback if provided
+            const statusConfig = getFileStatusConfig?.(fileResource, index);
+
+            return {
+                cardStyle,
+                draggable,
+                errorMessage: statusConfig?.errorMessage,
+                hideFileName: hideFileNames,
+                hideFileSize: hideFileSizes,
+                hideFileStatus: hideFileStatuses,
+                imageSource: fileResource,
+                onDelete: deleteHandler,
+                onSelect: bulkSelectionEnabled ? handleSelect : undefined,
+                ...(bulkSelectionEnabled ? { isSelected, selectable: true } : { selectable: false }),
+                progress: statusConfig?.progress,
+                showActionsOnHover,
+                status: statusConfig?.status,
+                statusIcon: statusConfig?.statusIcon,
+                statusText: statusConfig?.statusText,
+            };
+        },
+        [
+            bulkSelectionEnabled,
+            cardStyle,
+            draggable,
+            getFileStatusConfig,
+            handleDeleteFile,
+            handleSelect,
+            hideDeleteAction,
+            hideFileNames,
+            hideFileSizes,
+            hideFileStatuses,
+            selectedFiles,
+            showActionsOnHover,
+        ]
+    );
+
+    return (
+        <section
+            aria-label="File preview list"
+            className={cn(
+                'flex w-full flex-col',
+                {
+                    'h-full': previewStyle !== 'grid',
+                },
+                className
+            )}
+        >
+            {shouldUseVirtualizedList ? (
+                <FilePreviewVirtualizedList
+                    {...commonProps}
+                    createFileCardProps={createFileCardProps}
+                    files={files}
+                    previewStyle={previewStyle}
+                    selectedFiles={selectedFiles}
+                />
+            ) : (
+                <ul
+                    className={containerClasses}
+                    data-testid={dataTestId}
+                >
+                    {files.map((fileResource, index) => (
+                        <li
+                            data-testid={`${dataTestId}-item-${index}`}
+                            key={`${getItemIdentifier(fileResource)}-${index}`}
+                        >
+                            <FileCard
+                                data-testid={`${dataTestId}-card-${index}`}
+                                {...createFileCardProps(fileResource, index)}
+                            />
+                        </li>
+                    ))}
+                </ul>
+            )}
+        </section>
+    );
+};
+
+FilePreviewList.displayName = 'FilePreviewList';

package/src/FileUpload/components/FilePreviewList/virtualizerComponents/FilePreviewVirtualizedList/FilePreviewVirtualizedList.tsx

@@ -0,0 +1,88 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useVirtualizer, VirtualItem } from '@tanstack/react-virtual';
+import { useRef } from 'react';
+
+import { FileCard, FileCardProps } from '../../../../components/FileCard/FileCard';
+import { PreviewStyle } from '../../../../components/types';
+import { FileResource } from '../../../../types';
+
+/**
+ * Props for the virtualized list component
+ */
+type VirtualizedListProps = {
+    // Common props passed from parent
+    bulkSelectionEnabled?: boolean;
+    createFileCardProps: (fileResource: FileResource, index: number) => FileCardProps;
+    draggable?: boolean;
+    files: FileResource[];
+    hideDeleteAction?: boolean;
+    hideFileNames?: boolean;
+    hideFileSizes?: boolean;
+    previewStyle: PreviewStyle;
+    selectedFiles: string[];
+    showActionsOnHover?: boolean;
+};
+
+/**
+ * A virtualized list component for efficiently rendering large lists of file previews
+ * Only renders items that are currently visible in the viewport
+ */
+export const FilePreviewVirtualizedList = ({ createFileCardProps, files, previewStyle }: VirtualizedListProps) => {
+    const scrollRef = useRef<HTMLDivElement>(null);
+
+    const listItemHeight = previewStyle === 'list' ? 66 : 65;
+    const listItemGap = previewStyle === 'list' ? 8 : 0;
+
+    const virtualizer = useVirtualizer({
+        count: files.length,
+        estimateSize: () => listItemHeight,
+        gap: listItemGap,
+        getScrollElement: () => scrollRef.current,
+        overscan: 5,
+    });
+
+    const virtualItems = virtualizer.getVirtualItems();
+    return (
+        <div
+            className="relative h-full overflow-y-auto"
+            ref={scrollRef}
+        >
+            <ul
+                className={cn('flex flex-col', previewStyle === 'list' && 'gap-xs')}
+                data-testid="file-preview-virtualized-list-element"
+                style={{
+                    height: `${virtualizer.getTotalSize()}px`,
+                    position: 'relative',
+                    width: '100%',
+                }}
+            >
+                {virtualItems.map((virtualItem: VirtualItem) => {
+                    const file = files[virtualItem.index];
+
+                    return (
+                        <li
+                            data-index={virtualItem.index}
+                            data-testid={`file-preview-virtualized-list-item-${virtualItem.index}`}
+                            key={virtualItem.key}
+                            style={{
+                                height: `${virtualItem.size}px`,
+                                left: 0,
+                                position: 'absolute',
+                                top: 0,
+                                transform: `translateY(${virtualItem.start}px)`,
+                                width: '100%',
+                            }}
+                        >
+                            <FileCard
+                                data-testid={`file-preview-virtualized-list-card-${virtualItem.index}`}
+                                {...createFileCardProps(file, virtualItem.index)}
+                            />
+                        </li>
+                    );
+                })}
+            </ul>
+        </div>
+    );
+};
+
+FilePreviewVirtualizedList.displayName = 'FilePreviewVirtualizedList';

package/src/FileUpload/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,63 @@
+import { FileUploadProvider, FileUploadProviderConfigProps } from '../../providers/FileUploadProvider';
+import { FileUploadProps } from '../../types/sharedTypes';
+/* eslint-disable curly */
+import { FileDropzone } from '../FileDropzone/FileDropzone';
+import { FilePreviewList } from '../FilePreviewList/FilePreviewList';
+
+/**
+ * FileUpload component for handling single or multiple file uploads
+ * with built-in validation and preview capabilities.
+ *
+ * This is the main container component that combines the drag-and-drop area (FileDropzone)
+ * and the file preview list (FilePreviewList) into a single, cohesive interface.
+ * It handles the file validation, upload state management, and preview display through
+ * the FileUploadProvider context.
+ *
+ */
+export const FileUpload = ({
+    disabled,
+    error,
+    hideFilePreview = false,
+    initialFiles,
+    maxFiles,
+    maxSize,
+    onDrop,
+    onDropAccepted,
+    onDropRejected,
+    onFileDelete,
+    previewConfig,
+    previewStyle = 'list',
+    ...dropzoneProps
+}: FileUploadProps) => {
+    const providerProps: FileUploadProviderConfigProps = {
+        accept: dropzoneProps.accept,
+        disabled,
+        error,
+        initialFiles,
+        maxFiles,
+        maxSize,
+        onDrop,
+        onDropAccepted,
+        onDropRejected,
+        onFileDelete,
+        strictValidation: dropzoneProps.strictValidation,
+        validator: dropzoneProps.validator,
+    };
+
+    return (
+        <FileUploadProvider {...providerProps}>
+            <div className="flex flex-col gap-md">
+                <FileDropzone {...dropzoneProps} />
+                {!hideFilePreview && (
+                    <FilePreviewList
+                        {...previewConfig}
+                        onDelete={onFileDelete}
+                        previewStyle={previewStyle}
+                    />
+                )}
+            </div>
+        </FileUploadProvider>
+    );
+};
+
+FileUpload.displayName = 'FileUpload';