@evolve.ui/core-components 1.0.0 → 1.1.0

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

@@ -0,0 +1,221 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useContext } from 'react';
+import { useDropzone } from 'react-dropzone';
+
+import { Caption, LabelMini } from '../../../Typography/Text/Text';
+import { formatFileSize } from '../../../utils/formatFileSize';
+import { useFileValidation } from '../../hooks';
+import { useHandleDragEnter } from '../../hooks/upload/useHandleDragEnter/useHandleDragEnter';
+import { useHandleDrop } from '../../hooks/upload/useHandleDrop/useHandleDrop';
+import { useUploadAvailability } from '../../hooks/upload/useUploadAvailability/useUploadAvailability';
+import { createDropzoneValidator } from '../../hooks/validation/createDropzoneValidator';
+import { FileUploadContext, FileUploadContextType } from '../../providers/FileUploadProvider';
+import { FileDropzoneProps } from '../../types/sharedTypes';
+import { getMimeTypes } from '../../utils/getMimeTypes';
+import { getUploadZoneStyles } from '../../utils/styles';
+import { DropzoneContent } from './components/DropzoneContent/DropzoneContent';
+import { FileDropzoneDebugger } from './components/FileDropzoneDebugger/FileDropzoneDebugger';
+
+/**
+ * FileDropzone component for handling file uploads with drag and drop support.
+ * This is a versatile file input component that can work both as a standalone
+ * component or as part of the FileUpload system.
+ */
+
+/**
+ * Handles the dual-mode functionality of the FileDropzone component, supporting both standalone usage
+ * and provider-wrapped usage.
+ *
+ * ## Validation Modes
+ * - **Provider Mode**: Uses validation context from FileUploadProvider for coordinated validation across components
+ * - **Standalone Mode**: Creates local validation instance for independent operation
+ *
+ * ## Props & Context Resolution
+ * The component follows a specific precedence order for each property:
+ * 1. Direct props take highest priority (for granular control)
+ * 2. Context values serve as fallbacks (for coordinated state)
+ * 3. Default values as final fallbacks (for safety)
+ *
+ * This enables two key use cases:
+ * 1. Standalone Usage: <FileDropzone maxFiles={5} onDrop={handleDrop} />
+ * 2. Provider Usage:
+ *    <FileUploadProvider maxFiles={5}>
+ *      <FileDropzone /> // Inherits provider config
+ *      <FileDropzone maxFiles={1} /> // Overrides specific provider values
+ *    </FileUploadProvider>
+ */
+export const FileDropzone = ({
+    accept: acceptProp,
+    ariaLabel = 'Browse or drag files here to upload.',
+    className,
+    'data-testid': dataTestId = 'file-dropzone',
+    disabled: disabledProp = false,
+    disableDragValidation = false,
+    error,
+    files: filesProp,
+    helpText,
+    helpTextAlignCenter,
+    hideErrors = false,
+    hideHelpText = false,
+    labelText,
+    maxFiles: maxFilesProp,
+    maxSize: maxSizeProp,
+    onDrop: onDropProp,
+    onDropAccepted: onDropAcceptedProp,
+    onDropRejected: onDropRejectedProp,
+    onFilesChange: onFilesChangeProp,
+    showDebugger,
+    strictValidation,
+    validator,
+}: FileDropzoneProps) => {
+    const uploadContext = useContext<FileUploadContextType | undefined>(FileUploadContext);
+
+    const validationConfig = {
+        accept: acceptProp,
+        error,
+        maxFiles: maxFilesProp,
+        maxSize: maxSizeProp,
+        strictValidation,
+        validator,
+    };
+
+    /* IMPORTANT: This component supports both standalone usage and provider usage */
+    // useFileValidation automatically detects if we're in a provider context
+    // If not in provider, create local validation for standalone usage
+    const validation = useFileValidation(validationConfig);
+
+    // Determine whether to use context or local state for files and setFiles
+    const files = filesProp ?? uploadContext?.files ?? [];
+    const setFiles = onFilesChangeProp ?? uploadContext?.setFiles ?? (() => {});
+
+    // Intentionally check both props and context with precedence order
+    const disabled = disabledProp || uploadContext?.disabled;
+    const onDrop = onDropProp ?? uploadContext?.onDrop;
+    const onDropAccepted = onDropAcceptedProp ?? uploadContext?.onDropAccepted;
+    const onDropRejected = onDropRejectedProp ?? uploadContext?.onDropRejected;
+    const maxFiles = maxFilesProp ?? validation.maxFiles;
+    const maxSize = maxSizeProp ?? validation.maxSize;
+    const accept = acceptProp ?? validation.accept;
+    /* END IMPORTANT */
+
+    // Check if upload is disabled based on current state
+    const { hasReachedFileLimit, isDisabled } = useUploadAvailability({
+        disabled,
+        files,
+        maxFiles,
+    });
+
+    const formattedMaxSize = maxSize ? formatFileSize(maxSize) : undefined;
+
+    const defaultHelpText = formattedMaxSize ? `File size must be smaller than ${formattedMaxSize}` : undefined;
+
+    // If custom help text is provided, use it. Otherwise, use the default help text, or hide it.
+    const helpTextToDisplay = hideHelpText ? undefined : (helpText ?? defaultHelpText);
+
+    // Configure text based on multiple vs single file mode
+    const allowMultipleFiles = maxFiles === undefined || maxFiles > 1;
+    const filePluralizationText = allowMultipleFiles ? 'files' : 'a file';
+    const mimeTypes = getMimeTypes(accept);
+
+    // Set up drag and drop handlers
+    const handleDrop = useHandleDrop({
+        files,
+        onDrop,
+        onDropAccepted,
+        onDropRejected,
+        setFiles,
+        validation,
+    });
+
+    const handleDragEnter = useHandleDragEnter({
+        files,
+        mimeTypes,
+        validation,
+        validator,
+    });
+
+    // Configure the dropzone
+    const { getInputProps, getRootProps, isDragActive, isDragReject } = useDropzone({
+        accept: mimeTypes,
+        disabled: isDisabled,
+        maxSize,
+        multiple: allowMultipleFiles,
+        onDragEnter: disableDragValidation ? validation.clearAllValidation : handleDragEnter,
+        onDragLeave: validation.clearAllValidation,
+        onDrop: handleDrop,
+        // @ts-expect-error Our validator returns potentially function-based messages, React-Dropzone expects strings.
+        // This is intentional and allows us to resolve dynamic messages later with proper file counts.
+        validator: createDropzoneValidator(validation),
+    });
+
+    // Determine Dropzone styles based on interaction state
+    const activeCode = isDragActive ? validation.dragValidationError : validation.dropValidationErrors[0];
+    const uploadZoneStyles = getUploadZoneStyles({
+        disabled: isDisabled,
+        disableDragValidation,
+        isDragActive,
+        validationError: activeCode,
+    });
+
+    return (
+        <div
+            aria-label={ariaLabel}
+            className={cn('flex h-full w-full flex-col gap-[4px]', className)}
+            role="region"
+        >
+            {labelText && <LabelMini color={isDisabled ? 'disabled' : 'secondary'}>{labelText}</LabelMini>}
+            <div
+                {...getRootProps({
+                    'aria-disabled': isDisabled,
+                    className: cn('group min-h-[88px] w-full', uploadZoneStyles),
+                    'data-testid': `${dataTestId}-container`,
+                    onClick: validation.clearAllValidation,
+                    role: 'button',
+                })}
+            >
+                <input
+                    {...getInputProps({
+                        'aria-label': `Upload ${filePluralizationText}`,
+                        'data-testid': `${dataTestId}-input`,
+                    })}
+                />
+                <DropzoneContent
+                    dropzoneTextProps={{
+                        disableDragValidation,
+                        filePluralizationText,
+                        hasReachedFileLimit,
+                        isDisabled,
+                        isDragActive,
+                        isDragReject,
+                        maxFiles,
+                        validation,
+                    }}
+                    isDisabled={isDisabled}
+                />
+            </div>
+            <div
+                className={cn('relative flex flex-col gap-[4px]', {
+                    'items-center': helpTextAlignCenter,
+                })}
+            >
+                {helpTextToDisplay && (
+                    <Caption color={isDisabled ? 'disabled' : 'secondary'}>{helpTextToDisplay}</Caption>
+                )}
+                {!hideErrors &&
+                    validation.dropValidationErrors.map((error, index) => (
+                        <Caption
+                            color="critical"
+                            key={`${error.code}-${index}`}
+                            role="alert"
+                        >
+                            {error.message}
+                        </Caption>
+                    ))}
+            </div>
+            {/* Display debug information around fileRejections when showDebugger is true */}
+            {showDebugger && <FileDropzoneDebugger fileRejections={validation.fileRejections} />}
+        </div>
+    );
+};
+
+FileDropzone.displayName = 'FileDropzone';

