@liquidcommerce/elements-sdk 2.5.1 → 2.5.2-beta.1

package/README.md

@@ -192,6 +192,40 @@ Mark any div with a data attribute:
 
 **Use case:** Product grids, category pages, search results
 
+### Adding a Product List
+
+Display a filtered, paginated product catalog with infinite scroll. Perfect for category pages, catalog pages, and search results.
+
+Add a product list to any page with a data attribute:
+
+```html
+<div data-liquid-commerce-elements-products-list
+     data-card="standard"
+     data-rows="3"
+     data-columns="4"
+     data-filters="personalization,pre-order,delivery-options"
+     data-product-url="/product/{upc}">
+</div>
+
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+**Attributes:**
+- `data-liquid-commerce-elements-products-list` - Enables product list on this div
+- `data-card` - Card variant: `standard` (default)
+- `data-rows` - Number of rows per page (default: `3`)
+- `data-columns` - Number of columns (default: `4`)
+- `data-card-fill` - Makes cards fill available space (optional flag)
+- `data-filters` - Comma-separated filters: `personalization`, `pre-order`, `delivery-options`
+- `data-product-url` - Product URL template with `{upc}` or `{grouping}` placeholder
+
+**Use case:** Category pages, catalog pages, search results, filtered product browsing
+
 ### Customizing the Cart Button
 
 By default, you get a floating cart button. Here's how to customize it:
@@ -339,6 +373,16 @@ Here's every available data attribute:
   data-container-2="div-id"
   data-product-2="identifier"
   
+  <!-- Product List -->
+  <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-product-url="/product/{upc}">
+  </div>
+  
   <!-- URL Parameters -->
   data-product-param="lce_product"
   data-product-fulfillment-type-param="lce_fulfillment"
@@ -621,6 +665,46 @@ const component = await client.injectAddressElement('address-container');
 
 **Use case:** Shipping address collection page
 
+#### Product List
+
+```js
+await client.injectProductList({
+  containerId: 'product-list-container',
+  rows: 3,                    // Number of rows per page
+  columns: 4,                  // Number of columns
+  cardVariant: 'standard',    // Card style variant
+  fillCard: false,            // Fill card to available space
+  filters: [                  // Optional filters
+    'personalization',        // Show personalized products
+    'pre-order',              // Show pre-order products
+    'delivery-options'         // Show delivery type filters
+  ],
+  productUrl: '/product/{upc}' // Optional: Product detail page URL template
+});
+```
+
+**Parameters:**
+- `containerId` - Where to inject the product list
+- `rows` - Number of rows to display per page (default: `3`)
+- `columns` - Number of columns in the grid (default: `4`)
+- `cardVariant` - Card display style: `'standard'` (default)
+- `fillCard` - Whether cards should fill available space (default: `false`)
+- `filters` - Array of filter types to enable: `'personalization'`, `'pre-order'`, `'delivery-options'`
+- `productUrl` - Optional URL template for product links. Use `{upc}` or `{grouping}` placeholder
+
+**Features:**
+- ✅ Infinite scroll pagination
+- ✅ Filter by personalization, pre-order, delivery options
+- ✅ Address-aware (reloads when address changes)
+- ✅ Loading states and error handling
+- ✅ Automatic GTM tracking (`view_item_list`, `select_item`)
+- ✅ Add to cart directly from cards
+- ✅ Product links with tracking
+
+**Use case:** Category pages, catalog pages, search results, filtered product browsing
+
+**Note:** The product list automatically reloads when the address changes to show availability for the new location.
+
 #### Access All Injected Components
 
 ```js
@@ -1455,6 +1539,128 @@ window.addEventListener('lce:actions.product_add_to_cart', (event) => {
 });
 ```
 
+### Product List
+
+Display a filtered, paginated product catalog with infinite scroll. Perfect for category pages, catalog pages, and search results.
+
+#### Auto-Initialization
+
+Add a product list to any page with data attributes:
+
+```html
+<div data-liquid-commerce-elements-products-list
+     data-card="standard"
+     data-rows="3"
+     data-columns="4"
+     data-filters="personalization,pre-order,delivery-options"
+     data-product-url="/product/{upc}">
+</div>
+```
+
+#### Programmatic Injection
+
+```js
+await client.injectProductList({
+  containerId: 'product-list-container',
+  rows: 3,
+  columns: 4,
+  cardVariant: 'standard',
+  fillCard: false,
+  filters: ['personalization', 'pre-order', 'delivery-options'],
+  productUrl: '/product/{upc}'
+});
+```
+
+#### Features
+
+**Filtering:**
+- **Personalization filter** - Show only products that support engraving/personalization
+- **Pre-order filter** - Show only pre-order products
+- **Delivery options filter** - Filter by `all`, `shipping`, or `onDemand`
+
+**Smart Filter Logic:**
+- When "Same-Day Delivery" is selected, personalization and pre-order filters are automatically disabled
+- When personalization or pre-order is enabled, same-day delivery is automatically disabled
+- Filters work together intelligently to show only compatible product combinations
+
+**Infinite Scroll:**
+- Automatically loads more products as you scroll
+- Shows loading states during pagination
+- Handles "no more products" gracefully
+
+**Address-Aware:**
+- Automatically reloads when address changes
+- Shows availability based on current location
+- Updates product pricing and fulfillment options dynamically
+
+**Product Cards:**
+- Display product image, name, size, and price
+- Show availability status based on location
+- "Add to Cart" button (disabled if unavailable)
+- Clickable product links (if `productUrl` is provided)
+- Presale product support with special handling
+
+**Analytics Tracking:**
+- Automatically tracks `view_item_list` when products load
+- Tracks `select_item` when user clicks a product link
+- GTM integration for e-commerce events
+
+**Loading States:**
+- Shows skeleton loading cards during initial load
+- Displays loading indicator during infinite scroll
+- Error handling with user-friendly messages
+
+**Product URL Templates:**
+- Use `{upc}` placeholder for UPC-based URLs: `/product/{upc}`
+- Use `{grouping}` placeholder for Salsify grouping IDs: `/product/{grouping}`
+- Links open in new tab with proper security attributes
+
+#### Example: Category Page
+
+```html
+<div id="category-products"
+     data-liquid-commerce-elements-products-list
+     data-card="standard"
+     data-rows="4"
+     data-columns="4"
+     data-filters="personalization,delivery-options"
+     data-product-url="/products/{upc}">
+</div>
+
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+#### Example: Search Results
+
+```js
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production'
+});
+
+await client.injectProductList({
+  containerId: 'search-results',
+  rows: 6,
+  columns: 3,
+  cardVariant: 'standard',
+  fillCard: true,
+  filters: ['delivery-options'],
+  productUrl: '/search?q={grouping}'
+});
+```
+
+**Use cases:**
+- Category pages
+- Catalog pages
+- Search results
+- Filtered product browsing
+- Personalized product recommendations
+- Pre-order product showcases
+
 ---
 
 ## 🔧 Core Capabilities