@liquidcommerce/elements-sdk 2.7.8 → 2.7.10

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

@@ -188,6 +188,35 @@ document.getElementById('clear-cart-btn').addEventListener('click', async () =>
 });
 ```
 
+## Cleanup
+
+### Destroy Components When Done
+
+In single-page applications, clean up when navigating away:
+
+```javascript
+// Destroy individual component
+const component = client.getInjectedComponents().get('product-1');
+component?.destroy();
+
+// Destroy entire client (on route change)
+client.destroy();
+```
+
+### Avoid Leaking References
+
+```javascript
+// Good - clean up on unmount
+useEffect(() => {
+  const init = async () => {
+    const c = await Elements('KEY', { env: 'production' });
+    clientRef.current = c;
+  };
+  init();
+  return () => clientRef.current?.destroy();
+}, []);
+```
+
 ## Events
 
 ### Use Events for Reactive Updates

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

@@ -31,7 +31,7 @@ Add a cart button using data attributes on the SDK script:
   data-env="production"
   data-cart-button="header-cart"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="header-cart"></div>
@@ -49,7 +49,7 @@ Show the number of items in the cart:
   data-env="production"
   data-cart-badge-button="header-cart"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="header-cart"></div>
@@ -67,7 +67,7 @@ Create a floating button (bottom-right corner):
   data-env="production"
   data-cart-button
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -103,7 +103,7 @@ If you want to control cart opening manually:
   data-env="production"
   data-cart-button-hidden
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -514,7 +514,7 @@ Or with data attributes:
   data-promo-active-from="2024-06-01T00:00:00Z"
   data-promo-active-until="2024-08-31T23:59:59Z"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -530,7 +530,7 @@ Apply promo codes automatically via URL parameters:
   data-env="production"
   data-promo-code-param="lce_promo"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 
@@ -593,7 +593,7 @@ Or with data attributes:
   data-env="production"
   data-checkout-url="https://yoursite.com/checkout/{token}"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 

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

@@ -48,7 +48,7 @@ Configure checkout to load from URL parameter:
   data-checkout-container="checkout"
   data-checkout-param="lce_checkout"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="checkout"></div>
@@ -79,7 +79,7 @@ Or with data attributes:
   data-env="production"
   data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 ```
 

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

@@ -29,7 +29,7 @@ The simplest way to add a product is using HTML data attributes:
   data-container-1="product-display"
   data-product-1="00619947000020"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="product-display"></div>
@@ -48,7 +48,7 @@ The simplest way to add a product is using HTML data attributes:
   data-container-2="product-2"
   data-product-2="08504405135"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div id="product-1"></div>
@@ -66,7 +66,7 @@ Use `data-lce-product` on any div:
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div data-lce-product="00619947000020"></div>
@@ -86,7 +86,7 @@ For many products, use a JSON script tag:
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <script data-liquid-commerce-elements-products type="application/json">
@@ -496,7 +496,7 @@ If product data fails to load:
     data-container-1="product"
     data-product-1="00619947000020"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>

package/docs/v1/guides/product-list-component.md

@@ -25,14 +25,14 @@ Use data attributes to configure the product list:
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <div
   data-liquid-commerce-elements-products-list="my-collection-slug"
   data-rows="3"
   data-columns="4"
-  data-filters="price,brand,category"
+  data-filters="price,brands,categories"
   data-product-url="/product/{identifier}"
 ></div>
 ```
@@ -55,7 +55,7 @@ Separate containers for search and filters:
 <div data-liquid-commerce-elements-products-list-search="my-collection-slug"></div>
 
 <!-- Filters container -->
-<div data-liquid-commerce-elements-products-list-filters="my-collection-slug" data-filters="price,brand,fulfillment"></div>
+<div data-liquid-commerce-elements-products-list-filters="my-collection-slug" data-filters="price,brands,fulfillment"></div>
 
 <!-- Product list -->
 <div
@@ -76,117 +76,52 @@ const client = await Elements('YOUR_API_KEY', { env: 'production' });
 // Inject product list
 await client.injectProductList({
   containerId: 'products',
+  slug: 'my-collection-slug',
   rows: 3,
   columns: 4,
-  filters: ['price', 'brand', 'category', 'fulfillment'],
+  filters: ['price', 'brands', 'categories', 'fulfillment'],
   productUrl: '/product/{identifier}'
 });
 
 // Inject search (optional)
 await client.injectProductListSearch({
-  containerId: 'search'
+  containerId: 'search',
+  slug: 'my-collection-slug'
 });
 
 // Inject filters (optional)
 await client.injectProductListFilters({
   containerId: 'filters',
-  filters: ['price', 'brand']
+  slug: 'my-collection-slug',
+  filters: ['price', 'brands']
 });
 ```
 
 ## Available Filters
 
