@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/v1/guides/theming.md

@@ -0,0 +1,216 @@
+# Theming Guide
+
+Customize the appearance of Elements SDK components to match your brand.
+
+## Overview
+
+The SDK provides extensive theming capabilities through the `customTheme` configuration option. Themes are structured hierarchically:
+
+- **Global**: Colors, fonts, and styles that apply to all components
+- **Component-specific**: Overrides for individual components
+
+## Global Theme Configuration
+
+### Colors
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        accentColor: '#28a745',
+        defaultTextColor: '#333333',
+        selectedTextColor: '#007bff',
+        linkTextColor: '#0056b3',
+        errorColor: '#dc3545',
+        warningColor: '#ffc107',
+        successColor: '#28a745',
+        drawerBackgroundColor: '#ffffff'
+      }
+    }
+  }
+});
+```
+
+### Typography
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      headingFont: {
+        name: 'Poppins',
+        weights: [400, 600, 700]
+      },
+      paragraphFont: {
+        name: 'Inter',
+        weights: [400, 500]
+      }
+    }
+  }
+}
+```
+
+### Border Radius
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      buttonCornerRadius: '8px',
+      cardCornerRadius: '12px'
+    }
+  }
+}
+```
+
+### Global Layout Options
+
+```javascript
+customTheme: {
+  global: {
+    layout: {
+      enablePersonalization: true,
+      personalizationText: 'Add Engraving',
+      personalizationCardStyle: 'outlined',  // or 'filled'
+      allowPromoCodes: true,
+      inputFieldStyle: 'outlined',  // or 'filled'
+      showPoweredBy: true,
+      poweredByMode: 'light'  // or 'dark'
+    }
+  }
+}
+```
+
+## Component Themes
+
+### Product Component
+
+```javascript
+customTheme: {
+  product: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      showImages: true,
+      showOnlyMainImage: false,
+      showTitle: true,
+      showDescription: true,
+      showQuantityCounter: true,
+      quantityCounterStyle: 'outlined',
+      fulfillmentDisplay: 'carousel',
+      enableShippingFulfillment: true,
+      enableOnDemandFulfillment: true,
+      addToCartButtonText: 'Add to Cart',
+      addToCartButtonShowTotalPrice: true,
+      buyNowButtonText: 'Buy Now',
+      prioritizeEngraving: false,
+      noAvailabilityText: 'Not available in your area'
+    }
+  }
+}
+```
+
+### Cart Component
+
+```javascript
+customTheme: {
+  cart: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      showQuantityCounter: true,
+      quantityCounterStyle: 'outlined',
+      drawerHeaderText: 'Your Shopping Cart',
+      goToCheckoutButtonText: 'Proceed to Checkout'
+    }
+  }
+}
+```
+
+### Checkout Component
+
+```javascript
+customTheme: {
+  checkout: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      emailOptIn: {
+        show: true,
+        checked: false,
+        text: 'Subscribe to our newsletter for updates and offers.'
+      },
+      smsOptIn: {
+        show: true,
+        checked: false,
+        text: 'Receive SMS updates about your order and exclusive deals.'
+      },
+      allowGiftCards: true,
+      legalMessage: 'By placing your order, you agree to our Terms of Service and Privacy Policy.',
+      continueShoppingUrl: 'https://yoursite.com/shop',
+      exitUrl: 'https://yoursite.com',
+      thankYouButtonText: 'Continue Shopping',
+      drawerHeaderText: 'Checkout',
+      placeOrderButtonText: 'Place Order',
+      checkoutCompleted: {
+          customLogo: 'https://yoursite.com/logo.png',
+          customText: 'Thank you for your purchase! Your order has been received.'
+        }
+      }
+    }
+  }
+}
+```
+
+## Complete Example
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        accentColor: '#28a745',
+        buttonCornerRadius: '8px',
+        cardCornerRadius: '12px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600, 700]
+        },
+        paragraphFont: {
+          name: 'Inter',
+          weights: [400, 500]
+        }
+      },
+      layout: {
+        allowPromoCodes: true,
+        inputFieldStyle: 'outlined',
+        showPoweredBy: false
+      }
+    },
+    product: {
+      layout: {
+        addToCartButtonText: 'Add to Bag',
+        fulfillmentDisplay: 'popup'
+      }
+    },
+    cart: {
+      layout: {
+        checkoutButtonText: 'Checkout Now'
+      }
+    }
+  }
+});
+```
+
+## See Also
+
+- [Configuration Reference](../api/configuration.md)
+- [Component Guides](../guides/)

