@akinon/pz-virtual-try-on 2.0.0-beta.16 → 2.0.0-beta.18

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @akinon/pz-virtual-try-on
 
+## 2.0.0-beta.18
+
+### Patch Changes
+
+- Updated dependencies [929374c5]
+- Updated dependencies [71f8011d]
+- Updated dependencies [9be2c081]
+- Updated dependencies [bd431e36]
+- Updated dependencies [54eac86b]
+  - @akinon/next@2.0.0-beta.18
+
+## 2.0.0-beta.17
+
+### Minor Changes
+
+- 36143125: ZERO-3987: Add barcode scanner functionality with modal and button
+- 5fb34b5c: ZERO-3955: Add aspect ratio validation and error handling for image cropping
+
+### Patch Changes
+
+- Updated dependencies [8218dafa]
+- Updated dependencies [2a8ddcf6]
+- Updated dependencies [8a7fd0f4]
+- Updated dependencies [36143125]
+- Updated dependencies [f7e0f646]
+- Updated dependencies [94a86fcc]
+- Updated dependencies [bcaad120]
+  - @akinon/next@2.0.0-beta.17
+
 ## 2.0.0-beta.16
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,7 @@
 - [Customization Strategies](#markdown-header-customization-strategies)
 - [Professional Examples](#markdown-header-professional-examples)
 - [Usage Blueprints](#markdown-header-usage-blueprints)
+- [Upload Modal Content Customization](#markdown-header-upload-modal-content-customization)
 - [Styling Reference](#markdown-header-styling-reference)
 - [Workflow & Caching](#markdown-header-workflow-caching)
 - [Best Practices](#markdown-header-best-practices)
@@ -92,8 +93,10 @@
 - **⚙️ Per-Component Control**: Independent customization for each modal and component
 - **🔒 Type Safety**: Full TypeScript support for all customization options
 - **🌍 Localization Support**: Built-in `useLocalization` hook integration in every component for multi-language UI
+- **🖼️ Upload Modal Images**: Replace rule example images with custom branded assets via `customStyles.uploadModalImages`
+- **📝 Upload Modal Texts**: Customize all modal text content via `customStyles.uploadModalTexts`
 
-**Customizable Components (10/10 - 100%):**
+**Customizable Components (12/12 - 100%):**
 
 - ✅ `VirtualTryOnUploadModal` - 30+ render functions, 80+ style points, CSS variables, cropping UI
 - ✅ `VirtualTryOnResultModal` - 15+ render functions, 50+ style points, mobile-optimized feedback
@@ -103,9 +106,24 @@
 - ✅ `VirtualTryOnProductSelector` - 3 render functions, 30+ style points, max selection UI
 - ✅ `VirtualTryOnAsyncModal` - 5 render functions, 35+ style points, async feedback system
 - ✅ `BasketVirtualTryOn` - 2 render functions, 4 style points, eligibility filtering
+- ✅ `BarcodeScannerPlugin` - Complete VTO flow orchestration with customization pass-through
+- ✅ `BarcodeScannerButton` - 2 render functions, 2 style points, floating button
+- ✅ `BarcodeScannerModal` - 30+ render functions, 50+ style points, scanner UI
 - ✅ `BasketAsyncModal` - 3 render functions, 25+ style points, real-time polling
 - ✅ `VirtualTryOnButton` - 4 render functions, 10+ style points, variant support
 
+### 🆕 NEW: Barcode Scanner Integration
+
+- **📷 Barcode Scanning**: Scan product barcodes with your mobile camera to find and try on products instantly
+- **🔍 Universal Barcode Support**: Supports all major formats (EAN-13, EAN-8, UPC-A, UPC-E, Code-128, Code-39, QR Code, and more)
+- **📱 Homepage Only**: Floating button visible only on mobile devices and only on homepage
+- **⚡ Real-time Search**: Instantly searches products by barcode number
+- **🛒 Multi-Product Scanning**: Scan multiple products before continuing to VTO
+- **🎨 Fully Customizable**: 50+ style points, 30+ render functions, theme support, CSS variables
+- **📳 Haptic Feedback**: Optional vibration on successful scan
+- **🔒 Permission Handling**: Graceful camera permission requests and error handling
+- **⏱️ Auto-dismiss Errors**: Error messages automatically dismiss after 2 seconds
+
 ### 🆕 NEW: Multiple Product Try-On (Basket Integration)
 
 - **🛒 Basket Integration**: Try on multiple products from basket simultaneously (max 3 products)
@@ -127,6 +145,240 @@ Select `pz-virtual-try-on` when prompted. In existing monorepos run `yarn instal
 
 ## Quick Start
 
+### 🆕 Barcode Scanner Integration (Mobile Homepage)
+
+**NEW**: Scan product barcodes to instantly find and try on products!
+
+#### Method 1: Using PluginModule (Recommended)
+
+The barcode scanner is automatically available via the PluginModule system. Add it to your **homepage only** (not client-root, as it should only appear on the homepage):
+
+```tsx
+// In src/app/[commerce]/[locale]/[currency]/home-client.tsx
+'use client';
+
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+export function HomeClient() {
+  return (
+    <>
+      {/* Barcode Scanner Plugin - Mobile only floating button */}
+      <PluginModule component={Component.BarcodeScannerPlugin} />
+    </>
+  );
+}
+```
+
+Then use it in your homepage:
+
+```tsx
+// In src/app/[commerce]/[locale]/[currency]/page.tsx
+import { HomeClient } from './home-client';
+
+async function Page() {
+  return (
+    <>
+      {/* Your homepage widgets */}
+      <HomeClient />
+    </>
+  );
+}
+```
+
+#### Method 2: Direct Component Import
+
+```tsx
+import { BarcodeScannerPlugin } from '@akinon/pz-virtual-try-on';
+import type {
+  BarcodeScannerSettings,
+  VirtualTryOnPluginSettings
+} from '@akinon/pz-virtual-try-on';
+
+// Full customization example with styles and renderers
+const barcodeScannerSettings: BarcodeScannerSettings = {
+  maxProducts: 5,
+  vibrateOnScan: true,
+  // Theme customization
+  theme: {
+    colors: {
+      primary: '#3b82f6',
+      background: '#ffffff',
+      text: '#1f2937',
+      success: '#10b981',
+      error: '#ef4444',
+      scannerOverlay: 'rgba(0, 0, 0, 0.6)',
+      scannerFrame: '#3b82f6',
+      scannerCorner: '#3b82f6'
+    },
+    borderRadius: {
+      sm: '4px',
+      md: '8px',
+      lg: '16px'
+    }
+  },
+  // 50+ Custom style points
+  customStyles: {
+    // Floating button
+    floatingButton: 'bg-blue-600 shadow-xl hover:bg-blue-700',
+    floatingButtonIcon: 'text-white w-7 h-7',
+    // Modal
+    modalOverlay: 'bg-black/80',
+    modalContainer: 'bg-white rounded-2xl',
+    modalHeader: 'border-b border-gray-100',
+    modalCloseButton: 'hover:bg-gray-100 rounded-full',
+    // Scanner
+    scannerContainer: 'rounded-lg overflow-hidden',
+    scannerFrame: 'border-2 border-blue-500',
+    scannerHelpText: 'text-white text-sm',
+    // Products
+    productCard: 'rounded-lg shadow-sm',
+    productImage: 'object-cover',
+    productRemoveButton: 'bg-red-500 hover:bg-red-600',
+    // Actions
+    continueButton: 'bg-blue-600 hover:bg-blue-700 text-white font-semibold',
+    // Error states
+    errorContainer: 'bg-red-500/90 rounded-lg',
+    errorMessage: 'text-white',
+    // Loading
+    loadingSpinner: 'text-blue-500',
+    // Permission denied
+    permissionDeniedButton: 'bg-blue-600 text-white'
+  },
+  // 30+ Custom render functions
+  customRenderers: {
+    // Custom floating button
+    renderFloatingButton: ({ onClick }) => (
+      <button
+        onClick={onClick}
+        className="fixed bottom-20 right-4 z-50 md:hidden w-16 h-16 rounded-full bg-gradient-to-r from-blue-500 to-purple-500 text-white shadow-xl"
+      >
+        📷
+      </button>
+    ),
+    // Custom modal header
+    renderModalHeader: ({ title, onClose }) => (
+      <div className="flex justify-between items-center p-4 bg-gradient-to-r from-blue-500 to-purple-500">
+        <h2 className="text-white font-bold text-lg">{title}</h2>
+        <button onClick={onClose} className="text-white">
+          ✕
+        </button>
+      </div>
+    ),
+    // Custom product card
+    renderProductCard: ({ product, onRemove }) => (
+      <div className="relative p-2 bg-white rounded-lg shadow">
+        <img
+          src={product.productimage_set?.[0]?.image}
+          alt={product.name}
+          className="w-16 h-16 object-cover rounded"
+        />
+        <button
+          onClick={() => onRemove?.(product)}
+          className="absolute -top-2 -right-2 w-5 h-5 bg-red-500 text-white rounded-full text-xs"
+        >
+          ×
+        </button>
+      </div>
+    ),
+    // Custom continue button
+    renderContinueButton: ({ onClick, disabled, text }) => (
+      <button
+        onClick={onClick}
+        disabled={disabled}
+        className={`w-full py-3 rounded-full font-bold transition ${
+          disabled
+            ? 'bg-gray-300'
+            : 'bg-gradient-to-r from-blue-500 to-purple-500 text-white'
+        }`}
+      >
+        {text}
+      </button>
+    ),
+    // Custom error display
+    renderError: ({ error, onRetry }) => (
+      <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded">
+        <span>{error}</span>
+        {onRetry && (
+          <button onClick={onRetry} className="ml-2 underline">
+            Retry
+          </button>
+        )}
+      </div>
+    )
+  }
+};
+
+export function HomePage() {
+  return (
+    <div>
+      {/* Your homepage content */}
+
+      {/* Barcode Scanner Button (shows on mobile only) */}
+      <BarcodeScannerPlugin
+        barcodeScannerSettings={barcodeScannerSettings}
+        onProductsScanned={(products) => {
+          // Handle scanned products
+        }}
+        onVTOComplete={(result) => {
+          // Handle VTO completion
+        }}
+      />
+    </div>
+  );
+}
+```
+
+#### Method 3: Configure via settings.js
+
+You can also configure the barcode scanner via `settings.js`:
+
+```javascript
+// settings.js
+module.exports = {
+  // ... other settings
+  plugins: {
+    'pz-virtual-try-on': {
+      barcodeScanner: {
+        maxProducts: 5,
+        vibrateOnScan: true,
+        customStyles: {
+          floatingButton: 'bg-black shadow-xl',
+          continueButton: 'bg-black hover:bg-gray-800'
+        }
+      },
+      vto: {
+        theme: {
+          colors: {
+            primary: '#000000'
+          }
+        }
+      }
+    }
+  }
+};
+```
+
+**How it works:**
+
+1. Floating button appears in bottom-right corner (mobile only)
+2. Click opens fullscreen barcode scanner
+3. Point camera at product barcode
+4. Product is searched and displayed automatically
+5. Scan more products or click "Sanal Kabine Devam Et" (Continue to Virtual Cabin)
+6. Upload photo and see VTO results for all scanned products
+
+**Supported Barcode Formats:**
+
+- EAN-13 / EAN-8 (European Article Number)
+- UPC-A / UPC-E (Universal Product Code)
+- Code-128 / Code-39 / Code-93
+- QR Code
+- Data Matrix
+- PDF-417
+- Codabar
+- ITF (Interleaved 2 of 5)
+- Aztec
+
 ### 🆕 Basket Integration (Multiple Products)
 
 **NEW**: Try on multiple products from basket page!
@@ -226,10 +478,10 @@ const virtualTryOnSettings: VirtualTryOnPluginSettings = {
                 {step === 'upload'
                   ? ' 01'
                   : step === 'crop'
-                    ? ' 02'
-                    : step === 'processing'
-                      ? ' 03'
-                      : ' 04'}
+                  ? ' 02'
+                  : step === 'processing'
+                  ? ' 03'
+                  : ' 04'}
               </p>
               <h2 className="text-xl font-semibold text-gray-900">{title}</h2>
             </div>
@@ -648,7 +900,17 @@ type VirtualTryOnPluginSettings = {
   buttonSize?: 'sm' | 'md' | 'lg';
   legal_text?: string;
   instructions?: string;
-  customStyles?: Record<string, string | undefined>;
+  customStyles?: {
+    // CSS class overrides (300+ slots)
+    button?: string;
+    uploadModal?: string;
+    resultModal?: string;
+    // ... and many more
+    
+    // Upload Modal Content Customization
+    uploadModalImages?: VirtualTryOnModalImages;
+    uploadModalTexts?: VirtualTryOnModalTexts;
+  };
   customRenderers?: {
     UploadModal?: React.ComponentType<VirtualTryOnUploadModalProps>;
     ResultModal?: React.ComponentType<VirtualTryOnResultModalProps>;
@@ -672,7 +934,7 @@ type VirtualTryOnPluginSettings = {
 };
 ```
 
-> `customStyles` exposes 300+ slots (see [Styling Reference](#markdown-header-styling-reference)); `CustomRendererProps` provides 60+ render callbacks across all 10 components with full localization support.
+> `customStyles` exposes 300+ slots for CSS classes plus `uploadModalImages` and `uploadModalTexts` for content customization (see [Upload Modal Content Customization](#markdown-header-upload-modal-content-customization) and [Styling Reference](#markdown-header-styling-reference)); `CustomRendererProps` provides 60+ render callbacks across all 10 components with full localization support.
 
 ### Service Endpoints
 
@@ -1695,6 +1957,140 @@ Customize modal overlays, sizes, and button styles for brand consistency.
 />
 ```
 
+## Upload Modal Content Customization
+
+The upload modal images and texts can be fully customized via `customStyles.uploadModalImages` and `customStyles.uploadModalTexts`. This is useful for:
+
+- Replacing default rule images with custom branded examples
+- Translating or customizing all modal text content
+- Providing localized photo guidelines with custom imagery
+- A/B testing different upload instructions
+
+### Available Image Slots
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `ruleGoodExample` | Good photo example (rule 1 image) | Built-in asset |
+| `ruleBadExample1` | Bad example: cluttered background | Built-in asset |
+| `ruleBadExample2` | Bad example: poor lighting | Built-in asset |
+| `ruleBadExample3` | Bad example: cropped body | Built-in asset |
+| `ruleBadExample4` | Bad example: multiple people | Built-in asset |
+| `uploadIcon` | Upload area icon | Built-in SVG |
+
+### Available Text Slots
+
+| Property | Description | Fallback Localization Key |
+|----------|-------------|---------------------------|
+| `title` | Modal header title | `product.virtual_try_on.title` |
+| `editPhotoTitle` | Title when editing/cropping photo | `product.virtual_try_on.edit_photo_title` |
+| `uploadPrompt` | Main upload prompt text | `product.virtual_try_on.upload_prompt` |
+| `uploadRequirements` | File requirements text | `product.virtual_try_on.upload_requirements` |
+| `uploadInfo` | Additional upload info | `product.virtual_try_on.upload_info` |
+| `rule1` | Rule 1 description | `product.virtual_try_on.rule_1` |
+| `rule2` | Rule 2 description | `product.virtual_try_on.rule_2` |
+| `rule3` | Rule 3 description | `product.virtual_try_on.rule_3` |
+| `rule4` | Rule 4 description | `product.virtual_try_on.rule_4` |
+| `rule5` | Rule 5 description | `product.virtual_try_on.rule_5` |
+| `rule6` | Rule 6 description | `product.virtual_try_on.rule_6` |
+| `processingTitle` | Processing overlay title | `product.virtual_try_on.processing` |
+| `processingMessage` | Processing overlay message | `product.virtual_try_on.processing_message` |
+| `retryUpload` | Retry upload button text | `product.virtual_try_on.retry` |
+
+### Example: Custom Images and Texts
+
+```tsx
+import PluginModule, { Component } from '@akinon/next/components/plugin-module';
+
+<PluginModule
+  component={Component.VirtualTryOnPlugin}
+  props={{
+    product: data.product,
+    settings: {
+      customStyles: {
+        // Custom button styling
+        button: 'bg-purple-600 hover:bg-purple-700 text-white font-bold px-6 py-3 rounded-lg',
+        
+        // Custom Upload Modal Images
+        uploadModalImages: {
+          ruleGoodExample: 'https://cdn.example.com/vto/good-example.jpg',
+          ruleBadExample1: 'https://cdn.example.com/vto/bad-background.jpg',
+          ruleBadExample2: 'https://cdn.example.com/vto/bad-lighting.jpg',
+          ruleBadExample3: 'https://cdn.example.com/vto/bad-cropped.jpg',
+          ruleBadExample4: 'https://cdn.example.com/vto/bad-multiple.jpg',
+          uploadIcon: 'https://cdn.example.com/vto/upload-icon.svg'
+        },
+        
+        // Custom Upload Modal Texts
+        uploadModalTexts: {
+          title: '🎭 Virtual Try-On Studio',
+          editPhotoTitle: '✂️ Adjust Your Photo',
+          uploadPrompt: '📸 Drag & drop your photo here',
+          uploadRequirements: 'JPEG or PNG, max 5MB',
+          uploadInfo: 'Your photo will be processed securely',
+          rule1: '🌟 Use a plain background',
+          rule2: '💡 Ensure good lighting',
+          rule3: '👤 Show your full body',
+          rule4: '🚫 No multiple people',
+          rule5: '📐 Face the camera directly',
+          rule6: '👔 Wear fitted clothing',
+          processingTitle: '✨ Creating your look...',
+          processingMessage: 'Our AI is working its magic!',
+          retryUpload: '🔄 Try another photo'
+        }
+      }
+    }
+  }}
+/>
+```
+
+### TypeScript Interfaces
+
+```ts
+interface VirtualTryOnModalImages {
+  ruleGoodExample?: string;
+  ruleBadExample1?: string;
+  ruleBadExample2?: string;
+  ruleBadExample3?: string;
+  ruleBadExample4?: string;
+  uploadIcon?: string;
+}
+
+interface VirtualTryOnModalTexts {
+  title?: string;
+  editPhotoTitle?: string;
+  uploadPrompt?: string;
+  uploadRequirements?: string;
+  uploadInfo?: string;
+  rule1?: string;
+  rule2?: string;
+  rule3?: string;
+  rule4?: string;
+  rule5?: string;
+  rule6?: string;
+  processingTitle?: string;
+  processingMessage?: string;
+  retryUpload?: string;
+}
+
+// Usage in VirtualTryOnPluginSettings
+interface VirtualTryOnPluginSettings {
+  customStyles?: {
+    // ... other style slots
+    uploadModalImages?: VirtualTryOnModalImages;
+    uploadModalTexts?: VirtualTryOnModalTexts;
+  };
+}
+```
+
+### Fallback Behavior
+
+If a custom image or text is not provided, the component automatically falls back to:
+
+1. **Images**: Built-in default assets from the package
+2. **Texts**: Localized strings via `useLocalization()` hook with the corresponding translation key
+
+This allows partial customization - you can override only the images or texts you need while keeping defaults for the rest.
+
 ## Styling Reference
 
 ### Button Targets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akinon/pz-virtual-try-on",
-  "version": "2.0.0-beta.16",
+  "version": "2.0.0-beta.18",
   "license": "MIT",
   "main": "src/index.ts",
   "peerDependencies": {
@@ -8,10 +8,11 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/next": "2.0.0-beta.16",
+    "@akinon/next": "2.0.0-beta.18",
     "clsx": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "react-image-crop": "^11.0.5"
+    "react-image-crop": "^11.0.5",
+    "html5-qrcode": "^2.3.8"
   },
   "devDependencies": {
     "@types/node": "^18.7.8",