@evolve.ui/core-components 1.0.1 → 1.1.0

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

@@ -0,0 +1,259 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ChangeEvent } from 'react';
+
+import { Checkbox } from '../../../ChoiceListItem';
+import { IconButton } from '../../../IconButton/IconButton';
+import { DotsSixVertical, Paperclip, Trash } from '../../../Icons';
+import { ProgressCircle } from '../../../ProgressCircle/ProgressCircle';
+import { BodyPrimary, BodySecondary } from '../../../Typography/Text/Text';
+import { formatFileSize } from '../../../utils/formatFileSize';
+import { useImageFilePreviewUrl } from '../../hooks/filePreview/useImageFilePreviewUrl';
+import { BaseFileCardProps, ListFileCardStyle } from '../types';
+
+export type ListFileCardProps = BaseFileCardProps & {
+    cardStyle?: ListFileCardStyle;
+    'data-testid'?: string;
+    showActionsOnHover?: boolean;
+    statusText?: string;
+};
+
+export const ListFileCard = ({
+    actions,
+    cardStyle,
+    className,
+    'data-testid': dataTestId = 'list-file-card',
+    draggable,
+    errorMessage,
+    fileName,
+    hideFileName = false,
+    hideFileSize = false,
+    hideFileStatus = false,
+    imageSource,
+    isSelected,
+    onDelete,
+    onImageError,
+    onSelect,
+    progress,
+    selectable,
+    showActionsOnHover,
+    status = 'default',
+    statusIcon,
+    statusText,
+}: ListFileCardProps) => {
+    const previewUrl = useImageFilePreviewUrl(imageSource);
+
+    const isRemoteFile = 'url' in imageSource;
+    const fileSize = isRemoteFile ? '' : formatFileSize(imageSource.size);
+
+    // Automatically hide file size for URLs, respect the prop for Files
+    const shouldHideFileSize = hideFileSize || isRemoteFile;
+
+    const defaultFileName = isRemoteFile ? (imageSource.url.split('/').pop() ?? 'image') : imageSource.name;
+    const fileDisplayName = fileName ?? defaultFileName;
+
+    // Status checks
+    const isError = status === 'error';
+    const isPending = status === 'pending';
+    const isProgressing = status === 'progressing';
+    const isComplete = status === 'complete';
+    const isDragging = false; // ListFileCard doesn't currently support sortable YET, but adding for consistency with GridFileCard
+
+    // Determine when to auto-render ProgressCircle
+    // Only when statusIcon is not provided AND status is pending/progressing/complete
+    const shouldShowProgressCircle = !statusIcon && (isPending || isProgressing || isComplete);
+
+    // Determine what to show below the file name (priority: error > progressing > size)
+    let fileStatusText = null;
+
+    if (isError && errorMessage && !hideFileStatus) {
+        fileStatusText = <BodySecondary className="text-text-critical">{errorMessage}</BodySecondary>;
+    } else if ((isProgressing || isPending) && !hideFileStatus) {
+        // Use custom statusText if provided, otherwise use default
+        const defaultStatusText = isPending ? 'Pending' : 'Uploading';
+        const displayStatusText = statusText ?? defaultStatusText;
+        fileStatusText = <BodySecondary color="secondary">{displayStatusText}</BodySecondary>;
+    } else if (!shouldHideFileSize) {
+        fileStatusText = <BodySecondary color={isError ? 'critical' : 'secondary'}>{fileSize}</BodySecondary>;
+    }
+
+    const actionBtnClasses = showActionsOnHover
+        ? cn(
+              'opacity-0 group-focus-within/list-file-card:opacity-100 group-hover/list-file-card:opacity-100',
+              'focus:opacity-100',
+              'transition-opacity duration-200'
+          )
+        : '';
+
+    const isProcessing = isPending || isProgressing;
+
+    // Map status to ProgressCircle-compatible status (only needed when shouldShowProgressCircle is true)
+    let progressCircleStatus: 'pending' | 'progressing' | 'complete';
+    if (isPending) {
+        progressCircleStatus = 'pending';
+    } else if (isProgressing) {
+        progressCircleStatus = 'progressing';
+    } else {
+        progressCircleStatus = 'complete';
+    }
+
+    return (
+        <div
+            aria-busy={isProcessing || undefined}
+            className={cn(
+                'group/list-file-card flex w-full min-w-0 cursor-pointer items-center justify-between p-xs',
+                'transition-all duration-200',
+                {
+                    // Error state
+                    'bg-background-critical-light': isError && !isDragging,
+                    // Default state
+                    'bg-background-primary': !isError && !isDragging,
+                    // Drag state
+                    'z-50 scale-105 border-border-selected bg-background-secondary shadow-01': isDragging,
+                },
+                // List View (BorderContained) vs Table View (Single Border)
+                cardStyle === 'contained'
+                    ? cn('rounded-container border', {
+                          // Error state
+                          'border-border-critical hover:border-border-critical hover:bg-background-critical-light':
+                              isError && !isDragging,
+                          // Default state
+                          'border-border-secondary hover:border-border-secondary hover:bg-background-hover':
+                              !isError && !isDragging,
+                      })
+                    : cn('rounded-b-none border-b', {
+                          // Error state
+                          'border-b-border-critical focus-within:border-b-border-critical hover:bg-background-critical-light':
+                              isError && !isDragging,
+                          // Default state
+                          'border-b-border-secondary hover:bg-background-hover': !isError && !isDragging,
+                      }),
+                className
+            )}
+            data-testid={dataTestId}
+        >
+            <div className="flex min-w-0 flex-1 items-center gap-xs">
+                <div className="flex items-center gap-[4px]">
+                    {/* Show either Checkbox or DragHandle, not both */}
+                    {selectable ? (
+                        <Checkbox.Option
+                            checked={isSelected}
+                            className="![grid-template-columns:24px_0px_1fr]"
+                            data-testid="list-file-card-select-checkbox"
+                            onChange={(e: ChangeEvent<HTMLInputElement>) => {
+                                e.stopPropagation();
+                                onSelect?.(imageSource, e.target.checked);
+                            }}
+                        />
+                    ) : draggable ? (
+                        <DotsSixVertical
+                            color="primary"
+                            size="sm"
+                            style="bold"
+                        />
+                    ) : null}
+                    {previewUrl ? (
+                        <div className="relative h-xl w-xl items-center justify-center overflow-hidden rounded-container bg-background-subdued">
+                            <img
+                                alt={fileDisplayName}
+                                className="absolute inset-0 h-full w-full object-cover"
+                                onError={() => {
+                                    onImageError?.(imageSource);
+                                }}
+                                src={previewUrl}
+                            />
+                        </div>
+                    ) : (
+                        <div className="flex aspect-square min-w-xl items-center justify-center rounded-container bg-background-subdued">
+                            <Paperclip
+                                color="primary"
+                                size="sm"
+                            />
+                        </div>
+                    )}
+                </div>
+                <div className="flex min-w-0 flex-1 flex-col gap-[2px]">
+                    {!hideFileName && (
+                        <BodyPrimary
+                            className="truncate"
+                            color={isError ? 'critical' : 'primary'}
+                        >
+                            {fileDisplayName}
+                        </BodyPrimary>
+                    )}
+                    {fileStatusText}
+                </div>
+            </div>
+            {/* Actions */}
+            <div className="flex items-center gap-[4px]">
+                {actions?.map((action, index) => (
+                    <IconButton
+                        aria-label={action.name}
+                        className={actionBtnClasses}
+                        disabled={isProcessing}
+                        icon={action.icon}
+                        key={`${action.name}-${index}`}
+                        onClick={(e) => {
+                            e.stopPropagation();
+                            action.onClick(e, imageSource);
+                        }}
+                        size="sm"
+                        type="button"
+                    />
+                ))}
+                {onDelete && (
+                    <IconButton
+                        aria-label="Remove file"
+                        className={actionBtnClasses}
+                        data-testid="remove-file-button"
+                        disabled={isProcessing}
+                        icon={Trash}
+                        onClick={() => onDelete(imageSource)}
+                        size="sm"
+                        type="button"
+                    />
+                )}
+                {shouldShowProgressCircle ? (
+                    <div
+                        className="flex items-center"
+                        data-testid="list-file-card-progress-circle"
+                    >
+                        <ProgressCircle
+                            progress={progress}
+                            size="sm"
+                            status={progressCircleStatus}
+                        />
+                    </div>
+                ) : statusIcon ? (
+                    statusIcon.type === 'progressCircle' ? (
+                        <div
+                            className="flex items-center"
+                            data-testid="list-file-card-progress-circle"
+                        >
+                            <ProgressCircle
+                                centerIcon={statusIcon.centerIcon}
+                                color={statusIcon.color}
+                                indeterminateAnimation={statusIcon.indeterminateAnimation}
+                                progress={progress}
+                                size="sm"
+                                status={progressCircleStatus}
+                            />
+                        </div>
+                    ) : (
+                        <div
+                            className="flex items-center"
+                            data-testid="list-file-card-status-icon"
+                        >
+                            <statusIcon.icon
+                                color={statusIcon.color}
+                                size="md"
+                                style={statusIcon.style}
+                            />
+                        </div>
+                    )
+                ) : null}
+            </div>
+        </div>
+    );
+};
+
+ListFileCard.displayName = 'ListFileCard';