package/docs/v1/integration/angular.md

@@ -0,0 +1,39 @@
+# Angular Integration
+
+Initialize Elements in a browser-only lifecycle hook and inject the component after the view mounts.
+
+## Install
+
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+## Standalone Component Example
+
+```ts
+import { AfterViewInit, Component } from '@angular/core';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+@Component({
+  selector: 'app-product-page',
+  standalone: true,
+  template: '<div id="product"></div>'
+})
+export class ProductPageComponent implements AfterViewInit {
+  async ngAfterViewInit() {
+    const client = await Elements('YOUR_API_KEY', { env: 'production' });
+    await client.injectProductElement([
+      { containerId: 'product', identifier: '00619947000020' }
+    ]);
+  }
+}
+```
+
+## Notes
+
+- Initialize only in the browser (not during server rendering).
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/laravel.md

@@ -0,0 +1,41 @@
+# Laravel Integration
+
+Use the CDN build in a Blade view for a quick server-rendered setup.
+
+## Blade Template (CDN)
+
+```blade
+<!-- resources/views/product.blade.php -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Product</title>
+
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="{{ env('LCE_API_KEY') }}"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+</head>
+<body>
+  <div id="product"></div>
+</body>
+</html>
+```
+
+## Notes
+
+- Keep your API key in `.env` and reference it in Blade.
+- You can add a cart button with `data-cart-badge-button` on the script tag.
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)

package/docs/v1/integration/nextjs.md

