@osmandvc/react-upload-control 0.2.1

package/README.md

@@ -0,0 +1,421 @@
+# React Upload Control
+
+A modern, flexible file upload control for React applications.
+
+> ⚠️ **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!
+
+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.
+
+- 🚀 **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
+- 📷 **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)
+- 🎨 **Beautiful UI:** Modern, responsive design powered by Tailwind CSS
+- 📱 **Mobile Ready:** Optimized experience across all device sizes
+- ⚡ **Async Processing:** Handle file uploads asynchronously with progress updates
+- 🔍 **File Preview:** Built-in preview support for images
+- ⚙️ **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:
+
+```bash
+npm install @osmandvc/react-upload-control
+```
+
+or
+
+```bash
+yarn add @osmandvc/react-upload-control
+```
+
+## Getting Started
+
+This section will guide you through the process of setting up everything you need to get started. The library is built around the concept of providers and the React Context API, which means you need to wrap your application in a `UploadedFilesProvider` provider. If you want to use the default use case of a list of files and a drop area, you can do this by wrapping your `FileUploadControl` component in the provider. An minimal example of this can be seen below:
+
+```tsx
+import React, { PropsWithChildren } from "react";
+import {
+  FileUploadControl,
+  UploadedFilesProvider,
+  UploadedFile,
+  UploadFileResult,
+} from "react-upload-control";
+
+function MyFileUploadParent(props: PropsWithChildren) {
+  // Your custom delete and upload handlers (more about them later)...
+  // function handleDelete(files: UploadedFile[]) {...}
+  // function handleUpload(files: UploadedFile[], onProgressChange: (...) => void) {...}
+
+  function handleFinish(files: UploadedFile[]) {
+    console.log(files);
+  }
+
+  return (
+    <UploadedFilesProvider
+      handlers={{ onUpload: handleUpload, onFinish: handleFinish }}
+      config={{
+        mimeTypes: ["image/png", "image/jpeg"],
+        disableSorting: false, // Disable drag-to-reorder functionality
+      }}
+    >
+      <FileUploadControl />
+    </UploadedFilesProvider>
+  );
+}
+```
+
+## Upload Handler Guide
+
+The upload handler is a crucial part of the library that gives you complete control over how files are processed and uploaded.
+
+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
+
+```tsx
+async function handleUpload(
+  files: UploadedFile[],
+  onProgressChange: (
+    fileId: string,
+    progress: number,
+    error?: { text: string; code: string }
+  ) => void
+): Promise<UploadFileResult[]> {
+  try {
+    // Set initial progress for all files
+    files.forEach((file) => {
+      onProgressChange(file.id, 0);
+    });
+
+    // Create form data with all files
+    const formData = new FormData();
+    files.forEach((file, index) => {
+      if (file.file) {
+        formData.append(`files`, file.file);
+      }
+    });
+
+    // Make API call with all files
+    const response = await fetch("https://api.example.com/upload", {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      throw new Error("Upload failed");
+    }
+
+    // Example API response with processed file data
+    const result = await response.json();
+    // { success: true, files: [{ id: "...", url: "..." }] }
+
+    // Set progress to 100% for all files after successful upload
+    files.forEach((file) => {
+      onProgressChange(file.id, 100);
+    });
+
+    // Return success results with metadata from API
+    return files.map((file, index) => ({
+      fileId: file.id,
+      success: true,
+      metadata: {
+        url: result.files[index].url,
+        uploadedAt: new Date().toISOString(),
+      },
+    }));
+  } catch (error) {
+    // Set error state for all files
+    const errorResult = {
+      text: error.message || "Upload failed",
+      code: "BATCH_UPLOAD_ERROR",
+    };
+
+    // Return error results for all files
+    return files.map((file) => ({
+      fileId: file.id,
+      success: false,
+      error: errorResult,
+    }));
+  }
+}
+
+// Usage with the UploadedFilesProvider
+function MyFileUpload() {
+  return (
+    <UploadedFilesProvider
+      handlers={{
+        onUpload: handleUpload,
+        onFinish: (files) => {
+          // All files are uploaded successfully at this point
+          const urls = files.map((f) => f.metadata.url);
+          console.log("Uploaded file URLs:", urls);
+        },
+      }}
+      config={{
+        mimeTypes: ["image/jpeg", "image/png", "application/pdf"],
+        maxFileSizeMb: 10,
+      }}
+    >
+      <FileUploadControl />
+    </UploadedFilesProvider>
+  );
+}
+```
+
+### Example 2: Real-World AWS S3 Example
+
+```tsx
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { Upload } from "@aws-sdk/lib-storage";
+
+async function handleS3Upload(
+  files: UploadedFile[],
+  onProgressChange: (
+    fileId: string,
+    progress: number,
+    error?: { text: string; code: string }
+  ) => void
+): Promise<UploadFileResult[]> {
+  // Initialize the S3 client
+  const s3Client = new S3Client({
+    region: "your-region",
+    credentials: {
+      accessKeyId: "your-access-key",
+      secretAccessKey: "your-secret-key",
+    },
+  });
+
+  return Promise.all(
+    files.map(async (file) => {
+      try {
+        if (!file.file) throw new Error("No file provided");
+
+        // Generate a unique key for the file
+        const key = `uploads/${Date.now()}-${file.name}`;
+
+        // Create the upload
+        const upload = new Upload({
+          client: s3Client,
+          params: {
+            Bucket: "your-bucket-name",
+            Key: key,
+            Body: file.file,
+            ContentType: file.file.type,
+            // Optional: Set additional parameters
+            // ACL: 'public-read',
+            // Metadata: { /* your metadata */ }
+          },
+        });
+
+        // Handle upload progress
+        upload.on("httpUploadProgress", (progress) => {
+          const percentage = Math.round(
+            ((progress.loaded || 0) * 100) / (progress.total || 100)
+          );
+          onProgressChange(file.id, percentage);
+        });
+
+        // Perform the upload
+        await upload.done();
+
+        // Return success result with the S3 URL
+        return {
+          fileId: file.id,
+          success: true,
+          metadata: {
+            url: `https://your-bucket-name.s3.your-region.amazonaws.com/${key}`,
+          },
+        };
+      } catch (error) {
+        console.error("S3 upload error:", error);
+        return {
+          fileId: file.id,
+          success: false,
+          error: {
+            text: error.message || "S3 upload failed",
+            code: "S3_UPLOAD_ERROR",
+          },
+        };
+      }
+    })
+  );
+}
+
+// Usage with the UploadedFilesProvider
+function MyFileUpload() {
+  return (
+    <UploadedFilesProvider
+      handlers={{
+        onUpload: handleS3Upload,
+        onFinish: (files) => {
+          // All files are successfully uploaded at this point
+          const urls = files.map((f) => f.metadata.url);
+          console.log("Uploaded file URLs:", urls);
+        },
+      }}
+      config={{
+        mimeTypes: ["image/jpeg", "image/png", "application/pdf"],
+        maxFileSizeMb: 10,
+      }}
+    >
+      <FileUploadControl />
+    </UploadedFilesProvider>
+  );
+}
+```
+
+## 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.
+
+```typescript
+interface Props {
+  onDelete?: (files: UploadedFile[]) => void | Promise<void>;
+}
+```
+
+> Note: Unlike `onUpload`, the `onDelete` handler won't show progress or block the UI. This ensures users can quickly reset or clear their upload state without delays.
+
+## Core Components
+
+### FileUploadControl
+
+The default component that provides the file upload interface with a FileList and FileDropArea.
+
+```tsx
+<FileUploadControl
+  size="auto" // 'auto' | 'sm' | 'lg'
+  disableCamera={false} // Disable camera integration
+  disableFileSystem={false} // Disable file system uploads
+/>
+```
+
+### UploadedFilesProvider
+
+The provider component that manages the upload state and configuration.
+
+```tsx
+<UploadedFilesProvider
+  config={{
+    mimeTypes: ["image/jpeg", "image/png"], // Allowed file types
+    maxFileSizeMb: 10, // Maximum file size in MB
+    multiple: true, // Allow multiple file uploads
+    maxFiles: 5, // Maximum number of files
+    locale: "en", // Locale for i18n
+    resetOnFinish: false, // Reset state after finish
+    disableSorting: false, // Disable drag-to-reorder functionality
+  }}
+  handlers={{
+    onUpload: handleUpload, // Upload handler function
+    onDelete: handleDelete, // Delete handler function
+    onFinish: handleFinish, // Finish handler function
+  }}
+/>
+```
+
+## API Reference
+
+### UploadedFilesProvider Props
+
+| Prop      | Type                                                                                                                                                                              | Default   | Description                                 |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------- |
+| config    | { mimeTypes: string[], maxFileSizeMb: number, multiple: boolean, maxFiles: number, locale: string, resetOnFinish: boolean, disableSorting: boolean }                              | required  | Configuration object                        |
+| handlers  | { onUpload: (files: UploadedFile[]) => Promise<UploadFileResult[]>, onDelete: (files: UploadedFile[]) => Promise<UploadFileResult[]>, onFinish: (files: UploadedFile[]) => void } | required  | Handlers object                             |
+| children  | React.ReactNode                                                                                                                                                                   | required  | Child components to render                  |
+| initFiles | UploadedFile[]                                                                                                                                                                    | undefined | Initial files to populate the uploader with |
+| locale    | string                                                                                                                                                                            | 'en'      | Locale for internationalization             |
+
+### FileUploadControl Props
+
+| Prop              | Type                   | Default   | Description                 |
+| ----------------- | ---------------------- | --------- | --------------------------- |
+| size              | 'auto' \| 'sm' \| 'lg' | 'auto'    | Component size variant      |
+| disableCamera     | boolean                | false     | Disable camera integration  |
+| disableFileSystem | boolean                | false     | Disable file system uploads |
+| className         | string                 | undefined | Additional CSS classes      |
+
+## Understanding the UploadedFile Type
+
+When implementing your upload handlers, you'll work with the `UploadedFile` type, which provides access to various file properties:
+
+```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;
+  };
+}
+```
+
+## 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.
+
+The provider abstracts away:
+
+- File validation (size, type, count)
+- Progress tracking
+- File state management
+- Error handling
+- Upload coordination
+
+> 🔍 **Coming Soon**: Detailed documentation on creating custom upload components, handling file preprocessing, and implementing advanced validation logic.
+
+## Customization
+
+React Upload Control is highly customizable. You can tailor it to meet your specific needs by adjusting its configuration and using its extensive API. <i> Detailed documentation coming soon. </i>
+
+## Contributing
+
+We welcome contributions from the community. Feel free to open issues or submit pull requests on our [GitHub repository](https://github.com/osmandvc/react-upload-control).
+
+Please note that while React Upload Control is in an early state and has been battle-tested, bugs may still appear. We would appreciate it if you report any issues you encounter so they can be fixed as soon as possible. Contributions to improve the library are **very welcome**.
+
+Because the library is in its early stages, **we are open to suggestions and feedback. If you have any ideas for new features or enhancements, please don't hesitate to share them with us.**
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+MIT © Osman Deveci

package/dist/FileUploadContainer.d.ts

@@ -0,0 +1,9 @@
+import { PropsWithChildren } from "react";
+/**
+ * The Default Container for the File Upload Control
+ */
+interface ContainerProps extends PropsWithChildren {
+    className?: string;
+}
+export declare const FileUploadContainer: ({ className, children, }: ContainerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/FileUploadControl.d.ts

@@ -0,0 +1,5 @@
+import { FileUploadControlProps } from "./types";
+/**
+ * The Default File-Upload-Control Component with a Drop-Area and a List which displays the Files.
+ */
+export declare const FileUploadControl: ({ className, children, disableCamera, disableFileSystem, size, }: FileUploadControlProps) => import("react/jsx-runtime").JSX.Element;

package/dist/actions/FileDeleteAllButton.d.ts

@@ -0,0 +1 @@
+export declare const FileDeleteAllButton: () => import("react/jsx-runtime").JSX.Element;

package/dist/actions/FileItemActions.d.ts

@@ -0,0 +1,7 @@
+import { UploadedFileItemStage } from "../types";
+type Props = {
+    id: string;
+    stage?: UploadedFileItemStage;
+};
+export declare const FileItemActions: ({ id, stage }: Props) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/actions/FileUploadAllButton.d.ts

@@ -0,0 +1 @@
+export declare const FileUploadAllButton: () => import("react/jsx-runtime").JSX.Element;

package/dist/actions/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./FileUploadAllButton";
+export * from "./FileDeleteAllButton";
+export * from "./FileItemActions";

package/dist/components/camera/custom-react-webcam.d.ts

@@ -0,0 +1,58 @@
+import React from "react";
+interface ScreenshotDimensions {
+    width: number;
+    height: number;
+}
+interface ChildrenProps {
+    getScreenshot: (screenshotDimensions?: ScreenshotDimensions) => string | null;
+}
+export type WebcamProps = Omit<React.HTMLProps<HTMLVideoElement>, "ref"> & {
+    audio: boolean;
+    audioConstraints?: MediaStreamConstraints["audio"];
+    forceScreenshotSourceSize: boolean;
+    imageSmoothing: boolean;
+    mirrored: boolean;
+    minScreenshotHeight?: number;
+    minScreenshotWidth?: number;
+    onUserMedia: (stream: MediaStream) => void;
+    onUserMediaError: (error: string | DOMException) => void;
+    screenshotFormat: "image/webp" | "image/png" | "image/jpeg";
+    screenshotQuality: number;
+    videoConstraints?: MediaStreamConstraints["video"];
+    children?: (childrenProps: ChildrenProps) => JSX.Element;
+};
+interface WebcamState {
+    hasUserMedia: boolean;
+    src?: string;
+}
+export default class Webcam extends React.Component<WebcamProps, WebcamState> {
+    static defaultProps: {
+        audio: boolean;
+        forceScreenshotSourceSize: boolean;
+        imageSmoothing: boolean;
+        mirrored: boolean;
+        onUserMedia: () => undefined;
+        onUserMediaError: () => undefined;
+        screenshotFormat: string;
+        screenshotQuality: number;
+    };
+    private canvas;
+    private ctx;
+    private requestUserMediaId;
+    private unmounted;
+    private requestedUserMedia;
+    stream: MediaStream | null;
+    video: HTMLVideoElement | null;
+    constructor(props: WebcamProps);
+    componentDidMount(): void;
+    componentDidUpdate(nextProps: WebcamProps): void;
+    componentWillUnmount(): void;
+    private static stopMediaStream;
+    private stopAndCleanup;
+    getScreenshot(screenshotDimensions?: ScreenshotDimensions): string | null;
+    getCanvas(screenshotDimensions?: ScreenshotDimensions): HTMLCanvasElement | null;
+    private requestUserMedia;
+    private handleUserMedia;
+    render(): import("react/jsx-runtime").JSX.Element;
+}
+export {};

package/dist/components/camera/frames/WebcamFrameA4.d.ts

@@ -0,0 +1,20 @@
+interface WebcamFrameProps {
+    width: number;
+    height: number;
+    offset?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    proportion?: number;
+}
+export declare function getFrame(props: WebcamFrameProps): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    orientation: string;
+};
+export declare function WebcamFrameA4(props: WebcamFrameProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/camera/frames/index.d.ts

@@ -0,0 +1 @@
+export * from "./WebcamFrameA4";

package/dist/components/camera/index.d.ts

@@ -0,0 +1 @@
+export * from "./use-webcam";

package/dist/components/camera/use-webcam.d.ts

@@ -0,0 +1,34 @@
+import React from "react";
+export type WebcamOutputProps = {
+    imageUriBase64: string | undefined;
+    imageData: ImageData | undefined;
+};
+type WebcamProps = {
+    outputImageUriBase64: boolean;
+    outputImageData: boolean;
+    targetWidth: number;
+    targetHeight: number;
+    screenshotFormat: "image/jpeg" | "image/webp" | "image/png" | undefined;
+    screenshotQuality: number;
+    imageSmoothing: boolean;
+    mirrored: boolean;
+    videoConstraints: any;
+    onCapture(img: WebcamOutputProps): void;
+    onUserMediaError(error: string | DOMException): void;
+    onToggleDevice(): void;
+};
+export declare function useWebcam(props: Partial<WebcamProps>): {
+    WebcamComponent: () => import("react/jsx-runtime").JSX.Element;
+    userMediaStatus: string;
+    userMediaError: string | Error | undefined;
+    userMediaErrorString: string;
+    getDevices: () => Promise<MediaDeviceInfo[] | undefined>;
+    deviceCount: number | undefined;
+    selectedDeviceId: string | null;
+    setSelectedDeviceId: React.Dispatch<React.SetStateAction<string | null>>;
+    doCaptureImage: () => void;
+    doRotateDevice: () => void;
+    doMirrorDevice: () => void;
+    doNextDevice: () => Promise<void>;
+};
+export {};

package/dist/components/file-drop/FileDropArea.d.ts

@@ -0,0 +1,2 @@
+import { FileDropProps } from "../../types";
+export declare const FileDropArea: (props: FileDropProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/file-drop/FileDropLarge.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { FileLoaderActionsProps } from "../../types";
+export declare const FileDropLarge: ({ children, disableCamera, disableFileSystem, className, disabled, }: FileLoaderActionsProps & {
+    children?: React.ReactNode;
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/file-drop/FileDropSmall.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+import { FileLoaderActionsProps } from "../../types";
+export declare const FileDropSmall: ({ children, disableCamera, disableFileSystem, className, }: FileLoaderActionsProps & {
+    children?: React.ReactNode;
+    className?: string;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/file-list/FileList.d.ts

@@ -0,0 +1,2 @@
+import { FileListProps } from "../../types";
+export declare const FileList: ({ onDragEnd }: FileListProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/file-list/FileListActions.d.ts

@@ -0,0 +1 @@
+export declare const FileListActions: () => import("react/jsx-runtime").JSX.Element;

package/dist/components/file-list/FileListContainer.d.ts

@@ -0,0 +1,6 @@
+import { PropsWithChildren } from "react";
+interface ContainerProps extends PropsWithChildren {
+    className?: string;
+}
+export declare const FileListContainer: ({ children, className }: ContainerProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/file-list/FileListItem.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { FileListItemProps } from "../../types";
+export declare const FileListItem: React.MemoExoticComponent<({ size, name, previewImgSrc, id, uploadStatus, order, count, disabled, disableSorting, }: FileListItemProps) => import("react/jsx-runtime").JSX.Element>;

package/dist/components/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./file-list/FileList";
+export * from "./file-list/FileListActions";
+export * from "./file-list/FileListContainer";
+export * from "./file-list/FileListItem";
+export * from "./file-drop/FileDropSmall";
+export * from "./file-drop/FileDropLarge";

package/dist/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./use-state-machine";
+export * from "./use-mobile-detect";

package/dist/hooks/use-mobile-detect.d.ts

@@ -0,0 +1,9 @@
+type Device = {
+    isMobile?: boolean;
+    isDesktop?: boolean;
+    isAndroid?: boolean;
+    isIos?: boolean;
+    isSSR?: boolean;
+};
+export declare const useMobileDetect: () => Device;
+export {};

package/dist/hooks/use-state-machine.d.ts

@@ -0,0 +1,21 @@
+export declare enum STATUS {
+    IDLE = "IDLE",
+    LOADING = "LOADING",
+    PROCESSING = "PROCESSING",
+    ERROR = "ERROR",
+    READY = "READY",
+    PENDING = "PENDING"
+}
+export declare function useStateMachine(initialStatus?: string, initialValue?: any): {
+    smStatus: string;
+    smStatusIs: (...args: string[]) => boolean;
+    smStatusIsnt: (...args: string[]) => boolean;
+    smIsError: boolean;
+    smError: string | Error | undefined;
+    smErrorString: string;
+    smValue: any;
+    smGetStatus: () => string;
+    smSetStatus: (newStatus: string, error?: string | Error | undefined, value?: any) => void;
+    smResetStatus: (newStatus: string) => void;
+    status: typeof STATUS;
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import "@/src/styles/tailwind.css";
+export { FileUploadContainer } from "./FileUploadContainer";
+export { FileUploadControl } from "./FileUploadControl";
+export { UploadedFilesProvider } from "./providers";
+export { isFileDropError } from "./utils";
+export * from "./types";