@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.130

package/docs/v1/api/configuration.md

@@ -0,0 +1,587 @@
+# Configuration Reference
+
+Complete reference for all configuration options available in the Elements SDK.
+
+## Client Configuration
+
+### ILiquidCommerceElementsConfig
+
+Top-level configuration passed to `Elements()` or `ElementsBuilder()`.
+
+```typescript
+interface ILiquidCommerceElementsConfig {
+  env?: ElementsEnv;
+  promoTicker?: IPromoTicker[];
+  customTheme?: IClientCustomThemeConfig;
+  debugMode?: DebugMode;
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+  proxy?: IElementsProxyConfig;
+  gtm?: IElementsGTMConfig;
+  development?: ILiquidCommerceElementsDevelopmentConfig;
+}
+```
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `env` | `'staging' \| 'production'` | No | API environment |
+| `promoTicker` | `IPromoTicker[]` | No | Promotional ticker configurations |
+| `customTheme` | `IClientCustomThemeConfig` | No | Theme overrides for all components |
+| `debugMode` | `'none' \| 'console' \| 'panel'` | No | Debug output mode |
+| `checkout` | `ILiquidCommerceElementsCheckoutConfig` | No | Checkout behavior settings |
+| `proxy` | `IElementsProxyConfig` | No | Proxy configuration for API requests |
+| `gtm` | `IElementsGTMConfig` | No | Google tag gateway URL of your own GTM container |
+| `development` | `ILiquidCommerceElementsDevelopmentConfig` | No | Development/testing options |
+
+> **Note:** `debugMode` (`'console'` or `'panel'`) is **ignored in production** -- it is forced off when `env` is `'production'`. It only takes effect outside production (`'staging'`).
+
+---
+
+## Theme Configuration
+
+### IClientCustomThemeConfig
+
+Override default theme settings for any component.
+
+```typescript
+interface IClientCustomThemeConfig {
+  global?: UpdateComponentGlobalConfigs;
+  product?: UpdateProductComponent;
+  address?: UpdateAddressComponent;
+  cart?: UpdateCartComponent;
+  checkout?: UpdateCheckoutComponent;
+  productList?: UpdateProductListComponent;
+}
+```
+
+All theme properties are deeply partial -- you only need to specify the values you want to override.
+
+---
+
+### Global Theme
+
+#### IGlobalTheme
+
+```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;
+
+  /**
+   * Boundary color for form fields. Optional; defaults to a neutral that clears the 3:1
+   * contrast required by WCAG 1.4.11.
+   */
+  inputBorderColor?: string;
+
+  /** Keyboard focus ring color. Must reach 3:1 against the surface behind the control. */
+  focusRingColor?: string;
+}
+```
+
+> `inputBorderColor` and `focusRingColor` are optional. Omit them to keep the WCAG-compliant
+> defaults, or set them explicitly to keep those two details on-brand — any value you supply is used
+> as given, so check its contrast. See [Accessibility](../guides/accessibility.md).
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `buttonCornerRadius` | `string` | CSS border-radius for buttons (e.g., `'8px'`) |
+| `cardCornerRadius` | `string` | CSS border-radius for cards |
+| `headingFont` | `IFontFamily` | Font family and weights for headings |
+| `paragraphFont` | `IFontFamily` | Font family and weights for body text |
+| `primaryColor` | `string` | Primary brand color (buttons, links, highlights) |
+| `accentColor` | `string` | Secondary accent color |
+| `defaultTextColor` | `string` | Default text color |
+| `selectedTextColor` | `string` | Text color for selected/active elements |
+| `linkTextColor` | `string` | Color for links |
+| `errorColor` | `string` | Color for error states |
+| `warningColor` | `string` | Color for warning states |
+| `successColor` | `string` | Color for success states |
+| `drawerBackgroundColor` | `string` | Background color for drawer components |
+
+#### IFontFamily
+
+```typescript
+interface IFontFamily {
+  name: string;      // Google Font name (e.g., 'Inter')
+  weights: number[]; // Font weights to load (e.g., [400, 500, 700])
+}
+```
+
+> **Note:** Only Google Fonts are supported -- `name` must be a valid Google Fonts family. `Poppins` is always injected as the default font family in addition to any fonts you specify. Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`; if you run behind a CSP or proxy, allow these hosts.
+
+#### IGlobalLayout
+
+```typescript
+interface IGlobalLayout {
+  enablePersonalization: boolean;
+  personalizationText: string;
+  personalizationCardStyle: 'outlined' | 'filled';
+  allowPromoCodes: boolean;
+  inputFieldStyle: 'outlined' | 'filled';
+  enableOrderedProductSizes: boolean;
+  orderedProductSizes: string[];
+  showPoweredBy: boolean;
+  poweredByMode: 'light' | 'dark';
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enablePersonalization` | `boolean` | Enable engraving/personalization features |
+| `personalizationText` | `string` | Label text for personalization option |
+| `personalizationCardStyle` | `'outlined' \| 'filled'` | Visual style for personalization cards |
+| `allowPromoCodes` | `boolean` | Show promo code inputs in cart/checkout |
+| `inputFieldStyle` | `'outlined' \| 'filled'` | Visual style for input fields |
+| `enableOrderedProductSizes` | `boolean` | Enable a fixed display order for product/PLC size selectors (defined by `orderedProductSizes`) instead of the default ordering |
+| `orderedProductSizes` | `string[]` | Ordered list of size values controlling the sequence in which size selectors are rendered; changes trigger targeted rerenders of the affected size selectors |
+| `showPoweredBy` | `boolean` | Show "Powered by LiquidCommerce" badge |
+| `poweredByMode` | `'light' \| 'dark'` | Colour mode for the checkout: the powered-by badge, the Stripe payment form, and the California Proposition 65 warning panel |
+
+> **Note:** `showPoweredBy` is a server/plan-controlled setting and **cannot** be overridden by hosts. Any value supplied via `customTheme` (or a later config update) is stripped and the server value is restored. Only `poweredByMode` (`'light' \| 'dark'`) is host-overridable.
+
+**Example:**
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      primaryColor: '#007bff',
+      buttonCornerRadius: '8px',
+      headingFont: { name: 'Inter', weights: [400, 600, 700] }
+    },
+    layout: {
+      allowPromoCodes: true,
+      inputFieldStyle: 'outlined'
+    }
+  }
+}
+```
+
+---
+
+### Product Theme
+
+#### IProductComponent
+
+```typescript
+interface IProductComponent {
+  theme: IProductTheme;
+  layout: IProductLayout;
+}
+```
+
+#### IProductTheme
+
+```typescript
+interface IProductTheme {
+  backgroundColor: string;
+}
+```
+
+#### IProductLayout
+
+```typescript
+interface IProductLayout {
+  showImages: boolean;
+  showOnlyMainImage: boolean;
+  showTitle: boolean;
+  showDescription: boolean;
+  descriptionPosition: 'above' | 'below';
+  showQuantityCounter: boolean;
+  showOffHours: boolean;
+  quantityCounterStyle: 'outlined' | 'ghost';
+  fulfillmentDisplay: 'carousel' | 'popup';
+  enableShippingFulfillment: boolean;
+  enableOnDemandFulfillment: boolean;
+  primaryFulfillmentMethod: 'shipping' | 'onDemand';
+  showOnlyOneRetailer: boolean;
+  hideRetailerName: boolean;
+  addToCartButtonText: string;
+  addToCartButtonShowTotalPrice: boolean;
+  buyNowButtonText: string;
+  preSaleButtonText: string;
+  prioritizeEngraving: boolean;
+  noAvailabilityText: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `showImages` | `boolean` | Show product image carousel |
+| `showOnlyMainImage` | `boolean` | Show only the main product image (no carousel) |
+| `showTitle` | `boolean` | Show product title |
+| `showDescription` | `boolean` | Show product description |
+| `descriptionPosition` | `'above' \| 'below'` | Placement of the product description relative to other content |
+| `showQuantityCounter` | `boolean` | Show quantity selector |
+| `showOffHours` | `boolean` | Show off-hours messaging |
+| `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
+| `fulfillmentDisplay` | `'carousel' \| 'popup'` | How to display fulfillment/retailer options |
+| `enableShippingFulfillment` | `boolean` | Enable shipping fulfillment option |
+| `enableOnDemandFulfillment` | `boolean` | Enable on-demand delivery option |
+| `primaryFulfillmentMethod` | `'shipping' \| 'onDemand'` | Fulfillment method shown first and selected by default; falls back to the other enabled method when it has no availability |
+| `showOnlyOneRetailer` | `boolean` | Admin setting. Availability is narrowed server-side to one shipping and one on-demand retailer per product |
+| `hideRetailerName` | `boolean` | Admin setting, honoured only with `showOnlyOneRetailer`. Availability is narrowed to one retailer and one delivery method per size, and the product component and product list show only its delivery estimate (e.g. "Ships in 2-3 days") instead of the retailer choice. Cart and checkout still show the retailer |
+| `addToCartButtonText` | `string` | Custom text for add-to-cart button |
+| `addToCartButtonShowTotalPrice` | `boolean` | Show total price on add-to-cart button |
+| `buyNowButtonText` | `string` | Custom text for buy-now button |
+| `preSaleButtonText` | `string` | Custom text for pre-sale button |
+| `prioritizeEngraving` | `boolean` | Show engraving option before add-to-cart |
+| `noAvailabilityText` | `string` | Text shown when product is unavailable |
+
+**Example:**
+
+```javascript
+customTheme: {
+  product: {
+    layout: {
+      fulfillmentDisplay: 'popup',
+      addToCartButtonText: 'Add to Bag',
+      showQuantityCounter: true
+    }
+  }
+}
+```
+
+---
+
+### Cart Theme
+
+#### ICartComponent
+
+```typescript
+interface ICartComponent {
+  theme: ICartTheme;
+  layout: ICartLayout;
+}
+```
+
+#### ICartTheme
+
+```typescript
+interface ICartTheme {
+  backgroundColor: string;
+}
+```
+
+#### ICartLayout
+
+```typescript
+interface ICartLayout {
+  showShopRetailerButton?: boolean;
+  showQuantityCounter: boolean;
+  quantityCounterStyle: 'outlined' | 'ghost';
+  drawerHeaderText: string;
+  goToCheckoutButtonText: string;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `showShopRetailerButton` | `boolean` | Default `false`, including older server themes. Shows the retailer shopping button for eligible unmet minimums; requires a `cart_shop_retailer` event handler. |
+| `showQuantityCounter` | `boolean` | Show quantity counter in cart items |
+| `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
+| `drawerHeaderText` | `string` | Header text for the cart drawer |
+| `goToCheckoutButtonText` | `string` | Custom text for checkout button |
+
+**Example:**
+
+```javascript
+customTheme: {
+  cart: {
+    theme: { backgroundColor: '#f8f9fa' },
+    layout: {
+      drawerHeaderText: 'Your Bag',
+      goToCheckoutButtonText: 'Proceed to Checkout'
+    }
+  }
+}
+```
+
+---
+
+### Checkout Theme
+
+#### ICheckoutComponent
+
+```typescript
+interface ICheckoutComponent {
+  theme: ICheckoutTheme;
+  layout: ICheckoutLayout;
+}
+```
+
+#### ICheckoutTheme
+
+```typescript
+interface ICheckoutTheme {
+  backgroundColor: string;
+}
+```
+
+#### ICheckoutLayout
+
+```typescript
+interface ICheckoutLayout {
+  emailOptIn: ICheckoutMarketingOptIn;
+  smsOptIn: ICheckoutMarketingOptIn;
+  allowGiftCards: boolean;
+  requireBirthDate?: boolean;
+  legalMessage: ICheckoutLegalMessage;
+  continueShoppingUrl: string;
+  exitUrl: string;
+  thankYouButtonText: string;
+  drawerHeaderText: string;
+  placeOrderButtonText: string;
+  checkoutCompleted: ICheckoutCompleted;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `emailOptIn` | `ICheckoutMarketingOptIn` | Email marketing opt-in configuration |
+| `smsOptIn` | `ICheckoutMarketingOptIn` | SMS marketing opt-in configuration |
+| `allowGiftCards` | `boolean` | Enable gift card payment option |
+| `requireBirthDate` | `boolean` | Whether the shopper must enter a date of birth to place an order. Defaults to `true`. When `false` the form's field is optional and express checkout does not ask for it |
+| `legalMessage` | `ICheckoutLegalMessage` | Legal/terms message configuration |
+| `continueShoppingUrl` | `string` | URL for "Continue Shopping" link |
+| `exitUrl` | `string` | URL for exit/back navigation |
+| `thankYouButtonText` | `string` | Button text on order confirmation page |
+| `drawerHeaderText` | `string` | Header text for checkout drawer |
+| `placeOrderButtonText` | `string` | Custom text for place order button |
+| `checkoutCompleted` | `ICheckoutCompleted` | Order confirmation page customization |
+
+#### ICheckoutMarketingOptIn
+
+```typescript
+interface ICheckoutMarketingOptIn {
+  show: boolean;     // Show the opt-in checkbox
+  checked: boolean;  // Default checked state
+  text: string;      // Label text (supports rich HTML)
+}
+```
+
+#### ICheckoutLegalMessage
+
+```typescript
+interface ICheckoutLegalMessage {
+  show: boolean;  // Show the legal message
+  text: string;   // Message content (supports rich HTML)
+}
+```
+
+#### ICheckoutCompleted
+
+```typescript
+interface ICheckoutCompleted {
+  customLogo: string;        // URL to custom logo image
+  customText: string | null; // Custom confirmation text
+}
+```
+
+**Example:**
+
+```javascript
+customTheme: {
+  checkout: {
+    layout: {
+      placeOrderButtonText: 'Complete Purchase',
+      emailOptIn: { show: true, checked: false, text: 'Subscribe to our newsletter' },
+      legalMessage: { show: true, text: 'By placing this order, you agree to our <a href="/terms">Terms</a>.' }
+    }
+  }
+}
+```
+
+---
+
+### Address Theme
+
+#### IAddressComponent
+
+```typescript
+interface IAddressComponent {
+  theme: IAddressTheme;
+}
+```
+
+#### IAddressTheme
+
+```typescript
+interface IAddressTheme {
+  backgroundColor: string;
+}
+```
+
+---
+
+### Product List Theme
+
+#### IProductListComponent
+
+```typescript
+interface IProductListComponent {
+  theme: IProductListTheme;
+  layout: IProductListLayout;
+}
+```
+
+Product list theme updates use a special structure where lists are keyed by slug:
+
+```typescript
+interface UpdateProductListComponent {
+  theme?: { backgroundColor?: string };
+  layout?: {
+    lists?: Record<string, DeepPartial<IPLCList>>;
+  };
+}
+```
+
+**Example:**
+
+```javascript
+customTheme: {
+  productList: {
+    theme: { backgroundColor: '#ffffff' },
+    layout: {
+      lists: {
+        'best-sellers': {
+          productCard: {
+            style: 'card',
+            showPrice: true,
+            enablePreCart: true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Promo Ticker Configuration
+
+### IPromoTicker
+
+```typescript
+interface IPromoTicker {
+  promoCode: string;    // Promo code to auto-apply
+  text: string[];       // Array of messages to rotate
+  separator: string;    // Separator between messages (e.g., '|')
+  activeFrom: string;   // Start date in ISO 8601 UTC format
+  activeUntil: string;  // End date in ISO 8601 UTC format
+}
+```
+
+**Example:**
+
+```javascript
+promoTicker: [
+  {
+    promoCode: 'SUMMER20',
+    text: ['20% Off Summer Sale', 'Free Shipping on $50+'],
+    separator: '|',
+    activeFrom: '2026-06-01T00:00:00Z',
+    activeUntil: '2026-08-31T23:59:59Z'
+  }
+]
+```
+
+---
+
+## Checkout Configuration
+
+### ILiquidCommerceElementsCheckoutConfig
+
+```typescript
+interface ILiquidCommerceElementsCheckoutConfig {
+  pageUrl?: string;  // URL with {token} placeholder
+}
+```
+
+When `pageUrl` is set, the cart's checkout button redirects to this URL instead of opening the checkout drawer. Use `{token}` as a placeholder for the checkout session token.
+
+**Example:**
+
+```javascript
+checkout: {
+  pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
+}
+```
+
+---
+
+## Proxy Configuration
+
+### IElementsProxyConfig
+
+```typescript
+interface IElementsProxyConfig {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+```
+
+Route SDK API requests through your own server to avoid ad blockers.
+
+See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation details.
+
+---
+
+## GTM Configuration
+
+### IElementsGTMConfig
+
+```typescript
+interface IElementsGTMConfig {
+  gatewayUrl?: string;
+}
+```
+
+If your site loads its own GTM container through Google tag gateway for advertisers, set `gatewayUrl` to that first-party path (e.g. `'https://www.yoursite.com/metrics/'` or `'/metrics/'`) so the SDK recognizes the container before GTM has booted it. It affects detection only: your container receives SDK events through `dataLayer` with or without it. Declarative equivalent: `data-gtm-gateway-url`. An empty or non-string value drops the whole `gtm` config with a console warning.
+
+See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway).
+
+---
+
+## Development Configuration
+
+### ILiquidCommerceElementsDevelopmentConfig
+
+```typescript
+interface ILiquidCommerceElementsDevelopmentConfig {
+  customApiUrl?: string;
+  openShadowDom?: boolean;
+  mockMode?: boolean;
+  enableExpressCheckout?: boolean;
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
+| `openShadowDom` | `boolean` | Use an OPEN (inspectable) Shadow DOM instead of the default closed mode, for debugging. Shadow DOM is always attached; forced off in production (default: `false`) |
+| `mockMode` | `boolean` | Enable mock mode to receive mock data from the API; sends an `X-Liquid-Api-Mock-Mode` header with all requests (default: `false`) |
+| `enableExpressCheckout` | `boolean` | Show the Apple Pay / Google Pay express checkout and the checkout's delivery-method switch (same-day vs shipping) — the express block and delivery-method section in the checkout element, and `injectExpressCheckoutElement()` / `injectExpressCheckout()`, which otherwise render nothing and resolve to `null`. Honoured in every environment, production included (default: `false`) |
+
+> **Temporary:** this flag exists only while express checkout and the delivery-method switch are being verified. Once they are confirmed, the flag will be removed and both will always be on.
+
+> To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.
+
+---
+
+## See Also
+
+- [Client API](./client.md) - Client initialization and usage
+- [TypeScript Types](./typescript-types.md) - Complete type reference
+- [Theming Guide](../guides/theming.md) - Theming best practices