ultra-image-uploader 1.0.0 → 2.0.1

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 progress tracking, drag-and-drop, and multi-provider support.
 
 [![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** • **Progress Bars** • **ImgBB & Cloudinary** • **Auto Import Ready**
 
 </div>
 
@@ -15,32 +16,36 @@ 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
+- **Modern UI** - Clean, professional file upload interface matching industry standards
+- **Progress Tracking** - Real-time upload progress with smooth animations
+- **Drag & Drop** - Intuitive drag-and-drop file handling
+- **Multiple Providers** - Built-in support for ImgBB and Cloudinary
+- **File Validation** - Type and size validation with helpful error messages
 - **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
+- **Cancel/Remove** - Easy file management with cancel buttons
+- **TypeScript** - Fully typed for excellent DX
+- **Auto Import** - Works seamlessly with VS Code, WebStorm, and all popular editors
 
 ## Installation
 
+Install with any package manager:
+
 ```bash
+# npm
 npm install ultra-image-uploader
-# or
+
+# yarn
 yarn add ultra-image-uploader
-# or
+
+# pnpm
 pnpm add ultra-image-uploader
+
+# bun
+bun add ultra-image-uploader
 ```
 
 ## Quick Start
 
-### Basic Usage
-
 ```tsx
 import { ImageUploader } from "ultra-image-uploader";
 import { useState } from "react";
@@ -52,196 +57,120 @@ function App() {
     <ImageUploader
       images={images}
       setImages={setImages}
-      multiple={true}
-      theme="light"
+      multiple
     />
   );
 }
 ```
 
-### With ImgBB Upload
+## Usage Examples
+
+### Basic File Upload
 
 ```tsx
-import { ImageUploader, uploadImagesToImageBB } from "ultra-image-uploader";
-import { useState } from "react";
+import { ImageUploader } from "ultra-image-uploader";
 
-function ImageUploadForm() {
+function BasicUpload() {
   const [images, setImages] = useState<File[]>([]);
-  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
-  const [loading, setLoading] = useState(false);
-
-  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);
-    }
+
+  const handleUploadComplete = (urls: string[]) => {
+    console.log('Uploaded URLs:', urls);
   };
 
   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>
+    <ImageUploader
+      images={images}
+      setImages={setImages}
+      multiple
+      maxSize={50 * 1024 * 1024} // 50MB
+      onUploadComplete={handleUploadComplete}
+      uploadConfig={{
+        provider: 'imgbb',
+        config: { apiKey: 'your-api-key' }
+      }}
+    />
   );
 }
 ```
 
-### With Cloudinary
+### Upload with ImgBB
 
 ```tsx
-import { ImageUploader, uploadImagesToCloudinary } from "ultra-image-uploader";
-import { useState } from "react";
+import { ImageUploader } from "ultra-image-uploader";
 
-function CloudinaryUpload() {
+function ImgBBUpload() {
   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);
-    }
-  };
 
   return (
     <div>
       <ImageUploader
         images={images}
         setImages={setImages}
-        multiple={true}
-        theme="dark"
+        multiple
+        uploadConfig={{
+          provider: 'imgbb',
+          config: { apiKey: process.env.IMGBB_API_KEY }
+        }}
+        onUploadComplete={(urls) => {
+          console.log('Images uploaded to ImgBB:', urls);
+        }}
       />
-      <button onClick={handleUpload} disabled={loading}>
-        Upload to Cloudinary
-      </button>
     </div>
   );
 }
 ```
 
-### Auto Upload Mode
+### Upload with Cloudinary
 
 ```tsx
 import { ImageUploader } from "ultra-image-uploader";
-import { useState } from "react";
 
-function AutoUploadExample() {
+function CloudinaryUpload() {
   const [images, setImages] = useState<File[]>([]);
-  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
 
   return (
     <ImageUploader
       images={images}
       setImages={setImages}
-      multiple={true}
-      autoUpload={true}
+      multiple
       uploadConfig={{
-        provider: "imgbb",
-        config: { apiKey: "your-api-key" },
+        provider: 'cloudinary',
+        config: {
+          cloudName: 'your-cloud-name',
+          uploadPreset: 'your-upload-preset'
+        }
       }}
       onUploadComplete={(urls) => {
-        setUploadedUrls(urls);
-        console.log("All uploads complete!", urls);
-      }}
-      onUploadError={(error) => {
-        console.error("Upload failed:", error);
+        console.log('Images uploaded to Cloudinary:', urls);
       }}
-      theme="colorful"
     />
   );
 }
 ```
 
-## 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" />
+<ImageUploader
+  images={images}
+  setImages={setImages}
+  multiple
+  autoUpload
+  uploadConfig={{
+    provider: 'imgbb',
+    config: { apiKey: 'your-api-key' }
+  }}
+/>
 ```
 
-### Custom Theme
-
-Create your own theme with full customization:
+### Single File Upload
 
 ```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}
+  images={avatar}
+  setImages={setAvatar}
+  multiple={false}
+  maxSize={2 * 1024 * 1024} // 2MB
 />
 ```
 
@@ -249,232 +178,160 @@ const customTheme: UploaderTheme = {
 
 | 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 |
-| `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 |
+| `images` | `File[]` | **Required** | Selected image files |
+| `setImages` | `(files: File[]) => void` | **Required** | Update images state |
+| `multiple` | `boolean` | `true` | Allow multiple file selection |
+| `maxSize` | `number` | `52428800` | Max file size in bytes (50MB) |
+| `allowedTypes` | `string[]` | Image types | Allowed MIME types |
+| `className` | `string` | `''` | Extra CSS classes |
+| `autoUpload` | `boolean` | `false` | Auto-upload on 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 |
+| `onUploadComplete` | `(urls: string[]) => void` | `undefined` | Upload success callback |
+| `onUploadError` | `(error: Error) => void` | `undefined` | Upload error callback |
 
-## Upload Providers
+## Upload Functions
 
-### ImgBB
-
-Free image hosting with simple API:
+You can also use the upload functions directly:
 
 ```tsx
-import { uploadImagesToImageBB } from "ultra-image-uploader";
+import {
+  uploadImage,
+  uploadImages,
+  uploadImagesToImageBB,
+  uploadImagesToCloudinary
+} from "ultra-image-uploader";
+
+// Upload single image
+const result = await uploadImage(file, 'imgbb', { apiKey: 'key' });
+
+// Upload multiple images
+const results = await uploadImages(files, 'cloudinary', {
+  cloudName: 'your-cloud'
+});
 
-const result = await uploadImagesToImageBB(
-  images,
-  "your-imgbb-api-key"
-);
-console.log(result.urls);
+// Convenience functions
+const { urls } = await uploadImagesToImageBB(images, apiKey);
+const uploads = await uploadImagesToCloudinary(images, config);
 ```
 
-**Get API Key:** [imgbb.com/settings/api](https://imgbb.com/settings/api)
+## API Configuration
 
-### Cloudinary
+### ImgBB
 
-Enterprise-grade image hosting with transformations:
+1. Go to [imgbb.com/settings/api](https://imgbb.com/settings/api)
+2. Copy your API key
+3. Use in the component:
 
 ```tsx
-import { uploadImagesToCloudinary } from "ultra-image-uploader";
-
-const results = await uploadImagesToCloudinary(
-  images,
-  {
-    cloudName: "your-cloud-name",
-    uploadPreset: "your-upload-preset", // optional
-  },
-  {
-    onProgress: (progress) => console.log(progress.percentage),
-    transformOptions: {
-      width: 800,
-      height: 600,
-      quality: 85,
-      crop: "limit",
-    },
-  }
-);
+uploadConfig={{
+  provider: 'imgbb',
+  config: { apiKey: 'your-api-key' }
+}}
 ```
 
-**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
+### Cloudinary
 
-You can create custom upload providers:
+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)
+4. Use in the component:
 
 ```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)));
+uploadConfig={{
+  provider: 'cloudinary',
+  config: {
+    cloudName: 'your-cloud-name',
+    uploadPreset: 'your-upload-preset'
   }
-}
-
-// Register and use
-import { providerRegistry } from "ultra-image-uploader";
-providerRegistry.register(new CustomProvider());
+}}
 ```
 
-### File Validation
+## TypeScript
+
+All exports are fully typed:
 
 ```tsx
-import {
-  validateImageFile,
-  validateFileComplete,
-  formatFileSize,
+import type {
+  ImageUploaderProps,
+  UploadProvider,
+  UploadResult,
+  ProviderConfig,
+  UploadOptions
 } from "ultra-image-uploader";
+```
 
-// Quick validation
-const validation = validateImageFile(file, {
-  maxSize: 5 * 1024 * 1024, // 5MB
-  allowedTypes: ["image/jpeg", "image/png"],
-});
+## Auto Import Support
 
-if (!validation.valid) {
-  console.error("Errors:", validation.errors);
-}
+This package supports auto-import in all major editors:
 
-// Complete validation (with dimensions)
-const completeValidation = await validateFileComplete(file, {
-  maxSize: 10 * 1024 * 1024,
-  minWidth: 800,
-  maxWidth: 4000,
-  minHeight: 600,
-  maxHeight: 3000,
-});
-```
+- **VS Code** - Auto-suggestions work out of the box
+- **WebStorm** - Full IntelliSense support
+- **Neovim** - Works with LSP and completion plugins
+- **Sublime Text** - Works with LSP packages
+- **All TypeScript editors** - Full type checking and suggestions
 
-### Transforming Cloudinary Images
+## Styling
 
-Generate transformed URLs for existing Cloudinary images:
+The component uses Tailwind CSS classes. You can add custom styling:
 
 ```tsx
-import { CloudinaryProvider } from "ultra-image-uploader";
-
-const transformedUrl = CloudinaryProvider.generateTransformedUrl(
-  "https://res.cloudinary.com/.../image.jpg",
-  {
-    width: 400,
-    height: 300,
-    crop: "fill",
-    quality: 80,
-    format: "webp",
-  }
-);
+<ImageUploader
+  images={images}
+  setImages={setImages}
+  className="max-w-2xl mx-auto"
+/>
 ```
 
-## TypeScript Support
+### Custom Styling
 
-The package is fully typed. Import types as needed:
+For complete customization, you can wrap and override styles:
 
 ```tsx
-import type {
-  UploadProvider,
-  UploadResult,
-  ProviderConfig,
-  UploadOptions,
-  ImageUploaderProps,
-  UploaderTheme,
-  ValidationResult,
-  FileValidationOptions,
-} from "ultra-image-uploader";
+<div className="your-custom-wrapper">
+  <ImageUploader
+    images={images}
+    setImages={setImages}
+    className="your-custom-class"
+  />
+</div>
 ```
 
-## Examples
+## Troubleshooting
 
-### E-commerce Product Image Upload
+### Auto imports not working
 
-```tsx
-function ProductImageUpload() {
-  const [images, setImages] = useState<File[]>([]);
-  const [existingImages, setExistingImages] = useState<string[]>([
-    "https://example.com/product1.jpg",
-  ]);
+**VS Code:**
+1. Ensure TypeScript is enabled in your project
+2. Restart the TypeScript server: `Cmd/Ctrl + Shift + P` → "TypeScript: Restart TS Server"
+3. Check that `node_modules/ultra-image-uploader` exists
 
-  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}
-    />
-  );
-}
-```
+**WebStorm:**
+1. Invalidate caches: `File` → `Invalidate Caches and Restart`
+2. Ensure TypeScript plugin is enabled
 
-### Profile Picture Upload
+### Uploads failing
 
-```tsx
-function ProfilePicUpload() {
-  const [avatar, setAvatar] = useState<File[]>([]);
+1. **Check API keys** - Verify your ImgBB or Cloudinary credentials
+2. **CORS issues** - Ensure your domain is whitelisted
+3. **File size** - Check if file exceeds provider limits
+4. **Network** - Check browser console for network errors
 
-  return (
-    <ImageUploader
-      images={avatar}
-      setImages={setAvatar}
-      multiple={false}
-      maxSize={2 * 1024 * 1024} // 2MB
-      previewWidth={180}
-      previewHeight={180}
-      theme="minimal"
-    />
-  );
-}
-```
+### TypeScript errors
 
-## Migration from v0.0.x
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
 
-If you're upgrading from version 0.0.x, the API is backward compatible:
+# Restart TypeScript server in your editor
+```
 
