@liquidcommerce/elements-sdk 2.5.7 → 2.5.9

package/README.md

@@ -228,7 +228,7 @@ Add a product list to any page with a data attribute:
 
 ### Customizing the Cart Button
 
-By default, you get a floating cart button. Here's how to customize it:
+By default, you get a floating cart button with badge. Here's how to customize it:
 
 #### Option 1: Cart Button in a Specific Container
 
@@ -246,7 +246,56 @@ By default, you get a floating cart button. Here's how to customize it:
 ></script>
 ```
 
-#### Option 2: No Cart Button (Manual Control)
+**Position Options:**
+
+You can control where the cart button is placed relative to a target element:
+
+```html
+<!-- Place inside the target (default) -->
+<script data-cart-badge-button="header-cart" ...></script>
+
+<!-- Place above the target -->
+<script data-cart-badge-button="above:.header-logo" ...></script>
+
+<!-- Place below the target -->
+<script data-cart-badge-button="below:#main-nav" ...></script>
+
+<!-- Replace the target -->
+<script data-cart-badge-button="replace:.old-cart" ...></script>
+```
+
+**ID Auto-Prefixing:**
+
+Element IDs are automatically prefixed with `#` if needed:
+
+```html
+<!-- These are equivalent: -->
+<script data-cart-button="header-cart" ...></script>
+<script data-cart-button="#header-cart" ...></script>
+```
+
+#### Option 2: Floating Cart Button (Default)
+
+If no cart button attribute is provided, or if the target element is not found, the SDK automatically falls back to a floating cart button (bottom-right corner):
+
+```html
+<!-- Empty attribute = floating cart button without badge -->
+<script data-cart-button="" ...></script>
+
+<!-- Empty badge attribute = floating cart button with badge -->
+<script data-cart-badge-button="" ...></script>
+
+<!-- Or simply omit the attribute for floating button with badge -->
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+#### Option 3: No Cart Button (Manual Control)
+
+Hide the cart button completely when you want to manage cart access manually:
 
 ```html
 <script
@@ -258,6 +307,8 @@ By default, you get a floating cart button. Here's how to customize it:
 ></script>
 ```
 
+**Use case:** When you have a custom cart implementation or want to trigger cart display programmatically using `client.actions.cart.openCart()`
+
 ### Advanced Auto-Init Features
 
 #### Add Product via URL (Marketing Links)
@@ -357,15 +408,19 @@ Here's every available data attribute:
   data-env="production|staging|development|local"
   
   <!-- Cart Button -->
-  data-cart-button="container-id"
-  data-cart-badge-button="container-id"
-  data-cart-button-hidden
+  data-cart-button="container-id"              <!-- Simple cart button (no badge) -->
+  data-cart-badge-button="container-id"        <!-- Cart button with badge -->
+  data-cart-button-hidden                      <!-- Hide cart button completely -->
   
   <!-- Cart Button with Position Prefixes -->
-  data-cart-button="above:.logo"
-  data-cart-badge-button="below:#header"
-  data-cart-button="inside:.nav"
-  data-cart-badge-button="replace:.old-cart"
+  data-cart-button="above:.logo"               <!-- Place above target -->
+  data-cart-badge-button="below:#header"       <!-- Place below target -->
+  data-cart-button="inside:.nav"               <!-- Place inside target (default) -->
+  data-cart-badge-button="replace:.old-cart"   <!-- Replace target -->
+  
+  <!-- Cart Button Floating (empty values) -->
+  data-cart-button=""                          <!-- Floating button without badge -->
+  data-cart-badge-button=""                    <!-- Floating button with badge -->
   
   <!-- Products (Method 1: Direct) -->
   data-container-1="div-id"
@@ -775,16 +830,32 @@ Bind elements to auto-update with cart data:
 // Show live subtotal
 client.ui.cartSubtotal('cart-total-display');
 
-// Show live item count
+// Show live item count (default behavior: hides when count is 0)
 client.ui.cartItemsCount('cart-badge');
+
+// Show live item count (always visible, even when 0)
+client.ui.cartItemsCount('cart-badge', { hideZero: false });
 ```
 
+**Parameters for `cartItemsCount`:**
+- `elementId` (string) - ID of the element to update
+- `options` (object, optional) - Configuration options:
+  - `hideZero` (boolean, default: `true`) - When `true`, element is hidden when cart count is 0. When `false`, element remains visible showing "0".
+
 **Example:**
 ```html
 <nav>
   <span>Cart: $<span id="cart-total-display">0.00</span></span>
   <span>(<span id="cart-badge">0</span> items)</span>
 </nav>
+
+<script>
+  // Default behavior - badge hidden when cart is empty
+  client.ui.cartItemsCount('cart-badge');
+  
+  // Always show count, even when 0
+  client.ui.cartItemsCount('cart-badge', { hideZero: false });
+</script>
 ```
 
 ### Builder Methods (Development Mode)
