@liquidcommerce/elements-sdk 2.7.9 → 2.7.10

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

@@ -32,7 +32,7 @@ Use data attributes to configure the product list:
   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
@@ -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/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)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.9",
+  "version": "2.7.10",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "module": "./dist/index.esm.js",
   "types": "./dist/types/index.d.ts",
-  "packageManager": "pnpm@10.0.0",
+  "packageManager": "pnpm@10.33.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -47,11 +47,7 @@
     "dist/index.esm.js",
     "dist/index.checkout.esm.js",
     "umd/elements.js",
-    "umd/elements-checkout.js",
-    "src/index.ts",
-    "src/index.umd.ts",
-    "src/index.checkout.ts",
-    "src/index.checkout.umd.ts"
+    "umd/elements-checkout.js"
   ],
   "scripts": {
     "build": "rollup -c",
@@ -81,7 +77,7 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
+    "@biomejs/biome": "^2.4.11",
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@rollup/plugin-alias": "^6.0.0",
@@ -97,13 +93,13 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "conventional-changelog": "^7.2.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.60.0",
+    "rollup": "^4.60.1",
     "rollup-obfuscator": "^4.1.1",
-    "rollup-plugin-typescript2": "^0.36.0",
+    "rollup-plugin-typescript2": "^0.37.0",
     "semantic-release": "^25.0.3",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"