-### Price Range
-
-Filter products by price:
+The following filter type values can be used in the `filters` array:
+
+| Filter Value   | Description                              |
+|----------------|------------------------------------------|
+| `'price'`      | Price range slider with min/max values   |
+| `'brands'`     | Checkboxes for available brands          |
+| `'categories'` | Category selection checkboxes            |
+| `'fulfillment'`| Shipping vs. on-demand delivery toggle   |
+| `'engraving'`  | Filter by personalization support        |
+| `'sizes'`      | Filter by product size/volume            |
+| `'flavor'`     | Filter by flavor profile                 |
+| `'region'`     | Filter by region of origin               |
+| `'variety'`    | Filter by product variety                |
+| `'vintage'`    | Filter by vintage year                   |
+| `'country'`    | Filter by country of origin              |
+| `'appellation'`| Filter by appellation                    |
+| `'materials'`  | Filter by materials                      |
 
 ```javascript
-filters: ['price']
+// Example: use multiple filters
+filters: ['price', 'brands', 'categories', 'fulfillment', 'sizes']
 ```
 
-Shows price range slider with min/max values.
-
-### Brand
-
-Filter by brand/manufacturer:
-
-```javascript
-filters: ['brand']
-```
-
-Shows checkboxes for all available brands.
-
-### Category
-
-Filter by product category:
-
-```javascript
-filters: ['category']
-```
-
-Shows category selection dropdown or checkboxes.
-
-### Fulfillment Type
-
-Filter by shipping vs. on-demand delivery:
-
-```javascript
-filters: ['fulfillment']
-```
-
-Options:
-- Shipping only
-- On-demand delivery only
-- Both
-
-### Engraving
-
-Filter products that support personalization:
-
-```javascript
-filters: ['engraving']
-```
-
-Options:
-- Can be engraved
-- Cannot be engraved
-- Show all
-
-### Size
-
-Filter by product size (volume):
-
-```javascript
-filters: ['size']
-```
-
-Shows available sizes (e.g., 750ml, 1L, 1.75L).
-
-### Rating
-
-Filter by customer ratings:
-
-```javascript
-filters: ['rating']
-```
-
-Options:
-- 4+ stars
-- 3+ stars
-- All ratings
-
-### Availability
-
-Filter by stock status:
-
-```javascript
-filters: ['availability']
-```
-
-Options:
-- In stock only
-- All products
-
 ## Search Functionality
 
 ### Search Box
@@ -208,15 +143,7 @@ The search component provides full-text search across:
 
 ### Programmatic Search
 
-Control search via JavaScript:
-
-```javascript
-// Get current search term
-const currentSearch = store.get('productList.search.query');
-
-// Set search programmatically
-store.set('productList.search.query', 'whiskey');
-```
+Search is controlled through the injected search component. Use `injectProductListSearch()` to add a search box that automatically filters the associated product list.
 
 ## Grid Layout
 
