@akinon/pz-similar-products 1.92.0-rc.16

package/README.md

@@ -0,0 +1,1372 @@
+# Similar Products
+
+🔍 **AI-powered visual search plugin for e-commerce platforms with comprehensive customization options.**
+
+---
+
+## Table of Contents
+
+### 📋 Main Sections
+
+- [Features](#markdown-header-features)
+- [Installation](#markdown-header-installation)
+- [Quick Start](#markdown-header-quick-start)
+- [Available Components](#markdown-header-available-components)
+- [Configuration](#markdown-header-configuration)
+- [Customization Strategies](#markdown-header-customization-strategies)
+- [Professional Examples](#markdown-header-professional-examples)
+- [Usage Examples](#markdown-header-usage-examples)
+- [Complete Styling Reference](#markdown-header-complete-styling-reference)
+- [Best Practices](#markdown-header-best-practices)
+- [Summary](#markdown-header-summary)
+
+### 🔧 Quick Start Guide
+
+- [Plugin Module Integration](#markdown-header-plugin-module-integration)
+
+### 📦 Available Components
+
+- [ProductImageSearchFeature](#markdown-header-productimasearchfeature)
+- [HeaderImageSearchFeature](#markdown-header-headerimasearchfeature)
+- [SimilarProductsPlugin](#markdown-header-similarproductsplugin)
+
+### ⚙️ Configuration
+
+- [SimilarProductsSettings Interface](#markdown-header-similarproductssettings-interface)
+
+### 🎨 Professional Examples
+
+- [E-commerce Store Integration](#markdown-header-e-commerce-store-integration)
+- [Brand Customization](#markdown-header-brand-customization)
+- [Custom Product Cards with Badges](#markdown-header-custom-product-cards-with-badges)
+- [Advanced Filter Sidebar with Dynamic Icons](#markdown-header-advanced-filter-sidebar-with-dynamic-icons)
+- [Header Integration](#markdown-header-header-integration)
+- [Modern Pagination with Progress](#markdown-header-modern-pagination-with-progress)
+- [Advanced Modal with Custom Header & Controls](#markdown-header-advanced-modal-with-custom-header-controls)
+- [Complete Brand Theme Integration](#markdown-header-complete-brand-theme-integration)
+
+### 📖 Styling Reference
+
+- [Available Style Targets (40+ options)](#markdown-header-available-style-targets-40-options)
+- [Available Render Functions (25+ options)](#markdown-header-available-render-functions-25-options)
+
+### ✅ Best Practices
+
+- [Performance Optimization](#markdown-header-performance-optimization)
+- [Accessibility](#markdown-header-accessibility)
+- [Essential Props](#markdown-header-essential-props)
+- [Common Settings](#markdown-header-common-settings)
+
+---
+
+## Features
+
+- **🖼️ Visual Search**: AI-powered image-based product discovery
+- **✂️ Image Cropping**: Built-in cropping functionality with manual confirmation for precise searches
+- **🎛️ Advanced Filtering**: Dynamic facet-based filtering system
+- **📄 Multiple Pagination Modes**: Traditional pagination, load more button, and infinite scroll
+- **🎨 Granular Customization**: 40+ style targets and 25+ render points
+- **📱 Mobile Responsive**: Optimized for all device sizes
+- **⚡ Performance Optimized**: Lazy loading and efficient rendering
+- **🔧 TypeScript**: Full TypeScript support with detailed type definitions
+
+## Installation
+
+```bash
+npx @akinon/projectzero@latest --plugins
+```
+
+Select `pz-similar-products` from the plugin list during installation.
+
+## Quick Start
+
+### Plugin Module Integration
+
+The recommended way to integrate the plugin is using ProjectZero's PluginModule system:
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+// Product detail page integration
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    showResetButton: true,
+    settings: {
+      maxFileSize: 5,
+      enableCropping: true,
+      customStyles: {
+        modal: 'max-w-6xl rounded-xl shadow-2xl',
+        productItem: 'rounded-lg shadow-sm hover:shadow-lg'
+      }
+    }
+  }}
+/>
+
+// Header search integration
+<PluginModule
+  component={Component.HeaderImageSearchFeature}
+  props={{
+    isEnabled: true,
+    settings: {
+      maxFileSize: 5,
+      customStyles: {
+        imageSearchModal: 'max-w-lg rounded-xl'
+      }
+    }
+  }}
+/>
+```
+
+## Available Components
+
+### ProductImageSearchFeature
+
+Ready-to-use component for product detail pages with visual search functionality.
+
+**Props:**
+
+- `product`: Product object (required)
+- `activeIndex`: Current image index in product gallery
+- `showResetButton`: Show reset to original image button
+- `settings`: Customization settings object
+
+### HeaderImageSearchFeature
+
+Header search integration component for global image upload functionality.
+
+**Props:**
+
+- `isEnabled`: Enable/disable the feature
+- `settings`: Customization settings object
+
+### SimilarProductsPlugin
+
+Core modal component for advanced integration scenarios.
+
+**Props:**
+
+- `product`: Product object (required)
+- `isOpen`: Modal open state
+- `onClose`: Close handler function
+- `settings`: Customization settings object
+
+## Configuration
+
+### SimilarProductsSettings Interface
+
+```typescript
+interface SimilarProductsSettings {
+  // Core functionality
+  maxFileSize?: number; // MB (default: 5)
+  imageFormats?: string[]; // ['jpg', 'jpeg', 'png', 'webp']
+  cropAspectRatio?: number; // Fixed aspect ratio
+  resultsPerPage?: number; // Products per page (default: 20)
+  enableCropping?: boolean; // Enable image cropping (default: true)
+  enableFileUpload?: boolean; // Enable file upload (default: true)
+
+  // Pagination settings
+  paginationType?: 'pagination' | 'load-more' | 'infinite-scroll'; // Pagination mode (default: 'pagination')
+  loadMoreText?: string; // Load more button text (default: 'Load More')
+  loadMoreStyle?: 'button' | 'auto'; // Load more behavior (default: 'button')
+  loadMoreThreshold?: number; // Pixels from bottom for auto load (default: 100)
+  maxPagesLoadMore?: number; // Maximum pages to load in load-more mode
+
+  // 40+ granular style targets
+  customStyles?: {
+    // Main components
+    modal?: string;
+    filterSidebar?: string;
+    resultsGrid?: string;
+
+    // Deep nested elements
+    productItem?: string;
+    productImage?: string;
+    productTitle?: string;
+    productPrice?: string;
+    paginationButton?: string;
+    loadMoreButton?: string;
+    loadMoreContainer?: string;
+    activeFilterTag?: string;
+    filterGroup?: string;
+    imageSection?: string;
+    loadingSpinner?: string;
+    // ... see examples for complete list
+  };
+
+  // 25+ render functions for granular control
+  customRenderers?: {
+    render?: {
+      modal?: {
+        renderHeader?: (props) => React.ReactNode;
+        renderActiveFilters?: (props) => React.ReactNode;
+        renderControls?: (props) => React.ReactNode;
+        renderItemCount?: (props) => React.ReactNode;
+        // ... see examples for complete list
+      };
+      resultsGrid?: {
+        renderProductItem?: (props) => React.ReactNode;
+        renderPagination?: (props) => React.ReactNode;
+        renderGridContainer?: (props) => React.ReactNode;
+        // ... see examples for complete list
+      };
+      filterSidebar?: {
+        renderImageSection?: (props) => React.ReactNode;
+        renderFilterGroup?: (props) => React.ReactNode;
+        renderCropButton?: (props) => React.ReactNode;
+        // ... see examples for complete list
+      };
+    };
+  };
+
+  // Theme configuration
+  theme?: {
+    colors?: Record<string, string>;
+    spacing?: Record<string, string>;
+    borderRadius?: Record<string, string>;
+  };
+}
+```
+
+## Image Cropping with Manual Confirmation
+
+The plugin features an advanced image cropping system with manual confirmation for precise control over search queries.
+
+### Cropping Workflow
+
+1. **Activate Crop Mode**: Click the crop button (✂️) to enter cropping mode
+2. **Select Area**: Drag to select the desired area of the image
+3. **Confirm Selection**: Click the green tick button (✓) to process the crop
+4. **Cancel/Reset**: Click the X button to cancel current selection or return to previous successful crop
+
+### Smart Crop Memory
+
+The system intelligently manages crop states:
+
+- **Successful Crops**: Remembered and can be restored if new crop is cancelled
+- **Pending Crops**: Automatically discarded when crop mode is cancelled
+- **Visual Feedback**: Crop overlay remains visible when not in crop mode
+
+### Customization Options
+
+```tsx
+const cropSettings = {
+  enableCropping: true, // Enable/disable cropping feature
+  cropAspectRatio: 1, // Fixed aspect ratio (optional)
+
+  customStyles: {
+    cropButton: 'bg-white shadow-lg hover:shadow-xl transition-shadow',
+    tickButton: 'bg-green-50 text-green-600 hover:bg-green-100', // New tick button styling
+    imageContainer: 'border-2 border-dashed border-blue-300'
+  },
+
+  customRenderers: {
+    render: {
+      filterSidebar: {
+        renderCropButton: ({ isCropping, onClick, disabled }) => (
+          <button
+            onClick={onClick}
+            disabled={disabled}
+            className={`custom-crop-btn ${isCropping ? 'active' : ''}`}
+          >
+            {isCropping ? '✕ Cancel' : '✂️ Crop'}
+          </button>
+        ),
+        renderTickButton: ({ onClick, disabled }) => (
+          <button
+            onClick={onClick}
+            disabled={disabled}
+            className="custom-tick-btn bg-green-500 text-white rounded-full"
+          >
+            ✓ Apply Crop
+          </button>
+        )
+      }
+    }
+  }
+};
+```
+
+### Loading States
+
+Both crop and confirmation buttons show loading spinners during processing:
+
+```tsx
+const loadingSettings = {
+  customStyles: {
+    cropButton: 'transition-opacity duration-200',
+    tickButton: 'transition-opacity duration-200 disabled:opacity-50'
+  }
+};
+```
+
+## Load More & Pagination Modes
+
+The plugin supports three pagination modes for different user experiences:
+
+### Pagination Types
+
+1. **Traditional Pagination** (default): Classic page numbers with previous/next buttons
+2. **Load More Button**: Shows "Load More" button to append additional results
+3. **Infinite Scroll**: Automatically loads more content as user scrolls
+
+### Load More Configuration
+
+```tsx
+const loadMoreSettings = {
+  paginationType: 'load-more', // Enable load more mode
+  loadMoreText: 'Show More Products', // Custom button text
+  loadMoreStyle: 'button', // 'button' or 'auto' (for infinite scroll)
+  loadMoreThreshold: 100, // Pixels from bottom for auto-trigger
+  maxPagesLoadMore: 5, // Limit max pages in load-more mode
+
+  customStyles: {
+    loadMoreButton:
+      'px-8 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors',
+    loadMoreContainer: 'flex justify-center items-center mt-8'
+  }
+};
+```
+
+### Custom Load More Renderers
+
+Full control over load more functionality:
+
+```tsx
+const customLoadMoreSettings = {
+  paginationType: 'load-more',
+
+  customRenderers: {
+    render: {
+      resultsGrid: {
+        renderLoadMore: ({
+          onLoadMore,
+          hasMore,
+          isLoading,
+          currentPage,
+          totalPages
+        }) => (
+          <div className="flex flex-col items-center space-y-4 mt-12">
+            {/* Progress indicator */}
+            <div className="text-center">
+              <div className="text-sm text-gray-600 mb-2">
+                Page {currentPage} of {totalPages}
+              </div>
+              <div className="w-64 bg-gray-200 rounded-full h-2">
+                <div
+                  className="bg-blue-600 h-2 rounded-full transition-all duration-300"
+                  style={{
+                    width: `${(currentPage / totalPages) * 100}%`
+                  }}
+                ></div>
+              </div>
+            </div>
+
+            {/* Load more button */}
+            {hasMore && (
+              <button
+                onClick={onLoadMore}
+                disabled={isLoading}
+                className="flex items-center space-x-2 px-8 py-3 bg-gradient-to-r from-blue-600 to-purple-600 text-white rounded-lg hover:from-blue-700 hover:to-purple-700 disabled:opacity-50 transition-all"
+              >
+                {isLoading ? (
+                  <>
+                    <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-white"></div>
+                    <span>Loading...</span>
+                  </>
+                ) : (
+                  <>
+                    <span>Load More Products</span>
+                    <svg
+                      className="w-4 h-4"
+                      fill="none"
+                      stroke="currentColor"
+                      viewBox="0 0 24 24"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        strokeWidth={2}
+                        d="M19 9l-7 7-7-7"
+                      />
+                    </svg>
+                  </>
+                )}
+              </button>
+            )}
+
+            {/* Completion message */}
+            {!hasMore && (
+              <div className="text-center text-gray-500">
+                <p>All products loaded</p>
+              </div>
+            )}
+          </div>
+        ),
+
+        renderLoadMoreButton: ({ onClick, disabled, isLoading, text }) => (
+          <button
+            onClick={onClick}
+            disabled={disabled}
+            className="px-6 py-3 bg-black text-white rounded-md hover:bg-gray-800 disabled:opacity-50 transition-colors"
+          >
+            {isLoading ? (
+              <div className="flex items-center space-x-2">
+                <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-white"></div>
+                <span>Loading...</span>
+              </div>
+            ) : (
+              text
+            )}
+          </button>
+        )
+      }
+    }
+  }
+};
+```
+
+### Infinite Scroll Example
+
+Automatic loading with intersection observer:
+
+```tsx
+const infiniteScrollSettings = {
+  paginationType: 'infinite-scroll',
+  loadMoreThreshold: 200, // Start loading 200px before bottom
+  maxPagesLoadMore: 10, // Prevent endless loading
+
+  customStyles: {
+    loadMoreContainer: 'flex justify-center py-8',
+    loadingSpinner: 'h-8 w-8 text-blue-600'
+  }
+};
+```
+
+## Customization Strategies
+
+### 1. Quick Styling with CSS Classes
+
+For rapid customization, apply CSS classes to specific elements:
+
+```tsx
+const settings = {
+  customStyles: {
+    modal: 'max-w-6xl rounded-2xl shadow-2xl border-4 border-blue-500',
+    productItem: 'hover:scale-105 transition-all duration-300 shadow-lg',
+    filterSidebar: 'bg-gradient-to-b from-gray-50 to-white',
+    paginationButton: 'rounded-full px-4 py-2 bg-blue-600 text-white',
+    activeFilterTag: 'bg-blue-100 text-blue-800 px-3 py-1 rounded-full'
+  }
+};
+```
+
+### 2. Advanced Customization with Render Functions
+
+For complete control over specific interface elements:
+
+```tsx
+const settings = {
+  customRenderers: {
+    render: {
+      modal: {
+        renderHeader: ({ title, onClose }) => (
+          <div className="bg-gradient-to-r from-blue-600 to-purple-600 text-white p-6">
+            <div className="flex justify-between items-center">
+              <h2 className="text-2xl font-bold">🔍 Visual Search</h2>
+              <button
+                onClick={onClose}
+                className="text-white hover:text-blue-200"
+              >
+                ✕
+              </button>
+            </div>
+          </div>
+        )
+      },
+      resultsGrid: {
+        renderProductItem: ({ product, index }) => (
+          <div className="bg-white rounded-xl shadow-lg hover:shadow-xl transition-shadow">
+            <div className="aspect-square overflow-hidden rounded-t-xl">
+              <img
+                src={product.productimage_set?.[0]?.image}
+                alt={product.name}
+                className="w-full h-full object-cover hover:scale-110 transition-transform"
+              />
+            </div>
+            <div className="p-4">
+              <h3 className="font-semibold text-gray-900 mb-2">
+                {product.name}
+              </h3>
+              <p className="text-xl font-bold text-green-600">
+                {product.price} ₺
+              </p>
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+## Professional Examples
+
+### E-commerce Store Integration
+
+Complete production-ready implementation:
+
+```tsx
+const storeSettings = {
+  // Performance & functionality
+  maxFileSize: 5,
+  resultsPerPage: 24,
+  enableCropping: true,
+
+  // Professional styling
+  customStyles: {
+    modal: 'max-w-7xl rounded-xl shadow-2xl',
+    productItem: 'rounded-lg shadow-sm hover:shadow-lg transition-shadow',
+    paginationButton: 'px-4 py-2 rounded-lg border hover:bg-gray-50',
+    activeFilterTag: 'bg-blue-100 text-blue-800 px-3 py-1 rounded-full'
+  },
+
+  // Custom branding
+  customRenderers: {
+    render: {
+      modal: {
+        renderHeader: ({ title, onClose }) => (
+          <div className="bg-blue-600 text-white p-6 rounded-t-xl">
+            <div className="flex justify-between items-center">
+              <h2 className="text-2xl font-bold">Find Similar Products</h2>
+              <button
+                onClick={onClose}
+                className="text-white hover:text-blue-200"
+              >
+                ✕
+              </button>
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    showResetButton: true,
+    settings: storeSettings
+  }}
+/>;
+```
+
+### Brand Customization
+
+Customize colors, spacing and styling to match your brand:
+
+```tsx
+const brandSettings = {
+  theme: {
+    colors: {
+      primary: '#FF6B35', // Your brand color
+      secondary: '#004E64',
+      background: '#F8F9FA'
+    }
+  },
+
+  customStyles: {
+    modal: 'border-4 border-orange-500 rounded-2xl',
+    productItem: 'hover:scale-105 transition-transform',
+    activeFilterTag: 'bg-orange-100 text-orange-800 px-3 py-1 rounded-full'
+  }
+};
+```
+
+### Custom Product Cards with Badges
+
+Create custom product displays with badges, animations and enhanced styling:
+
+```tsx
+const customProductSettings = {
+  // Granular styling for product elements
+  customStyles: {
+    productItem:
+      'group relative bg-white rounded-xl shadow-sm hover:shadow-xl transition-all overflow-hidden',
+    productImageWrapper: 'relative aspect-square overflow-hidden',
+    productImage:
+      'w-full h-full object-cover group-hover:scale-105 transition-transform duration-300',
+    productInfo: 'p-4',
+    productTitle: 'font-semibold text-gray-900 mb-2 line-clamp-2',
+    productPrice: 'text-lg font-bold text-green-600',
+    productOldPrice: 'text-sm text-gray-500 line-through ml-2'
+  },
+
+  // Custom render function for complete control
+  customRenderers: {
+    render: {
+      resultsGrid: {
+        renderProductItem: ({ product, index }) => (
+          <div className="group relative bg-white rounded-xl shadow-sm hover:shadow-xl transition-all duration-300 overflow-hidden">
+            {/* Custom badges */}
+            {index < 3 && (
+              <div className="absolute top-2 left-2 z-10 bg-red-500 text-white text-xs px-2 py-1 rounded-full font-bold">
+                TOP {index + 1}
+              </div>
+            )}
+            {product.discount && (
+              <div className="absolute top-2 right-2 z-10 bg-orange-500 text-white text-xs px-2 py-1 rounded-full">
+                -{product.discount}%
+              </div>
+            )}
+
+            {/* Image with hover effect */}
+            <div className="aspect-square overflow-hidden">
+              <img
+                src={product.productimage_set?.[0]?.image}
+                alt={product.name}
+                className="w-full h-full object-cover group-hover:scale-110 transition-transform duration-300"
+              />
+            </div>
+
+            {/* Enhanced product info */}
+            <div className="p-4">
+              <h3 className="font-semibold text-gray-900 mb-2">
+                {product.name}
+              </h3>
+              <div className="flex items-center justify-between">
+                <div className="flex items-center gap-2">
+                  <span className="text-xl font-bold text-green-600">
+                    {product.price} ₺
+                  </span>
+                  {product.old_price && (
+                    <span className="text-sm text-gray-500 line-through">
+                      {product.old_price} ₺
+                    </span>
+                  )}
+                </div>
+                <button className="bg-blue-600 text-white px-3 py-1 rounded-full text-sm hover:bg-blue-700 transition-colors">
+                  Add to Cart
+                </button>
+              </div>
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+### Advanced Filter Sidebar with Dynamic Icons
+
+Customize filters with dynamic icons, enhanced mobile header, and professional styling:
+
+```tsx
+const advancedFilterSettings = {
+  customStyles: {
+    filterSidebarMobileHeader:
+      'bg-gradient-to-r from-purple-600 to-blue-600 text-white p-6 -m-6 mb-6',
+    filterGroup: 'mb-6 border-b border-gray-200 pb-4',
+    filterGroupTitle:
+      'text-lg font-semibold text-gray-900 mb-3 flex items-center',
+    filterItem:
+      'flex items-center justify-between py-2 hover:bg-gray-50 px-2 rounded transition-colors',
+    filterItemLabel: 'text-sm text-gray-700 flex-1',
+    filterItemCount: 'text-xs bg-gray-100 px-2 py-1 rounded-full ml-2',
+    imageSection: 'border-2 border-dashed border-purple-300 rounded-lg p-4',
+    cropButton: 'bg-purple-600 text-white shadow-lg hover:bg-purple-700',
+    uploadButton:
+      'bg-gradient-to-r from-blue-500 to-purple-600 text-white border-0 hover:from-blue-600 hover:to-purple-700',
+    resetButton:
+      'bg-gradient-to-r from-green-500 to-blue-500 text-white border-0'
+  },
+
+  customRenderers: {
+    render: {
+      filterSidebar: {
+        // Enhanced mobile header with icon and item count
+        renderMobileHeader: ({ title, itemCount, onClose }) => (
+          <div className="bg-gradient-to-r from-purple-600 to-blue-600 text-white p-6 -m-6 mb-6 rounded-lg">
+            <div className="flex justify-between items-center">
+              <div>
+                <h3 className="text-xl font-bold flex items-center">
+                  <svg
+                    className="w-6 h-6 mr-2"
+                    fill="currentColor"
+                    viewBox="0 0 20 20"
+                  >
+                    <path d="M3 4a1 1 0 011-1h12a1 1 0 011 1v2a1 1 0 01-.293.707L12 11.414V15a1 1 0 01-.293.707l-2 2A1 1 0 018 17v-5.586L3.293 6.707A1 1 0 013 6V4z" />
+                  </svg>
+                  {title}
+                </h3>
+                <p className="text-purple-100 text-sm">
+                  {itemCount} products found
+                </p>
+              </div>
+              <button
+                onClick={onClose}
+                className="text-white hover:text-purple-200"
+              >
+                <svg
+                  className="w-6 h-6"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M6 18L18 6M6 6l12 12"
+                  />
+                </svg>
+              </button>
+            </div>
+          </div>
+        ),
+
+        // Dynamic icons based on filter type
+        renderFilterGroup: ({ facet, onFacetChange, isLoading }) => (
+          <div className="mb-6 bg-white rounded-lg border border-gray-200 p-4">
+            <h4 className="font-bold text-gray-900 mb-3 flex items-center">
+              {/* Dynamic icons based on facet type */}
+              {facet.key === 'color' && (
+                <div className="w-4 h-4 bg-gradient-to-r from-red-500 to-blue-500 rounded-full mr-2"></div>
+              )}
+              {facet.key === 'size' && (
+                <svg
+                  className="w-4 h-4 mr-2"
+                  fill="currentColor"
+                  viewBox="0 0 20 20"
+                >
+                  <path d="M4 3a2 2 0 000 4h12a2 2 0 000-4H4zM4 9a2 2 0 000 4h12a2 2 0 000-4H4zM4 15a2 2 0 000 4h12a2 2 0 000-4H4z" />
+                </svg>
+              )}
+              {facet.key === 'brand' && (
+                <svg
+                  className="w-4 h-4 mr-2"
+                  fill="currentColor"
+                  viewBox="0 0 20 20"
+                >
+                  <path d="M9.049 2.927c.3-.921 1.603-.921 1.902 0l1.07 3.292a1 1 0 00.95.69h3.462c.969 0 1.371 1.24.588 1.81l-2.8 2.034a1 1 0 00-.364 1.118l1.07 3.292c.3.921-.755 1.688-1.54 1.118l-2.8-2.034a1 1 0 00-1.175 0l-2.8 2.034c-.784.57-1.838-.197-1.539-1.118l1.07-3.292a1 1 0 00-.364-1.118L2.98 8.72c-.783-.57-.38-1.81.588-1.81h3.461a1 1 0 00.951-.69l1.07-3.292z" />
+                </svg>
+              )}
+              {facet.name}
+            </h4>
+            <div className="space-y-2">
+              {facet.data.choices?.slice(0, 8).map((choice) => (
+                <label
+                  key={choice.value}
+                  className="flex items-center justify-between cursor-pointer p-2 hover:bg-gray-50 rounded transition-colors"
+                >
+                  <div className="flex items-center flex-1">
+                    <input
+                      type="checkbox"
+                      checked={choice.is_selected}
+                      onChange={() => onFacetChange(facet.key, choice.value)}
+                      disabled={isLoading}
+                      className="mr-3 rounded border-gray-300 text-purple-600 focus:ring-purple-500"
+                    />
+                    <span className="text-sm font-medium">{choice.label}</span>
+                  </div>
+                  <span className="text-xs bg-purple-100 text-purple-800 px-2 py-1 rounded-full font-medium">
+                    {choice.quantity}
+                  </span>
+                </label>
+              ))}
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+### Header Integration
+
+Add visual search to your site header:
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+export function SiteHeader() {
+  return (
+    <header className="flex items-center justify-between p-4">
+      <div className="logo">Your Store</div>
+
+      <div className="search-area flex items-center gap-4">
+        {/* Regular search */}
+        <input
+          type="text"
+          placeholder="Search products..."
+          className="border rounded-lg px-4 py-2"
+        />
+
+        {/* Visual search */}
+        <PluginModule
+          component={Component.HeaderImageSearchFeature}
+          props={{
+            isEnabled: true,
+            settings: {
+              maxFileSize: 5,
+              customStyles: {
+                imageSearchModal: 'max-w-lg rounded-xl'
+              }
+            }
+          }}
+        />
+      </div>
+    </header>
+  );
+}
+```
+
+### Modern Pagination with Progress
+
+Create advanced pagination with progress bars and smart page navigation:
+
+```tsx
+const modernPaginationSettings = {
+  customStyles: {
+    paginationContainer: 'flex flex-col items-center space-y-4 mt-8',
+    paginationInfo: 'text-sm text-gray-600 font-medium',
+    paginationButton:
+      'px-3 py-2 text-sm border border-gray-300 rounded-md hover:bg-gray-50 transition-colors',
+    paginationButtonActive:
+      'bg-blue-600 text-white border-blue-600 hover:bg-blue-700',
+    paginationPrevious:
+      'px-4 py-2 bg-gray-100 rounded-lg hover:bg-gray-200 transition-colors',
+    paginationNext:
+      'px-4 py-2 bg-gray-100 rounded-lg hover:bg-gray-200 transition-colors'
+  },
+
+  customRenderers: {
+    render: {
+      resultsGrid: {
+        renderPagination: ({ pagination, onPageChange, isLoading }) => (
+          <div className="flex flex-col items-center space-y-6 mt-12">
+            {/* Progress bar */}
+            <div className="text-center">
+              <div className="text-sm text-gray-600 mb-2">
+                Page {pagination.current_page} of {pagination.num_pages}
+              </div>
+              <div className="w-full bg-gray-200 rounded-full h-2 max-w-xs">
+                <div
+                  className="bg-blue-600 h-2 rounded-full transition-all duration-300"
+                  style={{
+                    width: `${
+                      (pagination.current_page / pagination.num_pages) * 100
+                    }%`
+                  }}
+                ></div>
+              </div>
+            </div>
+
+            {/* Smart pagination buttons */}
+            <div className="flex items-center space-x-2">
+              <button
+                onClick={() => onPageChange(pagination.current_page - 1)}
+                disabled={pagination.current_page === 1 || isLoading}
+                className="flex items-center px-4 py-2 bg-gray-100 rounded-lg hover:bg-gray-200 disabled:opacity-50 transition-colors"
+              >
+                <svg
+                  className="w-4 h-4 mr-2"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M15 19l-7-7 7-7"
+                  />
+                </svg>
+                Previous
+              </button>
+
+              {Array.from(
+                { length: Math.min(5, pagination.num_pages) },
+                (_, i) => {
+                  const page = i + Math.max(1, pagination.current_page - 2);
+                  const isActive = page === pagination.current_page;
+
+                  return (
+                    <button
+                      key={page}
+                      onClick={() => onPageChange(page)}
+                      disabled={isLoading}
+                      className={`px-4 py-2 rounded-lg transition-colors ${
+                        isActive
+                          ? 'bg-blue-600 text-white'
+                          : 'bg-gray-100 hover:bg-gray-200 text-gray-700'
+                      }`}
+                    >
+                      {page}
+                    </button>
+                  );
+                }
+              )}
+
+              <button
+                onClick={() => onPageChange(pagination.current_page + 1)}
+                disabled={
+                  pagination.current_page === pagination.num_pages || isLoading
+                }
+                className="flex items-center px-4 py-2 bg-gray-100 rounded-lg hover:bg-gray-200 disabled:opacity-50 transition-colors"
+              >
+                Next
+                <svg
+                  className="w-4 h-4 ml-2"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    strokeWidth={2}
+                    d="M9 5l7 7-7 7"
+                  />
+                </svg>
+              </button>
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+### Advanced Modal with Custom Header & Controls
+
+Create a fully branded modal experience:
+
+```tsx
+const advancedModalSettings = {
+  customStyles: {
+    modal: 'max-w-7xl rounded-2xl shadow-2xl border-4 border-blue-500',
+    activeFiltersContainer:
+      'bg-gradient-to-r from-blue-50 to-purple-50 border-l-4 border-blue-500 p-4',
+    activeFilterTag:
+      'bg-white border border-blue-200 text-blue-800 px-3 py-1 rounded-full shadow-sm',
+    controlsContainer: 'bg-gray-50 border-y border-gray-200',
+    itemCount:
+      'text-sm font-medium text-green-600 bg-green-100 px-3 py-1 rounded-full',
+    sortDropdown:
+      'bg-white border-2 border-gray-300 rounded-lg px-4 py-2 focus:border-blue-500 focus:ring-2 focus:ring-blue-200'
+  },
+
+  customRenderers: {
+    render: {
+      modal: {
+        renderHeader: ({ title, onClose }) => (
+          <div className="bg-gradient-to-r from-blue-600 via-purple-600 to-blue-800 text-white p-6">
+            <div className="flex justify-between items-center">
+              <div className="flex items-center">
+                <div className="w-10 h-10 bg-white bg-opacity-20 rounded-full flex items-center justify-center mr-4">
+                  <span className="text-2xl">🔍</span>
+                </div>
+                <div>
+                  <h2 className="text-2xl font-bold mb-1">
+                    🎯 AI Visual Search
+                  </h2>
+                  <p className="text-blue-100">
+                    Discover your perfect match with advanced AI
+                  </p>
+                </div>
+              </div>
+              <button
+                onClick={onClose}
+                className="text-white hover:text-blue-200 bg-white bg-opacity-20 rounded-full p-2 transition-colors"
+              >
+                ✕
+              </button>
+            </div>
+          </div>
+        ),
+        renderItemCount: ({ count, isLoading }) => (
+          <div className="flex items-center bg-green-100 text-green-800 px-3 py-2 rounded-lg">
+            <div
+              className={`w-2 h-2 rounded-full mr-2 ${
+                isLoading ? 'bg-yellow-500 animate-pulse' : 'bg-green-500'
+              }`}
+            ></div>
+            <span className="text-sm font-medium">
+              {count} {count === 1 ? 'product' : 'products'} found
+            </span>
+          </div>
+        ),
+        renderActiveFilterTag: ({ filter, onRemove, isLoading }) => (
+          <div className="inline-flex items-center bg-gradient-to-r from-blue-100 to-purple-100 border border-blue-300 text-blue-800 px-3 py-2 rounded-full text-sm font-medium shadow-sm mr-2 mb-2">
+            <span className="mr-2">{filter.label}</span>
+            <button
+              onClick={onRemove}
+              disabled={isLoading}
+              className="text-blue-600 hover:text-blue-800 hover:bg-blue-200 rounded-full p-1 transition-colors disabled:opacity-50"
+            >
+              ✕
+            </button>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+### Complete Brand Theme Integration
+
+Full brand customization with theme variables, CSS styling, and custom components:
+
+```tsx
+const brandThemeSettings = {
+  // CSS Variables and Theme
+  theme: {
+    colors: {
+      primary: '#FF6B35', // Brand orange
+      secondary: '#004E64', // Brand navy
+      accent: '#FFB700', // Brand yellow
+      background: '#F8F9FA',
+      text: '#212529'
+    },
+    spacing: {
+      xs: '0.25rem',
+      sm: '0.5rem',
+      md: '1rem',
+      lg: '1.5rem',
+      xl: '2rem'
+    },
+    borderRadius: {
+      sm: '0.25rem',
+      md: '0.5rem',
+      lg: '1rem'
+    }
+  },
+
+  // Comprehensive brand styling
+  customStyles: {
+    modal: 'max-w-7xl rounded-2xl shadow-2xl border-4 border-orange-500',
+    activeFiltersContainer: 'bg-orange-50 border-l-4 border-orange-500',
+    activeFilterTag: 'bg-orange-100 text-orange-800 border border-orange-300',
+    controlsContainer: 'bg-navy-900 text-white',
+    itemCount: 'bg-yellow-100 text-yellow-800 font-bold',
+    sortDropdown:
+      'border-orange-300 focus:border-orange-500 focus:ring-orange-200',
+    filterGroup: 'bg-white border-l-4 border-orange-500 shadow-lg',
+    filterGroupTitle: 'text-navy-900 font-bold text-lg',
+    productItem:
+      'border-2 border-orange-200 hover:border-orange-500 hover:shadow-lg',
+    productPrice: 'text-2xl font-bold text-orange-600',
+    pagination: 'space-x-2',
+    paginationButton: 'border-orange-300 text-orange-600 hover:bg-orange-50',
+    paginationButtonActive: 'bg-orange-600 text-white border-orange-600'
+  },
+
+  // Brand-specific custom components
+  customRenderers: {
+    render: {
+      modal: {
+        renderHeader: ({ title, onClose }) => (
+          <div className="bg-gradient-to-r from-orange-500 to-red-600 text-white p-6">
+            <div className="flex justify-between items-center">
+              <div className="flex items-center">
+                <div className="w-12 h-12 bg-white bg-opacity-20 rounded-full flex items-center justify-center mr-4">
+                  <span className="text-2xl">🔥</span>
+                </div>
+                <div>
+                  <h2 className="text-3xl font-bold mb-1">Visual Search</h2>
+                  <p className="text-orange-100">Powered by AI • Brand Store</p>
+                </div>
+              </div>
+              <button
+                onClick={onClose}
+                className="text-white hover:text-orange-200 bg-white bg-opacity-20 rounded-full p-3 transition-colors"
+              >
+                ✕
+              </button>
+            </div>
+          </div>
+        )
+      },
+      resultsGrid: {
+        renderProductItem: ({ product, index }) => (
+          <div className="bg-white rounded-xl border-2 border-orange-200 hover:border-orange-500 hover:shadow-xl transition-all duration-300 overflow-hidden">
+            {/* Brand-specific badges */}
+            {product.is_featured && (
+              <div className="absolute top-3 left-3 z-10 bg-gradient-to-r from-orange-500 to-red-500 text-white text-xs px-3 py-1 rounded-full font-bold shadow-lg">
+                🔥 FEATURED
+              </div>
+            )}
+
+            <div className="aspect-square overflow-hidden bg-gray-100">
+              <img
+                src={product.productimage_set?.[0]?.image}
+                alt={product.name}
+                className="w-full h-full object-cover hover:scale-105 transition-transform duration-300"
+              />
+            </div>
+
+            <div className="p-4 border-t-2 border-orange-100">
+              <h3 className="font-bold text-navy-900 mb-2 line-clamp-2">
+                {product.name}
+              </h3>
+              <div className="flex items-center justify-between">
+                <div>
+                  <span className="text-2xl font-bold text-orange-600">
+                    {product.price} ₺
+                  </span>
+                  {product.old_price && (
+                    <span className="text-sm text-gray-500 line-through ml-2">
+                      {product.old_price} ₺
+                    </span>
+                  )}
+                </div>
+                <button className="bg-gradient-to-r from-orange-500 to-red-500 text-white px-4 py-2 rounded-lg font-bold hover:from-orange-600 hover:to-red-600 transition-all shadow-lg">
+                  ADD TO CART
+                </button>
+              </div>
+            </div>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+## Usage Examples
+
+Here's how to use these customization settings in your components:
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+// Example 1: E-commerce store with custom product cards
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    showResetButton: true,
+    settings: customProductSettings
+  }}
+/>
+
+// Example 2: Advanced filtering with dynamic icons
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    settings: advancedFilterSettings
+  }}
+/>
+
+// Example 3: Modern pagination experience
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    settings: modernPaginationSettings
+  }}
+/>
+
+// Example 4: Advanced modal with custom controls
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    settings: advancedModalSettings
+  }}
+/>
+
+// Example 5: Complete brand integration
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    settings: brandThemeSettings
+  }}
+/>
+
+// Mix and match approaches
+const hybridSettings = {
+  // Use brand colors
+  theme: brandThemeSettings.theme,
+
+  // Use modern pagination
+  customRenderers: {
+    render: {
+      resultsGrid: {
+        renderPagination: modernPaginationSettings.customRenderers.render.resultsGrid.renderPagination
+      },
+      modal: {
+        renderHeader: brandThemeSettings.customRenderers.render.modal.renderHeader
+      }
+    }
+  },
+
+  // Use custom product cards styling
+  customStyles: {
+    ...customProductSettings.customStyles,
+    modal: brandThemeSettings.customStyles.modal
+  }
+};
+```
+
+## Complete Styling Reference
+
+### Available Style Targets (40+ options)
+
+**Modal & Layout:**
+
+- `modal`, `activeFiltersContainer`, `controlsContainer`, `imageSearchModal`
+
+**Filter Sidebar:**
+
+- `filterSidebar`, `filterSidebarMobileHeader`, `filterGroup`, `filterGroupTitle`, `filterGroupContent`
+- `filterItem`, `filterItemInput`, `filterItemLabel`, `filterItemCount`
+- `imageSection`, `imageContainer`, `imageWrapper`, `cropButton`, `tickButton`, `uploadButton`, `resetButton`, `errorMessage`, `cropControls`
+- `mobileActiveFilters`, `mobileActiveFilterTag`, `mobileClearAllButton`
+
+**Products & Results:**
+
+- `resultsGrid`, `resultsContainer`, `gridContainer`
+- `productItem`, `productImageWrapper`, `productImage`, `productInfo`, `productTitle`, `productPrice`, `productOldPrice`
+
+**Pagination:**
+
+- `pagination`, `paginationContainer`, `paginationInfo`, `paginationButton`, `paginationButtonActive`, `paginationButtonDisabled`, `paginationPrevious`, `paginationNext`, `loadMoreButton`, `loadMoreContainer`
+
+**Controls & Active Filters:**
+
+- `itemCount`, `sortDropdown`, `filterToggleButton`, `activeFilterTag`, `activeFilterTagButton`
+
+**Loading & States:**
+
+- `loadingSpinner`, `loadingOverlay`, `emptyState`, `emptyStateIcon`, `emptyStateText`
+
+### Available Render Functions (25+ options)
+
+**Modal Renderers:**
+
+- `renderModal`, `renderHeader`, `renderCloseButton`, `renderActiveFilters`, `renderActiveFilterTag`
+- `renderControls`, `renderSortDropdown`, `renderItemCount`, `renderFilterToggleButton`, `renderEmptyState`
+
+**Filter Sidebar Renderers:**
+
+- `renderSidebar`, `renderMobileHeader`, `renderImageSection`, `renderImageContainer`
+- `renderCropButton`, `renderTickButton`, `renderUploadButton`, `renderResetButton`, `renderErrorMessage`
+- `renderFilterGroup`, `renderFilterGroupTitle`, `renderFilterItem`, `renderFilterItemInput`, `renderFilterItemLabel`, `renderFilterItemCount`
+- `renderMobileActiveFilters`
+
+**Results Grid Renderers:**
+
+- `renderGrid`, `renderGridContainer`, `renderProductItem`, `renderProductImage`, `renderProductInfo`, `renderProductTitle`, `renderProductPrice`
+- `renderPagination`, `renderPaginationButton`, `renderPaginationInfo`, `renderPaginationPrevious`, `renderPaginationNext`, `renderLoadMore`, `renderLoadMoreButton`
+- `renderLoadingState`, `renderLoadingOverlay`, `renderEmptyState`
+
+## Best Practices
+
+### Performance Optimization
+
+```tsx
+const optimizedSettings = {
+  maxFileSize: 5, // Reasonable limit
+  resultsPerPage: 20, // Optimal for performance
+  enableCropping: true, // Better search accuracy
+
+  customStyles: {
+    loadingSpinner: 'text-blue-600', // Brand consistency
+    productItem: 'hover:shadow-lg transition-shadow' // Smooth interactions
+  }
+};
+```
+
+### Accessibility
+
+```tsx
+const accessibleSettings = {
+  customRenderers: {
+    render: {
+      modal: {
+        renderHeader: ({ title, onClose }) => (
+          <div className="bg-blue-600 text-white p-6">
+            <h2 className="text-xl font-bold" id="modal-title">
+              {title}
+            </h2>
+            <button
+              onClick={onClose}
+              aria-label="Close modal"
+              className="text-white hover:text-blue-200"
+            >
+              ✕
+            </button>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
+### Essential Props
+
+```tsx
+// Basic integration
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product, // Required: Product object
+    activeIndex, // Current image index
+    showResetButton: true, // Show reset functionality
+    settings: {
+      /* Your customization */
+    }
+  }}
+/>
+```
+
+### Common Settings
+
+```tsx
+const commonSettings = {
+  maxFileSize: 5, // 5MB file limit
+  resultsPerPage: 20, // 20 products per page
+  enableCropping: true, // Enable image cropping
+  enableFileUpload: true, // Enable file uploads
+
+  customStyles: {
+    modal: 'max-w-6xl rounded-xl shadow-2xl',
+    productItem: 'rounded-lg shadow-sm hover:shadow-lg'
+  }
+};
+```
+
+## Summary
+
+### 🚀 **Getting Started in 3 Steps:**
+
+1. **Install**: `npx @akinon/projectzero@latest --plugins`
+2. **Integrate**: Add `<PluginModule component={Component.ProductImageSearchFeature} />`
+3. **Customize**: Use any of the examples above or create your own
+
+### 🎨 **Customization Approaches:**
+
+- **Quick Styling**: Use `customStyles` for rapid CSS class customization
+- **Advanced Control**: Use `customRenderers` for complete component replacement
+- **Hybrid Approach**: Mix and match both methods for maximum flexibility
+
+**Made by the ProjectZero team**