@liquidcommerce/elements-sdk 2.6.0-beta.7 → 2.6.0-beta.70

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

@@ -0,0 +1,507 @@
+# 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://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,brands,categories"
+  data-product-url="/product/{identifier}"
+></div>
+```
+
+**Attributes:**
+- `data-liquid-commerce-elements-products-list`: Product list container; value is the collection slug
+- `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-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,brands,fulfillment"></div>
+
+<!-- Product list -->
+<div
+  data-liquid-commerce-elements-products-list="my-collection-slug"
+  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',
+  slug: 'my-collection-slug',
+  rows: 3,
+  columns: 4,
+  filters: ['price', 'brands', 'categories', 'fulfillment'],
+  productUrl: '/product/{identifier}'
+});
+
+// Inject search (optional)
+await client.injectProductListSearch({
+  containerId: 'search',
+  slug: 'my-collection-slug'
+});
+
+// Inject filters (optional)
+await client.injectProductListFilters({
+  containerId: 'filters',
+  slug: 'my-collection-slug',
+  filters: ['price', 'brands']
+});
+```
+
+## Available Filters
+
+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
+// Example: use multiple filters
+filters: ['price', 'brands', 'categories', 'fulfillment', 'sizes']
+```
+
+## 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
+
+Search is controlled through the injected search component. Use `injectProductListSearch()` to add a search box that automatically filters the associated product list.
+
+## 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',
+  slug: 'my-collection',
+  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
+
+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: {
+        backgroundColor: '#ffffff'
+      },
+      layout: {
+        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
+
+```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://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <h1>Whiskey Collection</h1>
+  
+  <!-- Search -->
+  <div data-liquid-commerce-elements-products-list-search="whiskey-collection"></div>
+
+  <div class="catalog">
+    <!-- Filters sidebar -->
+    <aside>
+      <div data-liquid-commerce-elements-products-list-filters="whiskey-collection" data-filters="price,brands,sizes"></div>
+    </aside>
+
+    <!-- Product grid -->
+    <main>
+      <div
+        data-liquid-commerce-elements-products-list="whiskey-collection"
+        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' });
+
+// Inject product list with search
+await client.injectProductList({
+  containerId: 'search-results',
+  slug: 'all-products',
+  rows: 5,
+  columns: 4,
+  filters: ['price', 'brands', 'categories']
+});
+
+await client.injectProductListSearch({
+  containerId: 'search-box',
+  slug: 'all-products'
+});
+```
+
+### 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',
+  slug: 'all-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',
+  slug: 'all-products',
+  rows: 3,
+  columns: 4,
+  filters: ['price', 'brands'],  // 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
+
+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:actions.cart_item_added', (event) => {
+  console.log('Item added from product list:', event.detail.data);
+});
+```
+
+### 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',
+  slug: 'whiskey-collection',
+  rows: 4,
+  columns: 3,
+  filters: ['price', 'brands', 'sizes']  // 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

package/docs/v1/guides/theming.md

@@ -0,0 +1,216 @@
+# Theming Guide
+
+Customize the appearance of Elements SDK components to match your brand.
+
+## Overview
+
+The SDK provides extensive theming capabilities through the `customTheme` configuration option. Themes are structured hierarchically:
+
+- **Global**: Colors, fonts, and styles that apply to all components
+- **Component-specific**: Overrides for individual components
+
+## Global Theme Configuration
+
+### Colors
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        accentColor: '#28a745',
+        defaultTextColor: '#333333',
+        selectedTextColor: '#007bff',
+        linkTextColor: '#0056b3',
+        errorColor: '#dc3545',
+        warningColor: '#ffc107',
+        successColor: '#28a745',
+        drawerBackgroundColor: '#ffffff'
+      }
+    }
+  }
+});
+```
+
+### Typography
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      headingFont: {
+        name: 'Poppins',
+        weights: [400, 600, 700]
+      },
+      paragraphFont: {
+        name: 'Inter',
+        weights: [400, 500]
+      }
+    }
+  }
+}
+```
+
+### Border Radius
+
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      buttonCornerRadius: '8px',
+      cardCornerRadius: '12px'
+    }
+  }
+}
+```
+
+### Global Layout Options
+
+```javascript
+customTheme: {
+  global: {
+    layout: {
+      enablePersonalization: true,
+      personalizationText: 'Add Engraving',
+      personalizationCardStyle: 'outlined',  // or 'filled'
+      allowPromoCodes: true,
+      inputFieldStyle: 'outlined',  // or 'filled'
+      showPoweredBy: true,
+      poweredByMode: 'light'  // or 'dark'
+    }
+  }
+}
+```
+
+## Component Themes
+
+### Product Component
+
+```javascript
+customTheme: {
+  product: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      showImages: true,
+      showOnlyMainImage: false,
+      showTitle: true,
+      showDescription: true,
+      showQuantityCounter: true,
+      quantityCounterStyle: 'outlined',
+      fulfillmentDisplay: 'carousel',
+      enableShippingFulfillment: true,
+      enableOnDemandFulfillment: true,
+      addToCartButtonText: 'Add to Cart',
+      addToCartButtonShowTotalPrice: true,
+      buyNowButtonText: 'Buy Now',
+      prioritizeEngraving: false,
+      noAvailabilityText: 'Not available in your area'
+    }
+  }
+}
+```
+
+### Cart Component
+
+```javascript
+customTheme: {
+  cart: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      showQuantityCounter: true,
+      quantityCounterStyle: 'outlined',
+      drawerHeaderText: 'Your Shopping Cart',
+      goToCheckoutButtonText: 'Proceed to Checkout'
+    }
+  }
+}
+```
+
+### Checkout Component
+
+```javascript
+customTheme: {
+  checkout: {
+    theme: {
+      backgroundColor: '#ffffff'
+    },
+    layout: {
+      emailOptIn: {
+        show: true,
+        checked: false,
+        text: 'Subscribe to our newsletter for updates and offers.'
+      },
+      smsOptIn: {
+        show: true,
+        checked: false,
+        text: 'Receive SMS updates about your order and exclusive deals.'
+      },
+      allowGiftCards: true,
+      legalMessage: 'By placing your order, you agree to our Terms of Service and Privacy Policy.',
+      continueShoppingUrl: 'https://yoursite.com/shop',
+      exitUrl: 'https://yoursite.com',
+      thankYouButtonText: 'Continue Shopping',
+      drawerHeaderText: 'Checkout',
+      placeOrderButtonText: 'Place Order',
+      checkoutCompleted: {
+          customLogo: 'https://yoursite.com/logo.png',
+          customText: 'Thank you for your purchase! Your order has been received.'
+        }
+      }
+    }
+  }
+}
+```
+
+## Complete Example
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        accentColor: '#28a745',
+        buttonCornerRadius: '8px',
+        cardCornerRadius: '12px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600, 700]
+        },
+        paragraphFont: {
+          name: 'Inter',
+          weights: [400, 500]
+        }
+      },
+      layout: {
+        allowPromoCodes: true,
+        inputFieldStyle: 'outlined',
+        showPoweredBy: false
+      }
+    },
+    product: {
+      layout: {
+        addToCartButtonText: 'Add to Bag',
+        fulfillmentDisplay: 'popup'
+      }
+    },
+    cart: {
+      layout: {
+        checkoutButtonText: 'Checkout Now'
+      }
+    }
+  }
+});
+```
+
+## See Also
+
+- [Configuration Reference](../api/configuration.md)
+- [Component Guides](../guides/)