@@ -238,6 +165,7 @@ The grid automatically adjusts for screen sizes:
 ```javascript
 await client.injectProductList({
   containerId: 'products',
+  slug: 'my-collection',
   rows: 5,        // Number of rows per page
   columns: 4      // Columns in grid (desktop)
 });
@@ -295,33 +223,46 @@ Each product card shows:
 
 ### Theme Configuration
 
+Product list theming is applied per-list using the collection slug as a key:
+
 ```javascript
 const client = await Elements('YOUR_API_KEY', {
   env: 'production',
   customTheme: {
     productList: {
       theme: {
-        cardBackgroundColor: '#ffffff',
-        cardBorderColor: '#e0e0e0',
-        cardHoverShadow: '0 4px 8px rgba(0,0,0,0.1)'
+        backgroundColor: '#ffffff'
       },
       layout: {
-        showProductImages: true,
-        showBrand: true,
-        showPrice: true,
-        showRating: true,
-        showAvailability: true,
-        showAddToCartButton: false,  // Enable quick add
-        cardImageAspectRatio: '1:1',  // or '4:3', '16:9'
-        gridGap: '20px',
-        enableInfiniteScroll: true,
-        productsPerPage: 12  // Override rows × columns
+        lists: {
+          'my-collection-slug': {
+            productCard: {
+              style: 'card',           // 'card' or 'ghost'
+              cornerRadius: '8px',
+              showPrice: true,
+              showSizes: true,
+              showRetailerName: true,
+              showFulfillmentOptions: true,
+              enableShippingFulfillment: true,
+              enableOnDemandFulfillment: true,
+              enablePersonalization: true,
+              showQuantityCounter: true,
+              enablePreCart: true,
+              showCollectionTags: false
+            },
+            presentationMode: 'drawer',  // 'drawer' or 'modal'
+            rows: 4,
+            columns: 3
+          }
+        }
       }
     }
   }
 });
 ```
 
+See [Configuration Reference](../api/configuration.md#product-list-theme) for the complete list of options.
+
 ## Use Cases
 
 ### Category Page
@@ -336,7 +277,7 @@ const client = await Elements('YOUR_API_KEY', {
     data-liquid-commerce-elements
     data-token="YOUR_API_KEY"
     data-env="production"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>
@@ -348,7 +289,7 @@ const client = await Elements('YOUR_API_KEY', {
   <div class="catalog">
     <!-- Filters sidebar -->
     <aside>
-      <div data-liquid-commerce-elements-products-list-filters="whiskey-collection" data-filters="price,brand,size"></div>
+      <div data-liquid-commerce-elements-products-list-filters="whiskey-collection" data-filters="price,brands,sizes"></div>
     </aside>
 
     <!-- Product grid -->
@@ -372,51 +313,18 @@ import { Elements } from '@liquidcommerce/elements-sdk';
 
 const client = await Elements('YOUR_API_KEY', { env: 'production' });
 
-// Get search query from URL
-const params = new URLSearchParams(window.location.search);
-const searchQuery = params.get('q');
-
-// Inject product list
+// Inject product list with search
 await client.injectProductList({
   containerId: 'search-results',
+  slug: 'all-products',
   rows: 5,
   columns: 4,
-  filters: ['price', 'brand', 'category']
-});
-
-// Apply search
-if (searchQuery) {
-  store.set('productList.search.query', searchQuery);
-}
-```
-
-### Dynamic Filtering
-
-```javascript
-// Listen for filter changes
-window.addEventListener('lce:productList.filterChanged', (event) => {
-  const { filterType, filterValue } = event.detail;
-  
-  console.log(`Filter changed: ${filterType} = ${filterValue}`);
-  
-  // Track filter usage
-  gtag('event', 'filter_applied', {
-    filter_type: filterType,
-    filter_value: filterValue
-  });
+  filters: ['price', 'brands', 'categories']
 });
 
-// Listen for search
-window.addEventListener('lce:productList.searchChanged', (event) => {
-  const { query, resultCount } = event.detail;
-  
-  console.log(`Search: "${query}" (${resultCount} results)`);
-  
-  // Track search
-  gtag('event', 'search', {
-    search_term: query,
-    result_count: resultCount
-  });
+await client.injectProductListSearch({
+  containerId: 'search-box',
+  slug: 'all-products'
 });
 ```
 