package/src/FileUpload/components/types.ts

@@ -0,0 +1,78 @@
+//should table be called 'page' or 'row'?
+
+import { DraggableAttributes } from '@dnd-kit/core';
+import { SyntheticListenerMap } from '@dnd-kit/core/dist/hooks/utilities';
+import { ComponentProps, CSSProperties } from 'react';
+
+import { AnyIcon } from '../../Icons/anyIcon';
+import { IconProps } from '../../Icons/IconBase';
+import { LoadingSpinner } from '../../LoadingSpinner/LoadingSpinner';
+import { ProgressCircle } from '../../ProgressCircle/ProgressCircle';
+import { FileResource } from '../types';
+
+export type FileCardAction = {
+    icon: AnyIcon;
+    iconStyle?: IconProps['style'];
+    name: string;
+    onClick: (e: React.MouseEvent<HTMLElement>, fileResource: FileResource) => void;
+};
+
+export type FileStatusIconConfig = {
+    color?: IconProps['color'];
+    icon: AnyIcon | typeof LoadingSpinner;
+    style?: IconProps['style'];
+    type: 'icon';
+};
+
+export type FileProgressCircleConfig = {
+    centerIcon?: ComponentProps<typeof ProgressCircle>['centerIcon'];
+    color?: ComponentProps<typeof ProgressCircle>['color'];
+    indeterminateAnimation?: ComponentProps<typeof ProgressCircle>['indeterminateAnimation'];
+    type: 'progressCircle';
+};
+
+export type FileStatusIcon = FileStatusIconConfig | FileProgressCircleConfig;
+
+export type FileStatusConfig = {
+    errorMessage?: string;
+    progress?: number;
+    status?: 'default' | 'pending' | 'progressing' | 'complete' | 'error';
+    statusIcon?: FileStatusIcon;
+    statusText?: string;
+};
+
+export type PreviewStyle = 'list' | 'compactList' | 'grid';
+export type BaseFileCardStyle = 'contained' | 'compact' | 'card';
+export type ListFileCardStyle = 'contained' | 'compact';
+
+export type BaseFileCardProps = {
+    /**
+     * GridCard Only: First 3 actions will be visible buttons,
+     * remaining will appear in overflow menu.
+     */
+    actions?: FileCardAction[];
+    className?: string;
+    draggable?: boolean;
+    errorMessage?: string;
+    fileName?: string;
+    hideFileName?: boolean;
+    hideFileSize?: boolean;
+    hideFileStatus?: boolean;
+    imageSource: FileResource;
+    isSelected?: boolean;
+    onDelete?: (fileResource: FileResource) => void;
+    onImageError?: (fileResource: FileResource) => void;
+    onSelect?: (fileResource: FileResource, isSelected: boolean) => void;
+    /** Progress percentage (0-100) for the file upload/processing */
+    progress?: number;
+    selectable?: boolean;
+    sortable?: {
+        attributes?: DraggableAttributes;
+        isDragging?: boolean;
+        listeners?: SyntheticListenerMap;
+        setNodeRef: (node: HTMLElement | null) => void;
+        styles?: CSSProperties;
+    };
+    status?: 'default' | 'pending' | 'progressing' | 'complete' | 'error';
+    statusIcon?: FileStatusIcon;
+} & ({ isSelected: boolean; selectable: true } | { isSelected?: boolean; selectable?: false });

