@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.131

package/docs/v1/guides/cart-component.md

@@ -0,0 +1,802 @@
+# Cart Component
+
+The Cart component provides a slide-out drawer for managing shopping cart items, applying promo codes, and proceeding to checkout.
+
+## Overview
+
+The Cart component automatically:
+- Displays cart items with images and details
+- Removes white / near-white backgrounds from item images so products blend into the drawer (automatic, not host-configurable)
+- Groups items by retailer
+- Shows real-time pricing and totals
+- Supports quantity updates
+- Handles promo code application
+- Persists cart across sessions and tabs
+- Provides checkout navigation
+
+A same-day line from a store that is closed now but takes orders for later (its fulfillment's `deliveryAvailability` says it cannot deliver now and can schedule) shows "Schedule delivery" in place of the delivery estimate. The shopper chooses the delivery window in checkout.
+
+## Basic Usage
+
+The cart is automatically available when using the SDK - no explicit injection needed for the drawer. However, you need a way for users to open it.
+
+### Cart Buttons
+
+#### Declarative Cart Button
+
+Add a cart button using data attributes on the SDK script:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button="header-cart"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div id="header-cart"></div>
+```
+
+#### Cart Button with Item Count Badge
+
+Show the number of items in the cart:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-badge-button="header-cart"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div id="header-cart"></div>
+```
+
+#### Floating Cart Button
+
+Create a floating button (top-right corner):
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+Leaving `data-cart-button` empty creates a floating button automatically.
+
+#### Positional Cart Button
+
+Control where the cart button appears:
+
+```html
+<!-- Inside an element -->
+<script data-cart-button="inside:#header"></script>
+
+<!-- Above an element -->
+<script data-cart-button="above:.navigation"></script>
+
+<!-- Below an element -->
+<script data-cart-button="below:#logo"></script>
+
+<!-- Replace an element -->
+<script data-cart-button="replace:#cart-placeholder"></script>
+```
+
+#### Hide Cart Button
+
+If you want to control cart opening manually:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button-hidden
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+#### Programmatic Cart Button
+
+Create cart buttons using JavaScript:
+
+```javascript
+// Button in a container
+window.LiquidCommerce.elements.ui.cartButton('my-container', false);  // No badge
+
+// Button with item count
+window.LiquidCommerce.elements.ui.cartButton('my-container', true);  // With badge
+
+// Floating button
+window.LiquidCommerce.elements.ui.floatingCartButton(true);  // With badge
+```
+
+### Custom Toggle Buttons
+
+Use your own button to toggle the cart:
+
+```html
+<button data-lce-cart-toggle-button>
+  View Cart
+</button>
+```
+
+The SDK automatically adds click handlers to elements with `data-lce-cart-toggle-button`.
+
+## Cart Actions
+
+### Open Cart
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+### Close Cart
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.closeCart();
+```
+
+### Toggle Cart
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.toggleCart();
+```
+
+### Add Product to Cart
+
+Add products programmatically:
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',  // or 'onDemand'
+    quantity: 2
+  },
+  {
+    identifier: '08504405135',
+    fulfillmentType: 'onDemand',
+    quantity: 1
+  }
+], true);  // true = open cart after adding
+```
+
+**Parameters:**
+- `identifier` (string): Product UPC, size ID, or salsifyGrouping ID
+- `fulfillmentType` (string): `'shipping'` or `'onDemand'`
+- `quantity` (number): Number of items (default: 1)
+- `engravingLines` (string[], optional): Engraving text lines for the product (applied when the product/variant supports engraving; ignored otherwise)
+- Second parameter (boolean): Open cart after adding (default: false)
+
+### Apply Promo Code
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.applyPromoCode('SUMMER20');
+```
+
+The SDK automatically:
+- Validates the promo code
+- Calculates discount
+- Updates cart totals
+- Shows success/error message
+
+### Remove Promo Code
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.removePromoCode();
+```
+
+### Reset Cart
+
+Clear all items from the cart:
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.resetCart();
+```
+
+### Get Cart Details
+
+Retrieve current cart information:
+
+```javascript
+const cartData = window.LiquidCommerce.elements.actions.cart.getDetails();
+
+console.log(cartData);
+// {
+//   cartId: 'cart_abc123',
+//   promoCodeDiscount: 1000,  // number | null
+//   subtotal: 9998,  // in cents
+//   itemCount: 5,
+//   items: {...},  // Record<itemId, ICartItem>
+//   retailers: {...},  // Record<retailerId, ICartRetailer>
+//   location: {...},  // or null
+//   ...
+// }
+```
+
+## Cart UI Helpers
+
+### Display Cart Subtotal
+
+Show cart subtotal anywhere on your page:
+
+```html
+<div>
+  Cart Total: <span id="cart-total"></span>
+</div>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
+}, { once: true });
+</script>
+```
+
+The element automatically updates when the cart changes.
+
+### Display Items Count
+
+Show the number of items in the cart:
+
+```html
+<div>
+  Items: <span id="items-count"></span>
+</div>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartItemsCount('items-count', {
+    hideZero: true  // Hide when cart is empty
+  });
+}, { once: true });
+</script>
+```
+
+Or using data attributes:
+
+```html
+<!-- Always show count, even when 0 -->
+<span data-lce-cart-items-count="keep-zero"></span>
+
+<!-- Hide when 0 (default behavior) -->
+<span data-lce-cart-items-count></span>
+```
+
+## Events
+
+### `lce:actions.cart_shop_retailer`
+
+A shopper activated **Shop {retailer}** from an unmet cart fulfillment minimum. Opt in with
+`customTheme.cart.layout.showShopRetailerButton: true` (default `false`). The cart command
+revalidates the fulfillment, its current retailer and items, fulfillment type, and remaining
+minimum before emitting. Unsupported, empty, stale or already-satisfied fulfillments emit nothing.
+
+```typescript
+interface ICartShopRetailerEventData {
+  retailerId: string;
+  fulfillmentId: string;
+  fulfillmentType: 'onDemand' | 'shipping';
+}
+```
+
+Listen with the exported constant; the usual event envelope is `{ data, metadata }`:
+
+```javascript
+window.addEventListener(`lce:actions.${ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER}`, (event) => {
+  const { retailerId, fulfillmentId, fulfillmentType } = event.detail.data;
+  // Revalidate against client.actions.cart.getDetails(), then close the drawer
+  // and route to your catalog scoped to this retailer and fulfillment type.
+});
+```
+
+The SDK leaves the drawer open and does not navigate. The host handles routing and derives
+retailer names, totals and minimums from current cart details. The event is also sent to `lce:actions`.
+
+
+
+### Cart Loaded
+
+Fired when cart data is loaded:
+
+```javascript
+window.addEventListener('lce:actions.cart_loaded', (event) => {
+  const { cartId, itemCount, subtotal } = event.detail.data;
+  console.log(`Cart loaded: ${itemCount} items, total: $${subtotal / 100}`);
+});
+```
+
+### Cart Opened/Closed
+
+```javascript
+window.addEventListener('lce:actions.cart_opened', (event) => {
+  console.log('Cart drawer opened');
+});
+
+window.addEventListener('lce:actions.cart_closed', (event) => {
+  console.log('Cart drawer closed');
+});
+```
+
+### Cart Updated
+
+Fired whenever cart contents change:
+
+```javascript
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { cartId, itemCount, subtotal } = event.detail.data.current;
+  console.log('Cart updated:', itemCount, 'items');
+});
+```
+
+### Item Added
+
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { cartId, itemId, quantity } = event.detail.data;
+  console.log(`Item ${itemId} added (quantity: ${quantity})`);
+});
+```
+
+### Item Removed
+
+```javascript
+window.addEventListener('lce:actions.cart_item_removed', (event) => {
+  const { cartId, itemId } = event.detail.data;
+  console.log(`Item ${itemId} removed`);
+});
+```
+
+### Quantity Changed
+
+```javascript
+window.addEventListener('lce:actions.cart_item_quantity_increase', (event) => {
+  const { cartId, itemId, quantity } = event.detail.data;
+  console.log(`Item ${itemId} quantity increased to ${quantity}`);
+});
+
+window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
+  const { cartId, itemId, quantity } = event.detail.data;
+  console.log(`Item ${itemId} quantity decreased to ${quantity}`);
+});
+```
+
+### Engraving Updated
+
+Fired when a cart line item's engraving is added or edited from the drawer (see [Engraving](#engraving)):
+
+```javascript
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { cartId, itemId, engravingLines, previousEngravingLines } = event.detail.data;
+  console.log(`Engraving updated for ${itemId}:`, engravingLines);
+});
+```
+
+### Promo Code Events
+
+```javascript
+window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
+  const { cartId, discount, newSubtotal } = event.detail.data;
+  console.log(`Promo code applied: $${discount / 100} off`);
+});
+
+window.addEventListener('lce:actions.cart_promo_code_removed', (event) => {
+  const { cartId, newSubtotal } = event.detail.data;
+  console.log('Promo code removed');
+});
+
+window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
+  const { cartId, error } = event.detail.data;
+  console.error('Promo code failed:', error);
+});
+```
+
+### Product Add Success/Failure
+
+```javascript
+window.addEventListener('lce:actions.cart_product_add_success', (event) => {
+  const { cartId, itemsAdded, identifiers } = event.detail.data;
+  console.log(`Successfully added ${itemsAdded} products`);
+});
+
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  const { cartId, identifiers, error } = event.detail.data;
+  console.error('Failed to add products:', error);
+});
+```
+
+### Cart Reset
+
+```javascript
+window.addEventListener('lce:actions.cart_reset', (event) => {
+  console.log('Cart has been reset');
+});
+```
+
+## Customization
+
+### Theme Configuration
+
+Customize cart appearance:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    cart: {
+      theme: {
+        backgroundColor: '#ffffff'
+      },
+      layout: {
+        showShopRetailerButton: false, // Enable only with a cart_shop_retailer event handler
+        showQuantityCounter: true,
+        quantityCounterStyle: 'outlined',  // or 'ghost'
+        drawerHeaderText: 'My Bag',
+        goToCheckoutButtonText: 'Checkout'
+      }
+    }
+  }
+});
+```
+
+### Shop the same retailer
+
+Set `customTheme.cart.layout.showShopRetailerButton: true` to show a native **Shop {retailer}**
+button beside each unmet order-minimum warning (below it on mobile). The default is `false`,
+including when the server theme predates this option. It only appears for a current, nonempty
+`onDemand` or `shipping` fulfillment with a positive amount remaining and valid retailer ownership.
+
+Handle `ELEMENTS_ACTIONS_EVENT.CART_SHOP_RETAILER` (`lce:actions.cart_shop_retailer`) to close the
+cart and open your retailer-filtered catalog. The SDK emits identifiers only and performs no
+navigation. Revalidate them against `client.actions.cart.getDetails()` before navigating; see
+[Events](./events.md) for the payload.
+
+## State Persistence
+
+### Local Storage
+
+The cart automatically persists to `localStorage`
+
+This allows the cart to survive:
+- Page refreshes
+- Browser restarts
+- Navigation between pages
+
+### Cross-Tab Persistence
+
+The cart is persisted to `localStorage` and reloaded on a fresh page load. The SDK does **not** provide live cross-tab synchronization — changes made in one tab will not automatically appear in other already-open tabs (there is no `storage` listener, `BroadcastChannel`, or polling). Another tab reflects the change only after it reloads.
+
+### Session Duration
+
+Cart and address session IDs are persisted in `localStorage` (with an API fallback) and are not automatically cleared by the SDK; cart lifetime/expiry is governed by server-side policy.
+
+## Address Requirement
+
+The cart requires a delivery address for:
+- Accurate availability
+- Correct pricing
+- Shipping calculations
+
+### Automatic Address Prompt
+
+If no address is set when adding to cart, the SDK:
+1. Opens address input drawer
+2. Waits for user to set address
+3. Retries the add-to-cart operation
+
+### Pre-set Address
+
+Set address before adding to cart:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId('ChIJ...');
+
+// Now add to cart
+await window.LiquidCommerce.elements.actions.cart.addProduct([...]);
+```
+
+## Promo Codes
+
+### Configuration
+
+Enable/disable promo codes globally:
+
+```javascript
+customTheme: {
+  global: {
+    layout: {
+      allowPromoCodes: true  // or false to disable
+    }
+  }
+}
+```
+
+### Promo Ticker
+
+Show promotional codes in a scrolling ticker:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  promoTicker: [
+    {
+      promoCode: 'SUMMER20',
+      text: ['20% Off Summer Sale', 'Free Shipping on Orders Over $50'],
+      separator: '•',
+      activeFrom: '2024-06-01T00:00:00Z',
+      activeUntil: '2024-08-31T23:59:59Z'
+    }
+  ]
+});
+```
+
+Or with data attributes:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-promo-code="SUMMER20"
+  data-promo-text="20% Off Summer Sale | Free Shipping on Orders Over $50"
+  data-promo-separator="•"
+  data-promo-active-from="2024-06-01T00:00:00Z"
+  data-promo-active-until="2024-08-31T23:59:59Z"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+### Auto-Apply from URL
+
+Apply promo codes automatically via URL parameters:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-promo-code-param="lce_promo"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+Now visiting `https://yoursite.com?lce_promo=SUMMER20` automatically applies the code.
+
+**Security Note:** Query parameters must start with `lce_` prefix to prevent conflicts with your application.
+
+## Retailer Grouping
+
+Items are automatically grouped by retailer in the cart:
+
+```
+┌─────────────────────────────────────┐
+│ Cart (3 items)                      │
+├─────────────────────────────────────┤
+│ Spirits Shop                        │
+│   • Premium Whiskey (750ml)    $49  │
+│   • Bourbon Bottle (1L)        $65  │
+│                                      │
+│ Wine & More                         │
+│   • Red Wine (750ml)           $25  │
+├─────────────────────────────────────┤
+│ Subtotal:                     $139  │
+│ Promo Code (SUMMER20):        -$28  │
+│ Total:                        $111  │
+└─────────────────────────────────────┘
+```
+
+## Order Minimums
+
+Retailers can require a minimum purchase amount before their items can be checked out. The cart enforces this per retailer:
+
+- When a retailer's minimum is not met, the cart drawer shows a per-retailer alert reading `+$X needed for order minimum`, where `$X` is the remaining amount required for that retailer.
+- The **Checkout** button is disabled until every retailer's minimum is met. (It is also disabled while the cart is loading/updating or when the cart is empty.)
+
+No configuration is required — the minimums are defined by each retailer and enforced automatically.
+
+## Engraving
+
+For engravable items, shoppers can add or edit engraving directly from a cart line item, without leaving the drawer.
+
+- If an engravable item has no engraving yet, the line item shows an **Add personalization** action (with the engraving fee) that opens the engraving form.
+- If the item already has engraving, its engraving is shown on the line item with an **Edit** button that reopens the form.
+
+The form respects the item's engraving constraints — `maxLines`, `maxCharsPerLine`, and the per-item `fee`. Saving emits [`lce:actions.cart_item_engraving_updated`](#engraving-updated) with the item's `engravingLines` and `previousEngravingLines`.
+
+**Note:** This in-drawer editing is distinct from the `engravingLines` array passed to [`addProduct`](#add-product-to-cart), which pre-fills engraving at the time an item is added.
+
+## Checkout Navigation
+
+### Checkout Drawer (Default)
+
+By default, clicking "Checkout" opens the checkout drawer:
+
+```javascript
+// User clicks checkout
+// Checkout drawer slides in
+```
+
+### Checkout Page (Custom URL)
+
+Redirect to a custom checkout page:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  checkout: {
+    pageUrl: 'https://yoursite.com/checkout/{token}'
+  }
+});
+```
+
+Or with data attributes:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout/{token}"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+The `{token}` placeholder is replaced with the session checkout token.
+
+## Use Cases
+
+### E-commerce Site
+
+```javascript
+// Track cart events for analytics
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { itemId, quantity } = event.detail.data;
+  gtag('event', 'add_to_cart', {
+    items: [{ item_id: itemId, quantity }],
+    currency: 'USD'
+  });
+});
+
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  // Update header cart count
+  document.getElementById('cart-badge').textContent = 
+    event.detail.data.current.itemCount;
+});
+```
+
+### Marketing Campaign
+
+```javascript
+// Check URL for campaign parameter
+const params = new URLSearchParams(window.location.search);
+const campaign = params.get('campaign');
+
+if (campaign === 'summer-sale') {
+  await window.LiquidCommerce.elements.actions.cart.applyPromoCode('SUMMER20');
+  window.LiquidCommerce.elements.actions.cart.openCart();
+}
+```
+
+### Abandoned Cart Recovery
+
+```javascript
+// Store cart ID in your system
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { cartId, itemCount } = event.detail.data.current;
+  
+  if (itemCount > 0) {
+    // Send cart ID to your backend for abandoned cart emails
+    fetch('/api/track-cart', {
+      method: 'POST',
+      body: JSON.stringify({ cartId, userId: currentUserId })
+    });
+  }
+});
+```
+
+## Best Practices
+
+### Initialize Cart Early
+
+Pre-load cart on page load for faster access:
+
+```javascript
+window.addEventListener('lce:actions.client_ready', () => {
+  // Cart loads automatically, but you can pre-fetch if needed
+  window.LiquidCommerce.elements.actions.cart.getDetails();
+}, { once: true });
+```
+
+### Provide Visual Feedback
+
+Show loading states when adding to cart:
+
+```javascript
+async function addToCart(productId) {
+  const button = document.getElementById('add-to-cart-btn');
+  button.disabled = true;
+  button.textContent = 'Adding...';
+  
+  try {
+    await window.LiquidCommerce.elements.actions.cart.addProduct([
+      { identifier: productId, fulfillmentType: 'shipping', quantity: 1 }
+    ], true);
+    
+    button.textContent = 'Added!';
+    setTimeout(() => {
+      button.disabled = false;
+      button.textContent = 'Add to Cart';
+    }, 2000);
+  } catch (error) {
+    button.textContent = 'Failed';
+    button.disabled = false;
+  }
+}
+```
+
+### Handle Empty Cart
+
+Show appropriate messaging for empty carts:
+
+```javascript
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { itemCount } = event.detail.data.current;
+  
+  if (itemCount === 0) {
+    // Show empty state in your UI
+    document.getElementById('cart-status').textContent = 
+      'Your cart is empty';
+  }
+});
+```
+
+## Troubleshooting
+
+### Cart Not Opening
+
+1. Check that SDK is initialized: `console.log(window.LiquidCommerce.elements)`
+2. Verify no JavaScript errors in console
+3. Ensure cart button is properly configured
+4. Try manually: `window.LiquidCommerce.elements.actions.cart.openCart()`
+
+### Items Not Adding
+
+1. Check that address is set: `window.LiquidCommerce.elements.actions.address.getDetails()`
+2. Verify product identifier is valid
+3. Check fulfillment type is available for the product
+4. Look for errors in browser console
+
+### Promo Code Not Working
+
+1. Verify promo codes are enabled in configuration
+2. Check code is valid and active
+3. Ensure code hasn't already been applied
+4. Check console for error messages
+
+## See Also
+
+- [Product Component](./product-component.md) - Add products to cart
+- [Checkout Component](./checkout-component.md) - Complete purchase
+- [Actions API](../api/actions/cart-actions.md) - Cart actions reference
+- [Events](./events.md) - All available events
+- [Theming](./theming.md) - Customize appearance