@@ -442,6 +350,7 @@ switch (productType) {
 
 await client.injectProductList({
   containerId: 'products',
+  slug: 'all-products',
   rows: 3,
   columns: 4,
   productUrl: urlPattern
@@ -493,9 +402,10 @@ For catalogs with thousands of products:
 ```javascript
 await client.injectProductList({
   containerId: 'products',
+  slug: 'all-products',
   rows: 3,
   columns: 4,
-  filters: ['price', 'brand'],  // Limit filters to most useful
+  filters: ['price', 'brands'],  // Limit filters to most useful
   // More rows = larger pages = fewer API calls
 });
 ```
@@ -514,13 +424,11 @@ await client.injectProductList({
 
 ### Show Result Counts
 
-Display the number of products found:
+The product list component automatically displays the number of results. You can also track cart additions from the list using standard cart events:
 
 ```javascript
-window.addEventListener('lce:productList.updated', (event) => {
-  const { totalProducts, displayedProducts } = event.detail;
-  document.getElementById('result-count').textContent = 
-    `Showing ${displayedProducts} of ${totalProducts} products`;
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added from product list:', event.detail.data);
 });
 ```
 
@@ -553,9 +461,10 @@ For category pages, pre-select relevant filters:
 // On whiskey category page
 await client.injectProductList({
   containerId: 'products',
+  slug: 'whiskey-collection',
   rows: 4,
   columns: 3,
-  filters: ['price', 'brand', 'size']  // Most relevant for whiskey
+  filters: ['price', 'brands', 'sizes']  // Most relevant for whiskey
 });
 ```
 

package/docs/v1/integration/laravel.md

@@ -21,7 +21,7 @@ Use the CDN build in a Blade view for a quick server-rendered setup.
     data-container-1="product"
     data-product-1="00619947000020"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>

package/docs/v1/integration/vanilla-js.md

@@ -21,7 +21,7 @@ Use the CDN build for the fastest setup, or use NPM if you have a build step.
     data-product-1="00619947000020"
     data-cart-badge-button="header-cart"
     type="text/javascript"
-    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
   ></script>
 </head>
 <body>
@@ -46,7 +46,7 @@ Use the CDN build for the fastest setup, or use NPM if you have a build step.
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
 ></script>
 
 <script>

package/docs/v1/reference/troubleshooting.md

@@ -64,6 +64,70 @@ This is expected behavior. The SDK ships an SSR stub that is automatically resol
 
 **No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
 
+## Styling Not Applied / CSS Not Working
+
+**Symptoms:** Components render but custom styles are ignored, or host page styles leak into components.
+
+**Cause:** Components use Shadow DOM for style isolation.
+
+**Fixes:**
+- Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
+- For debugging, enable `development.openShadowDom: true` to disable Shadow DOM temporarily.
+- Use the debug panel (`debugMode: 'panel'`) to inspect component state.
+
+## Component Not Updating After Data Changes
+
+**Symptoms:** Component shows stale data after an action completes.
+
+**Fixes:**
+- Call `.rerender()` on the injected component to force a refresh:
+  ```javascript
+  const components = client.getInjectedComponents();
+  components.get('product-1')?.rerender();
+  ```
+- Ensure you're not holding a stale reference -- call `getInjectedComponents()` again after injection.
+
+## Cleanup / Memory Leaks
+
+**Symptoms:** Components persist after navigating away in SPA, or duplicate components appear.
+
+**Fixes:**
+- Call `destroy()` on individual injected components when removing them:
+  ```javascript
+  const component = client.getInjectedComponents().get('product-1');
+  component?.destroy();
+  ```
+- Call `client.destroy()` when tearing down the entire SDK (e.g., on SPA route change).
+
+## Promo Ticker Not Showing
+
+**Symptoms:** Promo ticker is configured but not visible.
+
+**Fixes:**
+- Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
+- Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format).
+- Ensure `global.layout.allowPromoCodes` is not set to `false`.
+
+## Ad Blockers Blocking SDK Requests
+
+**Symptoms:** Network requests fail, products don't load, but no code errors.
+
+**Fixes:**
+- Set up a proxy to route API requests through your own domain:
+  ```javascript
+  proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy' }
+  ```
+- See [Proxy Setup Guide](../integration/proxy-setup.md) for server-side implementation.
+
+## Performance Issues on Large Product Lists
+
+**Symptoms:** Slow rendering or high memory usage with many products.
+
+**Fixes:**
+- Reduce `rows` and `columns` to load fewer products per page.
+- Limit the number of active filters.
+- Use the checkout-only build on checkout pages to reduce bundle size.
+
 ## Related Docs
 
 - [Installation](../getting-started/installation.md)