-```tsx
-// Old API still works
-import { uploadImagesToImageBB } from "ultra-image-uploader";
-const { urls } = await uploadImagesToImageBB(images, apiKey);
+### Build issues
 
-// 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);
+```bash
+# Clean and rebuild
+npm run clean
+npm run build
 ```
 
 ## Browser Support
@@ -482,17 +339,31 @@ const urls = results.map(r => r.url);
 - Chrome/Edge (latest)
 - Firefox (latest)
 - Safari (latest)
-- Mobile browsers
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Requirements
+
+- React >= 18.0.0
+- TypeScript (optional but recommended)
 
 ## License
 
 MIT © Digontha Das
 
-## Support & Contributing
+## Links
+
+- [GitHub](https://github.com/digontha/ultra-image-uploader)
+- [NPM](https://www.npmjs.com/package/ultra-image-uploader)
+- [Report Issues](https://github.com/digontha/ultra-image-uploader/issues)
+
+## Changelog
 
-- **Issues:** [GitHub Issues](https://github.com/digontha/ultra-image-uploader/issues)
-- **Contributing:** Pull requests are welcome!
-- **Discussions:** Ask questions and share ideas
+### v2.0.0
+- 🎨 Modern UI redesign with progress bars
+- ✅ Auto import support for all editors
+- 📦 Simplified package structure
+- 🚀 Improved drag-and-drop experience
+- 🎯 Better TypeScript support
 
 ---