@liquidcommerce/elements-sdk 2.6.0-beta.7 → 2.6.0-beta.70

package/docs/v1/api/ui-helpers.md

@@ -0,0 +1,200 @@
+# UI Helpers API
+
+UI helper methods for creating cart buttons and displaying cart information.
+
+## ui.cartButton()
+
+Create a cart button in a specific container.
+
+### Signature
+
+```typescript
+cartButton(containerId: string, showItemsCount?: boolean): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of container element |
+| `showItemsCount` | boolean | No | Show item count badge (default: false) |
+
+### Example
+
+```javascript
+// Simple cart button
+window.LiquidCommerce.elements.ui.cartButton('header-cart');
+
+// Cart button with item count badge
+window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
+```
+
+---
+
+## ui.floatingCartButton()
+
+Create a floating cart button (bottom-right corner).
+
+### Signature
+
+```typescript
+floatingCartButton(showItemsCount?: boolean): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `showItemsCount` | boolean | No | Show item count badge (default: false) |
+
+### Example
+
+```javascript
+// Floating button without badge
+window.LiquidCommerce.elements.ui.floatingCartButton();
+
+// Floating button with badge
+window.LiquidCommerce.elements.ui.floatingCartButton(true);
+```
+
+---
+
+## ui.cartSubtotal()
+
+Display cart subtotal in an element.
+
+### Signature
+
+```typescript
+cartSubtotal(elementId: string): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `elementId` | string | Yes | ID of element to update |
+
+### Example
+
+```html
+<div>Total: <span id="cart-total"></span></div>
+```
+
+```javascript
+window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
+// Element now shows: "$49.99"
+// Updates automatically when cart changes
+```
+
+---
+
+## ui.cartItemsCount()
+
+Display number of items in cart.
+
+### Signature
+
+```typescript
+cartItemsCount(elementId: string, options?: { hideZero: boolean }): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `elementId` | string | Yes | ID of element to update |
+| `options.hideZero` | boolean | No | Hide when cart is empty (default: true) |
+
+### Example
+
+```html
+<div>Cart (<span id="items-count"></span>)</div>
+```
+
+```javascript
+// Hide when cart is empty
+window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: true });
+
+// Always show count (even "0")
+window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: false });
+```
+
+## Use Cases
+
+### Header Cart Button
+
+```html
+<header>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/products">Products</a>
+    <div id="cart-btn"></div>
+  </nav>
+</header>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartButton('cart-btn', true);
+});
+</script>
+```
+
+### Cart Summary Widget
+
+```html
+<aside class="cart-summary">
+  <h3>Your Cart</h3>
+  <p>Items: <span id="item-count"></span></p>
+  <p>Total: <span id="cart-total"></span></p>
+</aside>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartItemsCount('item-count');
+  window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
+});
+</script>
+```
+
+### Floating Cart for Mobile
+
+```javascript
+// Show floating button only on mobile
+if (window.innerWidth < 768) {
+  window.LiquidCommerce.elements.ui.floatingCartButton(true);
+}
+```
+
+## Styling
+
+Cart buttons and UI elements can be styled with CSS:
+
+```css
+/* Cart button container */
+.lce-cart-desktop-button-container {
+  /* Your styles */
+}
+
+/* Cart items count */
+.lce-cart-items-count {
+  font-weight: bold;
+  color: #007bff;
+}
+
+/* When cart is empty */
+.lce-cart-items-count.no-items {
+  opacity: 0.5;
+}
+
+/* Cart subtotal */
+.lce-cart-subtotal {
+  font-size: 1.2em;
+  font-weight: bold;
+}
+```
+
+## See Also
+
+- [Cart Component Guide](../guides/cart-component.md)
+- [Cart Actions](./actions/cart-actions.md)

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

@@ -0,0 +1,198 @@
+# 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'
+  },
+  {
+    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, price } = event.detail.data;
+  gtag('event', 'view_item', {
+    items: [{ item_id: identifier, item_name: name, price: price / 100 }]
+  });
+});
+
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderId, total } = event.detail.data;
+  gtag('event', 'purchase', {
+    transaction_id: orderId,
+    value: total / 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/{identifier}'
+});
+```
+
+## 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,91 @@
+# 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-container="checkout"
+    data-checkout-param="lce_checkout"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <div id="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)