@mgonza02/goal-image-gallery 1.0.2 → 1.0.5

package/README.md

@@ -2,7 +2,20 @@
 
 ## Overview
 
-The `GoalImageGallery` is a modern, feature-rich image gallery component for the Goal application. It provides a comprehensive solution for displaying, managing, and uploading images with advanced UI/UX features and accessibility support.
+The `GoalImageGallery` is a modern, feature-rich image gallery component for React applications. It provides a comprehensive solution for displaying, managing, and uploading images with advanced UI/UX features, accessibility support, and extensive customization options. This component is designed to be highly modular, performant, and easy to integrate into any React application.
+
+## 🚀 Quick Start
+
+```bash
+npm install @mgonza02/goal-image-gallery
+```
+
+```javascript
+import { GoalImageGallery } from '@mgonza02/goal-image-gallery';
+
+// Basic usage
+<GoalImageGallery imageCodes={['img1', 'img2']} canEdit={false} />
+```
 
 ## Key Features
 
@@ -10,152 +23,770 @@ The `GoalImageGallery` is a modern, feature-rich image gallery component for the
 - **File Upload**: Traditional file selection with drag-and-drop support
 - **Clipboard Paste**: Paste images directly from clipboard using Ctrl+V
 - **URL Loading**: Load images from remote URLs
+- **Batch Upload**: Upload multiple images simultaneously
 
 ### 🎨 **Modern UI/UX**
-- Responsive grid layout that adapts to screen size
-- Smooth hover effects and transitions
-- Material Design 3 styling
-- Dark/light theme support
-- Loading states and skeleton animations
+- **Responsive Design**: Adapts to all screen sizes and devices
+- **Material Design 3**: Latest Material-UI components and styling
+- **Smooth Animations**: Hover effects, transitions, and loading states
+- **Dark/Light Theme**: Automatic theme detection and support
+- **Accessibility**: WCAG 2.1 AA compliant with full keyboard navigation
 
 ### 🔍 **Advanced Image Viewer**
-- Full-screen modal viewer
-- Zoom controls (0.5x to 3x)
-- Image navigation (previous/next)
-- Keyboard navigation support
-- Download functionality
-
-### ♿ **Accessibility**
-- ARIA labels and roles
-- Keyboard navigation
-- Screen reader support
-- High contrast mode compatibility
-- Focus management
-
-### 📱 **Mobile Responsive**
-- Touch-friendly interface
-- Optimized for mobile devices
-- Swipe gestures support
-- Responsive breakpoints
-
-## Installation
+- **Full-Screen Modal**: Immersive image viewing experience
+- **Zoom Controls**: Zoom from 0.5x to 3x with smooth transitions
+- **Image Navigation**: Previous/next with keyboard shortcuts
+- **Download Support**: Direct image download functionality
+- **Image Information**: Display metadata and details
+
+### 🛠️ **Customization & Extensibility**
+- **Slot System**: Replace default components with custom implementations
+- **Flexible Props**: Extensive configuration options
+- **TypeScript Support**: Full type definitions included
+- **Hook-Based Architecture**: Reusable custom hooks for complex logic
+
+### 📱 **Mobile-First Design**
+- **Touch Gestures**: Swipe, pinch-to-zoom, and tap interactions
+- **Responsive Breakpoints**: Optimized layouts for all devices
+- **Performance Optimized**: Lazy loading and efficient rendering
+- **Offline Support**: Graceful degradation for poor connectivity
+
+## Installation & Setup
+
+### NPM Installation
 
 ```bash
 npm install @mgonza02/goal-image-gallery
 ```
 
+### Peer Dependencies
+
+Make sure you have the required peer dependencies installed:
+
+```bash
+npm install @mui/material @mui/icons-material @emotion/react @emotion/styled react react-dom
+```
+
+### Import
+
 ```javascript
+// Main component
 import { GoalImageGallery } from '@mgonza02/goal-image-gallery';
+
+// Individual components and hooks
+import { 
+  ImageGalleryGrid, 
+  ImageGalleryModal, 
+  useImageGallery,
+  useImageZoom 
+} from '@mgonza02/goal-image-gallery';
+```
+
+### TypeScript Support
+
+The component includes full TypeScript definitions:
+
+```typescript
+import { GoalImageGalleryProps } from '@mgonza02/goal-image-gallery';
+
+const MyComponent: React.FC<{ images: string[] }> = ({ images }) => {
+  return (
+    <GoalImageGallery
+      imageCodes={images}
+      canEdit={true}
+      // TypeScript will provide full autocomplete and type checking
+    />
+  );
+};
 ```
 
