file-upload.tsx

Overview

The file-upload.tsx file provides a comprehensive, accessible, and customizable React component library for file uploading functionality. It supports drag-and-drop, file selection dialogs, file validation, progress tracking, and file metadata display. The library is designed with modular components that can be composed together or used individually, enabling flexible integration into React applications.

Key features include:

• Controlled and uncontrolled file upload state management.

• Drag-and-drop support with visual feedback.

• File type, size, and count validation.

• File upload progress tracking with multiple progress bar styles.

• File preview with automatic image thumbnail generation or icon fallback.

• Accessibility with ARIA attributes and keyboard support.

• Flexible styling with asChild prop for custom component wrappers.

• Context-based state management with React Context and a custom store.

Components and Utilities

1. FileUploadRoot

Purpose:
The root component that manages the overall file upload state and provides context to child components.

Props:

Usage Example:

<FileUploadRoot
  accept="image/*"
  maxFiles={5}
  maxSize={5 * 1024 * 1024}
  onUpload={async (files, { onProgress, onSuccess, onError }) => {
    for (const file of files) {
      // simulate upload
      for (let p = 0; p <= 100; p += 10) {
        onProgress(file, p);
        await new Promise(r => setTimeout(r, 100));
      }
      onSuccess(file);
    }
  }}
>
  {/* Dropzone, List, etc. */}
</FileUploadRoot>

2. FileUploadDropzone

Purpose:
Area where users can drag and drop files, click to open file dialog, or paste files from clipboard.

Props:

Features:

• Handles drag events to show active drag state.

• Clicking outside the trigger activates the file input.

• Supports keyboard interaction (Enter or Space triggers file dialog).

• Supports pasting files from clipboard.

3. FileUploadTrigger

Purpose:
A button or custom element that triggers the file selection dialog.

Props:

4. FileUploadList

Purpose:
Renders the list of uploaded files.

Props:

5. FileUploadItem

Purpose:
Represents a single file item in the upload list, including status and accessibility info.

Props:

6. FileUploadItemPreview

Purpose:
Renders a preview of the file, either an image thumbnail or a file type icon.

Props:

7. FileUploadItemMetadata

Purpose:
Displays metadata for a file such as name, size, and error message if any.

Props:

8. FileUploadItemProgress

Purpose:
Displays upload progress for an individual file.

Props:

9. FileUploadItemDelete

Purpose:
Button to remove a file from the upload list.

Props:

10. FileUploadClear

Purpose:
Button to clear all files from the upload list.

Props:

Hooks and Utilities

useLazyRef<T>(fn: () => T): React.RefObject<T>

Creates a ref that initializes lazily once.

• Parameters:
  fn - initializer function returning the value to store in the ref.

• Returns:
  A React ref object with the initialized value.

useDirection(dirProp?: Direction): Direction

Determines text direction ('ltr' or 'rtl') from context or prop.

useStore<T>(selector: (state: StoreState) => T): T

Subscribes to the internal store and selects a slice of the state.

• Parameters:
  selector - function to select part of store state.

• Returns:
  The selected state slice, re-rendering component when it changes.

useStoreContext(consumerName: string)

Accesses the internal store context, ensuring it exists.

useFileUploadContext(consumerName: string)

Accesses the file upload context, providing shared IDs, refs, and flags.

formatBytes(bytes: number): string

Formats bytes into human-readable strings (e.g., "1.2 MB").

getFileIcon(file: File): React.ReactNode

Returns an appropriate icon component based on the file's MIME type or extension.

Internal State Management

The file upload uses a custom store implemented with:

• createStore function creating a state container with listeners and dispatch.

• State includes:

  • files: Map of File to FileState (progress, status, error).

  • dragOver: Whether files are being dragged over dropzone.

  • invalid: Whether the current file state is invalid (e.g., validation error).

• Actions to add, remove files, update progress, set errors, clear all, and set drag state.

• The store notifies subscribers on state changes using React.useSyncExternalStore.

File Validation and Upload Workflow

1. File selection or drag-and-drop triggers onFilesChange.

2. Files are validated against:

   • Max number of files.

   • Custom validation function.

   • Accepted file types.

   • Max file size.

3. Accepted files are added to the store; rejected files trigger callbacks.

4. If an onUpload function is provided, it is called with accepted files and callbacks for progress, success, and error.

5. Progress updates dispatch store actions to update UI.

6. Errors and success update file status accordingly.

7. Users can delete individual files or clear all files.

Interaction with Other Parts of the System

• Utility functions come from external imports:

  • cn for className concatenation.

  • Slot from @radix-ui/react-slot for flexible component composition.

  • Icon components from lucide-react provide file type icons.

• The file upload components can be used standalone or integrated into larger forms or UI frameworks.

• Consumers provide upload logic via onUpload callback to integrate with backend APIs or storage services.

• Accessibility is ensured with ARIA roles, labels, and keyboard navigation support.

• The FileUploadRoot component provides context to children, enabling state sharing without prop drilling.

Important Implementation Details

• Uses React contexts (StoreContext, FileUploadContext, FileUploadItemContext) for state and metadata sharing.

• Uses a WeakMap cache to store and revoke object URLs for image previews to avoid memory leaks.

• Supports controlled and uncontrolled modes for file state.

• Throttles progress updates using requestAnimationFrame for efficient UI updates.

• Validates files synchronously before upload and rejects invalid files with appropriate messages.

• Drag-and-drop and paste support are implemented with proper event handling and accessibility considerations.

• Uses aria-* attributes extensively for screen reader support.

• Supports customizable rendering via asChild prop and render props in FileUploadItemPreview.

Visual Diagram: Component Structure and Interaction

componentDiagram
    direction LR

    FileUploadRoot <|-- FileUploadDropzone
    FileUploadRoot <|-- FileUploadTrigger
    FileUploadRoot <|-- FileUploadList

    FileUploadList <|-- FileUploadItem

    FileUploadItem <|-- FileUploadItemPreview
    FileUploadItem <|-- FileUploadItemMetadata
    FileUploadItem <|-- FileUploadItemProgress
    FileUploadItem <|-- FileUploadItemDelete

    FileUploadRoot "provides" --> StoreContext
    FileUploadRoot "provides" --> FileUploadContext

    FileUploadDropzone "uses" --> StoreContext
    FileUploadTrigger "uses" --> FileUploadContext
    FileUploadList "uses" --> StoreContext,FileUploadContext
    FileUploadItem "uses" --> StoreContext,FileUploadContext,FileUploadItemContext

    FileUploadItemPreview "uses" --> FileUploadItemContext,FileUploadContext
    FileUploadItemMetadata "uses" --> FileUploadItemContext,FileUploadContext
    FileUploadItemProgress "uses" --> FileUploadItemContext
    FileUploadItemDelete "uses" --> FileUploadItemContext,StoreContext

Summary

The file-upload.tsx file is a robust, accessible React file upload component suite that manages file selection, validation, uploading, and UI feedback via a modular set of components and hooks. It allows detailed customization and integration points for file handling workflows, making it suitable for complex file upload use cases in React applications.