@liquidcommerce/elements-sdk 2.6.0-beta.37 → 2.6.0-beta.39

package/docs/product-list.md

@@ -0,0 +1,311 @@
+# Product List
+
+The product list component displays a filterable, searchable grid of products with infinite scroll pagination. Ideal for category pages, search results, and "shop all" experiences where customers browse and discover products.
+
+## Overview
+
+The product list element provides:
+- Responsive product grid layout
+- Rich filtering (14 filter types)
+- Search functionality
+- Infinite scroll pagination
+- Address-aware inventory (reloads on location change)
+- Add to cart from product cards
+- Product links with tracking
+- Automatic GTM integration
+
+Clicking a product can open a modal/drawer or navigate to a detail page - your choice.
+
+---
+
+## Declarative Setup (HTML Attributes)
+
+Add a product list to any page with data attributes.
+
+### Basic Setup
+
+```html
+<div data-liquid-commerce-elements-products-list
+     data-rows="3"
+     data-columns="4"
+     data-filters="price,brands,categories"
+     data-product-url="/product/{upc}">
+</div>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Configuration Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data-liquid-commerce-elements-products-list` | - | - | Enables product list |
+| `data-rows` | 1-10 | 3 | Number of rows per page |
+| `data-columns` | 1-4 | 4 | Number of columns in grid |
+| `data-filters` | string | - | Comma-separated filter types |
+| `data-product-url` | string | - | Product page URL template |
+
+### Product URL Template
+
+Use `{upc}` or `{grouping}` as placeholders:
+
+```html
+<!-- Using UPC -->
+<div data-product-url="/product/{upc}" ...></div>
+
+<!-- Using Salsify grouping -->
+<div data-product-url="/products/{grouping}" ...></div>
+```
+
+### Available Filters
+
+| Filter | Description |
+|--------|-------------|
+| `engraving` | Engravable/personalizable products |
+| `presale` | Pre-order products |
+| `fulfillment` | Delivery type (shipping, on-demand) |
+| `price` | Price range slider |
+| `brands` | Brand multi-select |
+| `categories` | Category multi-select |
+| `flavor` | Flavor profiles |
+| `region` | Geographic regions |
+| `variety` | Product varieties |
+| `vintage` | Vintage years |
+| `country` | Country of origin |
+| `appellation` | Wine appellations |
+| `materials` | Product materials |
+| `sizes` | Size options |
+
+### Separate Search and Filters
+
+Place search and filters in different containers:
+
+```html
+<div id="search-bar"></div>
+<div id="filter-sidebar"></div>
+<div id="product-grid" data-liquid-commerce-elements-products-list
+     data-search-container="search-bar"
+     data-filters-container="filter-sidebar"
+     data-rows="4"
+     data-columns="3"
+     data-filters="price,brands,categories,variety">
+</div>
+```
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-search-container` | Container ID for search input |
+| `data-filters-container` | Container ID for filter panel |
+
+---
+
+## Programmatic Setup (JavaScript API)
+
+Inject product list components programmatically.
+
+### Product List Grid
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectProductList({
+  containerId: 'product-list-container',
+  rows: 3,
+  columns: 4,
+  filters: ['price', 'brands', 'categories', 'variety'],
+  productUrl: '/product/{upc}'
+});
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | Container element ID |
+| `rows` | number | No | Rows per page (1-10, default: 3) |
+| `columns` | number | No | Columns in grid (1-4, default: 4) |
+| `filters` | string[] | No | Filter types to enable |
+| `productUrl` | string | No | Product page URL template |
+
+### Search Component
+
+Inject a standalone search input:
+
+```javascript
+await client.injectProductListSearch({
+  containerId: 'search-container'
+});
+```
+
+### Filters Component
+
+Inject a standalone filter panel:
+
+```javascript
+await client.injectProductListFilters({
+  containerId: 'filters-container',
+  filters: ['price', 'brands', 'categories', 'variety']
+});
+```
+
+---
+
+## Actions
+
+Product list-specific actions are coming soon. For now, individual products in the list use standard [product actions](./actions.md#product-actions).
+
+---
+
+## Events
+
+The product list emits standard product events for interactions with individual items.
+
+### Product Events in List
+
+When customers interact with products in the list, these events fire:
+
+| Event | Description |
+|-------|-------------|
+| `product_loaded` | Product card data fetched |
+| `product_add_to_cart` | Item added from product card |
+
+### GTM Events
+
+The product list automatically tracks:
+
+| GTM Event | Trigger |
+|-----------|---------|
+| `view_item_list` | Products displayed |
+| `select_item` | Product clicked |
+| `add_to_cart` | Added from card |
+
+### Example: Track Product Clicks
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  // A product in the list was loaded
+  const { name, brand, identifier } = event.detail.data;
+  console.log('Product displayed:', name);
+});
+```
+
+---
+
+## Features
+
+### Infinite Scroll
+
+Products load automatically as customers scroll. No pagination buttons needed.
+
+### Smart Filters
+
+Filters show only relevant options based on current inventory. If no products match a filter option, it's hidden.
+
+### Address-Aware
+
+The product list automatically reloads when the customer changes their delivery address, showing:
+- Updated availability
+- Location-specific pricing
+- Relevant fulfillment options
+
+### Loading States
+
+The component shows skeleton loading states while fetching products, providing smooth user experience.
+
+---
+
+## Use Cases
+
+### Category Page
+
+```html
+<div class="page-layout">
+  <aside id="sidebar-filters"></aside>
+  <main>
+    <div id="search-area"></div>
+    <div id="products"
+         data-liquid-commerce-elements-products-list
+         data-search-container="search-area"
+         data-filters-container="sidebar-filters"
+         data-rows="4"
+         data-columns="3"
+         data-filters="price,brands,categories,flavor,variety"
+         data-product-url="/shop/{grouping}">
+    </div>
+  </main>
+</div>
+```
+
+### Simple Product Grid
+
+```html
+<div data-liquid-commerce-elements-products-list
+     data-rows="2"
+     data-columns="4"
+     data-product-url="/product/{upc}">
+</div>
+```
+
+No filters, just a browsable product grid.
+
+### Search Results Page
+
+```javascript
+await client.injectProductList({
+  containerId: 'search-results',
+  rows: 5,
+  columns: 4,
+  filters: ['fulfillment', 'price', 'brands'],
+  productUrl: '/product/{upc}'
+});
+
+await client.injectProductListSearch({
+  containerId: 'search-box'
+});
+```
+
+---
+
+## Customization
+
+Style the product list through theme configuration.
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    // Product card styling applies to list items
+    product: {
+      // Theme options
+    }
+  }
+});
+```
+
+### Display Modes
+
+Product cards in the list can open in:
+- **Modal** - Product details overlay
+- **Drawer** - Slide-out panel
+- **Navigate** - Go to product page (via `productUrl`)
+
+See [theming.md](./theming.md) for product list theme options including:
+- Card layout
+- Grid spacing
+- Filter panel styling
+- Display mode configuration
+
+---
+
+## See Also
+
+- [Product](./product.md) - Individual product component
+- [Actions Reference](./actions.md) - All available actions
+- [Events Reference](./events.md) - All available events
+- [Theming Guide](./theming.md) - Customization options

package/docs/product.md

@@ -0,0 +1,250 @@
+# Product
+
+The product element is the heart of the SDK - it displays product information, handles size and variant selection, shows real-time pricing based on delivery location, and lets customers add items to their cart.
+
+## Overview
+
+The product element renders a complete product card with:
+- Product imagery and details
+- Size/variant selection
+- Real-time pricing based on delivery address
+- Fulfillment options (shipping vs on-demand delivery)
+- Quantity controls
+- Add to cart functionality
+- Personalization/engraving options (when available)
+
+The component automatically adapts to the customer's delivery address, showing only available fulfillment options and location-specific pricing.
+
+---
+
+## Declarative Setup (HTML Attributes)
+
+Add products to your page without writing JavaScript. Choose the method that fits your use case.
+
+### Method 1: Direct Attributes
+
+Best for static pages with known products. Add products directly in the script tag:
+
+```html
+<div id="product-1"></div>
+<div id="product-2"></div>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-1"
+  data-product-1="00619947000020"
+  data-container-2="product-2"
+  data-product-2="00832889005513"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+The pattern is `data-container-N` paired with `data-product-N` where N is any number.
+
+### Method 2: JSON Configuration
+
+Best for CMS platforms and dynamic content. Configure products via a JSON script block:
+
+```html
+<div id="product-1"></div>
+<div id="product-2"></div>
+
+<script data-liquid-commerce-elements-products type="application/json">
+[
+  { "containerId": "product-1", "identifier": "00619947000020" },
+  { "containerId": "product-2", "identifier": "00832889005513" }
+]
+</script>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+This approach works well with templating engines and server-side rendering.
+
+### Method 3: Annotated Elements
+
+Best for product grids and lists. Mark any div with a data attribute:
+
+```html
+<div class="product-grid">
+  <div data-lce-product="00619947000020"></div>
+  <div data-lce-product="00832889005513"></div>
+  <div data-lce-product="00851468007252"></div>
+</div>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+The SDK automatically finds and initializes all elements with `data-lce-product`.
+
+---
+
+## Programmatic Setup (JavaScript API)
+
+For full control, inject products using the client API.
+
+### Basic Injection
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+const components = await client.injectProductElement([
+  { containerId: 'pdp-1', identifier: '00619947000020' },
+  { containerId: 'pdp-2', identifier: '00832889005513' }
+]);
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of the container element |
+| `identifier` | string | Yes | Product UPC, ID, or Salsify grouping ID |
+
+### Return Value
+
+Returns `IInjectedComponent[]` - an array of component wrappers with these methods:
+
+```javascript
+// Get the container element
+const element = components[0].getElement();
+
+// Get the component type
+const type = components[0].getType(); // 'product'
+
+// Force a re-render
+components[0].rerender();
+```
+
+### Dynamic Product Loading
+
+Load products dynamically based on user actions:
+
+```javascript
+// Load product when user clicks a button
+document.querySelector('#load-product').addEventListener('click', async () => {
+  await client.injectProductElement([
+    { containerId: 'dynamic-product', identifier: selectedProductId }
+  ]);
+});
+```
+
+---
+
+## Actions
+
+Control and query product state programmatically.
+
+### Get Product Details
+
+Retrieve the current state of a displayed product:
+
+```javascript
+const details = window.elements.actions.product.getDetails('00619947000020');
+
+// Returns product data including:
+// - name, brand, category
+// - selectedSizeId, selectedFulfillmentType
+// - availability status
+// - pricing information
+```
+
+---
+
+## Events
+
+Listen to product interactions and state changes.
+
+### Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { data, metadata } = event.detail;
+  console.log('Product loaded:', data.name);
+});
+```
+
+### Available Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `product_loaded` | Product data fetched and displayed | Full product details |
+| `product_add_to_cart` | Customer added product to cart | identifier, fulfillmentId, quantity |
+| `product_quantity_increase` | Quantity increased | identifier, quantity, previousQuantity |
+| `product_quantity_decrease` | Quantity decreased | identifier, quantity, previousQuantity |
+| `product_size_changed` | Size selection changed | identifier, selectedSizeId, previousSizeId |
+| `product_fulfillment_type_changed` | Shipping/on-demand changed | identifier, selectedFulfillmentType |
+| `product_fulfillment_changed` | Retailer selection changed | identifier, selectedFulfillmentId |
+
+### Example: Track Add to Cart
+
+```javascript
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { identifier, quantity, fulfillmentId } = event.detail.data;
+
+  // Send to analytics
+  analytics.track('Product Added', {
+    productId: identifier,
+    quantity: quantity,
+    fulfillment: fulfillmentId
+  });
+});
+```
+
+---
+
+## Customization
+
+Style product components through the theme configuration.
+
+### Basic Theming
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px'
+      }
+    },
+    product: {
+      // Product-specific theme options
+    }
+  }
+});
+```
+
+### Product Theme Options
+
+See [theming.md](./theming.md) for the complete list of product theme options including:
+- Layout configuration
+- Color overrides
+- Typography settings
+- Spacing and sizing
+
+---
+
+## See Also
+
+- [Actions Reference](./actions.md) - All available actions
+- [Events Reference](./events.md) - All available events
+- [Theming Guide](./theming.md) - Customization options