-## Basic Usage
+## Usage Examples
+
+### 1. Basic Read-Only Gallery
+
+Perfect for displaying images without editing capabilities:
 
-### Simple Gallery
 ```javascript
 <GoalImageGallery
   imageCodes={['img1', 'img2', 'img3']}
   canEdit={false}
+  emptyMessage="No images to display"
+  getImageUrl={({ imageCode }) => `https://api.example.com/images/${imageCode}`}
 />
 ```
 
-### Editable Gallery
+### 2. Editable Product Gallery
+
+Full-featured gallery with upload, edit, and delete capabilities:
+
+```javascript
+const ProductGallery = () => {
+  const [productImages, setProductImages] = useState(['prod1', 'prod2']);
+  
+  const handleImageUpload = async (imageData) => {
+    try {
+      const response = await api.uploadProductImage({
+        ...imageData,
+        productId: product.id,
+        companyId: currentCompany
+      });
+      
+      return {
+        success: true,
+        data: response.data,
+        message: 'Images uploaded successfully'
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error.message
+      };
+    }
+  };
+
+  const refreshProduct = (result) => {
+    // Update product data
+    setProductImages(prev => [...prev, result.data.code]);
+  };
+
+  return (
+    <GoalImageGallery
+      imageCodes={productImages}
+      canEdit={true}
+      ownerEntity={{ id: product.id, type: 'product' }}
+      imageHandlerApi={handleImageUpload}
+      afterUpload={refreshProduct}
+      multiple={true}
+      emptyMessage="No product images available"
+      showImageInfo={true}
+      allowDownload={true}
+      permission="EDIT_PRODUCTS"
+      hasPermission={(perm) => userPermissions.includes(perm)}
+      currentCompany={user.companyId}
+    />
+  );
+};
+```
+
+### 3. User Avatar Gallery
+
+Single image gallery for user avatars:
+
 ```javascript
 <GoalImageGallery
-  imageCodes={imageCodes}
-  canEdit={true}
-  ownerEntity={{ id: 'product-123' }}
-  imageHandlerApi={handleImageUpload}
-  afterUpload={refreshImages}
-  multiple={true}
+  imageCodes={user.avatar}
+  canEdit={isOwner}
+  ownerEntity={{ id: user.id, type: 'user' }}
+  imageHandlerApi={userImageApi.upload}
+  afterUpload={refreshUser}
+  multiple={false}
+  emptyMessage="No avatar set"
+  showImageInfo={false}
+  getImageUrl={({ imageCode }) => `https://cdn.example.com/avatars/${imageCode}`}
 />
 ```
 
-### Advanced Configuration
+### 4. Custom Image Selector
+
+Using the slot system to provide a custom image selector:
+
 ```javascript
+// Custom selector component
+const CustomImageSelector = ({ 
+  afterUpload, 
+  activate, 
+  onCancel, 
+  multiple, 
+  title, 
+  uploadMessage,
+  maxFileSize,
+  acceptedFormats,
+  customStyles 
+}) => {
+  const [dragActive, setDragActive] = useState(false);
+  const [uploading, setUploading] = useState(false);
+
+  const handleFiles = async (files) => {
+    setUploading(true);
+    try {
+      // Custom upload logic
+      const result = await uploadFiles(files);
+      afterUpload(result);
+    } catch (error) {
+      console.error('Upload failed:', error);
+    } finally {
+      setUploading(false);
+    }
+  };
+
+  return (
+    <div 
+      style={{
+        ...customStyles,
+        border: dragActive ? '2px solid #007bff' : '2px dashed #ccc',
+        borderRadius: '8px',
+        padding: '40px',
+        textAlign: 'center',
+        backgroundColor: dragActive ? '#f8f9fa' : '#fff'
+      }}
+      onDragOver={(e) => {
+        e.preventDefault();
+        setDragActive(true);
+      }}
+      onDragLeave={() => setDragActive(false)}
+      onDrop={async (e) => {
+        e.preventDefault();
+        setDragActive(false);
+        const files = Array.from(e.dataTransfer.files);
+        await handleFiles(files);
+      }}
+    >
+      <h3>{title}</h3>
+      <p>{uploadMessage}</p>
+      {uploading && <p>Uploading...</p>}
+      <input 
+        type="file" 
+        multiple={multiple}
+        accept={acceptedFormats?.join(',')}
+        onChange={(e) => handleFiles(Array.from(e.target.files))}
+        style={{ margin: '10px 0' }}
+      />
+      <br />
+      <button onClick={onCancel} disabled={uploading}>
+        Cancel
+      </button>
+    </div>
+  );
+};
+
+// Usage with custom selector
 <GoalImageGallery
