@liquidcommerce/elements-sdk 2.7.21 → 2.7.23

package/docs/v1/api/configuration.md

@@ -171,6 +171,7 @@ interface IProductLayout {
   showOnlyMainImage: boolean;
   showTitle: boolean;
   showDescription: boolean;
+  descriptionPosition: 'above' | 'below';
   showQuantityCounter: boolean;
   showOffHours: boolean;
   quantityCounterStyle: 'outlined' | 'ghost';
@@ -192,6 +193,7 @@ interface IProductLayout {
 | `showOnlyMainImage` | `boolean` | Show only the main product image (no carousel) |
 | `showTitle` | `boolean` | Show product title |
 | `showDescription` | `boolean` | Show product description |
+| `descriptionPosition` | `'above' \| 'below'` | Placement of the product description relative to other content |
 | `showQuantityCounter` | `boolean` | Show quantity selector |
 | `showOffHours` | `boolean` | Show off-hours messaging |
 | `quantityCounterStyle` | `'outlined' \| 'ghost'` | Visual style for quantity counter |
@@ -509,13 +511,15 @@ See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation detail
 interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
+  mockMode?: boolean;
 }
 ```
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `customApiUrl` | `string` | Custom API URL for local or custom backend testing |
-| `openShadowDom` | `boolean` | Disable Shadow DOM isolation for debugging (default: `false`) |
+| `openShadowDom` | `boolean` | Use an OPEN (inspectable) Shadow DOM instead of the default closed mode, for debugging. Shadow DOM is always attached; forced off in production (default: `false`) |
+| `mockMode` | `boolean` | Enable mock mode to receive mock data from the API; sends an `X-Liquid-Api-Mock-Mode` header with all requests (default: `false`) |
 
 > To pre-select a payment method and skip the card form (in any environment), use [`actions.checkout.setSavedPaymentMethod`](./actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod) instead.
 

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

@@ -53,9 +53,12 @@ injectAddressElement(
 
 ```javascript
 await client.injectAddressElement('address-container', {
-  onAddressSet: (address) => {
-    console.log('Address set:', address);
-  }
+  showLabel: true
+});
+
+// Listen for address changes via the published event (dispatched on window)
+window.addEventListener('lce:actions.address_updated', (event) => {
+  console.log('Address set:', event.detail.data);
 });
 ```
 
@@ -127,7 +130,7 @@ injectProductList(params: IInjectProductListParams): Promise<void>
 interface IInjectProductListParams {
   containerId: string;
   slug: string;              // Product list slug identifier
-  rows?: number;             // Default: 3
+  rows?: number;             // Default: 4
   columns?: number;          // Default: 4
   filters?: ProductListFilterType[];
   productUrl?: PLCProductUrl;  // string template OR Record<identifier, url> map
@@ -192,6 +195,7 @@ injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
 interface IInjectProductListSearchParams {
   containerId: string;
   slug: string;  // Product list slug identifier
+  filters?: ProductListFilterType[];
 }
 ```
 

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

@@ -103,6 +103,10 @@ interface ILiquidCommerceElementsConfig {
 }
 ```
 
+### ILiquidCommerceElementsBuilderConfig
+
+Same shape as `ILiquidCommerceElementsConfig`, used by `ElementsBuilder()`.
+
 ### ILiquidCommerceElementsCheckoutClientConfig
 
 Same shape as `ILiquidCommerceElementsConfig`, used for the checkout-only client.
@@ -135,6 +139,7 @@ interface IElementsProxyConfig {
 interface ILiquidCommerceElementsDevelopmentConfig {
   customApiUrl?: string;
   openShadowDom?: boolean;
+  mockMode?: boolean;  // when true, sends an 'X-Liquid-Api-Mock-Mode' header to receive mock data
 }
 ```
 
@@ -215,6 +220,7 @@ type PLCProductUrl = string | Record<string, string>;
 interface IInjectProductListSearchParams {
   containerId: string;
   slug: string;
+  filters?: ProductListFilterType[];
 }
 ```
 

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

@@ -28,7 +28,8 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
     two: 'Apt 4',
     city: 'New York',
     state: 'NY',
-    zip: '10001'
+    zip: '10001',
+    country: 'US'
   },
   {
     latitude: 40.7128,
@@ -49,17 +50,17 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
 
 ```javascript
 window.addEventListener('lce:actions.product_loaded', (event) => {
-  const { identifier, name, price } = event.detail.data;
+  const { identifier, name, priceInfo } = event.detail.data;
   gtag('event', 'view_item', {
-    items: [{ item_id: identifier, item_name: name, price: price / 100 }]
+    items: [{ item_id: identifier, item_name: name, price: (priceInfo?.minimum ?? 0) / 100 }]
   });
 });
 
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
-  const { orderId, total } = event.detail.data;
+  const { orderNumber, orderTotal } = event.detail.data;
   gtag('event', 'purchase', {
-    transaction_id: orderId,
-    value: total / 100,
+    transaction_id: orderNumber,
+    value: orderTotal / 100,
     currency: 'USD'
   });
 });

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