@@ -943,13 +1014,13 @@ await actions.cart.applyPromoCode('WELCOME10');
 
 // Listen for promo code feedback
 window.addEventListener('lce:actions.cart_promo_code_applied', function(event) {
-  const { applied, discountAmount, newTotal } = event.detail.data;
+  const { discountAmount, newTotal } = event.detail.data;
   console.log(`✅ Promo applied! Discount: $${discountAmount}, New total: $${newTotal}`);
   showSavingsMessage(discountAmount);
 });
 
 window.addEventListener('lce:actions.cart_promo_code_failed', function(event) {
-  const { attempted, error } = event.detail.data;
+  const { error } = event.detail.data;
   console.log(`❌ Promo failed:`, error);
   showErrorMessage('Promo code could not be applied');
 });
@@ -1004,27 +1075,27 @@ await actions.checkout.applyGiftCard('GIFT123');
 
 // Listen for checkout promo code feedback
 window.addEventListener('lce:actions.checkout_promo_code_applied', function(event) {
-  const { applied, discountAmount, newTotal } = event.detail.data;
+  const { discountAmount, newTotal } = event.detail.data;
   console.log(`✅ Checkout promo applied! Saved: $${discountAmount}`);
   updateCheckoutTotal(newTotal);
 });
 
 window.addEventListener('lce:actions.checkout_promo_code_failed', function(event) {
-  const { attempted, error } = event.detail.data;
+  const { error } = event.detail.data;
   console.log(`❌ Checkout promo failed:`, error);
   showCheckoutError('Promo code could not be applied');
 });
 
 // Listen for gift card feedback
 window.addEventListener('lce:actions.checkout_gift_card_applied', function(event) {
-  const { applied, newTotal } = event.detail.data;
+  const { newTotal } = event.detail.data;
   console.log('✅ Gift card applied successfully!');
   updateCheckoutTotal(newTotal);
   showSuccessMessage('Gift card applied to your order');
 });
 
 window.addEventListener('lce:actions.checkout_gift_card_failed', function(event) {
-  const { attempted, error } = event.detail.data;
+  const { error } = event.detail.data;
   console.log(`❌ Gift card failed:`, error);
   showCheckoutError('Gift card could not be applied');
 });
@@ -1097,8 +1168,11 @@ window.elements.onAllActions((data, metadata) => {
 - `lce:actions.checkout_submit_started` - Order submission began
 - `lce:actions.checkout_submit_completed` - Order completed successfully
 - `lce:actions.checkout_submit_failed` - Order failed
-- `lce:actions.checkout_customer_information_updated` - Customer info entered
-- `lce:actions.checkout_billing_information_updated` - Billing info entered
+- `lce:actions.checkout_customer_information_updated` - Customer info entered (returns boolean only, no sensitive data)
+- `lce:actions.checkout_gift_information_updated` - Gift recipient info entered (returns boolean only, no sensitive data)
+- `lce:actions.checkout_billing_information_updated` - Billing info entered (returns boolean only, no sensitive data)
+
+**Security Note:** Form update events return only `boolean: true` to track completion without exposing sensitive customer information (names, emails, phone numbers, addresses, etc.). This protects your customers from malicious scripts and data breaches.
 
 #### Address Events
 - `lce:actions.address_updated` - Address information changed
@@ -1417,12 +1491,12 @@ await client.actions.checkout.removeGiftCard('GIFT-1234-5678-9012');
 
 // Listen for gift card events
 window.addEventListener('lce:actions.checkout_gift_card_applied', (event) => {
-  const { code, appliedAmount, remainingBalance } = event.detail.data;
-  console.log(`Applied $${appliedAmount}, Remaining: $${remainingBalance}`);
+  const { newTotal } = event.detail.data;
+  console.log(`Gift card applied! New total: $${newTotal}`);
 });
 
 window.addEventListener('lce:actions.checkout_gift_card_failed', (event) => {
-  const { code, error } = event.detail.data;
+  const { error } = event.detail.data;
   console.log('Gift card failed:', error);
 });
 ```
@@ -1443,13 +1517,13 @@ await client.actions.cart.removePromoCode();
 
 // Listen for promo events
 window.addEventListener('lce:actions.cart_promo_code_applied', (event) => {
-  const { code, discountAmount, newTotal } = event.detail.data;
-  console.log(`${code} saved $${discountAmount}! New total: $${newTotal}`);
+  const { discountAmount, newTotal } = event.detail.data;
+  console.log(`Promo applied! Saved $${discountAmount}! New total: $${newTotal}`);
 });
 
 window.addEventListener('lce:actions.cart_promo_code_failed', (event) => {
-  const { code, error } = event.detail.data;
-  console.log('Promo failed:', error.message);
+  const { error } = event.detail.data;
+  console.log('Promo failed:', error);
 });
 ```