@liquidcommerce/elements-sdk 2.5.7 → 2.5.8

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)