ultra-image-uploader 0.0.2 → 1.0.0

package/README.md

@@ -1,17 +1,31 @@
 # Ultra Image Uploader
 
-A modern React component for handling image uploads with drag-and-drop functionality, image preview, and ImgBB integration.
+<div align="center">
+
+A modern, feature-rich React image upload component with support for multiple hosting 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)
+
+**Features** • **Multiple Providers** • **Themeable** • **TypeScript** • **Production Ready**
+
+</div>
+
+---
 
 ## Features
 
-- 🎯 **Easy Integration** - Simple to use with any React/Next.js project
-- 🖼️ **Drag & Drop** - Intuitive drag and drop interface
-- 📸 **Image Preview** - Instant preview of uploaded images
-- ✨ **Multiple Upload** - Support for multiple image uploads
-- 🔍 **File Validation** - Built-in file type and size validation
-- 🎨 **Customizable** - Highly customizable styling and components
-- 🗑️ **Delete Function** - Easy image removal functionality
-- 🔄 **ImgBB Integration** - Built-in support for ImgBB image hosting
+- **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
 
 ## Installation
 
@@ -32,20 +46,20 @@ import { ImageUploader } from "ultra-image-uploader";
 import { useState } from "react";
 
 function App() {
-  const [imageFiles, setImagesFiles] = useState<File[]>([]);
+  const [images, setImages] = useState<File[]>([]);
 
   return (
     <ImageUploader
-      images={imageFiles}
-      setImages={setImagesFiles}
-      mode="add"
+      images={images}
+      setImages={setImages}
       multiple={true}
+      theme="light"
     />
   );
 }
 ```
 
-### With ImgBB Integration
+### With ImgBB Upload
 
 ```tsx
 import { ImageUploader, uploadImagesToImageBB } from "ultra-image-uploader";
@@ -53,15 +67,17 @@ import { useState } from "react";
 
 function ImageUploadForm() {
   const [images, setImages] = useState<File[]>([]);
+  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
   const [loading, setLoading] = useState(false);
 
-  const handleGetImageUrl = async () => {
+  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);
@@ -75,72 +91,409 @@ function ImageUploadForm() {
       <ImageUploader
         images={images}
         setImages={setImages}
-        mode="add"
         multiple={true}
+        theme="modern"
       />
       <button
-        onClick={handleGetImageUrl}
+        onClick={handleUpload}
         disabled={loading || images.length === 0}
-        className="bg-blue-500 text-white p-2 rounded disabled:opacity-50"
+        className="bg-blue-500 text-white px-4 py-2 rounded disabled:opacity-50"
       >
-        {loading ? "Uploading..." : "Upload Images"}
+        {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>
   );
 }
 ```
 
+### With Cloudinary
+
+```tsx
+import { ImageUploader, uploadImagesToCloudinary } from "ultra-image-uploader";
+import { useState } from "react";
+
+function CloudinaryUpload() {
+  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"
+      />
+      <button onClick={handleUpload} disabled={loading}>
+        Upload to Cloudinary
+      </button>
+    </div>
+  );
+}
+```
+
+### Auto Upload Mode
+
+```tsx
+import { ImageUploader } from "ultra-image-uploader";
+import { useState } from "react";
+
+function AutoUploadExample() {
+  const [images, setImages] = useState<File[]>([]);
+  const [uploadedUrls, setUploadedUrls] = useState<string[]>([]);
+
+  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"
+    />
+  );
+}
+```
+
+## 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
+
+```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}
+/>
+```
+
 ## Component 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"`      | Required   | Component operation mode |