package/src/FileUpload/components/FileDropzone/components/DropzoneContent/DropzoneContent.tsx

@@ -0,0 +1,28 @@
+import { TextColorAliases } from '@evolve.ui/theme-system';
+
+import { UploadSimple } from '../../../../../Icons';
+import { BodyPrimary } from '../../../../../Typography/Text/Text';
+import { DropzoneText } from './DropzoneText';
+
+type DropzoneContentProps = {
+    dropzoneTextProps: React.ComponentProps<typeof DropzoneText>;
+    isDisabled: boolean;
+};
+
+export const DropzoneContent = ({ dropzoneTextProps, isDisabled }: DropzoneContentProps) => {
+    const dropzoneTextColor: TextColorAliases = isDisabled ? 'disabled' : 'primary';
+
+    return (
+        <div className="flex w-full flex-col items-center gap-xs">
+            <UploadSimple color={dropzoneTextColor} />
+            <BodyPrimary
+                className="text-center"
+                color={dropzoneTextColor}
+            >
+                <DropzoneText {...dropzoneTextProps} />
+            </BodyPrimary>
+        </div>
+    );
+};
+
+DropzoneContent.displayName = 'DropzoneContent';

package/src/FileUpload/components/FileDropzone/components/DropzoneContent/DropzoneText.tsx

