@osmandvc/react-upload-control 0.2.1 → 0.3.1

package/README.md

@@ -1,14 +1,37 @@
 # React Upload Control
 
-A modern, flexible file upload control for React applications.
+[![npm version](https://img.shields.io/npm/v/@osmandvc/react-upload-control.svg)](https://www.npmjs.com/package/@osmandvc/react-upload-control)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> ⚠️ **Early Release Notice:** This library is in active development! While it's already battle-tested and production-ready, we're working on comprehensive documentation and additional features. The current docs provide basic usage - stay tuned for in-depth guides, examples, and advanced customization options coming soon!
+A modern, flexible file upload control for React applications.
 
 React Upload Control is a free, lightweight and open-source file uploader library designed for modern React applications. This library is crafted to provide a high-quality developer experience (DX), making it easy to use for simple file uploads while offering extensive customization options for advanced use cases.
 
+## Demo
+
+Check out our interactive demo cases here:  
+[React Upload Control Demo](https://675c9582166050575d7b72e2-bzirycxazq.chromatic.com)
+
+## Why React Upload Control? 🤷‍♂️
+
+Born from real-world needs in a production environment, React Upload Control addresses common limitations found in existing file upload solutions. While there are many file upload libraries available, we found that most of them fell short in crucial areas:
+
+- 🔄 **No Drag-to-Reorder:** Most solutions lack built-in file ordering capabilities, a crucial feature for many applications
+- 📚 **Documentation Gaps:** Many libraries either have excessive boilerplate, insufficient documentation or lacking DX
+- 🔧 **Maintenance Issues:** Several options are outdated or no longer actively maintained
+- 🎨 **Poor UI/UX:** Many unstyled options result in subpar user interfaces
+- 🔒 **Vendor Lock-in:** Some solutions tie you to specific cloud services or platforms
+- 📦 **Bloated Dependencies:** Often file uploaders come bundled within larger UI libraries, increasing your bundle size
+
+React Upload Control was created to solve these problems, offering a standalone, modern file uploader that's both powerful and flexible. Whether you need a simple file upload control or a feature-rich solution with file processing capabilities, you can customize it to your specific needs without compromising on quality or developer experience.
+
+## Features summary 🔥
+
 - 🚀 **Modern Stack:** Built with React 18+ and TypeScript for type-safe development
 - 📁 **Drag & Drop:** Intuitive file uploading with visual feedback and validation
 - 📋 **File Management:** Drag-to-reorder capability for organizing user uploads
+- 🔄 **File Processing:** Optional pre/post-processing capabilities with [@osmandvc/react-upload-control-processors](https://www.npmjs.com/package/@osmandvc/react-upload-control-processors) or custom integrations
 - 📷 **Camera Integration:** Camera integration for capturing photos directly
 - 💻 **Developer Experience:** Simple API with comprehensive TypeScript support and documentation
 - 🌐 **Internationalization:** Built-in i18n support for multiple languages (currently English and German)
@@ -19,11 +42,6 @@ React Upload Control is a free, lightweight and open-source file uploader librar
 - ⚙️ **Unopinionated:** You decide how and where files are uploaded, no vendor lock-in
 - 🔓 **Open Source:** Free to use and modify under the MIT license
 
-## Demo
-
-Check out our interactive demo cases here:  
-[React Upload Control Demo](https://675c9582166050575d7b72e2-kpevajcgoj.chromatic.com/)
-
 ## Installation
 
 To install React Upload Control, use npm or yarn:
@@ -83,8 +101,6 @@ The upload handler receives two parameters:
 1. `files`: An array of `UploadedFile` objects to be uploaded
 2. `onProgressChange`: A callback function to update the upload progress
 
-The upload handler should return an array of `UploadFileResult` objects, which specify the success, error, and metadata for each file upload. The library will handle the UI updates based on the progress updates and final results you provide.
-
 Here are two examples of implementing an upload handler:
 
 ### Example 1: Simple Batch Upload
@@ -281,6 +297,58 @@ function MyFileUpload() {
 }
 ```
 
+### Understanding UploadFileResult
+
+The upload handler must return an array of `UploadFileResult` objects - one for each uploaded file. Here's the structure:
+
+```typescript
+type UploadFileResult = {
+  // The ID of the file that was uploaded (must match the original file.id)
+  fileId: string;
+
+  // Whether the upload was successful
+  success: boolean;
+
+  // Optional error information if success is false
+  error?: {
+    text: string; // Human-readable error message
+    code: string; // Error code for programmatic handling
+  };
+
+  // Optional metadata to attach to the file
+  metadata?: {
+    [key: string]: any; // Any additional data you want to store with the file
+  };
+};
+```
+
+Example of a successful upload result:
+
+```typescript
+{
+  fileId: "file123",
+  success: true,
+  metadata: {
+    url: "https://example.com/uploads/file123.jpg",
+    uploadedAt: "2025-01-02T12:00:00Z",
+    size: 1024000
+  }
+}
+```
+
+Example of a failed upload result:
+
+```typescript
+{
+  fileId: "file456",
+  success: false,
+  error: {
+    text: "File size exceeds server limit",
+    code: "SIZE_LIMIT_EXCEEDED"
+  }
+}
+```
+
 ## onDelete Handler
 
 The `onDelete` handler is designed to be non-blocking and does not include progress tracking. This is intentional for better UX - since it's primarily used for cleanup when resetting a control with already finished uploads. Users should be able to reset the control immediately without waiting for deletion to complete or being blocked by deletion errors.
@@ -351,41 +419,50 @@ The provider component that manages the upload state and configuration.
 | disableFileSystem | boolean                | false     | Disable file system uploads |
 | className         | string                 | undefined | Additional CSS classes      |
 
-## Understanding the UploadedFile Type
+## File Processing
 
-When implementing your upload handlers, you'll work with the `UploadedFile` type, which provides access to various file properties:
+React Upload Control supports file processing through the optional [@osmandvc/react-upload-control-processors](https://www.npmjs.com/package/@osmandvc/react-upload-control-processors) package. This enables you to process files before or after upload, with built-in support for PDF manipulation and extensible architecture for custom processors.
 
-```typescript
-interface UploadedFile {
-  id: string; // Unique identifier for the file
-  file?: File; // The actual File object
-  name: string; // File name
-  size?: number; // File size in bytes
-  type: string; // MIME type
-  base64Uri?: string; // Base64 encoded file content
-  previewImg?: {
-    // Preview image data (for images)
-    imgBase64Uri: string;
-    width?: number;
-    height?: number;
-  };
-  uploadStatus: {
-    // Current upload status
-    stage?: "IDLE" | "FINISHED" | "FAILED" | "UPLOADING" | "REMOVING";
-    progress?: number; // Upload progress (0-100)
-    error?: {
-      text: string; // Error message
-      code: string; // Error code
-    };
-  };
-  order?: number; // File order in the list
-  metadata?: {
-    // Custom metadata
-    [key: string]: any;
-  };
+```bash
+npm install @osmandvc/react-upload-control-processors
+```
+
+### Example: PDF to JPEG Conversion
+
+```tsx
+import {
+  FileUploadControl,
+  UploadedFile,
+  UploadedFilesProvider,
+  UploadFileResult,
+} from "@osmandvc/react-upload-control";
+import { processPdfToJpeg } from "@osmandvc/react-upload-control-processors";
+
+function FileUploadTest() {
+  return (
+    <div className="max-w-lg">
+      <UploadedFilesProvider
+        config={{
+          mimeTypes: ["image/png", "image/jpeg", "application/pdf"],
+          disableSorting: true,
+        }}
+        handlers={{
+          onUpload: handleUpload,
+          onFinish: handleFinish,
+          preProcessFiles: {
+            "application/pdf": processPdfToJpeg,
+          },
+        }}
+      >
+        <FileUploadControl />
+      </UploadedFilesProvider>
+    </div>
+  );
 }
 ```
 
+You can see a demo of this in action [here](https://675c9582166050575d7b72e2-bzirycxazq.chromatic.com/?path=/story/examples-upload-control-with-pdf-pre-processing--default).
+
 ## Creating Custom Upload Sources and Destinations
 
 The `useUploadFilesProvider` hook allows you to create your own file sources (like drop areas) and file destinations (like file lists) with ease. The provider handles all the complex validation and state management for you.