-  imageCodes={imageCodes}
+  imageCodes={images}
   canEdit={true}
+  ownerEntity={{ id: 'entity-123' }}
+  imageHandlerApi={handleUpload}
+  afterUpload={refreshData}
+  multiple={true}
+  slot={{
+    selector: CustomImageSelector
+  }}
+  slotProps={{
+    selector: {
+      maxFileSize: 10 * 1024 * 1024, // 10MB
+      acceptedFormats: ['image/jpeg', 'image/png', 'image/webp'],
+      customStyles: { 
+        borderColor: '#007bff',
+        backgroundColor: '#f8f9fa'
+      }
+    }
+  }}
+/>
+```
   ownerEntity={{ id: 'product-123', type: 'product' }}
   imageHandlerApi={handleImageUpload}
   afterUpload={refreshImages}
   multiple={true}
-  permission="EDIT_IMAGES"
-  emptyMessage="No product images available"
+  slot={{
+    selector: CustomImageSelector
+  }}
+  slotProps={{
+    selector: {
+      maxFileSize: 10 * 1024 * 1024, // 10MB
+      acceptedFormats: ['image/jpeg', 'image/png'],
+      uploadEndpoint: '/api/upload',
+      customStyles: { borderColor: '#007bff' }
+    }
+  }}
+/>
+```
+
+## Props Reference
+
+### Core Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `imageCodes` | `string \| string[]` | `[]` | No | Image codes to display in the gallery |
+| `canEdit` | `boolean` | `false` | No | Enable editing capabilities (upload, delete) |
+| `ownerEntity` | `object` | `undefined` | No | Entity that owns the images (required for editing) |
+| `imageHandlerApi` | `function` | `undefined` | No | API function for image operations (required for editing) |
+| `afterUpload` | `function` | `undefined` | No | Callback function called after successful upload |
+| `multiple` | `boolean` | `false` | No | Allow multiple image selection and upload |
+
+### Display Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `emptyMessage` | `string` | `'No hay imágenes para mostrar'` | No | Message displayed when no images are available |
+| `showImageInfo` | `boolean` | `false` | No | Show image information overlay on hover |
+| `allowDownload` | `boolean` | `false` | No | Enable image download functionality |
+| `getImageUrl` | `function` | `({ imageCode }) => '/images/${imageCode}'` | No | Function to generate image URLs from codes |
+| `noImageUrl` | `string` | `'/images/no-image.png'` | No | Fallback image URL for broken images |
+
+### Permission Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `permission` | `string` | `undefined` | No | Required permission string for editing |
+| `hasPermission` | `function` | `() => true` | No | Function to check if user has required permission |
+| `currentCompany` | `string` | `'default'` | No | Current company identifier for API calls |
+
+### Customization Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `slot` | `object` | `{}` | No | Slot components for customization |
+| `slotProps` | `object` | `{}` | No | Props passed to slot components |
+| `showError` | `function` | `console.error` | No | Function to display error messages |
+
+### Advanced Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `maxFileSize` | `number` | `25 * 1024 * 1024` | No | Maximum file size in bytes (25MB default) |
+| `acceptedFormats` | `string[]` | `['image/jpeg', 'image/png', 'image/gif', 'image/webp']` | No | Accepted image formats |
+| `thumbnailSize` | `number` | `200` | No | Thumbnail size in pixels |
+| `gridColumns` | `number` | `auto` | No | Number of columns in grid (auto-calculated if not provided) |
+| `enableLazyLoading` | `boolean` | `true` | No | Enable lazy loading for images |
+| `enableVirtualization` | `boolean` | `false` | No | Enable virtual scrolling for large image sets |
+
+### Prop Examples
+
+```javascript
+// Basic configuration
+<GoalImageGallery
+  imageCodes={['img1', 'img2', 'img3']}
+  canEdit={false}
+/>
+
+// Full configuration
+<GoalImageGallery
+  imageCodes={product.images}
+  canEdit={user.canEdit}
+  ownerEntity={{ id: product.id, type: 'product' }}
+  imageHandlerApi={async (data) => {
+    const response = await api.uploadImage(data);
+    return { success: true, data: response };
+  }}
+  afterUpload={(result) => {
+    console.log('Upload successful:', result);
+    refreshProduct();
+  }}
+  multiple={true}
+  permission="EDIT_PRODUCTS"
+  emptyMessage="No product images yet"
   showImageInfo={true}
   allowDownload={true}
+  getImageUrl={({ imageCode, thumbMail }) => 
+    `https://api.example.com/images/${imageCode}${thumbMail ? '?thumb=true' : ''}`
+  }
+  noImageUrl="https://api.example.com/images/placeholder.png"
+  hasPermission={(perm) => user.permissions.includes(perm)}
+  currentCompany={user.companyId}
+  showError={(msg) => toast.error(msg)}
+  maxFileSize={10 * 1024 * 1024}
+  acceptedFormats={['image/jpeg', 'image/png']}
+  thumbnailSize={150}
+  gridColumns={3}
 />
 ```
 
-## Props
+## Upload Methods & Features
+
+### 1. File Upload (Drag & Drop)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `canEdit` | `boolean` | `false` | Enable editing capabilities |
-| `ownerEntity` | `object` | - | Entity that owns the images |
-| `imageHandlerApi` | `function` | - | API function for image operations |
-| `afterUpload` | `function` | - | Callback after successful upload |
-| `imageCodes` | `string \| array` | - | Image codes to display |
-| `multiple` | `boolean` | `false` | Allow multiple image selection |
-| `permission` | `string` | - | Required permission for editing |
-| `emptyMessage` | `string` | `'No hay imágenes para mostrar'` | Message shown when no images |
-| `showImageInfo` | `boolean` | `false` | Show image information overlay |
-| `allowDownload` | `boolean` | `true` | Enable download functionality |
+The most common method for uploading images:
 
-## Upload Methods
+```javascript
+// Features:
+// - Click to select files
+// - Drag and drop support
+// - Multiple file selection
+// - File type validation
+// - Size limit enforcement
+// - Progress indication
 