package/src/FileUpload/hooks/filePreview/useImageFilePreviewUrl.ts

@@ -0,0 +1,62 @@
+import { useEffect, useState } from 'react';
+
+import { FileResource } from '../../types';
+
+/**
+ * Hook to manage file preview URLs with proper cleanup
+ * @param file - File to preview
+ * @returns Preview URL for image files, undefined for non-image files
+ */
+
+// -->  Cleans up any existing URL before creating a new one
+// -->  Handles cleanup when the file prop changes
+// -->  Is more memory-efficient since it immediately revokes unused URLs
+// -->  URLs are created only when needed (in the view)
+// -->  Cleanup is tied directly to component lifecycle - handles cleanup on unmount
+// -->  URLs are managed closer to where they're actually used
+// -->  It's more efficient since previews are only created for visible components
+
+export const useImageFilePreviewUrl = (file?: FileResource) => {
+    const [previewUrl, setPreviewUrl] = useState<string | undefined>();
+
+    useEffect(() => {
+        if (!file) {
+            return;
+        }
+
+        // If the file is a RemoteFile (has url property), use the url directly
+        if ('url' in file && file.url) {
+            setPreviewUrl(file.url);
+            return;
+        }
+
+        // At this point, file must be a File object
+        const fileObj = file as File;
+        const isImageFile = fileObj.type.startsWith('image/');
+
+        // Only create URL for image files
+        if (!isImageFile) {
+            return;
+        }
+
+        // Clean up previous URL before creating new one
+        if (previewUrl) {
+            URL.revokeObjectURL(previewUrl);
+        }
+
+        // Create preview URL
+        const url = URL.createObjectURL(fileObj);
+        setPreviewUrl(url);
+
+        // Cleanup
+        return () => {
+            if (url) {
+                URL.revokeObjectURL(url);
+            }
+        };
+        //Ignore, as this is a cleanup function - adding previewUrl could cause infinite re-renders
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [file]);
+
+    return previewUrl;
+};

package/src/FileUpload/hooks/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @package @evolve.ui/core-components/fileUpload/hooks
+ * Custom hooks for file upload functionality
+ *
+ * @module
+ * Exports:
+ * - useFileValidation: Handles file validation with support for size, type, and custom rules
+ * - useImageFilePreviewUrl: Generates preview URLs for image files with automatic cleanup
+ */
+export { useFileValidation } from './validation/useFileValidation';
+export { useImageFilePreviewUrl } from './filePreview/useImageFilePreviewUrl';

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

@@ -0,0 +1,154 @@
+import { useCallback } from 'react';
+
+import { UploadValidationContextType } from '../../../providers/UploadValidationProvider';
+import { FileResource, FileValidator } from '../../../types/commonTypes';
+import { createMessageContext } from '../../../utils/createMessageContext';
+import { resolveContextAwareMessage } from '../../../utils/messageUtils';
+
+/**
+ * Hook that handles file validation during drag events over a drop zone
+ * @param props Object containing:
+ *   - files: Currently selected files in the uploader
+ *   - mimeTypes: Optional mapping of accepted file types to their MIME type arrays
+ *   - validation: Validation context (from either UploadValidationProvider
+ *     or local useFileValidationLogic hook)
+ *   - validator: Optional custom validation function to perform additional checks
+ * @returns Callback function for handling dragenter events with early validation feedback
+ * @remarks
+ * - Provides immediate validation feedback while files are being dragged over the drop zone
+ * - File size validation is not possible during drag events as file data is not yet available
+ * - Validates in a specific priority order: custom validator → file count → file type
+ * - Clears all validation state when drag starts
+ * - Sets appropriate validation error messages for display in the UI
+ * - Works with the ValidationContext to maintain validation state
+ */
+
+type UseHandleDragEnterProps = {
+    /** Current files in the upload area */
+    files: FileResource[];
+    /** MIME types to accept */
+    mimeTypes?: Record<string, string[]>;
+    /** Validation context */
+    validation: UploadValidationContextType;
+    /** Custom validator function */
+    validator?: FileValidator;
+};
+
+// Fires when a user drags files over the upload zone - provides early feedback on file type and max file limit
+// Note: We cannot early-validate file size here since we don't have access to the file content during drag events, only after drop.
+export const useHandleDragEnter = ({ files, mimeTypes, validation, validator }: UseHandleDragEnterProps) => {
+    const {
+        accept,
+        clearAllValidation,
+        formattedMaxSize,
+        getValidationMessage,
+        maxFiles,
+        maxSize,
+        setDragValidationError,
+        validateCustomRules,
+        validateFileCount,
+        validateFileType,
+    } = validation;
+
+    return useCallback(
+        (event: React.DragEvent<HTMLElement>) => {
+            // Clear all previous validation errors when a new drag event occurs
+            clearAllValidation();
+
+            const items = event.dataTransfer.items;
+            if (items.length === 0) {
+                return;
+            }
+
+            // Validation priority follows a specific order with early returns:
+            // 1. Custom validator (highest priority)
+            if (validator) {
+                // Drag validation for custom validator uses the first dragged item
+                const file = items[0];
+                const validationResult = validateCustomRules(file);
+                if (validationResult) {
+                    // Use the first error in the array
+                    const result = validationResult[0];
+
+                    // Create context with all necessary data for the error message
+                    const messageContext = createMessageContext({
+                        accept,
+                        code: result.code,
+                        count: items.length,
+                        dragItems: items,
+                        formattedMaxSize,
+                        maxFiles,
+                        maxSize,
+                        messageType: 'drag',
+                    });
+
+                    // Set the error with a properly formatted message
+                    setDragValidationError({
+                        code: result.code,
+                        message: resolveContextAwareMessage(result.message, messageContext),
+                    });
+                    return;
+                }
+            }
+
+            // 2. File count validation (second priority)
+            if (!validateFileCount(files.length, items.length)) {
+                const overflowCount = files.length + items.length - (maxFiles ?? Infinity);
+
+                const errorCode = 'too-many-files';
+                const errorMessage = getValidationMessage({
+                    code: errorCode,
+                    count: overflowCount,
+                    messageType: 'drag',
+                });
+
+                setDragValidationError({
+                    code: errorCode,
+                    message: errorMessage,
+                });
+                return;
+            }
+
+            // 3. File type validation (lowest priority)
+            const invalidTypeFiles = Array.from(items).filter((item) => {
+                // Skip directories in validation (no type or kind is 'directory')
+                if (!item.type || item.kind === 'directory') {
+                    return false;
+                }
+                return !validateFileType(item.type, mimeTypes);
+            });
+
+            if (invalidTypeFiles.length > 0) {
+                const errorCode = 'file-invalid-type';
+                const errorMessage = getValidationMessage({
+                    code: errorCode,
+                    count: invalidTypeFiles.length,
+                    messageType: 'drag',
+                });
+
+                setDragValidationError({
+                    code: errorCode,
+                    message: errorMessage,
+                });
+                return;
+            }
+
+            // If we reach here, all validation passed - no error is set
+        },
+        [
+            files.length,
+            mimeTypes,
+            clearAllValidation,
+            setDragValidationError,
+            getValidationMessage,
+            validateFileCount,
+            maxFiles,
+            validateFileType,
+            validateCustomRules,
+            validator,
+            accept,
+            formattedMaxSize,
+            maxSize,
+        ]
+    );
+};