ultra-image-uploader 1.0.0 → 2.0.0

package/README.md

@@ -2,12 +2,13 @@
 
 <div align="center">
 
-A modern, feature-rich React image upload component with support for multiple hosting providers.
+A modern, beautiful React image upload component with support for multiple providers.
 
 [![npm version](https://badge.fury.io/js/ultra-image-uploader.svg)](https://www.npmjs.com/package/ultra-image-uploader)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT)
 
-**Features** • **Multiple Providers** • **Themeable** • **TypeScript** • **Production Ready**
+**Modern UI** • **Multiple Providers** • **5 Themes** • **Production Ready**
 
 </div>
 
@@ -15,32 +16,25 @@ A modern, feature-rich React image upload component with support for multiple ho
 
 ## Features
 
-- **Multiple Provider Support** - Built-in support for ImgBB and Cloudinary
-- **Drag & Drop** - Intuitive drag and drop interface
-- **Upload Progress** - Real-time upload progress tracking
-- **File Validation** - Comprehensive file type, size, and dimension validation
-- **Theme System** - 5 built-in themes + custom theme support
-- **Auto Upload** - Optional automatic upload on file selection
-- **Image Preview** - Instant preview with file size display
-- **Error Handling** - Graceful error handling with user feedback
-- **TypeScript** - Fully typed for excellent developer experience
-- **Customizable** - Highly customizable styling and behavior
-- **Tree Shakeable** - Optimized bundle size
+- **Beautiful UI** - Modern, clean design with smooth animations
+- **5 Built-in Themes** - Light, Dark, Modern, Ocean, Sunset
+- **Custom Themes** - Create your own color schemes
+- **Multiple Providers** - ImgBB & Cloudinary support
+- **Drag & Drop** - Intuitive file handling
+- **Upload Progress** - Real-time progress tracking
+- **File Validation** - Type and size validation
+- **Auto Upload** - Optional automatic uploading
+- **TypeScript** - Fully typed
+- **Simple API** - Easy to use
 
 ## Installation
 
 ```bash
 npm install ultra-image-uploader
-# or
-yarn add ultra-image-uploader
-# or
-pnpm add ultra-image-uploader
 ```
 
 ## Quick Start
 
-### Basic Usage
-
 ```tsx
 import { ImageUploader } from "ultra-image-uploader";
 import { useState } from "react";
@@ -52,447 +46,275 @@ function App() {
     <ImageUploader
       images={images}
       setImages={setImages}
-      multiple={true}
+      multiple
       theme="light"
     />
   );
 }
 ```
 
-### With ImgBB Upload
+## Themes
+
+Choose from 5 beautiful themes:
 
 ```tsx
-import { ImageUploader, uploadImagesToImageBB } from "ultra-image-uploader";
-import { useState } from "react";
+// Light (default)
+<ImageUploader theme="light" images={images} setImages={setImages} />
 
-function ImageUploadForm() {
-  const [images, setImages] = useState<File[]>([]);
-  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
-  const [loading, setLoading] = useState(false);
+// Dark
+<ImageUploader theme="dark" images={images} setImages={setImages} />
 
-  const handleUpload = async () => {
-    setLoading(true);
-    try {
-      const result = await uploadImagesToImageBB(
-        images,
-        "your-imgbb-api-key-here"
-      );
-      setUploadedUrls(result.urls);
-      console.log("Uploaded URLs:", result.urls);
-    } catch (error) {
-      console.error("Error uploading images:", error);
-    } finally {
-      setLoading(false);
-    }
-  };
+// Modern (pink)
+<ImageUploader theme="modern" images={images} setImages={setImages} />
 
-  return (
-    <div>
-      <ImageUploader
-        images={images}
-        setImages={setImages}
-        multiple={true}
-        theme="modern"
-      />
-      <button
-        onClick={handleUpload}
-        disabled={loading || images.length === 0}
-        className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
-      >
-        {loading ? "Uploading..." : "Upload to ImgBB"}
-      </button>
-
-      {uploadedUrls.length > 0 && (
-        <div>
-          <h3>Uploaded Images:</h3>
-          {uploadedUrls.map((url) => (
-            <img key={url} src={url} alt="Uploaded" />
-          ))}
-        </div>
-      )}
-    </div>
-  );
-}
+// Ocean (cyan)
+<ImageUploader theme="ocean" images={images} setImages={setImages} />
+
+// Sunset (orange)
+<ImageUploader theme="sunset" images={images} setImages={setImages} />
 ```
 
-### With Cloudinary
+## Custom Theme
 
 ```tsx
-import { ImageUploader, uploadImagesToCloudinary } from "ultra-image-uploader";
-import { useState } from "react";
+import { ImageUploader, type ThemeConfig } from "ultra-image-uploader";
+
+const customTheme: ThemeConfig = {
+  primary: '#ff6b6b',
+  background: '#fff',
+  border: '#ddd',
+  text: '#333',
+  textSecondary: '#666',
+  error: '#e74c3c',
+  success: '#2ecc71',
+  radius: '8px',
+};
+
+<ImageUploader
+  images={images}
+  setImages={setImages}
+  theme={customTheme}
+/>
+```
+
+## Upload to ImgBB
 
-function CloudinaryUpload() {
+```tsx
+import { ImageUploader, uploadImagesToImageBB } from "ultra-image-uploader";
+
+function UploadToImgBB() {
   const [images, setImages] = useState<File[]>([]);
-  const [loading, setLoading] = useState(false);
 
   const handleUpload = async () => {
-    setLoading(true);
-    try {
-      const results = await uploadImagesToCloudinary(
-        images,
-        {
-          cloudName: "your-cloud-name",
-          uploadPreset: "your-upload-preset", // for unsigned uploads
-        },
-        {
-          onProgress: (progress) => {
-            console.log(`Upload: ${progress.percentage}%`);
-          },
-          transformOptions: {
-            width: 800,
-            height: 600,
-            crop: "limit",
-            quality: 80,
-          },
-        }
-      );
-      console.log("Uploaded:", results);
-    } catch (error) {
-      console.error("Error:", error);
-    } finally {
-      setLoading(false);
-    }
+    const result = await uploadImagesToImageBB(images, 'YOUR_API_KEY');
+    console.log('Uploaded:', result.urls);
   };
 
   return (
     <div>
-      <ImageUploader
-        images={images}
-        setImages={setImages}
-        multiple={true}
-        theme="dark"
-      />
-      <button onClick={handleUpload} disabled={loading}>
-        Upload to Cloudinary
-      </button>
+      <ImageUploader images={images} setImages={setImages} multiple />
+      <button onClick={handleUpload}>Upload</button>
     </div>
   );
 }
 ```
 
-### Auto Upload Mode
+## Upload to Cloudinary
 
 ```tsx
-import { ImageUploader } from "ultra-image-uploader";
-import { useState } from "react";
+import { ImageUploader, uploadImagesToCloudinary } from "ultra-image-uploader";
 
-function AutoUploadExample() {
+function UploadToCloudinary() {
   const [images, setImages] = useState<File[]>([]);
-  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
+
+  const handleUpload = async () => {
+    const results = await uploadImagesToCloudinary(images, {
+      cloudName: 'your-cloud-name',
+      uploadPreset: 'your-upload-preset',
+    });
+    console.log('Uploaded:', results.map(r => r.url));
+  };
 
   return (
-    <ImageUploader
-      images={images}
-      setImages={setImages}
-      multiple={true}
-      autoUpload={true}
-      uploadConfig={{
-        provider: "imgbb",
-        config: { apiKey: "your-api-key" },
-      }}
-      onUploadComplete={(urls) => {
-        setUploadedUrls(urls);
-        console.log("All uploads complete!", urls);
-      }}
-      onUploadError={(error) => {
-        console.error("Upload failed:", error);
-      }}
-      theme="colorful"
-    />
+    <div>
+      <ImageUploader images={images} setImages={setImages} multiple theme="dark" />
+      <button onClick={handleUpload}>Upload</button>
+    </div>
   );
 }
 ```
 
-## Theming
-
-### Built-in Themes
-
-The component comes with 5 beautiful themes:
-
-- **`light`** - Clean and modern light theme
-- **`dark`** - Sleek dark theme
-- **`modern`** - Purple-themed modern design
-- **`minimal`** - Minimalist black and white
-- **`colorful`** - Warm amber/yellow theme
+## Auto Upload Mode
 
 ```tsx
-<ImageUploader images={images} setImages={setImages} theme="dark" />
-```
-
-### Custom Theme
-
-Create your own theme with full customization:
-
-```tsx
-import { ImageUploader, type UploaderTheme } from "ultra-image-uploader";
-
-const customTheme: UploaderTheme = {
-  primary: "#ff6b6b",
-  primaryHover: "#ee5a5a",
-  background: "#f7f7f7",
-  border: "#ddd",
-  text: "#333",
-  textSecondary: "#666",
-  error: "#e74c3c",
-  success: "#2ecc71",
-  radius: "8px",
-};
-
 <ImageUploader
   images={images}
   setImages={setImages}
-  customTheme={customTheme}
+  multiple
+  autoUpload
+  uploadConfig={{
+    provider: 'imgbb',
+    config: { apiKey: 'your-api-key' },
+  }}
+  onUploadComplete={(urls) => console.log('Done!', urls)}
+  onUploadError={(error) => console.error('Error:', error)}
 />
 ```
 
-## Component Props
+## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `images` | `File[]` | **Required** | Array of selected image files |
-| `setImages` | `(files: File[]) => void` | **Required** | Function to update images array |
-| `mode` | `'add' \| 'update'` | `'add'` | Component operation mode |
-| `defaultImages` | `string[]` | `[]` | Existing image URLs for update mode |
-| `multiple` | `boolean` | `false` | Allow multiple file selection |
-| `theme` | `ThemePreset` | `'light'` | Built-in theme to use |
-| `customTheme` | `UploaderTheme` | `undefined` | Custom theme configuration |
+| `images` | `File[]` | **Required** | Selected image files |
+| `setImages` | `(files: File[]) => void` | **Required** | Update images state |
+| `multiple` | `boolean` | `false` | Allow multiple files |
+| `theme` | `'light' \| 'dark' \| 'modern' \| 'ocean' \| 'sunset' \| ThemeConfig` | `'light'` | Theme to use |
+| `mode` | `'add' \| 'update'` | `'add'` | Component mode |
+| `defaultImages` | `string[]` | `[]` | Existing image URLs |
 | `uploadText` | `string` | `'Drop images here...'` | Upload area text |
-| `typeText` | `string` | `'PNG, JPG,...'` | File type hint text |
-| `maxSize` | `number` | `10485760` | Max file size in bytes (10MB) |
-| `allowedTypes` | `string[]` | `['image/jpeg', ...]` | Allowed MIME types |
-| `showFileSize` | `boolean` | `true` | Show file size on preview |
-| `dragAndDrop` | `boolean` | `true` | Enable drag and drop |
-| `previewWidth` | `number` | `150` | Preview image width in px |
-| `previewHeight` | `number` | `150` | Preview image height in px |
-| `className` | `string` | `''` | Additional CSS classes |
-| `autoUpload` | `boolean` | `false` | Auto-upload on file selection |
-| `uploadConfig` | `{ provider, config }` | `undefined` | Upload configuration |
-| `onUploadComplete` | `(urls: string[]) => void` | `undefined` | Callback on upload success |
-| `onUploadError` | `(error: Error) => void` | `undefined` | Callback on upload error |
-
-## Upload Providers
-
-### ImgBB
-
-Free image hosting with simple API:
-
-```tsx
-import { uploadImagesToImageBB } from "ultra-image-uploader";
-
-const result = await uploadImagesToImageBB(
-  images,
-  "your-imgbb-api-key"
-);
-console.log(result.urls);
-```
+| `maxSize` | `number` | `10485760` | Max file size (bytes) |
+| `allowedTypes` | `string[]` | Image types | Allowed MIME types |
+| `showFileSize` | `boolean` | `true` | Show file size |
+| `dragAndDrop` | `boolean` | `true` | Enable drag-drop |
+| `previewWidth` | `number` | `140` | Preview width (px) |
+| `previewHeight` | `number` | `140` | Preview height (px) |
+| `autoUpload` | `boolean` | `false` | Auto upload files |
+| `uploadConfig` | `{ provider, config }` | `undefined` | Upload config |
+| `onUploadComplete` | `(urls: string[]) => void` | `undefined` | Upload success callback |
+| `onUploadError` | `(error: Error) => void` | `undefined` | Upload error callback |
+| `className` | `string` | `''` | Extra CSS classes |
 
-**Get API Key:** [imgbb.com/settings/api](https://imgbb.com/settings/api)
+## Upload Functions
 
-### Cloudinary
+### `uploadImage(file, provider, config, options?)`
 
-Enterprise-grade image hosting with transformations:
+Upload a single image.
 
 ```tsx
-import { uploadImagesToCloudinary } from "ultra-image-uploader";
+import { uploadImage } from "ultra-image-uploader";
 
-const results = await uploadImagesToCloudinary(
-  images,
+const result = await uploadImage(
+  file,
+  'imgbb',
+  { apiKey: 'your-key' },
   {
-    cloudName: "your-cloud-name",
-    uploadPreset: "your-upload-preset", // optional
-  },
-  {
-    onProgress: (progress) => console.log(progress.percentage),
-    transformOptions: {
-      width: 800,
-      height: 600,
-      quality: 85,
-      crop: "limit",
-    },
+    onProgress: (p) => console.log(p.percentage + '%'),
   }
 );
+console.log(result.url);
 ```
 
-**Get Credentials:**
-1. Sign up at [cloudinary.com](https://cloudinary.com)
-2. Get your cloud name from dashboard
-3. Create an upload preset (Settings → Upload → Upload presets)
-
-## Advanced Usage
-
-### Custom Provider
+### `uploadImages(files, provider, config, options?)`
 
-You can create custom upload providers:
+Upload multiple images.
 
 ```tsx
-import { BaseImageProvider } from "ultra-image-uploader";
-
-class CustomProvider extends BaseImageProvider {
-  name = 'custom' as const;
-
-  async upload(file: File, config: ProviderConfig) {
-    // Your upload logic here
-    return {
-      url: "https://...",
-      provider: "custom",
-      originalFile: file,
-    };
-  }
-
-  async uploadMultiple(files: File[], config: ProviderConfig) {
-    return Promise.all(files.map(f => this.upload(f, config)));
-  }
-}
-
-// Register and use
-import { providerRegistry } from "ultra-image-uploader";
-providerRegistry.register(new CustomProvider());
+const results = await uploadImages(files, 'cloudinary', {
+  cloudName: 'your-cloud',
+});
 ```
 
-### File Validation
+### `uploadImagesToImageBB(images, apiKey)`
+
+Upload to ImgBB (shorthand).
 
 ```tsx
-import {
-  validateImageFile,
-  validateFileComplete,
-  formatFileSize,
-} from "ultra-image-uploader";
+const { urls } = await uploadImagesToImageBB(images, 'api-key');
+```
 
-// Quick validation
-const validation = validateImageFile(file, {
-  maxSize: 5 * 1024 * 1024, // 5MB
-  allowedTypes: ["image/jpeg", "image/png"],
-});
+### `uploadImagesToCloudinary(files, config, options?)`
 
-if (!validation.valid) {
-  console.error("Errors:", validation.errors);
-}
+Upload to Cloudinary (shorthand).
 
-// Complete validation (with dimensions)
-const completeValidation = await validateFileComplete(file, {
-  maxSize: 10 * 1024 * 1024,
-  minWidth: 800,
-  maxWidth: 4000,
-  minHeight: 600,
-  maxHeight: 3000,
+```tsx
+const results = await uploadImagesToCloudinary(images, {
+  cloudName: 'your-cloud',
+  uploadPreset: 'your-preset',
 });
 ```
 
-### Transforming Cloudinary Images
-
-Generate transformed URLs for existing Cloudinary images:
+## Get API Keys
 
-```tsx
-import { CloudinaryProvider } from "ultra-image-uploader";
+### ImgBB
+1. Go to [imgbb.com/settings/api](https://imgbb.com/settings/api)
+2. Copy your API key
 
-const transformedUrl = CloudinaryProvider.generateTransformedUrl(
-  "https://res.cloudinary.com/.../image.jpg",
-  {
-    width: 400,
-    height: 300,
-    crop: "fill",
-    quality: 80,
-    format: "webp",
-  }
-);
-```
+### Cloudinary
+1. Sign up at [cloudinary.com](https://cloudinary.com)
+2. Get your cloud name from dashboard
+3. Create upload preset (Settings → Upload)
 
-## TypeScript Support
+## TypeScript
 
-The package is fully typed. Import types as needed:
+All types are exported:
 
 ```tsx
 import type {
   UploadProvider,
   UploadResult,
-  ProviderConfig,
-  UploadOptions,
+  ThemeConfig,
   ImageUploaderProps,
-  UploaderTheme,
-  ValidationResult,
   FileValidationOptions,
+  // ... more
 } from "ultra-image-uploader";
 ```
 
 ## Examples
 
-### E-commerce Product Image Upload
+### Profile Picture
 
 ```tsx
-function ProductImageUpload() {
-  const [images, setImages] = useState<File[]>([]);
-  const [existingImages, setExistingImages] = useState<string[]>([
-    "https://example.com/product1.jpg",
-  ]);
-
-  return (
-    <ImageUploader
-      images={images}
-      setImages={setImages}
-      mode="update"
-      defaultImages={existingImages}
-      multiple={true}
-      maxSize={5 * 1024 * 1024} // 5MB
-      allowedTypes={["image/jpeg", "image/webp"]}
-      theme="modern"
-      previewWidth={200}
-      previewHeight={200}
-    />
-  );
-}
+<ImageUploader
+  images={avatar}
+  setImages={setAvatar}
+  multiple={false}
+  maxSize={2 * 1024 * 1024}
+  theme="modern"
+/>
 ```
 
-### Profile Picture Upload
+### Product Gallery
 
 ```tsx
-function ProfilePicUpload() {
-  const [avatar, setAvatar] = useState<File[]>([]);
-
-  return (
-    <ImageUploader
-      images={avatar}
-      setImages={setAvatar}
-      multiple={false}
-      maxSize={2 * 1024 * 1024} // 2MB
-      previewWidth={180}
-      previewHeight={180}
-      theme="minimal"
-    />
-  );
-}
+<ImageUploader
+  images={products}
+  setImages={setProducts}
+  multiple
+  mode="update"
+  defaultImages={existingImages}
+  allowedTypes={['image/jpeg', 'image/webp']}
+  theme="ocean"
+/>
 ```
 
-## Migration from v0.0.x
-
-If you're upgrading from version 0.0.x, the API is backward compatible:
+### Custom Colors
 
 ```tsx
-// Old API still works
-import { uploadImagesToImageBB } from "ultra-image-uploader";
-const { urls } = await uploadImagesToImageBB(images, apiKey);
-
-// But you can now use the new provider-agnostic API
-import { uploadImages } from "ultra-image-uploader";
-const results = await uploadImages(images, "imgbb", { apiKey });
-const urls = results.map(r => r.url);
+<ImageUploader
+  images={images}
+  setImages={setImages}
+  theme={{
+    primary: '#00d9ff',
+    background: '#0a0a0a',
+    border: '#333',
+    text: '#fff',
+    textSecondary: '#999',
+    error: '#ff4757',
+    success: '#2ed573',
+    radius: '16px',
+  }}
+/>
 ```
 
-## Browser Support
-
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
-- Mobile browsers
-
 ## License
 
 MIT © Digontha Das
 
-## Support & Contributing
+## Links
 
-- **Issues:** [GitHub Issues](https://github.com/digontha/ultra-image-uploader/issues)
-- **Contributing:** Pull requests are welcome!
-- **Discussions:** Ask questions and share ideas
+- [GitHub](https://github.com/digontha/ultra-image-uploader)
+- [NPM](https://www.npmjs.com/package/ultra-image-uploader)
+- [Issues](https://github.com/digontha/ultra-image-uploader/issues)
 
 ---