-### 1. File Upload
-Users can upload images by:
-- Clicking the "Add Image" button
-- Dragging and dropping files onto the gallery
-- Using the file selection dialog
+<GoalImageGallery
+  canEdit={true}
+  multiple={true}
+  maxFileSize={10 * 1024 * 1024} // 10MB
+  acceptedFormats={['image/jpeg', 'image/png', 'image/webp']}
+  // ... other props
+/>
+```
 
-**Supported formats**: JPEG, PNG, GIF, WebP
-**Maximum file size**: 25MB (configurable)
+**Supported Features:**
+- **File Types**: JPEG, PNG, GIF, WebP, SVG
+- **Size Limits**: Configurable (default: 25MB)
+- **Batch Upload**: Upload multiple files simultaneously
+- **Progress Tracking**: Visual progress indicators
+- **Error Handling**: File validation and error reporting
 
 ### 2. Clipboard Paste
-Users can paste images directly from the clipboard:
-- Copy an image from any source (screenshot, browser, etc.)
-- Press `Ctrl+V` anywhere in the gallery
-- The image will be automatically processed and uploaded
 
-**Note**: Clipboard functionality requires modern browser support
+Revolutionary clipboard image support:
+
+```javascript
+// Usage:
+// 1. Copy image from any source (screenshot, browser, etc.)
+// 2. Focus on the gallery
+// 3. Press Ctrl+V (Cmd+V on Mac)
+// 4. Image is automatically processed and uploaded
+
+// Auto-enabled when canEdit={true}
+<GoalImageGallery
+  canEdit={true}
+  // Clipboard paste is automatically available
+/>
+```
+
+**Clipboard Features:**
+- **Cross-Platform**: Works on Windows, Mac, and Linux
+- **Source Agnostic**: Copy from any application
+- **Auto-Processing**: Automatic image processing and optimization
+- **Format Support**: All major image formats
+- **Browser Support**: Modern browsers (Chrome, Firefox, Safari, Edge)
 
 ### 3. URL Loading
-Users can load images from URLs:
-- Enter a direct image URL
-- The component validates the URL and loads the image
-- Supports all standard image formats
 
-## Keyboard Shortcuts
+Load images from external URLs:
 
-### Image Viewer
-- `←` / `→`: Navigate between images
-- `+` / `=`: Zoom in
-- `-`: Zoom out
-- `Escape`: Close image viewer
+```javascript
+// Users can enter image URLs directly
+// Component validates and loads the image
+// Supports CORS-enabled images
+
+const handleUrlUpload = async (imageUrl) => {
+  try {
+    const response = await fetch(imageUrl);
+    const blob = await response.blob();
+    
+    // Process the image
+    const result = await processImageBlob(blob);
+    
+    return {
+      success: true,
+      data: result
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: 'Failed to load image from URL'
+    };
+  }
+};
+```
+
+### 4. Mobile Camera Integration
+
+Enhanced mobile support:
+
+```javascript
+// Mobile-specific features:
+// - Camera access
+// - Photo library access
+// - Touch gestures
+// - Responsive design
+
+<GoalImageGallery
+  canEdit={true}
+  // Mobile camera is automatically available on mobile devices
+  mobileOptimized={true}
+  touchGestures={true}
+/>
+```
+
+## Keyboard Shortcuts & Navigation
+
+### Image Viewer Shortcuts
+
+| Shortcut | Action | Context |
+|----------|---------|---------|
+| `←` / `→` | Navigate between images | Image viewer open |
+| `+` / `=` | Zoom in | Image viewer open |
+| `-` | Zoom out | Image viewer open |
+| `Escape` | Close image viewer | Image viewer open |
+| `Space` | Toggle fullscreen | Image viewer open |
+| `Enter` | Open selected image | Gallery focused |
 
 ### Gallery Navigation
-- `Tab`: Navigate between interactive elements
-- `Enter` / `Space`: Activate buttons
-- `Escape`: Close dialogs
 
-## API Integration
+| Shortcut | Action | Context |
+|----------|---------|---------|
+| `Tab` | Navigate between elements | Gallery focused |
+| `Shift + Tab` | Navigate backwards | Gallery focused |
+| `Enter` / `Space` | Activate button/link | Element focused |
+| `Ctrl + V` | Paste from clipboard | Editing enabled |
+| `Delete` | Remove selected image | Image selected |
 
-The component requires an `imageHandlerApi` function that handles image operations:
+### Accessibility Features
+
+```javascript
+// Built-in accessibility features:
+<GoalImageGallery
+  // ARIA labels are automatically generated
+  ariaLabel="Product image gallery"
+  ariaDescribedBy="gallery-instructions"
+  
+  // Screen reader support
+  screenReaderOptimized={true}
+  
+  // High contrast mode
+  highContrastMode={true}
+  
+  // Keyboard navigation
+  keyboardNavigation={true}
+  
+  // Focus management
+  manageFocus={true}
+/>
+```
+
+### Custom Keyboard Shortcuts
+
+```javascript
+import { useKeyboardNavigation } from '@mgonza02/goal-image-gallery';
+
+const CustomGallery = () => {
+  const { handleKeyPress } = useKeyboardNavigation({
+    onPreviousImage: () => console.log('Previous'),
+    onNextImage: () => console.log('Next'),
+    onCloseImage: () => console.log('Close'),
+    onZoomIn: () => console.log('Zoom in'),
+    onZoomOut: () => console.log('Zoom out'),
+    // Add custom shortcuts
+    customShortcuts: {
+      'd': () => downloadCurrentImage(),
+      'i': () => showImageInfo(),
+      'f': () => toggleFullscreen()
+    }
+  });
+
+  return (
+    <div onKeyDown={handleKeyPress}>
+      <GoalImageGallery {...props} />
+    </div>
+  );
+};
+```
+
+## API Integration & Data Flow
+
+### API Handler Function
+
+The `imageHandlerApi` function is the core of the upload system:
 
 ```javascript
 const handleImageUpload = async (imageData) => {
   try {
+    // imageData contains:
+    // - files: Array of File objects
+    // - metadata: Additional data (owner, company, etc.)
+    // - options: Upload options (compression, format, etc.)
+    
     const response = await api.uploadImages({
-      ...imageData,
-      companyId: currentCompany,
-      entityId: ownerEntity.id
+      files: imageData.files,
+      companyId: imageData.metadata.companyId,
+      entityId: imageData.metadata.entityId,
+      entityType: imageData.metadata.entityType,
+      folder: imageData.options.folder,
+      compression: imageData.options.compression,
+      thumbnailSize: imageData.options.thumbnailSize
+    });
+    
+    // Must return standardized response
+    return {
+      success: true,
+      data: response.data, // Array of uploaded image objects
+      message: 'Images uploaded successfully',
+      codes: response.data.map(img => img.code) // Optional: image codes
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: error.message || 'Upload failed',
+      error: error
+    };
+  }
+};
+```
+
+### API Response Format
+
+Expected response format from your API:
+
+```javascript
+// Successful response
+{
+  success: true,
+  data: [
+    {
+      id: 123,
+      code: 'img_abc123',
+      url: 'https://cdn.example.com/images/img_abc123.jpg',
+      thumbnailUrl: 'https://cdn.example.com/images/img_abc123_thumb.jpg',
+      filename: 'product-image.jpg',
+      size: 1024000,
+      width: 1920,
+      height: 1080,
+      mimeType: 'image/jpeg',
+      uploadedAt: '2023-01-01T00:00:00Z'
+    }
+  ],
+  message: 'Upload successful'
+}
+
+// Error response
+{
+  success: false,
+  message: 'File size too large',
+  error: {
+    code: 'FILE_TOO_LARGE',
+    details: 'Maximum file size is 25MB'
+  }
+}
+```
+
+### Real-World API Integration Examples
+
+#### 1. REST API Integration
+
+```javascript
+const restApiHandler = async (imageData) => {
+  const formData = new FormData();
+  
+  // Add files
+  imageData.files.forEach((file, index) => {
+    formData.append(`files[${index}]`, file);
+  });
+  
+  // Add metadata
+  formData.append('companyId', imageData.metadata.companyId);
+  formData.append('entityId', imageData.metadata.entityId);
+  formData.append('entityType', imageData.metadata.entityType);
+  
+  try {
+    const response = await fetch('/api/images/upload', {
+      method: 'POST',
+      body: formData,
+      headers: {
+        'Authorization': `Bearer ${authToken}`,
+        // Don't set Content-Type, let browser set it with boundary
+      }
+    });
+    
+    const result = await response.json();
+    
+    if (!response.ok) {
+      throw new Error(result.message || 'Upload failed');
+    }
+    
+    return {
+      success: true,
+      data: result.images,
+      message: result.message
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: error.message
+    };
+  }
+};
+```
+
+#### 2. GraphQL Integration
+
+```javascript
+import { useMutation } from '@apollo/client';
+
+const UPLOAD_IMAGES = gql`
+  mutation UploadImages($files: [Upload!]!, $input: ImageUploadInput!) {
+    uploadImages(files: $files, input: $input) {
+      success
+      message
+      images {
+        id
+        code
+        url
+        thumbnailUrl
+        filename
+        size
+        width
+        height
+      }
+    }
+  }
+`;
+
+const GraphQLImageGallery = ({ ownerEntity, ...props }) => {
+  const [uploadImages] = useMutation(UPLOAD_IMAGES);
+  
+  const handleImageUpload = async (imageData) => {
+    try {
+      const { data } = await uploadImages({
+        variables: {
+          files: imageData.files,
+          input: {
+            companyId: imageData.metadata.companyId,
+            entityId: imageData.metadata.entityId,
+            entityType: imageData.metadata.entityType
+          }
+        }
+      });
+      
+      return {
+        success: data.uploadImages.success,
+        data: data.uploadImages.images,
+        message: data.uploadImages.message
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: error.message
+      };
+    }
+  };
+  
+  return (
+    <GoalImageGallery
+      {...props}
+      ownerEntity={ownerEntity}
+      imageHandlerApi={handleImageUpload}
+    />
+  );
+};
+```
+
+#### 3. Firebase Storage Integration
+
+```javascript
+import { ref, uploadBytes, getDownloadURL } from 'firebase/storage';
+import { storage } from './firebaseConfig';
+
+const firebaseHandler = async (imageData) => {
+  try {
+    const uploadPromises = imageData.files.map(async (file) => {
+      const storageRef = ref(storage, `images/${Date.now()}_${file.name}`);
+      const snapshot = await uploadBytes(storageRef, file);
+      const downloadURL = await getDownloadURL(snapshot.ref);
+      
+      return {
+        id: snapshot.ref.fullPath,
+        code: snapshot.ref.name,
+        url: downloadURL,
+        filename: file.name,
+        size: file.size,
+        mimeType: file.type
+      };
     });
     
+    const results = await Promise.all(uploadPromises);
+    
     return {
       success: true,
-      data: response.data,
-      message: 'Images uploaded successfully'
+      data: results,
+      message: 'Images uploaded to Firebase'
     };
   } catch (error) {
     return {
@@ -166,6 +797,140 @@ const handleImageUpload = async (imageData) => {
 };
 ```
 
+### Error Handling Best Practices
+
+```javascript
+const robustApiHandler = async (imageData) => {
+  try {
+    // Validate files before upload
+    const validFiles = imageData.files.filter(file => {
+      if (file.size > 25 * 1024 * 1024) {
+        console.warn(`File ${file.name} is too large`);
+        return false;
+      }
+      if (!file.type.startsWith('image/')) {
+        console.warn(`File ${file.name} is not an image`);
+        return false;
+      }
+      return true;
+    });
+    
+    if (validFiles.length === 0) {
+      return {
+        success: false,
+        message: 'No valid files to upload'
+      };
+    }
+    
+    // Attempt upload with retry logic
+    let attempts = 0;
+    const maxAttempts = 3;
+    
+    while (attempts < maxAttempts) {
+      try {
+        const response = await uploadFiles(validFiles);
+        return {
+          success: true,
+          data: response.data,
+          message: 'Upload successful'
+        };
+      } catch (error) {
+        attempts++;
+        if (attempts >= maxAttempts) {
+          throw error;
+        }
+        
+        // Wait before retry
+        await new Promise(resolve => setTimeout(resolve, 1000 * attempts));
+      }
+    }
+  } catch (error) {
+    // Log error for debugging
+    console.error('Image upload failed:', error);
+    
+    return {
+      success: false,
+      message: error.message || 'Upload failed. Please try again.',
+      error: error
+    };
+  }
+};
+```
+    };
+  }
+};
+```
+
+## Customization Options
+
+### Slot System
+
+The GoalImageGallery supports a flexible slot system for customization:
+
+#### Custom Image Selector
+
+You can provide your own image selector component:
+
+```javascript
+// Custom selector component
+const CustomImageSelector = ({ 
+  afterUpload, 
+  activate, 
+  onCancel, 
+  multiple, 
+  title, 
+  uploadMessage,
+  maxFileSize,
+  acceptedFormats,
+  customStyles 
+}) => {
+  const handleFileSelect = async (files) => {
+    // Your custom upload logic
+    const result = await uploadFiles(files);
+    afterUpload(result);
+  };
+
+  return (
+    <div style={{ ...customStyles, padding: '20px' }}>
+      <h3>{title}</h3>
+      <p>{uploadMessage}</p>
+      <input 
+        type="file" 
+        multiple={multiple}
+        accept={acceptedFormats.join(',')}
+        onChange={(e) => handleFileSelect(e.target.files)}
+      />
+      <button onClick={onCancel}>Cancel</button>
+    </div>
+  );
+};
+
+// Usage
+<GoalImageGallery
+  // ... other props
+  slot={{
+    selector: CustomImageSelector
+  }}
+  slotProps={{
+    selector: {
+      maxFileSize: 10 * 1024 * 1024,
+      acceptedFormats: ['image/jpeg', 'image/png'],
+      customStyles: { 
+        border: '2px dashed #007bff',
+        borderRadius: '8px',
+        backgroundColor: '#f8f9fa'
+      }
+    }
+  }}
+/>
+```
+
+### Available Slots
+
+| Slot | Description | Props Passed |
+|------|-------------|--------------|
+| `selector` | Custom image selector/uploader component | `afterUpload`, `activate`, `onCancel`, `multiple`, `title`, `uploadMessage`, and custom props from `slotProps.selector` |
+
 ## Styling and Theming
 
 The component uses Material-UI's theming system and can be customized: