@liquidcommerce/elements-sdk 2.6.0-beta.11 → 2.6.0-beta.111

package/docs/v1/examples/advanced-patterns.md

@@ -0,0 +1,199 @@
+# Advanced Patterns
+
+A collection of common production patterns using events, programmatic injection, address prefill, and checkout redirects.
+
+## 1) Dynamic Product Injection
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+const products = ['00619947000020', '08504405135', '08068660001'];
+
+await client.injectProductElement(
+  products.map((identifier, index) => ({
+    containerId: `product-${index}`,
+    identifier
+  }))
+);
+```
+
+## 2) Pre-Set Address (Skip Prompt)
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main St',
+    two: 'Apt 4',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'
+  },
+  {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+);
+```
+
+## 3) Custom Cart Button
+
+```html
+<button data-lce-cart-toggle-button>
+  View Cart
+</button>
+```
+
+## 4) Analytics With Events
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, name, priceInfo } = event.detail.data;
+  gtag('event', 'view_item', {
+    items: [{ item_id: identifier, item_name: name, price: (priceInfo?.minimum ?? 0) / 100 }]
+  });
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber, orderTotal } = event.detail.data;
+  gtag('event', 'purchase', {
+    transaction_id: orderNumber,
+    value: orderTotal / 100,
+    currency: 'USD'
+  });
+});
+```
+
+## 5) Redirect Checkout to Your Page
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  checkout: {
+    pageUrl: 'https://yoursite.com/checkout?lce_checkout={token}'
+  }
+});
+```
+
+## 6) Debugging Helpers
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  debugMode: 'console',
+  development: {
+    openShadowDom: true
+  }
+});
+```
+
+## 7) Cleanup on SPA Navigation
+
+```javascript
+let client = null;
+
+async function mountElements() {
+  client = await Elements('YOUR_API_KEY', { env: 'production' });
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '00619947000020' }
+  ]);
+}
+
+function unmountElements() {
+  if (client) {
+    client.destroy();
+    client = null;
+  }
+}
+
+// React example
+useEffect(() => {
+  mountElements();
+  return () => unmountElements();
+}, []);
+```
+
+## 8) Checkout-Only Page
+
+For a dedicated checkout page, use the tree-shaken checkout build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+
+await client.injectCheckout({
+  containerId: 'checkout',
+  checkoutId: new URLSearchParams(window.location.search).get('lce_checkout'),
+  hideHeader: false
+});
+```
+
+## 9) Promo Ticker with Time Windows
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  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'
+    },
+    {
+      promoCode: 'FALL10',
+      text: ['10% Off Fall Collection'],
+      separator: '|',
+      activeFrom: '2026-09-01T00:00:00Z',
+      activeUntil: '2026-11-30T23:59:59Z'
+    }
+  ]
+});
+```
+
+## 10) Product List with Filters and Search
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectProductListSearch({
+  containerId: 'search-box',
+  slug: 'whiskey-collection'
+});
+
+await client.injectProductListFilters({
+  containerId: 'sidebar-filters',
+  slug: 'whiskey-collection',
+  filters: ['price', 'brands', 'sizes', 'fulfillment']
+});
+
+await client.injectProductList({
+  containerId: 'product-grid',
+  slug: 'whiskey-collection',
+  rows: 4,
+  columns: 3,
+  productUrl: '/products/{grouping}'
+});
+```
+
+## 11) Check Product Availability by State
+
+```javascript
+const availability = await window.LiquidCommerce.elements.actions.product
+  .getProductAvailabilityByState(['00619947000020', '08504405135'], 'CA');
+
+console.log('Availability in CA:', availability);
+```
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Product Component](../guides/product-component.md)
+- [Checkout Component](../guides/checkout-component.md)
+- [Client API](../api/client.md)

package/docs/v1/examples/checkout-flow.md

@@ -0,0 +1,90 @@
+# Complete Checkout Flow
+
+A two-page setup: a product page that adds to cart and redirects to a dedicated checkout page.
+
+## What You'll Build
+
+- Product page with cart and checkout redirect
+- Dedicated checkout page that loads by URL parameter
+
+## Page 1: Product Page
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>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"
+    data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/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>
+```
+
+When users click checkout, the cart redirects to your hosted checkout page with a `lce_checkout` ID in the URL.
+
+## Page 2: Checkout Page
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Checkout</title>
+
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-checkout-param="lce_checkout"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <div data-lce-checkout></div>
+</body>
+</html>
+```
+
+## Optional: Skip Cart and Go Directly to Checkout
+
+```javascript
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);
+```
+
+## Related Docs
+
+- [Checkout Component](../guides/checkout-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Client API](../api/client.md)

package/docs/v1/examples/custom-theming.md

@@ -0,0 +1,63 @@
+# Custom Theming
+
+Apply a branded theme across product, cart, and checkout components using `customTheme`.
+
+## Example (NPM)
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#1f4f91',
+        accentColor: '#f39c12',
+        defaultTextColor: '#1c1c1c',
+        buttonCornerRadius: '10px',
+        cardCornerRadius: '14px',
+        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',
+        showOnlyMainImage: true
+      }
+    },
+    cart: {
+      layout: {
+        drawerHeaderText: 'Your Cart',
+        goToCheckoutButtonText: 'Checkout Now'
+      }
+    },
+    checkout: {
+      layout: {
+        placeOrderButtonText: 'Place Order',
+        exitUrl: 'https://yoursite.com/shop'
+      }
+    }
+  }
+});
+```
+
+> If you use custom fonts, make sure the font is available on the page.
+
+## Related Docs
+
+- [Theming Guide](../guides/theming.md)
+- [Configuration Reference](../api/configuration.md)

package/docs/v1/examples/multi-product-page.md

@@ -0,0 +1,90 @@
+# Multi-Product Page
+
+Show multiple products on a single page using declarative attributes or programmatic injection.
+
+## Option A: Declarative (Data Attributes)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Multi-Product Page</title>
+
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product-1"
+    data-product-1="00619947000020"
+    data-container-2="product-2"
+    data-product-2="08504405135"
+    data-container-3="product-3"
+    data-product-3="08068660001"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+
+  <style>
+    body { font-family: Arial, sans-serif; margin: 0; padding: 24px; background: #f7f7f7; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 20px; }
+    .card { background: #fff; border-radius: 10px; padding: 16px; min-height: 520px; }
+  </style>
+</head>
+<body>
+  <h1>Featured Products</h1>
+  <div class="grid">
+    <div id="product-1" class="card"></div>
+    <div id="product-2" class="card"></div>
+    <div id="product-3" class="card"></div>
+  </div>
+</body>
+</html>
+```
+
+## Option B: JSON Configuration
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<script data-liquid-commerce-elements-products type="application/json">
+[
+  { "containerId": "product-1", "identifier": "00619947000020" },
+  { "containerId": "product-2", "identifier": "08504405135" },
+  { "containerId": "product-3", "identifier": "08068660001" }
+]
+</script>
+```
+
+## Option C: Programmatic Injection (NPM)
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' },
+  { containerId: 'product-3', identifier: '08068660001' }
+]);
+```
+
+## Tips
+
+- Give each container a `min-height` to reduce layout shift while data loads.
+- Add a cart button once per page (see [Cart Component](../guides/cart-component.md)).
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Quick Start](../getting-started/quick-start.md)

package/docs/v1/examples/simple-product-page.md

@@ -0,0 +1,89 @@
+# Simple Product Page
+
+A minimal, production-ready product page using the CDN build with a single Product component and the default cart drawer.
+
+## What You'll Build
+
+- One product component
+- Optional cart button with item count
+- Default cart and checkout flow
+
+## Prerequisites
+
+- LiquidCommerce API key
+- One product identifier (UPC or grouping ID)
+
+## HTML (CDN)
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Simple 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://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      margin: 0;
+      padding: 0;
+      background: #f7f7f7;
+    }
+    header {
+      background: #fff;
+      padding: 16px 24px;
+      box-shadow: 0 2px 6px rgba(0,0,0,0.08);
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    main {
+      max-width: 1100px;
+      margin: 24px auto;
+      padding: 0 24px;
+    }
+    #product {
+      background: #fff;
+      border-radius: 10px;
+      padding: 20px;
+      min-height: 600px;
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Premium Spirits</h1>
+    <div id="header-cart"></div>
+  </header>
+
+  <main>
+    <div id="product"></div>
+  </main>
+</body>
+</html>
+```
+
+## What to Tweak Next
+
+- Change the product identifier: `data-product-1="YOUR_PRODUCT_ID"`
+- Add a second product (see [Multi-Product Page](./multi-product-page.md))
+- Customize styling via theming (see [Theming Guide](../guides/theming.md))
+
+## Related Docs
+
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Quick Start](../getting-started/quick-start.md)