@@ -0,0 +1,81 @@
+import { useMemo } from 'react';
+
+import { useWindowIsMobile } from '../../../../../providers';
+import { SubtleLink } from '../../../../../Typography/Links/Links';
+import { UploadValidationContextType } from '../../../../providers/UploadValidationProvider';
+
+type DropzoneTextProps = {
+    disableDragValidation: boolean;
+    filePluralizationText: string;
+    hasReachedFileLimit: boolean;
+    isDisabled: boolean;
+    isDragActive: boolean;
+    isDragReject: boolean;
+    maxFiles?: number;
+    validation: UploadValidationContextType;
+};
+
+export const DropzoneText = ({
+    disableDragValidation,
+    filePluralizationText,
+    hasReachedFileLimit,
+    isDisabled,
+    isDragActive,
+    isDragReject,
+    maxFiles,
+    validation,
+}: DropzoneTextProps) => {
+    const isMobile = useWindowIsMobile();
+    const { dragValidationError } = validation;
+
+    const dropzoneText = useMemo(() => {
+        // Static states (before any drag)
+        if (hasReachedFileLimit) {
+            return <>{`${maxFiles} file limit reached. Remove files to upload more.`}</>;
+        }
+
+        // Show validation messages during drag
+        if (isDragActive && dragValidationError?.code) {
+            return <>{dragValidationError.message}</>;
+        }
+
+        // Show "Drop files here" during valid drag
+        if (isDragActive && (disableDragValidation || !isDragReject)) {
+            return <>Drop files here to upload</>;
+        }
+
+        // Default states (no drag)
+        if (isMobile) {
+            return <>{`Click to browse and add ${filePluralizationText}`}</>;
+        }
+
+        // Desktop default
+        return (
+            <>
+                <SubtleLink
+                    className="group-hover:underline"
+                    disabled={isDisabled}
+                    href="#"
+                    onClick={(e) => e.preventDefault()}
+                >
+                    Browse
+                </SubtleLink>{' '}
+                or drag {filePluralizationText} here to upload
+            </>
+        );
+    }, [
+        filePluralizationText,
+        hasReachedFileLimit,
+        isDisabled,
+        isDragActive,
+        isDragReject,
+        disableDragValidation,
+        maxFiles,
+        isMobile,
+        dragValidationError,
+    ]);
+
+    return <>{dropzoneText}</>;
+};
+
+DropzoneText.displayName = 'DropzoneText';

