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

package/docs/events.md

@@ -0,0 +1,181 @@
+# Events
+
+Events tell you what's happening in real-time: when products load, items get added to cart, checkout completes, and more. Use them to trigger analytics, show custom notifications, sync with your backend, or build reactive UI.
+
+## Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.EVENT_NAME', (event) => {
+  const data = event.detail.data;
+  const metadata = event.detail.metadata;
+});
+```
+
+### Event Metadata
+
+Every event includes metadata:
+
+```javascript
+{
+  eventId: string,           // Unique event ID
+  namespace: 'actions',      // Event namespace
+  event: string,             // Event name
+  originalEvent: string,     // Full namespaced event
+  actionNamespace?: string,  // 'address' | 'product' | 'cart' | 'checkout'
+  timestamp: number          // Unix timestamp
+}
+```
+
+---
+
+## Lifecycle Events
+
+| Event | Description |
+|-------|-------------|
+| `client_ready` | SDK initialized and ready to use |
+
+---
+
+## Product Events
+
+| Event | Description |
+|-------|-------------|
+| `product_loaded` | Product data fetched and displayed |
+| `product_add_to_cart` | Customer added product to cart |
+| `product_quantity_increase` | Quantity increased on product |
+| `product_quantity_decrease` | Quantity decreased on product |
+| `product_size_changed` | Size/variant selection changed |
+| `product_fulfillment_type_changed` | Shipping/on-demand type changed |
+| `product_fulfillment_changed` | Specific retailer/fulfillment changed |
+
+---
+
+## Address Events
+
+| Event | Description |
+|-------|-------------|
+| `address_updated` | Delivery location set or changed |
+| `address_cleared` | Delivery location removed |
+| `address_failed` | Address operation failed |
+
+---
+
+## Cart Events
+
+| Event | Description |
+|-------|-------------|
+| `cart_loaded` | Cart data fetched and ready |
+| `cart_opened` | Cart drawer opened |
+| `cart_closed` | Cart drawer closed |
+| `cart_updated` | Cart items or totals changed |
+| `cart_reset` | Cart cleared completely |
+| `cart_failed` | Cart operation failed |
+| `cart_item_added` | Item added to cart |
+| `cart_item_removed` | Item removed from cart |
+| `cart_item_quantity_increase` | Item quantity increased |
+| `cart_item_quantity_decrease` | Item quantity decreased |
+| `cart_item_engraving_updated` | Personalization added/changed/removed |
+| `cart_product_add_success` | Programmatic add succeeded |
+| `cart_product_add_failed` | Programmatic add failed |
+| `cart_promo_code_applied` | Discount code applied |
+| `cart_promo_code_removed` | Discount code removed |
+| `cart_promo_code_failed` | Discount code rejected |
+
+---
+
+## Checkout Events
+
+### Lifecycle
+
+| Event | Description |
+|-------|-------------|
+| `checkout_loaded` | Checkout ready |
+| `checkout_opened` | Checkout drawer opened |
+| `checkout_closed` | Checkout drawer closed |
+| `checkout_failed` | Checkout operation failed |
+
+### Submit
+
+| Event | Description |
+|-------|-------------|
+| `checkout_submit_started` | Payment processing started |
+| `checkout_submit_completed` | Order successfully placed |
+| `checkout_submit_failed` | Order submission failed |
+
+### Form Updates
+
+| Event | Description |
+|-------|-------------|
+| `checkout_customer_information_updated` | Customer form completed |
+| `checkout_billing_information_updated` | Billing form completed |
+| `checkout_gift_information_updated` | Gift form completed |
+| `checkout_is_gift_toggled` | Gift option toggled |
+| `checkout_billing_same_as_shipping_toggled` | Billing address option toggled |
+| `checkout_marketing_preferences_toggled` | Email/SMS opt-in toggled |
+
+### Item Changes
+
+| Event | Description |
+|-------|-------------|
+| `checkout_item_removed` | Item removed from checkout |
+| `checkout_item_quantity_increase` | Item quantity increased |
+| `checkout_item_quantity_decrease` | Item quantity decreased |
+| `checkout_item_engraving_updated` | Personalization changed |
+| `checkout_tip_updated` | Delivery tip changed |
+
+### Discounts
+
+| Event | Description |
+|-------|-------------|
+| `checkout_product_add_success` | Programmatic add succeeded |
+| `checkout_product_add_failed` | Programmatic add failed |
+| `checkout_promo_code_applied` | Discount applied |
+| `checkout_promo_code_removed` | Discount removed |
+| `checkout_promo_code_failed` | Discount rejected |
+| `checkout_gift_card_applied` | Gift card applied |
+| `checkout_gift_card_removed` | Gift card removed |
+| `checkout_gift_card_failed` | Gift card rejected |
+
+---
+
+## Listening to All Events
+
+Catch all action events with a namespace listener:
+
+```javascript
+// All action events
+window.addEventListener('lce:actions', (event) => {
+  const eventName = event.detail.metadata.event;
+  console.log('Event fired:', eventName);
+});
+```
+
+---
+
+## Security Notes
+
+Events are designed with security in mind:
+
+**Included in events:**
+- Success/failure status
+- Discount amounts (visible in UI)
+- Total amounts (visible in UI)
+- Item counts and identifiers
+
+**Never included:**
+- Promo codes or gift card codes
+- Gift card balances
+- Customer names, emails, addresses
+- Payment information
+
+Form update events (like `checkout_customer_information_updated`) only indicate completion, not actual customer data.
+
+---
+
+## See Also
+
+- [Actions Reference](./actions.md) - Programmatic control
+- [Product](./product.md) - Product component
+- [Cart](./cart.md) - Cart component
+- [Checkout](./checkout.md) - Checkout component
+- [Address](./address.md) - Address component

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