@@ -0,0 +1,60 @@
+# Next.js Integration
+
+Use a client component (App Router) or `useEffect` in a client-only page (Pages Router). Initialize the SDK on the client.
+
+## App Router (Client Component)
+
+```jsx
+'use client';
+
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: { baseUrl: '/api/elements-proxy' }
+      });
+
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+
+  return <div id="product"></div>;
+}
+```
+
+## Pages Router
+
+```jsx
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', { env: 'production' });
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+
+  return <div id="product"></div>;
+}
+```
+
+## Notes
+
+- Do not initialize server-side (Window/Document required).
+- For ad blocker mitigation, configure the proxy (see [Proxy Setup](./proxy-setup.md)).
+
+## Related Docs
+
+- [Proxy Setup](./proxy-setup.md)
+- [Product Component](../guides/product-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/proxy-setup.md

@@ -0,0 +1,89 @@
+# Proxy Setup
+
+If ad blockers or network policies block the SDK assets, use a proxy on your domain. The SDK supports a `proxy.baseUrl` that routes API calls through your server.
+
+## 1) Configure the SDK
+
+### NPM
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  proxy: {
+    baseUrl: 'https://yoursite.com/api/elements-proxy'
+  }
+});
+```
+
+### CDN (Next.js example)
+
+```jsx
+'use client';
+
+import { useEffect } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+export default function ProductPage() {
+  useEffect(() => {
+    (async () => {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: { baseUrl: '/api/elements-proxy' }
+      });
+
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    })();
+  }, []);
+
+  return <div id="product"></div>;
+}
+```
+
+## 2) Create the Proxy Endpoint
+
+Your endpoint should forward requests to the LiquidCommerce Elements API, preserving method, headers, and body.
+
+### Minimal Express Example
+
+```javascript
+import express from 'express';
+import fetch from 'node-fetch';
+
+const app = express();
+app.use(express.json());
+
+app.all('/api/elements-proxy/*', async (req, res) => {
+  const targetPath = req.params[0];
+  const targetUrl = `https://api.liquidcommerce.us/${targetPath}`;
+
+  const response = await fetch(targetUrl, {
+    method: req.method,
+    headers: {
+      ...req.headers,
+      host: 'api.liquidcommerce.us'
+    },
+    body: ['GET', 'HEAD'].includes(req.method) ? undefined : JSON.stringify(req.body)
+  });
+
+  const data = await response.text();
+  res.status(response.status).send(data);
+});
+
+app.listen(3000, () => {
+  console.log('Proxy listening on port 3000');
+});
+```
+
+## Notes
+
+- Keep your API key server-side whenever possible.
+- Ensure CORS allows your storefront domain to call the proxy.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/react.md

@@ -0,0 +1,64 @@
+# React Integration
+
+Use the NPM package and initialize the SDK client on the client side. Then inject components after mount.
+
+## Install
+
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+## Basic Product Page
+
+```jsx
+import { useEffect, useState } from 'react';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+export default function ProductPage() {
+  const [client, setClient] = useState(null);
+
+  useEffect(() => {
+    let mounted = true;
+    (async () => {
+      const instance = await Elements('YOUR_API_KEY', { env: 'production' });
+      if (mounted) setClient(instance);
+    })();
+    return () => { mounted = false; };
+  }, []);
+
+  useEffect(() => {
+    if (!client) return;
+    client.injectProductElement([
+      { containerId: 'product', identifier: '00619947000020' }
+    ]);
+  }, [client]);
+
+  return <div id="product"></div>;
+}
+```
+
+## Cart Button
+
+```jsx
+import { useEffect } from 'react';
+
+export default function CartButton() {
+  useEffect(() => {
+    if (!window.elements) return;
+    window.elements.ui.cartButton('header-cart', true);
+  }, []);
+
+  return <div id="header-cart"></div>;
+}
+```
+
+## Notes
+
+- Initialize only on the client; the SDK uses browser APIs.
+- For multiple products, call `injectProductElement` with multiple entries.
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/vanilla-js.md

@@ -0,0 +1,84 @@
+# Vanilla JavaScript Integration
+
+Use the CDN build for the fastest setup, or use NPM if you have a build step.
+
+## Option A: CDN (Declarative)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Vanilla JS Product Page</title>
+
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    data-cart-badge-button="header-cart"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+</head>
+<body>
+  <header>
+    <h1>Premium Spirits</h1>
+    <div id="header-cart"></div>
+  </header>
+
+  <main>
+    <div id="product"></div>
+  </main>
+</body>
+</html>
+```
+
+## Option B: CDN (Programmatic)
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.elements;
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+});
+</script>
+
+<div id="product"></div>
+```
+
+## Option C: NPM
+
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Client API](../api/client.md)

package/docs/v1/integration/vue.md

@@ -0,0 +1,34 @@
+# Vue Integration
+
+Use the NPM package and initialize Elements in `onMounted`.
+
+## Install
+
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+## Vue 3 (Single File Component)
+
+```vue
+<template>
+  <div id="product"></div>
+</template>
+
+<script setup>
+import { onMounted } from 'vue';
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+onMounted(async () => {
+  const client = await Elements('YOUR_API_KEY', { env: 'production' });
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+});
+</script>
+```
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Client API](../api/client.md)

package/docs/v1/reference/browser-support.md

@@ -0,0 +1,44 @@
+# Browser Support
+
+The Elements SDK requires modern browser features (Web Components + Shadow DOM). If you need to support older browsers, include polyfills.
+
+## Minimum Versions
+
+- Chrome 66+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+
+## Required Features
+
+- Custom Elements (Web Components)
+- Shadow DOM
+- ES2018 JavaScript
+- Fetch API
+- LocalStorage
+
+## Server-Side Rendering (SSR)
+
+The SDK is browser-only, but it is safe to import in SSR frameworks (Next.js, Remix, Nuxt).
+In non-browser environments, initialization is skipped. If you call the SDK on the server,
+it returns `null` and logs a warning instead of throwing.
+
+Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
+to render components.
+
+## Polyfills (Legacy Browsers)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Notes
+
+- Always load the SDK script with `defer` to avoid blocking page render.
+- If you see Web Components errors in the console, add the polyfill before the SDK.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Troubleshooting](./troubleshooting.md)