@liquidcommerce/elements-sdk 2.2.2 → 2.4.0

package/docs/THEMING.md

@@ -0,0 +1,592 @@
+# 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;
+  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',
+      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;
+    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;
+  };
+}
+```
+
+**Example:**
+```javascript
+customTheme: {
+  product: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      showImages: true,
+      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'
+    }
+  }
+}
+```
+
+## 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;
+    checkoutCompleted: {
+      customLogo: string;
+      customText: string | null;
+    };
+  };
+  layout: {
+    emailOptIn: {
+      show: boolean;
+      checked: boolean;
+      text: string;
+    };
+    smsOptIn: {
+      show: boolean;
+      checked: boolean;
+      text: string;
+    };
+    allowGiftCards: boolean;
+    legalMessage: {
+      show: boolean;
+      text: string;
+    };
+    exitUrl: string;
+    thankYouButtonText: string;
+    drawerHeaderText: string;
+    placeOrderButtonText: string;
+    placeOrderButtonShowRequiredFields: boolean;
+  };
+}
+```
+
+**Example:**
+```javascript
+customTheme: {
+  checkout: {
+    theme: {
+      backgroundColor: '#ffffff',
+      checkoutCompleted: {
+        customLogo: 'https://yourdomain.com/logo.png',
+        customText: 'Thank you for your order!'
+      }
+    },
+    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.'
+      },
+      exitUrl: '/',
+      thankYouButtonText: 'Continue Shopping',
+      drawerHeaderText: 'Checkout',
+      placeOrderButtonText: 'Place Order',
+      placeOrderButtonShowRequiredFields: true
+    }
+  }
+}
+```
+
+## Address Component
+
+```typescript
+interface IAddressComponent {
+  theme: {
+    backgroundColor: string;
+  };
+}
+```
+
+**Example:**
+```javascript
+customTheme: {
+  address: {
+    theme: {
+      backgroundColor: '#ffffff'
+    }
+  }
+}
+```
+
+## 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',
+        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,
+        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'
+      }
+    },
+    cart: {
+      theme: {
+        backgroundColor: '#ffffff'
+      },
+      layout: {
+        showQuantityCounter: true,
+        quantityCounterStyle: 'outlined',
+        drawerHeaderText: 'Your Cart',
+        goToCheckoutButtonText: 'Checkout'
+      }
+    },
+    checkout: {
+      theme: {
+        backgroundColor: '#ffffff',
+        checkoutCompleted: {
+          customLogo: 'https://yourdomain.com/logo.png',
+          customText: null
+        }
+      },
+      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: ''
+        },
+        exitUrl: '/',
+        thankYouButtonText: 'Continue Shopping',
+        drawerHeaderText: 'Checkout',
+        placeOrderButtonText: 'Place Order',
+        placeOrderButtonShowRequiredFields: true
+      }
+    },
+    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