package/src/FileUpload/components/FileDropzone/components/FileDropzoneDebugger/FileDropzoneDebugger.tsx

@@ -0,0 +1,40 @@
+import { Tabs } from '../../../../../Tabs/Tabs';
+import { FileRejection } from '../../../../types/commonTypes';
+import { FileRejectionsDisplay } from './FileRejectionsDisplay';
+
+type Props = {
+    fileRejections: FileRejection[];
+};
+
+export const FileDropzoneDebugger = ({ fileRejections = [] }: Props) => {
+    return (
+        <div className="mt-md rounded-container p-sm outline-dashed outline-1 -outline-offset-1 outline-border-secondary">
+            <Tabs
+                tabs={[
+                    {
+                        content: (
+                            <FileRejectionsDisplay
+                                displayMode="by-error"
+                                fileRejections={fileRejections}
+                            />
+                        ),
+                        contentId: 'rejections-by-error',
+                        label: 'Errors',
+                    },
+                    {
+                        content: (
+                            <FileRejectionsDisplay
+                                displayMode="by-file"
+                                fileRejections={fileRejections}
+                            />
+                        ),
+                        contentId: 'rejections-by-file',
+                        label: 'Files',
+                    },
+                ]}
+            />
+        </div>
+    );
+};
+
+FileDropzoneDebugger.displayName = 'FileDropzoneDebugger';

package/src/FileUpload/components/FileDropzone/components/FileDropzoneDebugger/FileRejectionsDisplay.tsx

@@ -0,0 +1,110 @@
+import { Badge } from '../../../../../Badge/Badge';
+import { ColumnType, Table } from '../../../../../Table';
+import { BodyPrimary, H4 } from '../../../../../Typography/Text/Text';
+import { FileErrorCode, FileRejection } from '../../../../types';
+import { builtInErrorCodes } from '../../../../utils/constants';
+
+type DisplayMode = 'by-error' | 'by-file';
+
+type Props = {
+    displayMode: DisplayMode;
+    fileRejections: FileRejection[];
+};
+
+type TableData = {
+    col1: string;
+    col2: string | string[];
+    col3: string | string[];
+    key: string;
+};
+
+const BadgeCell = ({ codes }: { codes: string | string[] }) => {
+    const codeArray = Array.isArray(codes) ? codes : [codes];
+
+    return (
+        <div className="flex flex-col justify-start gap-[4px]">
+            {codeArray.map((code, index) => (
+                <Badge
+                    className="my-[2px]"
+                    color="critical"
+                    data-testid={`badge-${code}`}
+                    emphasis={builtInErrorCodes.includes(code as FileErrorCode) ? 'subtle' : 'bold'}
+                    key={`${code}-${index}`}
+                    size="xs"
+                >
+                    {code}
+                </Badge>
+            ))}
+        </div>
+    );
+};
+
+export const FileRejectionsDisplay = ({ displayMode, fileRejections = [] }: Props) => {
+    const totalErrors = fileRejections.reduce((sum, rejection) => sum + rejection.errors.length, 0);
+
+    const tableData =
+        displayMode === 'by-error'
+            ? fileRejections.flatMap((rejection, fileIndex) =>
+                  rejection.errors.map((error, errorIndex) => ({
+                      col1: rejection.file.name,
+                      col2: error.code,
+                      col3: error.message,
+                      key: `${rejection.file.name}-${fileIndex}-${errorIndex}`,
+                  }))
+              )
+            : fileRejections.map((rejection, index) => ({
+                  col1: rejection.file.name,
+                  col2: rejection.errors.map((error) => error.code),
+                  col3: rejection.errors.map((error) => error.message),
+                  key: `${rejection.file.name}-${index}`,
+              }));
+
+    const columns: ColumnType<TableData>[] = [
+        {
+            align: 'left',
+            header: 'File Name',
+            key: 'col1',
+        },
+        {
+            header: displayMode === 'by-error' ? 'Error Code' : 'Error Codes',
+            key: 'col2',
+            renderItem: (data: TableData) => <BadgeCell codes={data.col2} />,
+        },
+        {
+            header: displayMode === 'by-error' ? 'Message' : 'Messages',
+            key: 'col3',
+            renderItem:
+                displayMode === 'by-file'
+                    ? (data: TableData) => (
+                          <div className="flex flex-col gap-[2px]">
+                              {(data.col3 as string[]).map((message, index) => (
+                                  <span key={index}>{message}</span>
+                              ))}
+                          </div>
+                      )
+                    : undefined,
+        },
+    ];
+
+    return (
+        <>
+            <div className="mb-xs mt-sm flex items-center justify-between px-[2px]">
+                <H4>File Rejections {displayMode === 'by-error' ? '(by Error)' : '(by File)'}</H4>
+                <BodyPrimary>
+                    {fileRejections.length} files ({totalErrors} errors)
+                </BodyPrimary>
+            </div>
+            <Table
+                columns={columns}
+                data={tableData}
+                emptyStateHeaderText="No files rejected"
+                emptyStateSupportingText="Upload files to monitor rejections"
+                fillHorizontal
+                hideBorder
+                rowDensity="sm"
+            />
+        </>
+    );
+};
+
+FileRejectionsDisplay.displayName = 'FileRejectionsDisplay';

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