@@ -60,14 +60,13 @@ When users click checkout, the cart redirects to your hosted checkout page with
     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>
+  <div data-lce-checkout></div>
 </body>
 </html>
 ```

package/docs/v1/getting-started/concepts.md

@@ -96,12 +96,13 @@ The SDK uses a two-phase initialization strategy for optimal performance:
 - Store initialization
 - Theme setup
 - Core component registration
+- Telemetry / logger wiring
+- Debug panel (if enabled)
 
-**Phase 2: Deferred Services (After 100ms)**
-- Analytics/telemetry
+**Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
+- Analytics (Google Tag Manager)
 - Cart pre-loading
 - Heavy component registration
-- Debug panel (if enabled)
 
 This ensures fast initial page loads while still providing full functionality.
 
@@ -111,8 +112,8 @@ Listen for the client ready event to know when the SDK is initialized:
 
 ```javascript
 window.addEventListener('lce:actions.client_ready', (event) => {
-  console.log('SDK version:', event.detail.version);
-  console.log('Ready at:', event.detail.timestamp);
+  console.log('SDK version:', event.detail.data.version);
+  console.log('Ready at:', event.detail.data.timestamp);
   
   // Safe to use client
   window.LiquidCommerce.elements.actions.cart.openCart();
@@ -207,18 +208,17 @@ The SDK maintains its own internal state for cart, checkout, and user data.
 ### Store Service
 
 The SDK uses a centralized store service that:
-- Maintains reactive state
+- Maintains reactive state (in-memory, within a single tab)
 - Persists data to localStorage
 - Falls back to API storage
-- Syncs across browser tabs
 
 ### State Persistence
 
 **Cart State:**
 - Saved to localStorage
 - Persists across sessions
-- Syncs across tabs automatically
 - Survives page refreshes
+- Other tabs pick up the persisted cart on their next load (no live cross-tab sync)
 
 **Address State:**
 - Saved when set by user
@@ -230,17 +230,9 @@ The SDK uses a centralized store service that:
 - Exists during checkout flow
 - Cleared after order completion
 
-### Cross-Tab Synchronization
+### Cross-Tab Persistence
 
-When you update the cart in one tab, all other tabs update automatically:
-
-```javascript
-// Tab 1
-await window.LiquidCommerce.elements.actions.cart.addProduct([...]);
-
-// Tab 2 automatically receives the update
-// No additional code needed
-```
+State is persisted to `localStorage` keyed by device ID. The SDK does **not** register a `storage` listener, `BroadcastChannel`, or other inter-tab subscription, so there is **no live cross-tab synchronization** — a change made in one tab is only reflected in another already-open tab after that tab reloads (which re-runs the persisted-state load and re-fetches by the persisted cart ID).
 
 ## Component Lifecycle
 
@@ -269,10 +261,12 @@ Manual rerendering:
 
 ```javascript
 const components = window.LiquidCommerce.elements.getInjectedComponents();
-const productComponent = components.get('product-1');
+// The Map is keyed by the container ID passed to inject* (with any leading '#' stripped),
+// not a '<type>-<index>' string. For a component injected into id="product":
+const productComponent = components.get('product');
 
 // Force rerender
-productComponent.rerender();
+productComponent?.rerender();
 ```
 
 ### Component Removal
@@ -319,8 +313,9 @@ lce:forms.billing
 
 ```javascript
 window.addEventListener('lce:actions.cart_item_added', (event) => {
-  console.log('Item added:', event.detail);
-  // { cartId, itemId, quantity, ... }
+  console.log('Item added:', event.detail.data);
+  // event.detail is { data, metadata }; payload fields live under .data:
+  // { cartId, itemId, fulfillmentId, partNumber, quantity, engravingLines? }
 });
 ```
 
@@ -332,14 +327,14 @@ The SDK is designed to fail gracefully and not crash your site.
 
 ### Error Isolation
 
-SDK errors are caught and logged, but don't propagate to your application:
+SDK errors are logged and also emitted as a `*_FAILED` event, then re-thrown so your code can catch them:
 
 ```javascript
-// Even if SDK throws an error, your code continues
+// The SDK emits CART_PRODUCT_ADD_FAILED and re-throws, so this catch runs
 try {
   await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid data */]);
 } catch (error) {
-  console.log('This error is caught by SDK internally');
+  console.log('This error is re-thrown by the SDK and caught here');
 }
 
 // Your page keeps working

package/docs/v1/getting-started/installation.md

@@ -36,7 +36,7 @@ Add the following script tag to your page's `<head>` section:
 |-----------|----------|-------------|
 | `data-liquid-commerce-elements` | Yes | Identifies this as the Elements SDK script |
 | `data-token` | Yes | Your LiquidCommerce API key |
-| `data-env` | Yes | Environment: `development`, `staging`, or `production` |
+| `data-env` | No | Environment: `development`, `staging`, or `production`. Defaults to `production` if omitted. |
 | `defer` | Recommended | Allows non-blocking script loading |
 
 ### Where to Place the Script
@@ -73,7 +73,7 @@ If you only need checkout functionality (without product displays or cart), use
 ```html
 <script
   defer
-  data-liquid-commerce-elements-checkout
+  data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
@@ -245,7 +245,7 @@ The SDK accepts a configuration object during initialization:
 
 ```javascript
 const client = await Elements('YOUR_API_KEY', {
-  env: 'production',           // Required: 'development' | 'staging' | 'production'
+  env: 'production',           // Optional (defaults to 'production'): 'development' | 'staging' | 'production'
   debugMode: 'console',         // Optional: 'none' | 'console' | 'panel'
   customTheme: { /* ... */ },   // Optional: Theme customization
   promoTicker: [ /* ... */ ],   // Optional: Promo ticker configuration
@@ -293,7 +293,7 @@ If the SDK script fails to load:
 If you see an error about Web Components:
 
 ```
-[LiquidCommerce Elements] SDK requires support for Web Components
+[LiquidCommerce Elements] SDK requires support for Web Components. Please include a Web Components polyfill for older browsers.
 ```
 
 Include a Web Components polyfill before the SDK script:

package/docs/v1/guides/address-component.md

@@ -34,10 +34,11 @@ Use the standalone address component when you need a dedicated address selection
 ```javascript
 const client = await Elements('YOUR_API_KEY', { env: 'production' });
 
-await client.injectAddressElement('address-container', {
-  onAddressSet: (address) => {
-    console.log('Address set:', address);
-  }
+await client.injectAddressElement('address-container');
+
+// React to address selection by listening for the address_updated event
+window.addEventListener('lce:actions.address_updated', (event) => {
+  console.log('Address set:', event.detail.data);
 });
 ```
 
@@ -67,10 +68,11 @@ For custom address flows without Google Places:
 await window.LiquidCommerce.elements.actions.address.setAddressManually(
   {
     one: '123 Main Street',
-    two: 'Apt 4',         // Optional
+    two: 'Apt 4',         // Optional at runtime
     city: 'New York',
     state: 'NY',
-    zip: '10001'
+    zip: '10001',
+    country: 'US'
   },
   {
     latitude: 40.7128,
@@ -85,6 +87,7 @@ await window.LiquidCommerce.elements.actions.address.setAddressManually(
 - `city`: City name (required)
 - `state`: Two-letter state code (required)
 - `zip`: ZIP/postal code (required)
+- `country`: Country code, e.g. `'US'` (required by the `IAddressAddress` type)
 - `latitude`: Number between -90 and 90 (required)
 - `longitude`: Number between -180 and 180 (required)
 
@@ -103,7 +106,8 @@ console.log(addressData);
 //     two: 'Apt 4',
 //     city: 'New York',
 //     state: 'NY',
-//     zip: '10001'
+//     zip: '10001',
+//     country: 'US'
 //   },
 //   coordinates: {
 //     latitude: 40.7128,
@@ -316,7 +320,7 @@ Addresses persist:
 
 Addresses are:
 - Stored locally in the browser
-- Not sent to external servers except for availability checking
+- Sent to LiquidCommerce servers for availability/product loading; the address id (with the cart id) may also be persisted server-side as a session fallback when localStorage is unavailable (and a delete request is sent when the address is cleared)
 - Cleared when user logs out (if you implement logout handling)
 
 ## Best Practices

package/docs/v1/guides/best-practices.md

@@ -225,7 +225,7 @@ useEffect(() => {
 // Update UI when cart changes
 window.addEventListener('lce:actions.cart_updated', () => {
   const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
-  updateHeaderCartCount(cart.itemsCount);
+  updateHeaderCartCount(cart.itemCount);
 });
 ```
 
@@ -233,18 +233,18 @@ window.addEventListener('lce:actions.cart_updated', () => {
 
 ```javascript
 window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
-  const { orderId, total } = event.detail.data;
+  const { orderNumber, orderTotal } = event.detail.data;
   
   // Analytics
   gtag('event', 'purchase', {
-    transaction_id: orderId,
-    value: total / 100
+    transaction_id: orderNumber,
+    value: orderTotal / 100
   });
   
   // Backend tracking
   fetch('/api/track-order', {
     method: 'POST',
-    body: JSON.stringify({ orderId, total })
+    body: JSON.stringify({ orderNumber, orderTotal })
   });
 });
 ```

package/docs/v1/guides/cart-component.md

@@ -57,7 +57,7 @@ Show the number of items in the cart:
 
 #### Floating Cart Button
 
-Create a floating button (bottom-right corner):
+Create a floating button (top-right corner):
 
 ```html
 <script
@@ -174,9 +174,10 @@ await window.LiquidCommerce.elements.actions.cart.addProduct([
 ```
 
 **Parameters:**
-- `identifier` (string): Product UPC, SKU, or ID
+- `identifier` (string): Product UPC, size ID, or salsifyGrouping ID
 - `fulfillmentType` (string): `'shipping'` or `'onDemand'`
 - `quantity` (number): Number of items (default: 1)
+- `engravingLines` (string[], optional): Engraving text lines for the product (applied when the product/variant supports engraving; ignored otherwise)
 - Second parameter (boolean): Open cart after adding (default: false)
 
 ### Apply Promo Code
@@ -215,13 +216,12 @@ const cartData = window.LiquidCommerce.elements.actions.cart.getDetails();
 console.log(cartData);
 // {
 //   cartId: 'cart_abc123',
-//   items: [...],
+//   promoCodeDiscount: 1000,  // number | null
 //   subtotal: 9998,  // in cents
-//   total: 9998,
-//   itemsCount: 3,
-//   itemsQuantity: 5,
-//   promoCode: { code: 'SUMMER20', discount: 1000 },
-//   retailers: [...],
+//   itemCount: 5,
+//   items: {...},  // Record<itemId, ICartItem>
+//   retailers: {...},  // Record<retailerId, ICartRetailer>
+//   location: {...},  // or null
 //   ...
 // }
 ```
@@ -282,8 +282,8 @@ Fired when cart data is loaded:
 
 ```javascript
 window.addEventListener('lce:actions.cart_loaded', (event) => {
-  const { cartId, itemsCount, subtotal } = event.detail.data;
-  console.log(`Cart loaded: ${itemsCount} items, total: $${subtotal / 100}`);
+  const { cartId, itemCount, subtotal } = event.detail.data;
+  console.log(`Cart loaded: ${itemCount} items, total: $${subtotal / 100}`);
 });
 ```
 
@@ -305,8 +305,8 @@ Fired whenever cart contents change:
 
 ```javascript
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  const { cartId, itemsCount, subtotal } = event.detail.data;
-  console.log('Cart updated:', itemsCount, 'items');
+  const { cartId, itemCount, subtotal } = event.detail.data.current;
+  console.log('Cart updated:', itemCount, 'items');
 });
 ```
 
@@ -332,13 +332,13 @@ window.addEventListener('lce:actions.cart_item_removed', (event) => {
 
 ```javascript
 window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {
-  const { cartId, itemId, newQuantity } = event.detail.data;
-  console.log(`Item ${itemId} quantity increased to ${newQuantity}`);
+  const { cartId, itemId, quantity } = event.detail.data;
+  console.log(`Item ${itemId} quantity increased to ${quantity}`);
 });
 
 window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
-  const { cartId, itemId, newQuantity } = event.detail.data;
-  console.log(`Item ${itemId} quantity decreased to ${newQuantity}`);
+  const { cartId, itemId, quantity } = event.detail.data;
+  console.log(`Item ${itemId} quantity decreased to ${quantity}`);
 });
 ```
 
@@ -399,7 +399,7 @@ const client = await Elements('YOUR_API_KEY', {
       },
       layout: {
         showQuantityCounter: true,
-        quantityCounterStyle: 'outlined',  // or 'input'
+        quantityCounterStyle: 'outlined',  // or 'ghost'
         drawerHeaderText: 'My Bag',
         goToCheckoutButtonText: 'Checkout'
       }
@@ -419,26 +419,13 @@ This allows the cart to survive:
 - Browser restarts
 - Navigation between pages
 
-### Cross-Tab Synchronization
-
-When you update the cart in one tab, all other open tabs automatically sync:
-
-```javascript
-// Tab 1: Add item
-await window.LiquidCommerce.elements.actions.cart.addProduct([...]);
-
-// Tab 2: Cart automatically updates
-// No additional code needed
-```
+### Cross-Tab Persistence
 
-The SDK uses the following mechanisms:
-- localStorage events
-- Periodic polling
-- API-based fallback
+The cart is persisted to `localStorage` and reloaded on a fresh page load. The SDK does **not** provide live cross-tab synchronization — changes made in one tab will not automatically appear in other already-open tabs (there is no `storage` listener, `BroadcastChannel`, or polling). Another tab reflects the change only after it reloads.
 
 ### Session Duration
 
-Carts persist for 45 days by default. After 45 days of inactivity, the cart is cleared.
+Cart and address session IDs are persisted in `localStorage` (with an API fallback) and are not automatically cleared by the SDK; cart lifetime/expiry is governed by server-side policy.
 
 ## Address Requirement
 
@@ -606,8 +593,9 @@ The `{token}` placeholder is replaced with the session checkout token.
 ```javascript
 // Track cart events for analytics
 window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { itemId, quantity } = event.detail.data;
   gtag('event', 'add_to_cart', {
-    value: event.detail.data.price / 100,
+    items: [{ item_id: itemId, quantity }],
     currency: 'USD'
   });
 });
@@ -615,7 +603,7 @@ window.addEventListener('lce:actions.cart_item_added', (event) => {
 window.addEventListener('lce:actions.cart_updated', (event) => {
   // Update header cart count
   document.getElementById('cart-badge').textContent = 
-    event.detail.data.itemsCount;
+    event.detail.data.current.itemCount;
 });
 ```
 
@@ -637,9 +625,9 @@ if (campaign === 'summer-sale') {
 ```javascript
 // Store cart ID in your system
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  const { cartId, itemsCount } = event.detail.data;
+  const { cartId, itemCount } = event.detail.data.current;
   
-  if (itemsCount > 0) {
+  if (itemCount > 0) {
     // Send cart ID to your backend for abandoned cart emails
     fetch('/api/track-cart', {
       method: 'POST',
@@ -695,9 +683,9 @@ Show appropriate messaging for empty carts:
 
 ```javascript
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  const { itemsCount } = event.detail.data;
+  const { itemCount } = event.detail.data.current;
   
-  if (itemsCount === 0) {
+  if (itemCount === 0) {
     // Show empty state in your UI
     document.getElementById('cart-status').textContent = 
       'Your cart is empty';