@liquidcommerce/elements-sdk 2.6.0-beta.6 → 2.6.0-beta.61

package/docs/v1/api/injection-methods.md

@@ -0,0 +1,247 @@
+# Injection Methods API
+
+Methods for injecting SDK components into your page.
+
+## injectProductElement()
+
+Inject one or more product displays.
+
+### Signature
+
+```typescript
+injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductElement {
+  containerId: string;  // ID of container element
+  identifier: string;   // Product Identifier
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' }
+]);
+```
+
+### Returns
+
+Array of injected component objects.
+
+---
+
+## injectAddressElement()
+
+Inject standalone address component.
+
+### Signature
+
+```typescript
+injectAddressElement(
+  containerId: string,
+  options?: IAddressOptions
+): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectAddressElement('address-container', {
+  onAddressSet: (address) => {
+    console.log('Address set:', address);
+  }
+});
+```
+
+---
+
+## injectCartElement()
+
+Inject standalone cart (rarely needed - cart drawer is automatic).
+
+### Signature
+
+```typescript
+injectCartElement(containerId: string): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectCartElement('cart-container');
+```
+
+---
+
+## injectCheckoutElement()
+
+Inject hosted checkout page.
+
+### Signature
+
+```typescript
+injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>
+```
+
+### Parameters
+
+```typescript
+interface IInjectCheckoutParams {
+  containerId: string;
+  checkoutId?: string;   // Optional checkout token to load
+  hideHeader?: boolean;  // Hide checkout header
+}
+```
+
+### Example
+
+```javascript
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'cart_abc123',
+  hideHeader: false
+});
+```
+
+---
+
+## injectProductList()
+
+Inject product catalog/listing.
+
+### Signature
+
+```typescript
+injectProductList(params: IInjectProductListParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListParams {
+  containerId: string;
+  rows?: number;             // Default: 3
+  columns?: number;          // Default: 4
+  filters?: ProductListFilterType[];
+  productUrl?: string;       // URL pattern with {identifier}
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  rows: 4,
+  columns: 3,
+  filters: ['price', 'brand', 'category'],
+  productUrl: '/product/{identifier}'
+});
+```
+
+---
+
+## injectProductListSearch()
+
+Inject product search box.
+
+### Signature
+
+```typescript
+injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListSearchParams {
+  containerId: string;
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListSearch({
+  containerId: 'search-box'
+});
+```
+
+---
+
+## injectProductListFilters()
+
+Inject product filter panel.
+
+### Signature
+
+```typescript
+injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListFiltersParams {
+  containerId: string;
+  filters: ProductListFilterType[];
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListFilters({
+  containerId: 'filters',
+  filters: ['price', 'brand', 'fulfillment']
+});
+```
+
+---
+
+## Component Management
+
+### getInjectedComponents()
+
+Retrieve all injected components.
+
+```typescript
+getInjectedComponents(): Map<string, IInjectedComponent>
+```
+
+```javascript
+const components = client.getInjectedComponents();
+
+// Get specific component
+const product = components.get('product-1');
+
+// Rerender component
+product.rerender();
+
+// Get container element
+const container = product.getElement();
+
+// Get component type
+const type = product.getType(); // 'product'
+```
+
+### IInjectedComponent Interface
+
+```typescript
+interface IInjectedComponent {
+  getType(): ComponentType;
+  getElement(): HTMLElement;
+  rerender(): void;
+}
+```
+
+## See Also
+
+- [Client API](./client.md)
+- [Component Guides](../guides/)

package/docs/v1/api/typescript-types.md

@@ -0,0 +1 @@
+to be created...

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,96 @@
+# 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
+  }
+});
+```
+
+## 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://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>
+```
+
+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://assets-elements.liquidcommerce.us/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)