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

package/docs/cart.md

@@ -0,0 +1,387 @@
+# Cart
+
+The cart component provides a complete shopping cart experience as a slide-out drawer. Customers can review items, adjust quantities, apply promo codes, and proceed to checkout. The cart updates instantly when products are added from anywhere on the page.
+
+## Overview
+
+The cart element handles everything shopping cart related:
+- Slide-out drawer UI with item list
+- Real-time quantity adjustments
+- Promo code application
+- Subtotal and fee calculations
+- Proceed to checkout flow
+- Cross-tab synchronization
+- Session persistence
+
+The cart syncs in real-time across browser tabs and persists between sessions, so customers can continue where they left off.
+
+---
+
+## Declarative Setup (HTML Attributes)
+
+Configure the cart button with data attributes. By default, you get a floating cart button in the top-right corner.
+
+### Default Floating Button
+
+No configuration needed - just include the SDK:
+
+```html
+<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 gives you a floating cart button with item count badge.
+
+### Cart Button in Specific Container
+
+Place the cart button inside a specific element:
+
+```html
+<nav>
+  <div id="header-cart"></div>
+</nav>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-badge-button="header-cart"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Position Modifiers
+
+Control where the button appears relative to a target:
+
+```html
+<!-- Inside the target (default) -->
+<script data-cart-badge-button="header-cart" ...></script>
+
+<!-- Above the target -->
+<script data-cart-badge-button="above:.header-logo" ...></script>
+
+<!-- Below the target -->
+<script data-cart-badge-button="below:#main-nav" ...></script>
+
+<!-- Replace the target -->
+<script data-cart-badge-button="replace:.old-cart" ...></script>
+```
+
+### Cart Button Variants
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-cart-button` | Cart button without badge |
+| `data-cart-badge-button` | Cart button with item count badge |
+
+### Mobile Cart Button
+
+Configure different placements for desktop and mobile:
+
+```html
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-badge-button="above:.desktop-nav"
+  data-cart-mobile-badge-button="below:.mobile-header"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+Mobile attributes support the same position modifiers (`above:`, `below:`, `replace:`, `inside:`).
+
+### Custom Cart Toggle
+
+Use your own button to toggle the cart:
+
+```html
+<button data-lce-cart-toggle-button>My Cart</button>
+<span data-lce-cart-items-count>0</span>
+
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button-hidden
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-lce-cart-toggle-button` | Makes any element a cart toggle |
+| `data-lce-cart-items-count` | Auto-updates with item count |
+| `data-cart-button-hidden` | Hides the default cart button |
+
+Use `data-lce-cart-items-count="keep-zero"` to show count even when cart is empty.
+
+### Hide Cart Button Completely
+
+For manual cart control via JavaScript:
+
+```html
+<script
+  defer
+  type="text/javascript"
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button-hidden
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+---
+
+## Programmatic Setup (JavaScript API)
+
+For full control, use the client API to inject cart components.
+
+### Cart Element (Full Cart View)
+
+Inject the cart into a container for a dedicated cart page:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+const component = await client.injectCartElement('cart-container');
+```
+
+### UI Helper Methods
+
+Quick methods for common cart UI needs:
+
+```javascript
+// Cart button in a container
+client.ui.cartButton('header-cart', true); // true = show item count
+
+// Floating cart button
+client.ui.floatingCartButton(true); // true = show item count
+
+// Display cart subtotal
+client.ui.cartSubtotal('subtotal-display');
+
+// Display item count
+client.ui.cartItemsCount('count-display', {
+  keepZero: true // Show "0" instead of hiding when empty
+});
+```
+
+---
+
+## Actions
+
+Control the cart programmatically.
+
+### Open / Close / Toggle
+
+```javascript
+// Open the cart drawer
+window.elements.actions.cart.openCart();
+
+// Close the cart drawer
+window.elements.actions.cart.closeCart();
+
+// Toggle cart drawer
+window.elements.actions.cart.toggleCart();
+```
+
+### Add Products
+
+Add items to cart programmatically (great for "Buy Now" buttons or bundles):
+
+```javascript
+await window.elements.actions.cart.addProduct(
+  [
+    {
+      identifier: '00619947000020',
+      fulfillmentType: 'shipping',
+      quantity: 2
+    },
+    {
+      identifier: '00832889005513',
+      fulfillmentType: 'onDemand',
+      quantity: 1
+    }
+  ],
+  true // Open cart after adding (optional)
+);
+```
+
+### Promo Codes
+
+```javascript
+// Apply a promo code
+await window.elements.actions.cart.applyPromoCode('SUMMER20');
+
+// Remove the applied promo code
+await window.elements.actions.cart.removePromoCode();
+```
+
+### Reset Cart
+
+Clear all items from the cart:
+
+```javascript
+await window.elements.actions.cart.resetCart();
+```
+
+### Get Cart Details
+
+Retrieve current cart state:
+
+```javascript
+const cart = window.elements.actions.cart.getDetails();
+
+console.log(cart.itemCount);
+console.log(cart.subtotal);
+console.log(cart.items);
+```
+
+---
+
+## Events
+
+Listen to cart interactions and state changes.
+
+### Subscribing to Events
+
+```javascript
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { current, previous } = event.detail.data;
+  console.log('Cart updated:', current.itemCount, 'items');
+});
+```
+
+### Available Events
+
+| Event | Description | Key Data |
+|-------|-------------|----------|
+| `cart_loaded` | Cart data ready | Full cart state |
+| `cart_opened` | Drawer opened | boolean |
+| `cart_closed` | Drawer closed | boolean |
+| `cart_updated` | Items or totals changed | previous, current state |
+| `cart_reset` | Cart cleared | boolean |
+| `cart_failed` | Operation failed | cartId, message |
+| `cart_item_added` | Item added | cartId, itemId, quantity |
+| `cart_item_removed` | Item removed | cartId, itemId |
+| `cart_item_quantity_increase` | Quantity increased | cartId, itemId, quantity, previousQuantity |
+| `cart_item_quantity_decrease` | Quantity decreased | cartId, itemId, quantity, previousQuantity |
+| `cart_item_engraving_updated` | Personalization changed | cartId, itemId, engravingLines |
+| `cart_product_add_success` | Programmatic add succeeded | cartId, itemsAdded, identifiers |
+| `cart_product_add_failed` | Programmatic add failed | cartId, identifiers, error |
+| `cart_promo_code_applied` | Discount applied | cartId, discount, newSubtotal |
+| `cart_promo_code_removed` | Discount removed | cartId, newSubtotal |
+| `cart_promo_code_failed` | Discount rejected | cartId, error |
+
+### Example: Analytics Integration
+
+```javascript
+// Track add to cart
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  const { itemId, quantity } = event.detail.data;
+  analytics.track('Cart Item Added', { itemId, quantity });
+});
+
+// Track cart abandonment prevention
+window.addEventListener('lce:actions.cart_closed', () => {
+  const cart = window.elements.actions.cart.getDetails();
+  if (cart.itemCount > 0) {
+    // User closed cart with items - trigger retention flow
+    showRetentionOffer();
+  }
+});
+```
+
+---
+
+## Use Cases
+
+### Smart Cart Timing
+
+Open the cart after the customer adds their third item:
+
+```javascript
+let addCount = 0;
+
+window.addEventListener('lce:actions.cart_item_added', () => {
+  addCount++;
+  if (addCount === 3) {
+    window.elements.actions.cart.openCart();
+  }
+});
+```
+
+### Bundle Sales
+
+Add complementary products with one click:
+
+```javascript
+document.querySelector('#buy-bundle').addEventListener('click', async () => {
+  await window.elements.actions.cart.addProduct([
+    { identifier: 'MAIN_PRODUCT', fulfillmentType: 'shipping', quantity: 1 },
+    { identifier: 'ACCESSORY_1', fulfillmentType: 'shipping', quantity: 1 },
+    { identifier: 'ACCESSORY_2', fulfillmentType: 'shipping', quantity: 1 }
+  ], true);
+});
+```
+
+### Custom Cart Button with Count
+
+```javascript
+const cartBtn = document.querySelector('#my-cart-button');
+const countBadge = document.querySelector('#cart-count');
+
+// Update count when cart changes
+window.addEventListener('lce:actions.cart_updated', (event) => {
+  const { current } = event.detail.data;
+  countBadge.textContent = current.itemCount || '';
+  countBadge.hidden = current.itemCount === 0;
+});
+
+// Toggle cart on click
+cartBtn.addEventListener('click', () => {
+  window.elements.actions.cart.toggleCart();
+});
+```
+
+---
+
+## Customization
+
+Style the cart through theme configuration.
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  customTheme: {
+    cart: {
+      // Cart-specific theme options
+    }
+  }
+});
+```
+
+See [theming.md](./theming.md) for available cart theme options.
+
+---
+
+## See Also
+
+- [Checkout](./checkout.md) - Complete purchase flow
+- [Actions Reference](./actions.md) - All available actions
+- [Events Reference](./events.md) - All available events
+- [Theming Guide](./theming.md) - Customization options