@@ -0,0 +1,183 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useContext } from 'react';
+import { useDropzone } from 'react-dropzone';
+
+import { useFileValidation } from '../../hooks';
+import { useHandleDragEnter } from '../../hooks/upload/useHandleDragEnter/useHandleDragEnter';
+import { useHandleDrop } from '../../hooks/upload/useHandleDrop/useHandleDrop';
+import { useUploadAvailability } from '../../hooks/upload/useUploadAvailability/useUploadAvailability';
+import { createDropzoneValidator } from '../../hooks/validation/createDropzoneValidator';
+import { FileUploadContext, FileUploadContextType } from '../../providers/FileUploadProvider';
+import { FileDropzoneOverlayProps } from '../../types/sharedTypes';
+import { getMimeTypes } from '../../utils/getMimeTypes';
+import { FileDropzoneDebugger } from '../FileDropzone/components/FileDropzoneDebugger/FileDropzoneDebugger';
+import { OverlayDropzoneContent } from './components/OverlayDropzoneContent';
+import { getUploadOverlayStyles } from './styles';
+
+export const FileDropzoneOverlay = ({
+    accept: acceptProp,
+    ariaLabel,
+    children,
+    className,
+    'data-testid': dataTestId = 'file-dropzone-overlay',
+    disableClickThrough = false,
+    disabled: disabledProp = false,
+    disableDragValidation = false,
+    dragText = 'Drop files to upload',
+    error,
+    files: filesProp,
+    icon,
+    maxFiles: maxFilesProp,
+    maxSize: maxSizeProp,
+    onDrop: onDropProp,
+    onDropAccepted: onDropAcceptedProp,
+    onDropRejected: onDropRejectedProp,
+    onFilesChange: onFilesChangeProp,
+    showDebugger,
+    strictValidation,
+    styleOptions,
+    validator,
+}: FileDropzoneOverlayProps) => {
+    const uploadContext = useContext<FileUploadContextType | undefined>(FileUploadContext);
+
+    const validationConfig = {
+        accept: acceptProp,
+        error,
+        maxFiles: maxFilesProp,
+        maxSize: maxSizeProp,
+        strictValidation,
+        validator,
+    };
+
+    /* IMPORTANT: This component supports both standalone usage and provider usage */
+    // useFileValidation automatically detects if we're in a provider context
+    // If not in provider, create local validation for standalone usage
+    const validation = useFileValidation(validationConfig);
+
+    // Determine whether to use context or local state for files and setFiles
+    const files = filesProp ?? uploadContext?.files ?? [];
+    const setFiles = onFilesChangeProp ?? uploadContext?.setFiles ?? (() => {});
+
+    // Intentionally check both props and context with precedence order
+    const disabled = disabledProp || uploadContext?.disabled;
+    const onDrop = onDropProp ?? uploadContext?.onDrop;
+    const onDropAccepted = onDropAcceptedProp ?? uploadContext?.onDropAccepted;
+    const onDropRejected = onDropRejectedProp ?? uploadContext?.onDropRejected;
+    const maxFiles = maxFilesProp ?? validation.maxFiles;
+    const maxSize = maxSizeProp ?? validation.maxSize;
+    const accept = acceptProp ?? validation.accept;
+    /* END IMPORTANT */
+
+    // Check if upload is disabled based on current state
+    const { isDisabled } = useUploadAvailability({
+        disabled,
+        files,
+        maxFiles,
+    });
+
+    // Configure text based on multiple vs single file mode
+    const allowMultipleFiles = maxFiles === undefined || maxFiles > 1;
+    const filePluralizationText = allowMultipleFiles ? 'files' : 'a file';
+    const mimeTypes = getMimeTypes(accept);
+
+    // Set up drag and drop handlers
+    const handleDrop = useHandleDrop({
+        files,
+        onDrop,
+        onDropAccepted,
+        onDropRejected,
+        setFiles,
+        validation,
+    });
+
+    const handleDragEnter = useHandleDragEnter({
+        files,
+        mimeTypes,
+        validation,
+        validator,
+    });
+
+    // Configure the dropzone
+    const { getInputProps, getRootProps, isDragActive } = useDropzone({
+        accept: mimeTypes,
+        disabled: isDisabled,
+        maxSize,
+        multiple: allowMultipleFiles,
+        noClick: !disableClickThrough, // When clickThrough is not disabled, prevent file picker dialog
+        noKeyboard: !disableClickThrough, // When clickThrough is not disabled, prevent keyboard interactions
+        onDragEnter: disableDragValidation ? validation.clearAllValidation : handleDragEnter,
+        onDragLeave: validation.clearAllValidation,
+        onDrop: handleDrop,
+        // @ts-expect-error Our validator returns potentially function-based messages, React-Dropzone expects strings.
+        // This is intentional and allows us to resolve dynamic messages later with proper file counts.
+        validator: createDropzoneValidator(validation),
+    });
+
+    // Determine Dropzone styles based on interaction state
+    const activeCode = isDragActive ? validation.dragValidationError : validation.dropValidationErrors[0];
+    const uploadZoneStyles = getUploadOverlayStyles({
+        disableClickThrough,
+        disabled: isDisabled,
+        disableDragValidation,
+        isDragActive,
+        styleOptions,
+        validationError: activeCode,
+    });
+
+    // Map innerPadding to Tailwind padding classes
+    const paddingMap = {
+        '2xl': 'p-2xl',
+        lg: 'p-lg',
+        md: 'p-md',
+        sm: 'p-sm',
+        xl: 'p-xl',
+        xs: 'p-xs',
+    } as const;
+    const innerPaddingClass = styleOptions?.innerPadding ? paddingMap[styleOptions.innerPadding] : undefined;
+    const fillParentClass = styleOptions?.fillParent ? 'h-full' : 'relative';
+
+    return (
+        <>
+            <div
+                {...getRootProps({
+                    'aria-disabled': isDisabled,
+                    'aria-label': ariaLabel ?? (isDragActive ? dragText : undefined),
+                    className: cn('group/dropzone', fillParentClass, className),
+                    'data-testid': `${dataTestId}-root`,
+                })}
+            >
+                <input
+                    {...getInputProps({
+                        'aria-label': `Upload ${filePluralizationText}`,
+                        'data-testid': `${dataTestId}-input`,
+                    })}
+                />
+
+                {/* Child content - isolation-isolate scopes children's z-indices so the overlay can sit above them */}
+                <div className={cn('isolate', fillParentClass, innerPaddingClass)}>{children}</div>
+
+                {/* Visual overlay - only appears when dragging */}
+                <div
+                    className={cn('w-full', uploadZoneStyles)}
+                    data-testid={`${dataTestId}-container`}
+                >
+                    {/* Only show visual feedback when actively dragging */}
+                    {isDragActive && (
+                        <OverlayDropzoneContent
+                            accept={accept}
+                            customIcon={icon}
+                            dragText={dragText}
+                            isDragActive={isDragActive}
+                            maxFiles={maxFiles}
+                            validation={validation}
+                        />
+                    )}
+                </div>
+            </div>
+            {/* Display debug information around fileRejections when showDebugger is true */}
+            {showDebugger && <FileDropzoneDebugger fileRejections={validation.fileRejections} />}
+        </>
+    );
+};
+
+FileDropzoneOverlay.displayName = 'FileDropzoneOverlay';