@liquidcommerce/elements-sdk 2.6.0-beta.37 → 2.6.0-beta.39

package/docs/{CONFIGURATION.md → configuration.md}

@@ -11,7 +11,10 @@ const client = await Elements('YOUR_API_KEY', {
   isBuilder: false,
   customTheme: {},
   proxy: {},
-  promoTicker: []
+  promoTicker: [],
+  checkout: {
+    pageUrl: 'https://yoursite.com/checkout?id={id}'  // Optional: hosted checkout
+  }
 });
 ```
 
@@ -83,7 +86,7 @@ isBuilder: true  // Enables builder.* methods
 **Type:** `object`  
 **Default:** `{}`
 
-Custom theme configuration. See [`THEMING.md`](./THEMING.md) for complete reference.
+Custom theme configuration. See [`theming.md`](./theming.md) for complete reference.
 
 ```javascript
 customTheme: {
@@ -188,7 +191,7 @@ headers: {
 }
 ```
 
-See [`PROXY.md`](./PROXY.md) for implementation guide.
+See [`proxy.md`](./proxy.md) for implementation guide.
 
 ### `promoTicker`
 
@@ -262,6 +265,33 @@ activeUntil: '2025-12-31T23:59:59Z'
 
 **Note:** Only active promotions are displayed.
 
+### `checkout`
+
+**Type:** `object`
+**Default:** `undefined`
+
+Configuration for hosted checkout (external checkout page).
+
+```javascript
+checkout: {
+  pageUrl: 'https://yoursite.com/checkout?id={id}'
+}
+```
+
+**Properties:**
+
+#### `checkout.pageUrl`
+
+**Type:** `string` (required)
+
+URL of your dedicated checkout page. The `{id}` placeholder is replaced with the checkout token.
+
+```javascript
+pageUrl: 'https://yoursite.com/checkout?id={id}'
+```
+
+When set, the "Go to Checkout" button in the cart redirects to this URL instead of opening the checkout drawer.
+
 ## Auto-Initialization Configuration
 
 When using auto-initialization, configure via `data-` attributes on the script tag.
@@ -270,6 +300,8 @@ When using auto-initialization, configure via `data-` attributes on the script t
 
 ```html
 <script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
@@ -376,6 +408,28 @@ data-cart-badge-button=""                   <!-- Empty value = floating button w
 - `replace:` - Replace the target element
 - `inside:` - Place inside the target element (default)
 
+#### `data-cart-mobile-button`
+
+**Type:** `string`
+
+Mobile-specific cart button (no badge). Same syntax as `data-cart-button` but only shown on mobile devices.
+
+```html
+data-cart-mobile-button="below:.mobile-header"
+data-cart-mobile-button="inside:.mobile-nav"
+```
+
+#### `data-cart-mobile-badge-button`
+
+**Type:** `string`
+
+Mobile-specific cart button with item count badge. Same syntax as `data-cart-badge-button` but only shown on mobile devices.
+
+```html
+data-cart-mobile-badge-button="below:.mobile-header"
+data-cart-mobile-badge-button="inside:.mobile-nav"
+```
+
 #### `data-cart-button-hidden`
 
 **Type:** flag (no value)
@@ -392,7 +446,9 @@ data-cart-button-hidden
 
 **Simple cart button (no badge):**
 ```html
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-button="header-cart"
@@ -402,7 +458,9 @@ data-cart-button-hidden
 
 **Cart button with item count badge:**
 ```html
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-badge-button="header-cart"
@@ -413,7 +471,9 @@ data-cart-button-hidden
 **Using position-prefixed selectors:**
 ```html
 <!-- Place inside the target element (default) -->
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-badge-button="inside:.header .nav-links"
@@ -421,7 +481,9 @@ data-cart-button-hidden
 </script>
 
 <!-- Place above the target element -->
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-button="above:.header .logo"
@@ -429,7 +491,9 @@ data-cart-button-hidden
 </script>
 
 <!-- Place below the target element -->
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-badge-button="below:#main-navigation"
@@ -437,7 +501,9 @@ data-cart-button-hidden
 </script>
 
 <!-- Replace the target element -->
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-button="replace:.old-cart-button"
@@ -447,7 +513,9 @@ data-cart-button-hidden
 
 **No cart button:**
 ```html
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   data-cart-button-hidden
@@ -457,7 +525,9 @@ data-cart-button-hidden
 
 **Default behavior (floating cart button with badge):**
 ```html
-<script 
+<script
+  defer
+  type="text/javascript"
   data-liquid-commerce-elements
   data-token="your-api-key"
   src="elements.js">
@@ -517,11 +587,9 @@ data-product-2="00832889005513"
 
 ```html
 <div data-liquid-commerce-elements-products-list
-     data-card="standard"
      data-rows="3"
      data-columns="4"
-     data-card-fill
-     data-filters="personalization,pre-order,delivery-options"
+     data-filters="engraving,presale,fulfillment,price,brands"
      data-product-url="/product/{upc}">
 </div>
 ```
@@ -534,23 +602,12 @@ data-product-2="00832889005513"
 
 Enables product list on this div element.
 
-##### `data-card`
-
-**Type:** `'standard'`  
-**Default:** `'standard'`
-
-Card variant style.
-
-```html
-data-card="standard"
-```
-
 ##### `data-rows`
 
-**Type:** `number`  
+**Type:** `number`
 **Default:** `3`
 
-Number of rows to display per page.
+Number of rows to display per page (1-10).
 
 ```html
 data-rows="4"
@@ -558,39 +615,40 @@ data-rows="4"
 
 ##### `data-columns`
 
-**Type:** `number`  
+**Type:** `number`
 **Default:** `4`
 
-Number of columns in the grid.
+Number of columns in the grid (1-4).
 
 ```html
 data-columns="4"
 ```
 
-##### `data-card-fill`
-
-**Type:** flag (no value)
-
-Whether cards should fill the whole card with white background color to match the image background color.
-
-```html
-data-card-fill
-```
-
 ##### `data-filters`
 
 **Type:** `string` (comma-separated)
 
-Filter types to enable: `personalization`, `pre-order`, `delivery-options`.
+Filter types to enable.
 
 ```html
-data-filters="personalization,pre-order,delivery-options"
+data-filters="engraving,presale,fulfillment,price,brands"
 ```
 
 **Available filters:**
-- `personalization` - Show filter for personalized/engravable products
-- `pre-order` - Show filter for pre-order products
-- `delivery-options` - Show filter for delivery type (all, shipping, onDemand)
+- `engraving` - Show filter for personalized/engravable products
+- `presale` - Show filter for pre-order products
+- `fulfillment` - Show filter for delivery type (shipping, onDemand)
+- `price` - Show price range filter
+- `brands` - Show brand filter
+- `categories` - Show category filter
+- `flavor` - Show flavor filter
+- `region` - Show region filter
+- `variety` - Show variety filter
+- `vintage` - Show vintage year filter
+- `country` - Show country filter
+- `appellation` - Show appellation filter
+- `materials` - Show materials filter
+- `sizes` - Show size filter
 
 ##### `data-product-url`
 
@@ -607,6 +665,60 @@ data-product-url="/products/{grouping}"
 - `{upc}` - Replaced with product UPC
 - `{grouping}` - Replaced with Salsify grouping ID
 
+### Product List Search and Filters Containers
+
+You can place search and filter components in separate containers:
+
+```html
+<!-- Search bar (any div) -->
+<div data-search-container></div>
+
+<!-- Filter panel (any div) -->
+<div data-filters-container></div>
+```
+
+These work alongside the main `data-liquid-commerce-elements-products-list` container. The search and filter components communicate with the product list automatically.
+
+### Checkout URL Configuration
+
+#### `data-checkout-url`
+
+**Type:** `string`
+
+URL for hosted checkout page. The `{id}` placeholder is replaced with the checkout token.
+
+```html
+data-checkout-url="https://yoursite.com/checkout?id={id}"
+```
+
+When set, the "Go to Checkout" button in the cart redirects to this URL instead of opening the checkout drawer.
+
+### Custom Cart Elements
+
+#### `data-lce-cart-toggle-button`
+
+**Type:** flag (no value)
+
+Add to any element to make it toggle the cart open/closed on click.
+
+```html
+<button data-lce-cart-toggle-button>Open Cart</button>
+```
+
+#### `data-lce-cart-items-count`
+
+**Type:** `string` (optional value: `"keep-zero"`)
+
+Displays the current cart item count inside the element. Updated automatically.
+
+```html
+<!-- Hides when count is 0 -->
+<span data-lce-cart-items-count></span>
+
+<!-- Always shows count, even when 0 -->
+<span data-lce-cart-items-count="keep-zero">0</span>
+```
+
 ### URL Parameter Configuration
 
 #### `data-product-param`
@@ -692,6 +804,53 @@ data-promo-active-from="2025-01-01T00:00:00Z"
 data-promo-active-until="2025-12-31T23:59:59Z"
 ```
 
+## Checkout-Only Build (Hosted Checkout)
+
+For hosted checkout pages, use the checkout-only build for a smaller bundle.
+
+### Auto-Initialization
+
+```html
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-checkout
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-debug-mode="none"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+
+**Attributes:**
+- `data-liquid-commerce-checkout` - Enables checkout-only auto-initialization (required)
+- `data-token` - Your API key (required)
+- `data-env` - Environment: `production`, `staging`, `development`
+- `data-debug-mode` - Debug mode: `console`, `panel`
+- `data-checkout-url` - Checkout page URL (for redirect behavior)
+
+### Programmatic Initialization
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+
+const component = await client.injectCheckout({
+  containerId: 'checkout-container',
+  checkoutId: 'checkout-token-from-url',  // Optional: checkout token
+  hideHeader: true                  // Optional
+});
+```
+
+**Differences from full SDK:**
+- Smaller bundle (tree-shaken, no product/cart/PLP components)
+- Only `injectCheckout()` method available (no `injectProductElement`, `injectCartElement`, etc.)
+- Checkout actions only (no `openCheckout`/`closeCheckout`/`toggleCheckout` drawer controls)
+- Same theming, events, and configuration system
+
 ## TypeScript Types
 
 ### `ILiquidCommerceElementsConfig`
@@ -704,6 +863,11 @@ interface ILiquidCommerceElementsConfig {
   customTheme?: IClientCustomThemeConfig;
   proxy?: IElementsProxyConfig;
   promoTicker?: IPromoTicker[];
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+}
+
+interface ILiquidCommerceElementsCheckoutConfig {
+  pageUrl: string; // URL with {id} placeholder for checkout token
 }
 ```
 
@@ -846,8 +1010,8 @@ const client = await Elements(process.env.LCE_API_KEY, {
 
 ## Related Documentation
 
-- [Theming Guide](./THEMING.md) - Complete theme configuration reference
-- [Proxy Setup](./PROXY.md) - Proxy implementation guide
-- [Actions Reference](./ACTIONS.md) - Programmatic control API
-- [Events Reference](./EVENTS.md) - Event system and tracking
+- [Theming Guide](./theming.md) - Complete theme configuration reference
+- [Proxy Setup](./proxy.md) - Proxy implementation guide
+- [Actions Reference](./actions.md) - Programmatic control API
+- [Events Reference](./events.md) - Event system and tracking
 

package/docs/events.md

@@ -0,0 +1,181 @@
+# Events
+
+Events tell you what's happening in real-time: when products load, items get added to cart, checkout completes, and more. Use them to trigger analytics, show custom notifications, sync with your backend, or build reactive UI.
+
+## Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.EVENT_NAME', (event) => {
+  const data = event.detail.data;
+  const metadata = event.detail.metadata;
+});
+```
+
+### Event Metadata
+
+Every event includes metadata:
+
+```javascript
+{
+  eventId: string,           // Unique event ID
+  namespace: 'actions',      // Event namespace
+  event: string,             // Event name
+  originalEvent: string,     // Full namespaced event
+  actionNamespace?: string,  // 'address' | 'product' | 'cart' | 'checkout'
+  timestamp: number          // Unix timestamp
+}
+```
+
+---
+
+## Lifecycle Events
+
+| Event | Description |
+|-------|-------------|
+| `client_ready` | SDK initialized and ready to use |
+
+---
+
+## Product Events
+
+| Event | Description |
+|-------|-------------|
+| `product_loaded` | Product data fetched and displayed |
+| `product_add_to_cart` | Customer added product to cart |
+| `product_quantity_increase` | Quantity increased on product |
+| `product_quantity_decrease` | Quantity decreased on product |
+| `product_size_changed` | Size/variant selection changed |
+| `product_fulfillment_type_changed` | Shipping/on-demand type changed |
+| `product_fulfillment_changed` | Specific retailer/fulfillment changed |
+
+---
+
+## Address Events
+
+| Event | Description |
+|-------|-------------|
+| `address_updated` | Delivery location set or changed |
+| `address_cleared` | Delivery location removed |
+| `address_failed` | Address operation failed |
+
+---
+
+## Cart Events
+
+| Event | Description |
+|-------|-------------|
+| `cart_loaded` | Cart data fetched and ready |
+| `cart_opened` | Cart drawer opened |
+| `cart_closed` | Cart drawer closed |
+| `cart_updated` | Cart items or totals changed |
+| `cart_reset` | Cart cleared completely |
+| `cart_failed` | Cart operation failed |
+| `cart_item_added` | Item added to cart |
+| `cart_item_removed` | Item removed from cart |
+| `cart_item_quantity_increase` | Item quantity increased |
+| `cart_item_quantity_decrease` | Item quantity decreased |
+| `cart_item_engraving_updated` | Personalization added/changed/removed |
+| `cart_product_add_success` | Programmatic add succeeded |
+| `cart_product_add_failed` | Programmatic add failed |
+| `cart_promo_code_applied` | Discount code applied |
+| `cart_promo_code_removed` | Discount code removed |
+| `cart_promo_code_failed` | Discount code rejected |
+
+---
+
+## Checkout Events
+
+### Lifecycle
+
+| Event | Description |
+|-------|-------------|
+| `checkout_loaded` | Checkout ready |
+| `checkout_opened` | Checkout drawer opened |
+| `checkout_closed` | Checkout drawer closed |
+| `checkout_failed` | Checkout operation failed |
+
+### Submit
+
+| Event | Description |
+|-------|-------------|
+| `checkout_submit_started` | Payment processing started |
+| `checkout_submit_completed` | Order successfully placed |
+| `checkout_submit_failed` | Order submission failed |
+
+### Form Updates
+
+| Event | Description |
+|-------|-------------|
+| `checkout_customer_information_updated` | Customer form completed |
+| `checkout_billing_information_updated` | Billing form completed |
+| `checkout_gift_information_updated` | Gift form completed |
+| `checkout_is_gift_toggled` | Gift option toggled |
+| `checkout_billing_same_as_shipping_toggled` | Billing address option toggled |
+| `checkout_marketing_preferences_toggled` | Email/SMS opt-in toggled |
+
+### Item Changes
+
+| Event | Description |
+|-------|-------------|
+| `checkout_item_removed` | Item removed from checkout |
+| `checkout_item_quantity_increase` | Item quantity increased |
+| `checkout_item_quantity_decrease` | Item quantity decreased |
+| `checkout_item_engraving_updated` | Personalization changed |
+| `checkout_tip_updated` | Delivery tip changed |
+
+### Discounts
+
+| Event | Description |
+|-------|-------------|
+| `checkout_product_add_success` | Programmatic add succeeded |
+| `checkout_product_add_failed` | Programmatic add failed |
+| `checkout_promo_code_applied` | Discount applied |
+| `checkout_promo_code_removed` | Discount removed |
+| `checkout_promo_code_failed` | Discount rejected |
+| `checkout_gift_card_applied` | Gift card applied |
+| `checkout_gift_card_removed` | Gift card removed |
+| `checkout_gift_card_failed` | Gift card rejected |
+
+---
+
+## Listening to All Events
+
+Catch all action events with a namespace listener:
+
+```javascript
+// All action events
+window.addEventListener('lce:actions', (event) => {
+  const eventName = event.detail.metadata.event;
+  console.log('Event fired:', eventName);
+});
+```
+
+---
+
+## Security Notes
+
+Events are designed with security in mind:
+
+**Included in events:**
+- Success/failure status
+- Discount amounts (visible in UI)
+- Total amounts (visible in UI)
+- Item counts and identifiers
+
+**Never included:**
+- Promo codes or gift card codes
+- Gift card balances
+- Customer names, emails, addresses
+- Payment information
+
+Form update events (like `checkout_customer_information_updated`) only indicate completion, not actual customer data.
+
+---
+
+## See Also
+
+- [Actions Reference](./actions.md) - Programmatic control
+- [Product](./product.md) - Product component
+- [Cart](./cart.md) - Cart component
+- [Checkout](./checkout.md) - Checkout component
+- [Address](./address.md) - Address component