smart-dropzone-react/README.md

🚀 A production-ready React dropzone component with smart defaults, drag & drop reordering, chunked uploads, resume functionality, and comprehensive provider support (Cloudinary, AWS S3, Supabase)

# 🚀 Smart Dropzone

[![npm version](https://badge.fury.io/js/smart-dropzone-react.svg)](https://badge.fury.io/js/smart-dropzone-react)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB)](https://reactjs.org/)
[![Test Coverage](https://img.shields.io/badge/Coverage-83.7%25-brightgreen)](./coverage)

A **production-ready** React dropzone component with smart defaults, advanced features, and comprehensive provider support. Built for modern applications that need reliable file uploads with excellent user experience.

## ✨ **Key Features**

- 🎯 **Smart Defaults** - Zero configuration to get started, extensive customization available
- 🔄 **Chunked Uploads** - Handle large files with resume capability and progress tracking
- 🎨 **Drag & Drop Reordering** - Intuitive file reordering with visual feedback
- 🌐 **Multi-Provider Support** - Cloudinary, AWS S3, Supabase, and extensible architecture
- ♿ **Accessibility First** - WCAG compliant with screen reader support and keyboard navigation
- 🌍 **Internationalization** - Built-in i18n support with multiple languages
- 📱 **Responsive Design** - Works seamlessly across desktop and mobile devices
- 🚀 **Performance Optimized** - Lazy loading, tree shaking, and minimal bundle impact
- 🛡️ **Type Safe** - Full TypeScript support with comprehensive type definitions
- 📊 **Production Ready** - 83.7% test coverage with extensive edge case handling

## 📦 **Installation**

```bash
# npm
npm install smart-dropzone-react

# yarn
yarn add smart-dropzone-react

# pnpm
pnpm add smart-dropzone-react
```

### Peer Dependencies

```bash
npm install react react-dom
```

**React Version Support:**

- ✅ React 18.x (Full support)
- ✅ React 19.x (Full support with latest features)
- 🔄 React 17.x (Legacy support - may have compatibility issues)

## 🚀 **Quick Start**

### Zero Configuration (Cloudinary)

```tsx
import { SimpleUpload } from "@tanflare/smart-dropzone";

function App() {
  return (
    <SimpleUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
      onFilesAdded={(files) => console.log("Files uploaded:", files)}
    />
  );
}
```

### With Smart Presets

```tsx
import { SmartDropzoneSimple } from "smart-dropzone-react";

// Gallery preset - optimized for images
function ImageGallery() {
  return (
    <SmartDropzoneSimple
      preset="gallery"
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
    />
  );
}

// Document preset - optimized for files
function DocumentUpload() {
  return (
    <SmartDropzoneSimple
      preset="documents"
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "your-upload-preset",
      }}
    />
  );
}
```

### Advanced Configuration

```tsx
import { SmartDropzone, CloudinaryProvider } from "smart-dropzone-react";

function AdvancedUpload() {
  const provider = new CloudinaryProvider({
    cloudName: "your-cloud-name",
    uploadPreset: "your-upload-preset",
    defaultFolder: "uploads",
  });

  return (
    <SmartDropzone
      provider={provider}
      maxFiles={10}
      maxFileSize={50 * 1024 * 1024} // 50MB
      allowedTypes={["image/*", "application/pdf"]}
      enableReorder={true}
      enableResume={true}
      showPreview={true}
      theme="dark"
      onFilesAdded={(files) => console.log("Files uploaded:", files)}
      onError={(error) => console.error("Upload error:", error)}
      onProgress={(fileId, progress) =>
        console.log(`File ${fileId}: ${progress}%`)
      }
    />
  );
}
```

## 🎨 **Available Presets**

| Preset       | Use Case            | Max Files | File Types                      | Features                     |
| ------------ | ------------------- | --------- | ------------------------------- | ---------------------------- |
| `simple`     | Basic uploads       | 5         | `image/*`, `application/pdf`    | Preview, Progress            |
| `gallery`    | Image galleries     | 20        | `image/*`                       | Preview, Reorder, Thumbnails |
| `documents`  | Document management | 10        | `application/*`, `text/*`       | File info, Validation        |
| `media`      | Media content       | 15        | `image/*`, `video/*`, `audio/*` | Preview, Player              |
| `enterprise` | Large-scale uploads | 50        | All types                       | All features, Analytics      |

## 🌐 **Provider Support**

### Cloudinary

```tsx
import { CloudinaryProvider } from "smart-dropzone-react";

const provider = new CloudinaryProvider({
  cloudName: "your-cloud-name",
  uploadPreset: "your-upload-preset",
  defaultFolder: "uploads",
  // Optional: Add transformations
  transformations: {
    quality: "auto",
    fetch_format: "auto",
  },
});
```

### AWS S3 (Coming Soon)

```tsx
import { S3Provider } from "smart-dropzone-react";

const provider = new S3Provider({
  accessKeyId: "your-access-key",
  secretAccessKey: "your-secret-key",
  bucket: "your-bucket-name",
  region: "us-east-1",
});
```

### Custom Provider

```tsx
import { BaseProvider } from "smart-dropzone-react";

class CustomProvider extends BaseProvider {
  async uploadFile(file: File, options?: UploadOptions) {
    // Your custom upload logic
    return {
      id: "file-id",
      url: "https://your-cdn.com/file.jpg",
      uploadedAt: new Date(),
    };
  }

  // Implement other required methods...
}
```

## 🎯 **Real-World Examples**

### E-commerce Product Images

```tsx
import { GalleryUpload } from "smart-dropzone-react";

function ProductImageUpload({ productId }) {
  return (
    <GalleryUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "product-images",
        defaultFolder: `products/${productId}`,
      }}
      maxFiles={8}
      onFilesAdded={(files) => {
        // Update product images in your database
        updateProductImages(productId, files);
      }}
      overrides={{
        showFileSize: true,
        enableReorder: true,
        theme: "light",
      }}
    />
  );
}
```

### User Profile Avatar

```tsx
import { SimpleUpload } from "@tanflare/smart-dropzone";

function AvatarUpload({ userId }) {
  return (
    <div className="w-32 h-32">
      <SimpleUpload
        cloudinary={{
          cloudName: "your-cloud-name",
          uploadPreset: "avatars",
          defaultFolder: "users/avatars",
        }}
        maxFiles={1}
        allowedTypes={["image/*"]}
        onFilesAdded={([file]) => {
          // Update user avatar
          updateUserAvatar(userId, file.url);
        }}
        overrides={{
          variant: "filled",
          size: "sm",
        }}
      />
    </div>
  );
}
```

### Document Management

```tsx
import { DocumentUpload } from "smart-dropzone-react";

function DocumentManager() {
  const [documents, setDocuments] = useState([]);

  return (
    <DocumentUpload
      cloudinary={{
        cloudName: "your-cloud-name",
        uploadPreset: "documents",
      }}
      onFilesAdded={(newFiles) => {
        setDocuments((prev) => [...prev, ...newFiles]);
        // Send to your document management system
        indexDocuments(newFiles);
      }}
      overrides={{
        maxFileSize: 100 * 1024 * 1024, // 100MB
        showFileType: true,
        showFileSize: true,
      }}
    />
  );
}
```

## 🛠️ **Advanced Features**

### Chunked Uploads with Resume

```tsx
<SmartDropzone
  provider={cloudinaryProvider}
  enableResume={true}
  chunkSize={1024 * 1024} // 1MB chunks
  onChunkProgress={(fileId, chunkIndex, totalChunks) => {
    console.log(`File ${fileId}: chunk ${chunkIndex}/${totalChunks}`);
  }}
  onResumeUpload={(fileId) => {
    console.log(`Resuming upload for ${fileId}`);
  }}
/>
```

### Accessibility & Internationalization

```tsx
<SmartDropzone
  provider={cloudinaryProvider}
  accessibility={{
    highContrast: true,
    reducedMotion: false,
    screenReaderSupport: true,
  }}
  i18n={{
    locale: "es",
    customTranslations: {
      "dropzone.dragActive": "Suelta los archivos aquí...",
    },
  }}
/>
```

### Performance Monitoring

```tsx
<SmartDropzone
  provider={cloudinaryProvider}
  enablePerformanceMonitoring={true}
  onPerformanceData={(metrics) => {
    console.log("Performance metrics:", {
      renderTime: metrics.renderTime,
      uploadSpeed: metrics.uploadSpeed,
      memoryUsage: metrics.memoryUsage,
    });
  }}
/>
```

## 🎨 **Styling & Theming**

### Built-in Themes

```tsx
// Light theme (default)
<SmartDropzone theme="light" />

// Dark theme
<SmartDropzone theme="dark" />

// Custom theme
<SmartDropzone
  theme={{
    colors: {
      primary: "#007bff",
      secondary: "#6c757d",
      success: "#28a745",
      error: "#dc3545"
    },
    borderRadius: "8px",
    spacing: "1rem"
  }}
/>
```

### CSS Custom Properties

```css
:root {
  --smart-dropzone-primary: #007bff;
  --smart-dropzone-border-radius: 8px;
  --smart-dropzone-transition: all 0.2s ease;
}
```

### Tailwind CSS Integration

```tsx
<SmartDropzone
  className="border-dashed border-2 border-blue-300 hover:border-blue-500 rounded-lg p-8"
  provider={provider}
/>
```

## 📚 **API Reference**

### Components

- **`SmartDropzone`** - Main component with full feature set
- **`SmartDropzoneSimple`** - Simplified component with preset support
- **`SimpleUpload`** - Zero-config component for basic uploads
- **`GalleryUpload`** - Optimized for image galleries
- **`DocumentUpload`** - Optimized for document management
- **`MediaUpload`** - Optimized for media files
- **`EnterpriseUpload`** - Full-featured for enterprise use

### Providers

- **`CloudinaryProvider`** - Cloudinary upload service
- **`S3Provider`** - Amazon S3 (coming soon)
- **`SupabaseProvider`** - Supabase storage (coming soon)
- **`BaseProvider`** - Base class for custom providers

### Hooks

- **`useUpload`** - Core upload management hook
- **`useFilePreview`** - File preview generation
- **`useDragReorder`** - Drag and drop reordering
- **`useAccessibility`** - Accessibility features

For complete API documentation, see [API.md](./docs/API.md).

## 🧪 **Testing**

The package includes comprehensive tests with 83.7% coverage:

```bash
# Run tests
npm run test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run all tests (unit + e2e + type checking)
npm run test:all
```

## 🚀 **Performance**

- **Bundle Size**: ~45KB gzipped (tree-shakeable)
- **First Paint**: <100ms for initial render
- **Upload Performance**: Optimized chunking for large files
- **Memory Usage**: Efficient cleanup and garbage collection
- **Browser Support**: Modern browsers (ES2020+)

## 🌟 **Browser Support**

| Browser | Version |
| ------- | ------- |
| Chrome  | ≥88     |
| Firefox | ≥85     |
| Safari  | ≥14     |
| Edge    | ≥88     |

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/harishkhojare/smart-dropzone.git

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

# Build package
pnpm build
```

## 📄 **License**

MIT © [Tanflare Team](https://github.com/tanflare)

## 🆘 **Support**

- 📖 [Documentation](https://github.com/tanflare/smart-dropzone/blob/main/README.md)
- 🐛 [Issue Tracker](https://github.com/tanflare/smart-dropzone/issues)
- 💬 [Discussions](https://github.com/tanflare/smart-dropzone/discussions)
- 📧 [Email Support](mailto:support@tanflare.com)

## 🏆 **Sponsors**

Special thanks to our sponsors and contributors who make this project possible!

---

**Made with ❤️ by the Tanflare Team**