@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

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

@@ -0,0 +1,598 @@
+# Product List Component
+
+The Product List component provides a filterable, searchable product catalog with infinite scroll for building category pages and search results.
+
+## Overview
+
+The Product List component:
+- Displays products in a responsive grid
+- Supports infinite scroll pagination
+- Provides search functionality
+- Offers advanced filtering options
+- Links to product detail pages
+- Shows real-time availability
+- Supports add-to-cart from list view
+
+## Basic Usage
+
+### Declarative Setup
+
+Use data attributes to configure the product list:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div
+  data-liquid-commerce-elements-products-list
+  data-rows="3"
+  data-columns="4"
+  data-filters="price,brand,category"
+  data-product-url="/product/{identifier}"
+></div>
+```
+
+**Attributes:**
+- `data-liquid-commerce-elements-products-list`: Marks element as product list container
+- `data-rows`: Number of rows to display (default: 3)
+- `data-columns`: Number of columns (default: 4)
+- `data-filters`: Comma-separated filter types
+- `data-product-url`: URL pattern for product detail pages (optional)
+
+The `{identifier}` placeholder in `data-product-url` is replaced with the product's identifier.
+
+### With Search and Filters
+
+Separate containers for search and filters:
+
+```html
+<!-- Search container -->
+<div data-search-container></div>
+
+<!-- Filters container -->
+<div data-filters-container data-filters="price,brand,fulfillment"></div>
+
+<!-- Product list -->
+<div
+  data-liquid-commerce-elements-products-list
+  data-rows="4"
+  data-columns="3"
+  data-product-url="/products/{identifier}"
+></div>
+```
+
+### Programmatic Setup
+
+Use JavaScript for dynamic configuration:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+// Inject product list
+await client.injectProductList({
+  containerId: 'products',
+  rows: 3,
+  columns: 4,
+  filters: ['price', 'brand', 'category', 'fulfillment'],
+  productUrl: '/product/{identifier}'
+});
+
+// Inject search (optional)
+await client.injectProductListSearch({
+  containerId: 'search'
+});
+
+// Inject filters (optional)
+await client.injectProductListFilters({
+  containerId: 'filters',
+  filters: ['price', 'brand']
+});
+```
+
+## Available Filters
+
+### Price Range
+
+Filter products by price:
+
+```javascript
+filters: ['price']
+```
+
+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
+
+The search component provides full-text search across:
+- Product names
+- Descriptions
+- Brand names
+- Categories
+- SKUs/UPCs
+
+### Search Behavior
+
+- Real-time search as user types (debounced)
+- Minimum 2 characters to trigger search
+- Highlights matching terms in results
+- Shows result count
+- "Clear search" button appears when active
+
+### 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');
+```
+
+## Grid Layout
+
+### Responsive Grid
+
+The grid automatically adjusts for screen sizes:
+
+**Desktop** (> 1024px):
+- Uses configured columns (e.g., 4 columns)
+
+**Tablet** (768px - 1024px):
+- Reduces to 3 or 2 columns
+
+**Mobile** (< 768px):
+- Single column or 2 columns depending on space
+
+### Configuring Layout
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  rows: 5,        // Number of rows per page
+  columns: 4      // Columns in grid (desktop)
+});
+```
+
+Total products per page = rows × columns (e.g., 5 × 4 = 20 products)
+
+## Infinite Scroll
+
+### How It Works
+
+1. Initial products load (rows × columns)
+2. User scrolls to bottom
+3. Next page loads automatically
+4. Appends to existing products
+5. Continues until all products shown
+
+### Loading States
+
+Shows loading indicator:
+- On initial load
+- When loading next page
+- When applying filters
+- When searching
+
+### End of Results
+
+When all products are shown:
+- Infinite scroll stops
+- Shows "No more products" message
+- Scroll to top button may appear
+
+## Product Cards
+
+Each product card shows:
+
+- Product image
+- Product name
+- Brand
+- Price (or price range for multiple sizes)
+- Rating (if available)
+- "Quick View" or "View Details" button
+- "Add to Cart" button (optional)
+- Availability indicator
+
+### Card Interaction
+
+**Click on card:** Navigate to product detail page (if `productUrl` configured)
+
+**Quick Add:** Add product to cart directly from list view (if enabled)
+
+**Click on image:** Open image in lightbox or navigate to product page
+
+## Customization
+
+### Theme Configuration
+
+```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)'
+      },
+      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
+      }
+    }
+  }
+});
+```
+
+## Use Cases
+
+### Category Page
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Whiskey Collection</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+</head>
+<body>
+  <h1>Whiskey Collection</h1>
+  
+  <!-- Search -->
+  <div data-search-container></div>
+  
+  <div class="catalog">
+    <!-- Filters sidebar -->
+    <aside>
+      <div data-filters-container data-filters="price,brand,size"></div>
+    </aside>
+    
+    <!-- Product grid -->
+    <main>
+      <div
+        data-liquid-commerce-elements-products-list
+        data-rows="4"
+        data-columns="3"
+        data-product-url="/whiskey/{identifier}"
+      ></div>
+    </main>
+  </div>
+</body>
+</html>
+```
+
+### Search Results Page
+
+```javascript
+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
+await client.injectProductList({
+  containerId: 'search-results',
+  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
+  });
+});
+
+// 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
+  });
+});
+```
+
+### Custom Product URL Patterns
+
+Different URL patterns for different product types:
+
+```javascript
+// Get product type from data
+const productType = getProductTypeFromData();
+
+let urlPattern;
+switch (productType) {
+  case 'whiskey':
+    urlPattern = '/spirits/whiskey/{identifier}';
+    break;
+  case 'wine':
+    urlPattern = '/wine/{identifier}';
+    break;
+  default:
+    urlPattern = '/products/{identifier}';
+}
+
+await client.injectProductList({
+  containerId: 'products',
+  rows: 3,
+  columns: 4,
+  productUrl: urlPattern
+});
+```
+
+## Events
+
+While product list events are primarily internal, you can listen for cart events when users add products:
+
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { itemId, quantity } = event.detail.data;
+  console.log(`Product added from list: ${itemId}`);
+});
+```
+
+## Accessibility
+
+The product list component includes:
+
+- Keyboard navigation support
+- Screen reader labels
+- ARIA attributes for filters and search
+- Focus management
+- High contrast support
+
+### Keyboard Shortcuts
+
+- `Tab`: Navigate between products and filters
+- `Enter/Space`: Select product or toggle filter
+- `Escape`: Clear search or close filters
+- `Arrow keys`: Navigate grid (when focused)
+
+## Performance
+
+### Optimization Features
+
+- **Image lazy loading**: Images load as they enter viewport
+- **Virtual scrolling**: Only renders visible products
+- **Debounced search**: Reduces API calls during typing
+- **Filter caching**: Caches filter results
+- **Progressive loading**: Loads in batches
+
+### Large Catalogs
+
+For catalogs with thousands of products:
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  rows: 3,
+  columns: 4,
+  filters: ['price', 'brand'],  // Limit filters to most useful
+  // More rows = larger pages = fewer API calls
+});
+```
+
+## Best Practices
+
+### Provide Clear Navigation
+
+```html
+<nav class="breadcrumb">
+  <a href="/">Home</a> &gt;
+  <a href="/products">Products</a> &gt;
+  <span>Whiskey</span>
+</nav>
+```
+
+### Show Result Counts
+
+Display the number of products found:
+
+```javascript
+window.addEventListener('lce:productList.updated', (event) => {
+  const { totalProducts, displayedProducts } = event.detail;
+  document.getElementById('result-count').textContent = 
+    `Showing ${displayedProducts} of ${totalProducts} products`;
+});
+```
+
+### Mobile-First Design
+
+Ensure filters work well on mobile:
+
+```css
+@media (max-width: 768px) {
+  .filters-sidebar {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    transform: translateY(100%);
+    transition: transform 0.3s;
+  }
+  
+  .filters-sidebar.open {
+    transform: translateY(0);
+  }
+}
+```
+
+### Default to Relevant Filters
+
+For category pages, pre-select relevant filters:
+
+```javascript
+// On whiskey category page
+await client.injectProductList({
+  containerId: 'products',
+  rows: 4,
+  columns: 3,
+  filters: ['price', 'brand', 'size']  // Most relevant for whiskey
+});
+```
+
+## Troubleshooting
+
+### Products Not Loading
+
+1. Check browser console for errors
+2. Verify API key is correct
+3. Ensure container ID exists
+4. Check network tab for API responses
+5. Verify products exist in catalog
+
+### Filters Not Working
+
+1. Ensure filter types are spelled correctly
+2. Check that products have filterable attributes
+3. Verify theme config allows filters
+4. Look for JavaScript errors
+
+### Infinite Scroll Not Triggering
+
+1. Check container has finite height
+2. Verify scroll event listeners are attached
+3. Ensure there are more products to load
+4. Check console for errors
+
+### Search Not Finding Products
+
+1. Verify minimum character count is met (2 chars)
+2. Check search is not case-sensitive (it shouldn't be)
+3. Ensure products have searchable text fields
+4. Look for API errors in network tab
+
+## See Also
+
+- [Product Component](./product-component.md) - Individual product display
+- [Cart Component](./cart-component.md) - Add products to cart
+- [Theming](./theming.md) - Customize appearance
+- [Events](./events.md) - Available events