@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/THEMING.md

@@ -1,681 +0,0 @@
-# Theming Guide
-
-Complete reference for customizing the appearance of LiquidCommerce Elements SDK components based on actual SDK interfaces.
-
-## Overview
-
-The SDK provides theme customization through the `customTheme` configuration option. Theme configuration uses a hierarchical structure with global and component-specific settings.
-
-## Basic Usage
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  customTheme: {
-    global: {
-      theme: { /* global theme */ },
-      layout: { /* global layout */ }
-    },
-    product: { /* product theme */ },
-    cart: { /* cart theme */ },
-    checkout: { /* checkout theme */ },
-    address: { /* address theme */ }
-  }
-});
-```
-
-## Global Configuration
-
-### Global Theme
-
-```typescript
-interface IGlobalTheme {
-  buttonCornerRadius: string;
-  cardCornerRadius: string;
-  headingFont: IFontFamily;
-  paragraphFont: IFontFamily;
-  primaryColor: string;
-  accentColor: string;
-  defaultTextColor: string;
-  selectedTextColor: string;
-  linkTextColor: string;
-  errorColor: string;
-  warningColor: string;
-  successColor: string;
-  drawerBackgroundColor: string;
-}
-
-interface IFontFamily {
-  name: string;
-  weights: number[];
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  global: {
-    theme: {
-      buttonCornerRadius: '8px',
-      cardCornerRadius: '12px',
-      headingFont: {
-        name: 'Inter',
-        weights: [600, 700]
-      },
-      paragraphFont: {
-        name: 'Inter',
-        weights: [400, 500]
-      },
-      primaryColor: '#007bff',
-      accentColor: '#6c757d',
-      defaultTextColor: '#212529',
-      selectedTextColor: '#ffffff',
-      linkTextColor: '#1d4ed8',
-      errorColor: '#dc3545',
-      warningColor: '#ffc107',
-      successColor: '#28a745',
-      drawerBackgroundColor: '#ffffff'
-    }
-  }
-}
-```
-
-### Global Layout
-
-```typescript
-interface IGlobalLayout {
-  enablePersonalization: boolean;
-  personalizationText: string;
-  personalizationCardStyle: 'outlined' | 'filled';
-  allowPromoCodes: boolean;
-  inputFieldStyle: 'outlined' | 'filled';
-  showPoweredBy: boolean;        // ⚠️ READ-ONLY: Cannot be customized (paid feature)
-  poweredByMode: 'light' | 'dark'; // Can be customized
-}
-```
-
-**⚠️ Protected Field**: `showPoweredBy` is controlled by LiquidCommerce and cannot be overridden through custom theme configuration. This is a paid feature managed through your LiquidCommerce dashboard. However, `poweredByMode` can be customized to match your site's theme (light or dark).
-
-**Example:**
-```javascript
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: true,
-      personalizationText: 'Personalize your product',
-      personalizationCardStyle: 'outlined',
-      allowPromoCodes: true,
-      inputFieldStyle: 'filled',
-      poweredByMode: 'dark' // Can be customized (light or dark)
-      // Note: showPoweredBy is read-only and cannot be customized here
-    }
-  }
-}
-```
-
-### Personalization (Engraving) Configuration
-
-The personalization feature is controlled globally and affects how engraving appears across all contexts (product, cart, and checkout).
-
-**Configuration Options:**
-
-- **`enablePersonalization`** (boolean): Master switch to enable/disable personalization feature globally. When `false`, engraving options won't appear even for engravable products.
-
-- **`personalizationText`** (string): The text shown on the "Add Personalization" button in product views. This is the call-to-action that customers see before adding engraving.
-
-- **`personalizationCardStyle`** ('outlined' | 'filled'): Controls the visual style of personalization cards displayed in cart and checkout:
-  - `'outlined'`: Border-based style with transparent background
-  - `'filled'`: Filled background style
-
-**Context-Specific Behavior:**
-
-The SDK intelligently displays personalization differently based on context:
-
-1. **Product View:** Shows button with `personalizationText` and engraving fee (e.g., "Personalize your product +$5.00")
-
-2. **Cart View:** Displays engraving details in a card with edit/remove buttons using the `personalizationCardStyle`
-
-3. **Checkout View:** Shows engraving details in a card (read-only) with only remove button using the `personalizationCardStyle`
-
-**Example Configurations:**
-
-```javascript
-// Minimal personalization (use defaults)
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: true
-    }
-  }
-}
-
-// Custom personalization styling
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: true,
-      personalizationText: 'Make it yours',
-      personalizationCardStyle: 'filled'
-    }
-  }
-}
-
-// Disable personalization globally
-customTheme: {
-  global: {
-    layout: {
-      enablePersonalization: false
-    }
-  }
-}
-```
-
-**Note:** Individual products determine if they support engraving based on product metadata. The global setting only controls whether the feature is available when products support it.
-
-## Product Component
-
-```typescript
-interface IProductComponent {
-  theme: {
-    backgroundColor: string;
-  };
-  layout: {
-    showImages: boolean;
-    showOnlyMainImage: boolean;
-    showTitle: boolean;
-    showDescription: boolean;
-    showQuantityCounter: boolean;
-    showOffHours: boolean;
-    quantityCounterStyle: 'outlined' | 'ghost';
-    fulfillmentDisplay: 'carousel' | 'popup';
-    enableShippingFulfillment: boolean;
-    enableOnDemandFulfillment: boolean;
-    addToCartButtonText: string;
-    addToCartButtonShowTotalPrice: boolean;
-    buyNowButtonText: string;
-    preSaleButtonText: string;
-    prioritizeEngraving: boolean;
-    noAvailabilityText: string;
-  };
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  product: {
-    theme: {
-      backgroundColor: '#ffffff'
-    },
-    layout: {
-      showImages: true,
-      showOnlyMainImage: false,
-      showTitle: true,
-      showDescription: true,
-      showQuantityCounter: true,
-      showOffHours: false,
-      quantityCounterStyle: 'outlined',
-      fulfillmentDisplay: 'carousel',
-      enableShippingFulfillment: true,
-      enableOnDemandFulfillment: true,
-      addToCartButtonText: 'Add to Cart',
-      addToCartButtonShowTotalPrice: true,
-      buyNowButtonText: 'Buy Now',
-      preSaleButtonText: 'Pre-Order',
-      prioritizeEngraving: false,
-      noAvailabilityText: 'Not available in your area'
-    }
-  }
-}
-```
-
-## Cart Component
-
-```typescript
-interface ICartComponent {
-  theme: {
-    backgroundColor: string;
-  };
-  layout: {
-    showQuantityCounter: boolean;
-    quantityCounterStyle: 'outlined' | 'ghost';
-    drawerHeaderText: string;
-    goToCheckoutButtonText: string;
-  };
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  cart: {
-    theme: {
-      backgroundColor: '#ffffff'
-    },
-    layout: {
-      showQuantityCounter: true,
-      quantityCounterStyle: 'outlined',
-      drawerHeaderText: 'Your Cart',
-      goToCheckoutButtonText: 'Proceed to Checkout'
-    }
-  }
-}
-```
-
-## Checkout Component
-
-```typescript
-interface ICheckoutComponent {
-  theme: {
-    backgroundColor: string;
-  };
-  layout: {
-    emailOptIn: {
-      show: boolean;
-      checked: boolean;
-      text: string;
-    };
-    smsOptIn: {
-      show: boolean;
-      checked: boolean;
-      text: string;
-    };
-    allowGiftCards: boolean;
-    legalMessage: {
-      show: boolean;
-      text: string;
-    };
-    continueShoppingUrl: string;
-    exitUrl: string;
-    thankYouButtonText: string;
-    drawerHeaderText: string;
-    placeOrderButtonText: string;
-    checkoutCompleted: {
-      customLogo: string;
-      customText: string | null;
-    };
-  };
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  checkout: {
-    theme: {
-      backgroundColor: '#ffffff'
-    },
-    layout: {
-      emailOptIn: {
-        show: true,
-        checked: false,
-        text: 'Send me marketing emails'
-      },
-      smsOptIn: {
-        show: true,
-        checked: false,
-        text: 'Send me SMS updates'
-      },
-      allowGiftCards: true,
-      legalMessage: {
-        show: true,
-        text: 'By placing this order, you agree to our terms and conditions.'
-      },
-      continueShoppingUrl: '/',
-      exitUrl: '/',
-      thankYouButtonText: 'Continue Shopping',
-      drawerHeaderText: 'Checkout',
-      placeOrderButtonText: 'Place Order',
-      checkoutCompleted: {
-        customLogo: 'https://yourdomain.com/logo.png',
-        customText: 'Thank you for your order!'
-      }
-    }
-  }
-}
-```
-
-**Layout Properties:**
-
-- **`continueShoppingUrl`** (string): URL to redirect to when customer clicks "Continue Shopping" after order completion
-- **`exitUrl`** (string): URL for the exit/close action in checkout
-- **`legalMessage.text`** (string): Supports rich text / HTML content
-
-## Address Component
-
-```typescript
-interface IAddressComponent {
-  theme: {
-    backgroundColor: string;
-  };
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  address: {
-    theme: {
-      backgroundColor: '#ffffff'
-    }
-  }
-}
-```
-
-## Product List Component
-
-```typescript
-interface IProductListComponent {
-  theme: {
-    backgroundColor: string;
-  };
-  layout: {
-    productCard: {
-      style: 'card' | 'ghost';
-      cornerRadius: 'rounded' | 'sharp';
-      showPrice: boolean;
-      showSizeSelector: boolean;
-      showFulfillment: boolean;
-      showRetailerName: boolean;
-      showQuantityCounter: boolean;
-      enableShippingFulfillment: boolean;
-      enableOnDemandFulfillment: boolean;
-      showCollections: boolean;
-      enablePersonalization: boolean;
-    };
-    displayMode: 'modal' | 'drawer';
-  };
-}
-```
-
-**Example:**
-```javascript
-customTheme: {
-  productList: {
-    theme: {
-      backgroundColor: '#f8f9fa'
-    },
-    layout: {
-      productCard: {
-        style: 'card',
-        cornerRadius: 'rounded',
-        showPrice: true,
-        showSizeSelector: true,
-        showFulfillment: true,
-        showRetailerName: false,
-        showQuantityCounter: true,
-        enableShippingFulfillment: true,
-        enableOnDemandFulfillment: true,
-        showCollections: false,
-        enablePersonalization: true
-      },
-      displayMode: 'drawer'
-    }
-  }
-}
-```
-
-**Card Style Options:**
-
-- **`style`**: `'card'` shows a bordered card with background, `'ghost'` shows a minimal borderless card
-- **`cornerRadius`**: `'rounded'` uses rounded corners, `'sharp'` uses square corners
-- **`displayMode`**: `'modal'` opens product details in a modal, `'drawer'` opens in a side drawer
-
-**Card Feature Flags:**
-
-- **`showPrice`**: Display price on the product card
-- **`showSizeSelector`**: Show size/variant selector on the card
-- **`showFulfillment`**: Show fulfillment type indicator
-- **`showRetailerName`**: Show the retailer name
-- **`showQuantityCounter`**: Show quantity increment/decrement controls
-- **`enableShippingFulfillment`**: Allow shipping fulfillment option
-- **`enableOnDemandFulfillment`**: Allow on-demand fulfillment option
-- **`showCollections`**: Show product collection/tag labels
-- **`enablePersonalization`**: Show personalization/engraving option on cards
-
-## Complete Configuration Example
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  env: 'production',
-  customTheme: {
-    global: {
-      theme: {
-        buttonCornerRadius: '8px',
-        cardCornerRadius: '12px',
-        headingFont: {
-          name: 'Inter',
-          weights: [600, 700]
-        },
-        paragraphFont: {
-          name: 'Inter',
-          weights: [400, 500]
-        },
-        primaryColor: '#007bff',
-        accentColor: '#6c757d',
-        defaultTextColor: '#212529',
-        selectedTextColor: '#ffffff',
-        linkTextColor: '#1d4ed8',
-        errorColor: '#dc3545',
-        warningColor: '#ffc107',
-        successColor: '#28a745',
-        drawerBackgroundColor: '#ffffff'
-      },
-      layout: {
-        enablePersonalization: true,
-        personalizationText: 'Make it yours',
-        personalizationCardStyle: 'outlined',
-        allowPromoCodes: true,
-        inputFieldStyle: 'filled',
-        poweredByMode: 'light'
-      }
-    },
-    product: {
-      theme: {
-        backgroundColor: '#ffffff'
-      },
-      layout: {
-        showImages: true,
-        showOnlyMainImage: false,
-        showTitle: true,
-        showDescription: true,
-        showQuantityCounter: true,
-        showOffHours: false,
-        quantityCounterStyle: 'outlined',
-        fulfillmentDisplay: 'carousel',
-        enableShippingFulfillment: true,
-        enableOnDemandFulfillment: true,
-        addToCartButtonText: 'Add to Cart',
-        addToCartButtonShowTotalPrice: true,
-        buyNowButtonText: 'Buy Now',
-        preSaleButtonText: 'Pre-Order',
-        prioritizeEngraving: false,
-        noAvailabilityText: 'Not available in your area'
-      }
-    },
-    cart: {
-      theme: {
-        backgroundColor: '#ffffff'
-      },
-      layout: {
-        showQuantityCounter: true,
-        quantityCounterStyle: 'outlined',
-        drawerHeaderText: 'Your Cart',
-        goToCheckoutButtonText: 'Checkout'
-      }
-    },
-    checkout: {
-      theme: {
-        backgroundColor: '#ffffff'
-      },
-      layout: {
-        emailOptIn: {
-          show: true,
-          checked: false,
-          text: 'Email me with news and offers'
-        },
-        smsOptIn: {
-          show: true,
-          checked: false,
-          text: 'Text me with updates'
-        },
-        allowGiftCards: true,
-        legalMessage: {
-          show: false,
-          text: ''
-        },
-        continueShoppingUrl: '/',
-        exitUrl: '/',
-        thankYouButtonText: 'Continue Shopping',
-        drawerHeaderText: 'Checkout',
-        placeOrderButtonText: 'Place Order',
-        checkoutCompleted: {
-          customLogo: 'https://yourdomain.com/logo.png',
-          customText: null
-        }
-      }
-    },
-    address: {
-      theme: {
-        backgroundColor: '#ffffff'
-      }
-    }
-  }
-});
-```
-
-## Dynamic Theme Updates (Builder Mode)
-
-When `isBuilder: true`, update themes dynamically:
-
-```javascript
-const client = await Elements('YOUR_API_KEY', {
-  env: 'development',
-  isBuilder: true
-});
-
-// Update global theme
-await client.builder.updateComponentGlobalConfigs({
-  theme: {
-    primaryColor: '#ff6b6b'
-  }
-});
-
-// Update product component
-await client.builder.updateProductComponent({
-  layout: {
-    addToCartButtonText: 'Add to Bag'
-  }
-});
-
-// Update cart component
-client.builder.updateCartComponent({
-  layout: {
-    drawerHeaderText: 'Shopping Bag'
-  }
-});
-
-// Update checkout component
-client.builder.updateCheckoutComponent({
-  layout: {
-    placeOrderButtonText: 'Complete Purchase'
-  }
-});
-
-// Update address component
-client.builder.updateAddressComponent({
-  theme: {
-    backgroundColor: '#f8f9fa'
-  }
-});
-```
-
-## TypeScript Support
-
-The SDK includes full TypeScript definitions:
-
-```typescript
-import type {
-  IClientCustomThemeConfig,
-  UpdateComponentGlobalConfigs,
-  UpdateProductComponent,
-  UpdateCartComponent,
-  UpdateCheckoutComponent,
-  UpdateAddressComponent
-} from '@liquidcommerce/elements-sdk';
-
-const customTheme: IClientCustomThemeConfig = {
-  global: {
-    theme: {
-      primaryColor: '#007bff'
-    }
-  }
-};
-```
-
-## Theme Presets
-
-### Minimal
-
-```javascript
-customTheme: {
-  global: {
-    theme: {
-      buttonCornerRadius: '4px',
-      cardCornerRadius: '4px',
-      primaryColor: '#000000',
-      accentColor: '#666666'
-    }
-  }
-}
-```
-
-### Rounded
-
-```javascript
-customTheme: {
-  global: {
-    theme: {
-      buttonCornerRadius: '24px',
-      cardCornerRadius: '16px'
-    }
-  }
-}
-```
-
-### Bold Colors
-
-```javascript
-customTheme: {
-  global: {
-    theme: {
-      primaryColor: '#ff4757',
-      accentColor: '#5f27cd',
-      successColor: '#1dd1a1',
-      errorColor: '#ee5a6f'
-    }
-  }
-}
-```
-
-## Best Practices
-
-1. **Start minimal** - Only override what you need
-2. **Maintain consistency** - Use consistent corner radius and colors across components
-3. **Test accessibility** - Ensure sufficient color contrast
-4. **Use web fonts** - Load fonts before initializing SDK for smooth rendering
-5. **Match your brand** - Use your existing brand colors and typography
-6. **Test on mobile** - Verify appearance on different screen sizes
-7. **Use TypeScript** - Leverage type checking to avoid errors
-8. **Document your theme** - Keep a reference of your theme customizations
-
-## Limitations
-
-- Theme configuration is deep-merged with default theme
-- Some UI elements may not be customizable (core functionality)
-- Font loading is your responsibility (load fonts before SDK init)
-- Background colors apply to drawer containers, not individual elements
-
-## Related Documentation
-
-- [Configuration Reference](./CONFIGURATION.md) - All SDK configuration options
-- [Troubleshooting Guide](./TROUBLESHOOTING.md) - Common theming issues