-| `defaultImages`  | `string[]`               | `[]`       | Existing image URLs for update mode |
-| `multiple`       | `boolean`                | `false`    | Allow multiple file selection |
-| `inputStyles`    | `string`                 | `""`       | Custom CSS classes for upload input |
-| `containerStyles`| `string`                 | `""`       | Custom CSS classes for container |
-| `uploadText`     | `string`                 | `"Browse files or drag & drop"` | Upload area text |
-| `typeText`       | `string`                 | `"PNG, JPG, JPEG, WEBP"` | Allowed file types text |
+| 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 |
+| `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
 
-## ImgBB Utility
+Free image hosting with simple API:
 
-The package includes a utility function for uploading to ImgBB:
+```tsx
+import { uploadImagesToImageBB } from "ultra-image-uploader";
+
+const result = await uploadImagesToImageBB(
+  images,
+  "your-imgbb-api-key"
+);
+console.log(result.urls);
+```
+
+**Get API Key:** [imgbb.com/settings/api](https://imgbb.com/settings/api)
+
+### Cloudinary
+
+Enterprise-grade image hosting with transformations:
+
+```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",
+    },
+  }
+);
+```
+
+**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
+
+You can create custom upload providers:
+
+```tsx
+import { BaseImageProvider } from "ultra-image-uploader";
+
+class CustomProvider extends BaseImageProvider {
+  name = 'custom' as const;
 
-```ts
-interface ImageBBUrlResult {
-  urls: string[];
+  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());
+```
+
+### File Validation
+
+```tsx
+import {
+  validateImageFile,
+  validateFileComplete,
+  formatFileSize,
+} from "ultra-image-uploader";
+
+// Quick validation
+const validation = validateImageFile(file, {
+  maxSize: 5 * 1024 * 1024, // 5MB
+  allowedTypes: ["image/jpeg", "image/png"],
+});
+
+if (!validation.valid) {
+  console.error("Errors:", validation.errors);
 }
 
-async function uploadImagesToImageBB(
-  images: File[],
-  apiKey: string
-): Promise<ImageBBUrlResult>
+// Complete validation (with dimensions)
+const completeValidation = await validateFileComplete(file, {
+  maxSize: 10 * 1024 * 1024,
+  minWidth: 800,
+  maxWidth: 4000,
+  minHeight: 600,
+  maxHeight: 3000,
+});
 ```
 
-## Development
+### Transforming Cloudinary Images
 
-To contribute to this project:
+Generate transformed URLs for existing Cloudinary images:
 
-1. Clone the repository
-2. Install dependencies:
-   ```bash
-   yarn
-   ```
-3. Make your changes
-4. Run the build:
-   ```bash
-   yarn build
-   ```
-5. Test your changes
-6. Submit a pull request
+```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",
+  }
+);
+```
+
+## TypeScript Support
+
+The package is fully typed. Import types as needed:
+
+```tsx
+import type {
+  UploadProvider,
+  UploadResult,
+  ProviderConfig,
+  UploadOptions,
+  ImageUploaderProps,
+  UploaderTheme,
+  ValidationResult,
+  FileValidationOptions,
+} from "ultra-image-uploader";
+```
+
+## Examples
+
+### E-commerce Product Image Upload
+
+```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}
+    />
+  );
+}
+```
+
+### Profile Picture Upload
+
+```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"
+    />
+  );
+}
+```
+
+## Migration from v0.0.x
+
+If you're upgrading from version 0.0.x, the API is backward compatible:
+
+```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);
+```
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers
 
 ## License
 
 MIT © Digontha Das
 
-## Support
+## Support & Contributing
+
+- **Issues:** [GitHub Issues](https://github.com/digontha/ultra-image-uploader/issues)
+- **Contributing:** Pull requests are welcome!
+- **Discussions:** Ask questions and share ideas
+
+---
 
-For support or feature requests, please [open an issue](https://github.com/Digontha/ultra_image_uploader) on GitHub.
+Made with ❤️ by [Digontha Das](https://github.com/digontha)

package/dist/components/ImageUploader.d.ts

@@ -1,12 +1,66 @@
+import type { UploadProvider, ProviderConfig } from '../types';
+/**
+ * Theme configuration for the uploader
+ */
+export interface UploaderTheme {
+    primary?: string;
+    primaryHover?: string;
+    background?: string;
+    border?: string;
+    text?: string;
+    textSecondary?: string;
+    error?: string;
+    success?: string;
+    radius?: string;
+}
+export type ThemePreset = 'light' | 'dark' | 'modern' | 'minimal' | 'colorful';
+/**
+ * Props for the ImageUploader component
+ */
 export interface ImageUploaderProps {
+    /** Currently selected image files */
     images: File[];
+    /** Function to update the images array */
     setImages: (images: File[]) => void;
-    mode: "add" | "update";
+    /** Operation mode */
+    mode?: 'add' | 'update';
+    /** Existing image URLs for update mode */
     defaultImages?: string[];
+    /** Allow multiple file selection */
     multiple?: boolean;
-    inputStyles?: string;
-    containerStyles?: string;
+    /** Custom CSS classes */
+    className?: string;
+    /** Upload area text */
     uploadText?: string;
+    /** File type hint text */
     typeText?: string;
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allowed file types */
+    allowedTypes?: string[];
+    /** Theme preset */
+    theme?: ThemePreset;
+    /** Custom theme object */
+    customTheme?: UploaderTheme;
+    /** Show file size preview */
+    showFileSize?: boolean;
+    /** Enable drag and drop */
+    dragAndDrop?: boolean;
+    /** Image preview width */
+    previewWidth?: number;
+    /** Image preview height */
+    previewHeight?: number;
+    /** Callback when upload completes */
+    onUploadComplete?: (urls: string[]) => void;
+    /** Callback when upload fails */
+    onUploadError?: (error: Error) => void;
+    /** Auto upload on file selection */
+    autoUpload?: boolean;
+    /** Upload provider configuration */
+    uploadConfig?: {
+        provider: UploadProvider;
+        config: ProviderConfig;
+    };
 }
-export declare function ImageUploader({ images, setImages, mode, defaultImages, multiple, inputStyles, containerStyles, uploadText, typeText, }: ImageUploaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ImageUploader({ images, setImages, mode, defaultImages, multiple, className, uploadText, typeText, maxSize, allowedTypes, theme, customTheme, showFileSize, dragAndDrop, previewWidth, previewHeight, onUploadComplete, onUploadError, autoUpload, uploadConfig, }: ImageUploaderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ImageUploader.d.ts.map

package/dist/components/ImageUploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageUploader.d.ts","sourceRoot":"","sources":["../../src/components/ImageUploader.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AA4D/E;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,MAAM,EAAE,IAAI,EAAE,CAAC;IACf,0CAA0C;IAC1C,SAAS,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;IACpC,qBAAqB;IACrB,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IACxB,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mBAAmB;IACnB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,0BAA0B;IAC1B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,6BAA6B;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IAC5C,iCAAiC;IACjC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACvC,oCAAoC;IACpC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,YAAY,CAAC,EAAE;QACb,QAAQ,EAAE,cAAc,CAAC;QACzB,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAUD,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,SAAS,EACT,IAAY,EACZ,aAAkB,EAClB,QAAgB,EAChB,SAAc,EACd,UAAkD,EAClD,QAAiD,EACjD,OAA0B,EAC1B,YAAkF,EAClF,KAAe,EACf,WAAW,EACX,YAAmB,EACnB,WAAkB,EAClB,YAAkB,EAClB,aAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,UAAkB,EAClB,YAAY,GACb,EAAE,kBAAkB,2CAkVpB"}