@akinon/pz-similar-products 1.92.0-rc.31 → 1.92.0-rc.33

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @akinon/pz-similar-products
 
+## 1.92.0-rc.33
+
+### Minor Changes
+
+- 59b275c: ZERO-3532: Pass settings prop to SimilarProductsButton for enhanced functionality
+
+## 1.92.0-rc.32
+
+### Minor Changes
+
+- 54e3179: ZERO-3532: Added customize options to icons
+
 ## 1.92.0-rc.31
 
 ## 1.92.0-rc.30

package/README.md

@@ -10,6 +10,7 @@
 
 - [Features](#markdown-header-features)
 - [Installation](#markdown-header-installation)
+- [Icon Customization](#markdown-header-icon-customization)
 - [Quick Start](#markdown-header-quick-start)
 - [Available Components](#markdown-header-available-components)
 - [Configuration](#markdown-header-configuration)
@@ -64,6 +65,7 @@
 
 - **🖼️ Visual Search**: AI-powered image-based product discovery
 - **✂️ Image Cropping**: Built-in cropping functionality with manual confirmation for precise searches
+- **🔤 Text Search**: Search similar products by text description with customizable input
 - **🎛️ Advanced Filtering**: Dynamic facet-based filtering system
 - **📄 Multiple Pagination Modes**: Traditional pagination, load more button, and infinite scroll
 - **🎨 Granular Customization**: 50+ style targets and 30+ render points
@@ -79,6 +81,92 @@ npx @akinon/projectzero@latest --plugins
 
 Select `pz-similar-products` from the plugin list during installation.
 
+## Icon Customization
+
+The plugin provides complete control over icon appearance and behavior through two complementary approaches:
+
+### Icon Names (`iconNames`)
+
+Change which icons are displayed by specifying different icon names:
+
+```tsx
+const iconCustomization = {
+  iconNames: {
+    searchButton: 'magnifier',     // Search button (default: 'search')
+    modalClose: 'x',               // Modal close buttons (default: 'close') 
+    filter: 'funnel',              // Filter button (default: 'filter')
+    filterRemove: 'trash',         // Filter tag remove buttons (default: 'close')
+    modalSearch: 'search-outline', // Modal search button (default: 'search')
+    modalSearchClear: 'clear',     // Search input clear button (default: 'close')
+    imageSearchButton: 'upload'    // Image search button (default: 'search')
+  }
+};
+```
+
+### Icon Styles (`customStyles`)
+
+Customize the visual appearance of icons with CSS classes:
+
+```tsx
+const iconStyling = {
+  customStyles: {
+    searchButtonIcon: 'fill-blue-500 hover:fill-blue-600 transition-colors',
+    modalCloseIcon: 'text-red-500 hover:text-red-700 w-4 h-4',
+    filterIcon: 'text-purple-500 w-5 h-5',
+    filterRemoveIcon: 'text-orange-500 hover:text-orange-700 w-3 h-3',
+    imageSearchButtonIcon: 'text-blue-500 hover:text-blue-600 w-5 h-5'
+  }
+};
+```
+
+### Complete Icon Customization Example
+
+```tsx
+const completeIconSettings = {
+  // Change icon names
+  iconNames: {
+    searchButton: 'search-alt',
+    modalClose: 'times',
+    filter: 'filter-alt',
+    filterRemove: 'remove',
+    modalSearch: 'magnifying-glass',
+    modalSearchClear: 'clear-alt',
+    imageSearchButton: 'upload-cloud'
+  },
+  
+  // Style the icons
+  customStyles: {
+    searchButtonIcon: 'fill-indigo-500 hover:fill-indigo-600 transition-all duration-200',
+    modalCloseIcon: 'text-gray-500 hover:text-gray-700 w-5 h-5',
+    filterIcon: 'text-blue-500 hover:text-blue-600 w-4 h-4',
+    filterRemoveIcon: 'text-red-400 hover:text-red-600 w-3 h-3 transition-colors',
+    modalSearchIcon: 'text-green-500 hover:text-green-600',
+    modalSearchClearIcon: 'text-gray-400 hover:text-gray-600',
+    imageSearchButtonIcon: 'text-indigo-500 hover:text-indigo-600 w-5 h-5'
+  }
+};
+
+// Usage
+<PluginModule
+  component={Component.ProductImageSearchFeature}
+  props={{
+    product,
+    activeIndex,
+    settings: completeIconSettings
+  }}
+/>
+```
+
+### Available Icon Customization Points
+
+- **Search Button** (`searchButton`): Main search button icon in product images
+- **Modal Close** (`modalClose`): Close buttons in modals and filter tags
+- **Filter** (`filter`): Filter toggle button icon
+- **Filter Remove** (`filterRemove`): Remove icons in active filter tags
+- **Modal Search** (`modalSearch`): Search button icon in text search input
+- **Modal Search Clear** (`modalSearchClear`): Clear button icon in text search input
+- **Image Search Button** (`imageSearchButton`): Camera/upload icon in header search feature
+
 ## Quick Start
 
 ### Plugin Module Integration
@@ -167,6 +255,7 @@ interface SimilarProductsSettings {
   resultsPerPage?: number; // Products per page (default: 20)
   enableCropping?: boolean; // Enable image cropping (default: true)
   enableFileUpload?: boolean; // Enable file upload (default: true)
+  enableTextSearch?: boolean; // Enable text search input (default: false)
 
   // Pagination settings
   paginationType?: 'pagination' | 'load-more' | 'infinite-scroll'; // Pagination mode (default: 'pagination')
@@ -199,6 +288,21 @@ interface SimilarProductsSettings {
     itemCount?: string;
     sortDropdown?: string;
     filterToggleButton?: string;
+    
+    // Text search input
+    modalSearchInput?: string;
+    modalSearchContainer?: string;
+    modalSearchButton?: string;
+    modalSearchIcon?: string;
+    modalSearchClearButton?: string;
+    modalSearchClearIcon?: string;
+    
+    // Icon customization
+    searchButtonIcon?: string; // Search button icon styling
+    modalCloseIcon?: string; // Modal close button icons styling
+    filterIcon?: string; // Filter button icon styling
+    filterRemoveIcon?: string; // Filter tag remove icons styling
+    imageSearchButtonIcon?: string; // Image search button icon styling
 
     // Filter sidebar mobile
     filterSidebarMobileHeader?: string;
@@ -286,6 +390,17 @@ interface SimilarProductsSettings {
     cropSelectionHighlight?: string;
   };
 
+  // Icon name customization
+  iconNames?: {
+    searchButton?: string; // Search button icon name (default: 'search')
+    modalClose?: string; // Modal close button icon name (default: 'close')
+    filter?: string; // Filter button icon name (default: 'filter')
+    filterRemove?: string; // Filter tag remove icon name (default: 'close')
+    modalSearch?: string; // Modal search button icon name (default: 'search')
+    modalSearchClear?: string; // Modal search clear button icon name (default: 'close')
+    imageSearchButton?: string; // Image search button icon name (default: 'search')
+  };
+
   // 25+ render functions for granular control
   customRenderers?: {
     // Component-level renderers (full control)
@@ -304,6 +419,8 @@ interface SimilarProductsSettings {
         renderItemCount?: (props) => React.ReactNode;
         renderSortDropdown?: (props) => React.ReactNode;
         renderFilterToggleButton?: (props) => React.ReactNode;
+        renderModalSearchInput?: (props) => React.ReactNode;
+        renderSearchIcon?: (props) => React.ReactNode;
         // ... see examples for complete list
       };
       filterSidebar?: {
@@ -341,6 +458,91 @@ interface SimilarProductsSettings {
 }
 ```
 
+## Text Search Integration
+
+The plugin features a built-in text search functionality that allows users to search for similar products using descriptive text.
+
+### Text Search Features
+
+1. **Search Input**: Appears only when API results are available
+2. **Enter Key Support**: Press Enter to trigger search
+3. **Search Icon**: Clickable icon for mobile users
+4. **Clear Button**: X button to clear text and trigger search without text
+5. **Custom Styling**: Fully customizable input, button, and icon
+6. **Custom Icon**: Replaceable search icon via render functions
+
+### Basic Text Search Configuration
+
+```tsx
+const textSearchSettings = {
+  enableTextSearch: true, // Enable text search input
+  
+  customStyles: {
+    modalSearchContainer: 'relative flex items-center',
+    modalSearchInput: 'h-10 px-4 pr-20 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500',
+    modalSearchButton: 'absolute right-2 top-1/2 -translate-y-1/2 p-2 hover:bg-gray-100 rounded-md',
+    modalSearchIcon: 'text-gray-500',
+    modalSearchClearButton: 'absolute right-12 top-1/2 -translate-y-1/2 p-2 hover:bg-gray-100 rounded-md',
+    modalSearchClearIcon: 'text-gray-400 hover:text-gray-600'
+  }
+};
+```
+
+### Custom Search Icon
+
+```tsx
+const customIconSettings = {
+  enableTextSearch: true,
+  
+  customRenderers: {
+    render: {
+      modal: {
+        renderSearchIcon: ({ disabled, onClick }) => (
+          <svg 
+            className="w-5 h-5 text-blue-500 cursor-pointer hover:text-blue-700" 
+            onClick={onClick}
+            fill="none" 
+            stroke="currentColor" 
+            viewBox="0 0 24 24"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
+          </svg>
+        ),
+        renderModalSearchInput: ({ searchText, setSearchText, isLoading, placeholder, onSearch }) => (
+          <div className="relative">
+            <input
+              type="text"
+              value={searchText}
+              onChange={(e) => setSearchText(e.target.value)}
+              onKeyDown={(e) => e.key === 'Enter' && onSearch && onSearch()}
+              placeholder={placeholder}
+              className="w-full h-10 px-4 pr-20 border-2 border-blue-300 rounded-lg focus:border-blue-500"
+              disabled={isLoading}
+            />
+            {searchText && (
+              <button
+                onClick={() => setSearchText('')}
+                disabled={isLoading}
+                className="absolute right-12 top-1/2 -translate-y-1/2 p-2 text-gray-400 hover:text-gray-600"
+              >
+                ✕
+              </button>
+            )}
+            <button
+              onClick={onSearch}
+              disabled={isLoading}
+              className="absolute right-2 top-1/2 -translate-y-1/2 p-2 text-blue-500 hover:text-blue-700"
+            >
+              🔍
+            </button>
+          </div>
+        )
+      }
+    }
+  }
+};
+```
+
 ## Image Cropping with Manual Confirmation
 
 The plugin features an advanced image cropping system with manual confirmation for precise control over search queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/pz-similar-products",
-  "version": "1.92.0-rc.31",
+  "version": "1.92.0-rc.33",
   "license": "MIT",
   "main": "src/index.ts",
   "peerDependencies": {

package/src/data/endpoints.ts

@@ -27,9 +27,9 @@ export const similarProductsApi = api.injectEndpoints({
   endpoints: (build) => ({
     getSimilarProductsByUrl: build.query<
       SimilarProductsResponse,
-      { url: string; limit?: number; excluded_product_ids?: number[] }
+      { url: string; limit?: number; excluded_product_ids?: number[]; text?: string }
     >({
-      query: ({ url, limit = 20, excluded_product_ids }) => {
+      query: ({ url, limit = 20, excluded_product_ids, text }) => {
         const params = new URLSearchParams();
         params.append('limit', String(limit));
         params.append('url', url);
@@ -38,6 +38,10 @@ export const similarProductsApi = api.injectEndpoints({
           params.append('excluded_product_ids', excluded_product_ids.join(','));
         }
 
+        if (text) {
+          params.append('text', text);
+        }
+
         return {
           url: `/api/similar-products?${params.toString()}`,
           method: 'GET',
@@ -50,12 +54,17 @@ export const similarProductsApi = api.injectEndpoints({
 
     getSimilarProductsByImage: build.mutation<
       SimilarProductsResponse,
-      { image: string; limit?: number; excluded_product_ids?: number[] }
+      { image: string; limit?: number; excluded_product_ids?: number[]; text?: string }
     >({
-      query: ({ image, limit = 20, excluded_product_ids }) => {
+      query: ({ image, limit = 20, excluded_product_ids, text }) => {
         const params = new URLSearchParams();
         params.append('limit', String(limit));
 
+        const bodyData: any = { image, excluded_product_ids };
+        if (text) {
+          bodyData.text = text;
+        }
+
         return {
           url: `/api/similar-products?${params.toString()}`,
           method: 'POST',
@@ -63,7 +72,7 @@ export const similarProductsApi = api.injectEndpoints({
             'Content-Type': 'application/json',
             Accept: 'application/json'
           },
-          body: JSON.stringify({ image, excluded_product_ids })
+          body: JSON.stringify(bodyData)
         };
       }
     }),

package/src/hooks/use-similar-products.ts

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useRef } from 'react';
 import { Product } from '@akinon/next/types';
 import {
   useLazyGetSimilarProductsByUrlQuery,
@@ -13,6 +13,7 @@ import {
   validateImageFromDataUrl,
   type ImageValidationResult
 } from '../utils/image-validation';
+import { debounce } from '../utils';
 
 type SearchResults = SimilarProductsListResponse;
 
@@ -24,6 +25,7 @@ export function useSimilarProducts(product: Product) {
   const { t } = useLocalization();
   const [currentImageUrl, setCurrentImageUrl] = useState('');
   const [fileError, setFileError] = useState('');
+  const [searchText, setSearchText] = useState('');
   const [searchResults, setSearchResults] = useState<SearchResults | null>(
     null
   );
@@ -33,6 +35,16 @@ export function useSimilarProducts(product: Product) {
   const [isCropProcessing, setIsCropProcessing] = useState(false);
   const [loadedPages, setLoadedPages] = useState<Set<number>>(new Set([1]));
   const [allLoadedProducts, setAllLoadedProducts] = useState<Product[]>([]);
+  const [currentImageBase64, setCurrentImageBase64] = useState<string>('');
+  const [hasCroppedImage, setHasCroppedImage] = useState(false);
+
+  const searchTextRef = useRef<string>('');
+  const hasUploadedImageRef = useRef<boolean>(false);
+
+  const setSearchTextWithRef = useCallback((text: string) => {
+    setSearchText(text);
+    searchTextRef.current = text;
+  }, []);
 
   const [fetchSimilarProductsByUrl, { isLoading: isUrlSearchLoading }] =
     useLazyGetSimilarProductsByUrlQuery();
@@ -426,17 +438,24 @@ export function useSimilarProducts(product: Product) {
   );
 
   const fetchSimilarProductsByImageUrl = useCallback(
-    async (imageUrl: string) => {
+    async (imageUrl: string, overrideText?: string) => {
       setFileError('');
+
       try {
         const productPk = product?.pk;
         const excludedIds = productPk ? [productPk] : undefined;
 
-        const result = await fetchSimilarProductsByUrl({
+        const textToUse =
+          overrideText !== undefined ? overrideText : searchTextRef.current;
+
+        const requestParams = {
           url: imageUrl,
           limit: 20,
-          excluded_product_ids: excludedIds
-        }).unwrap();
+          excluded_product_ids: excludedIds,
+          text: textToUse || undefined
+        };
+
+        const result = await fetchSimilarProductsByUrl(requestParams).unwrap();
 
         await handleSearchResults(result);
         return result;
@@ -450,6 +469,8 @@ export function useSimilarProducts(product: Product) {
     [
       fetchSimilarProductsByUrl,
       product?.pk,
+      searchText,
+      searchTextRef,
       handleSearchResults,
       updateResultsAndKey,
       createEmptySearchResults,
@@ -462,31 +483,62 @@ export function useSimilarProducts(product: Product) {
     if (product?.productimage_set?.length > 0) {
       const initialImageUrl = product.productimage_set[0].image;
       setCurrentImageUrl(initialImageUrl);
+      setHasCroppedImage(false);
+      setCurrentImageBase64('');
+      setHasUploadedImage(false);
+      hasUploadedImageRef.current = false;
     }
   }, [product]);
 
   const fetchSimilarProductsByBase64 = useCallback(
-    async (base64Image: string) => {
+    async (
+      base64Image: string,
+      overrideText?: string,
+      forceExclude?: boolean
+    ) => {
       const base64Data = base64Image.startsWith('data:')
         ? base64Image.split(',')[1]
         : base64Image;
 
+      const textToUse =
+        overrideText !== undefined ? overrideText : searchTextRef.current;
+
+      const shouldExclude =
+        forceExclude !== undefined ? forceExclude : !hasUploadedImage;
+
+      const requestData = {
+        image: base64Data,
+        limit: 20,
+        excluded_product_ids: shouldExclude
+          ? product?.pk
+            ? [product.pk]
+            : undefined
+          : undefined,
+        text: textToUse || undefined
+      };
+
       return handleImageSearch(
-        async () =>
-          getSimilarProductsByImage({
-            image: base64Data,
-            limit: 20
-          }).unwrap(),
+        async () => getSimilarProductsByImage(requestData).unwrap(),
         base64Image,
         'Image search'
       );
     },
-    [getSimilarProductsByImage, handleImageSearch]
+    [
+      getSimilarProductsByImage,
+      searchText,
+      searchTextRef,
+      handleImageSearch,
+      hasUploadedImage,
+      product?.pk
+    ]
   );
 
   const fetchSimilarProductsByImageCrop = useCallback(
-    async (dataString: string) => {
+    async (dataString: string, excludeCurrentProduct: boolean = true) => {
       setFileError('');
+
+      setCurrentImageBase64(dataString);
+      setHasCroppedImage(true);
       if (dataString.startsWith('data:application/x-cors-fallback;base64,')) {
         try {
           const fallbackDataEncoded = dataString.replace(
@@ -549,9 +601,12 @@ export function useSimilarProducts(product: Product) {
                           getSimilarProductsByImage({
                             image: base64Data,
                             limit: 20,
-                            excluded_product_ids: product?.pk
-                              ? [product.pk]
-                              : undefined
+                            excluded_product_ids: excludeCurrentProduct
+                              ? product?.pk
+                                ? [product.pk]
+                                : undefined
+                              : undefined,
+                            text: searchTextRef.current || undefined
                           }).unwrap(),
                         croppedBase64,
                         'Proxy crop search'
@@ -601,7 +656,12 @@ export function useSimilarProducts(product: Product) {
           getSimilarProductsByImage({
             image: base64Data,
             limit: 20,
-            excluded_product_ids: product?.pk ? [product.pk] : undefined
+            excluded_product_ids: excludeCurrentProduct
+              ? product?.pk
+                ? [product.pk]
+                : undefined
+              : undefined,
+            text: searchTextRef.current || undefined
           }).unwrap(),
         dataString,
         'Image crop search'
@@ -609,11 +669,14 @@ export function useSimilarProducts(product: Product) {
     },
     [
       getSimilarProductsByImage,
+      searchText,
+      searchTextRef,
       handleImageSearch,
       product,
       fetchSimilarProductsByImageUrl,
       setFileError,
-      t
+      t,
+      hasUploadedImage
     ]
   );
 
@@ -624,6 +687,8 @@ export function useSimilarProducts(product: Product) {
     const file = event.target.files?.[0];
     if (!file) return;
 
+    setSearchTextWithRef('');
+
     try {
       let processedFile = file;
 
@@ -650,6 +715,9 @@ export function useSimilarProducts(product: Product) {
         const dataUrl = e.target?.result as string;
         setCurrentImageUrl(dataUrl);
         setHasUploadedImage(true);
+        hasUploadedImageRef.current = true;
+        setHasCroppedImage(false);
+        setCurrentImageBase64('');
 
         const metadataValidation = await validateImageFromDataUrl(dataUrl);
         if (!metadataValidation.isValid) {
@@ -658,7 +726,7 @@ export function useSimilarProducts(product: Product) {
           );
           return;
         }
-        fetchSimilarProductsByBase64(dataUrl);
+        fetchSimilarProductsByBase64(dataUrl, undefined, false);
       };
 
       reader.onerror = () =>
@@ -679,6 +747,8 @@ export function useSimilarProducts(product: Product) {
 
     try {
       setCurrentImageUrl(base64Image);
+      setCurrentImageBase64(base64Image);
+      setHasCroppedImage(true);
 
       const metadataValidation = await validateImageFromDataUrl(base64Image);
       if (!metadataValidation.isValid) {
@@ -688,10 +758,14 @@ export function useSimilarProducts(product: Product) {
         return;
       }
 
-      if (hasUploadedImage) {
-        await fetchSimilarProductsByBase64(base64Image);
+      if (hasUploadedImageRef.current) {
+        await fetchSimilarProductsByBase64(
+          base64Image,
+          searchTextRef.current,
+          false
+        );
       } else {
-        await fetchSimilarProductsByImageCrop(base64Image);
+        await fetchSimilarProductsByImageCrop(base64Image, true);
       }
     } catch (error) {
       setFileError(t('common.similar_products.errors.crop_processing_error'));
@@ -882,6 +956,11 @@ export function useSimilarProducts(product: Product) {
     setLoadedPages(new Set([1]));
   }, []);
 
+  const resetCropState = useCallback(() => {
+    setHasCroppedImage(false);
+    setCurrentImageBase64('');
+  }, []);
+
   const clearFileInput = useCallback(
     (fileInputRef: React.RefObject<HTMLInputElement>) => {
       if (fileInputRef.current) {
@@ -891,6 +970,47 @@ export function useSimilarProducts(product: Product) {
     []
   );
 
+  const handleTextSearch = useCallback(async () => {
+    const textToUse = searchTextRef.current || searchText;
+
+    if (hasCroppedImage && currentImageBase64) {
+      await fetchSimilarProductsByBase64(currentImageBase64, textToUse, !hasUploadedImage);
+    } else if (hasUploadedImage && currentImageUrl) {
+      await fetchSimilarProductsByBase64(currentImageUrl, textToUse, false);
+    } else if (currentImageUrl) {
+      await fetchSimilarProductsByImageUrl(currentImageUrl, textToUse);
+    }
+  }, [
+    searchText,
+    searchTextRef,
+    currentImageUrl,
+    currentImageBase64,
+    hasCroppedImage,
+    hasUploadedImage,
+    fetchSimilarProductsByImageUrl,
+    fetchSimilarProductsByBase64
+  ]);
+
+  const handleClearText = useCallback(async () => {
+    setSearchTextWithRef('');
+
+    if (hasCroppedImage && currentImageBase64) {
+      await fetchSimilarProductsByBase64(currentImageBase64, '', !hasUploadedImage);
+    } else if (hasUploadedImage && currentImageUrl) {
+      await fetchSimilarProductsByBase64(currentImageUrl, '', false);
+    } else if (currentImageUrl) {
+      await fetchSimilarProductsByImageUrl(currentImageUrl, '');
+    }
+  }, [
+    hasCroppedImage,
+    currentImageBase64,
+    currentImageUrl,
+    hasUploadedImage,
+    fetchSimilarProductsByBase64,
+    fetchSimilarProductsByImageUrl,
+    setSearchTextWithRef
+  ]);
+
   const handleLoadMore = async () => {
     if (!searchResults?.pagination || isLoading) return;
 
@@ -931,6 +1051,8 @@ export function useSimilarProducts(product: Product) {
     setCurrentImageUrl,
     isLoading,
     fileError,
+    searchText,
+    setSearchText: setSearchTextWithRef,
     searchResults,
     resultsKey,
     hasUploadedImage,
@@ -949,6 +1071,9 @@ export function useSimilarProducts(product: Product) {
     allLoadedProducts,
     clearError,
     clearResults,
-    clearFileInput
+    clearFileInput,
+    handleTextSearch,
+    handleClearText,
+    resetCropState
   };
 }