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

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

package/docs/{THEMING.md → theming.md}

@@ -677,5 +677,6 @@ customTheme: {
 
 ## Related Documentation
 
-- [Configuration Reference](./CONFIGURATION.md) - All SDK configuration options
-- [Troubleshooting Guide](./TROUBLESHOOTING.md) - Common theming issues
+- [Troubleshooting Guide](./troubleshooting.md) - Common theming issues
+- [Actions Reference](./actions.md) - Programmatic control
+- [Events Reference](./events.md) - Event system

package/docs/{TROUBLESHOOTING.md → troubleshooting.md}

@@ -54,7 +54,7 @@ Cart items have location-specific pricing, availability, and fulfillment options
 
 #### 3. Ad Blockers
 
-**Solution:** Configure a [proxy](./PROXY.md) to route requests through your domain.
+**Solution:** Configure a [proxy](./proxy.md) to route requests through your domain.
 
 ### Authentication Failures
 
@@ -785,9 +785,9 @@ If you're still experiencing issues:
 
 ## Related Documentation
 
-- [Configuration Reference](./CONFIGURATION.md) - Configuration options
-- [Actions Reference](./ACTIONS.md) - Programmatic control
-- [Events Reference](./EVENTS.md) - Event system
-- [Browser Support](./BROWSER_SUPPORT.md) - Browser compatibility
-- [Proxy Setup](./PROXY.md) - Proxy configuration
+- [Actions Reference](./actions.md) - Programmatic control
+- [Events Reference](./events.md) - Event system
+- [Browser Support](./browser-support.md) - Browser compatibility
+- [Proxy Setup](./proxy.md) - Proxy configuration
+- [Theming](./theming.md) - Customization options
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.38",
+  "version": "2.6.0-beta.39",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",