@liquidcommerce/elements-sdk 2.4.0 → 2.4.2

package/README.md

@@ -207,8 +207,7 @@ By default, you get a floating cart button. Here's how to customize it:
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-cart-id="header-cart"
-  data-show-cart-items
+  data-cart-badge-button="header-cart"
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
 ```
@@ -220,7 +219,7 @@ By default, you get a floating cart button. Here's how to customize it:
   data-liquid-commerce-elements
   data-token="YOUR_API_KEY"
   data-env="production"
-  data-hide-cart-floating-button
+  data-cart-button-hidden
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
 ```
@@ -324,9 +323,15 @@ Here's every available data attribute:
   data-env="production|staging|development|local"
   
   <!-- Cart Button -->
-  data-cart-id="container-id"
-  data-show-cart-items
-  data-hide-cart-floating-button
+  data-cart-button="container-id"
+  data-cart-badge-button="container-id"
+  data-cart-button-hidden
+  
+  <!-- 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"
   
   <!-- Products (Method 1: Direct) -->
   data-container-1="div-id"
@@ -392,7 +397,7 @@ pnpm add @liquidcommerce/elements-sdk
   });
 
   // Inject components
-  await client.injectProductElement([
+  const components = await client.injectProductElement([
     { containerId: 'pdp-1', identifier: '00619947000020' }
   ]);
 
@@ -559,15 +564,20 @@ promoTicker: [
 
 ### Component Injection
 
-Inject SDK components into your page containers.
+Inject SDK components into your page containers. All injection methods return wrapper objects that provide component control.
 
 #### Products
 
 ```js
-await client.injectProductElement([
+const components = await client.injectProductElement([
   { containerId: 'pdp-1', identifier: '00619947000020' },
   { containerId: 'pdp-2', identifier: '00832889005513' }
 ]);
+
+// Returns: IInjectedComponent[] - Array of component wrappers
+// components[0].rerender() - Rerender the first component
+// components[0].getElement() - Get the container element
+// components[0].getType() - Get component type
 ```
 
 **Identifier types:** UPC, product ID, or Salsify grouping ID
@@ -575,7 +585,12 @@ await client.injectProductElement([
 #### Cart
 
 ```js
-await client.injectCartElement('cart-container');
+const component = await client.injectCartElement('cart-container');
+
+// Returns: IInjectedComponent | null - Component wrapper or null if failed
+// component.rerender() - Rerender the component
+// component.getElement() - Get the container element
+// component.getType() - Get component type
 ```
 
 **Use case:** Dedicated cart page
@@ -583,7 +598,12 @@ await client.injectCartElement('cart-container');
 #### Checkout
 
 ```js
-await client.injectCheckoutElement('checkout-container');
+const component = await client.injectCheckoutElement('checkout-container');
+
+// Returns: IInjectedComponent | null - Component wrapper or null if failed
+// component.rerender() - Rerender the component
+// component.getElement() - Get the container element
+// component.getType() - Get component type
 ```
 
 **Use case:** Dedicated checkout page
@@ -591,11 +611,51 @@ await client.injectCheckoutElement('checkout-container');
 #### Address
 
 ```js
-await client.injectAddressElement('address-container');
+const component = await client.injectAddressElement('address-container');
+
+// Returns: IInjectedComponent | null - Component wrapper or null if failed
+// component.rerender() - Rerender the component
+// component.getElement() - Get the container element
+// component.getType() - Get component type
 ```
 
 **Use case:** Shipping address collection page
 
+#### Access All Injected Components
+
+```js
+// Get all injected components
+const injectedComponents = client.getInjectedComponents();
+
+// Access specific components by container ID
+const productComponent = injectedComponents.get('product-container-1');
+const cartComponent = injectedComponents.get('cart-container');
+
+// Iterate through all components
+injectedComponents.forEach((component, containerId) => {
+  console.log(`Container: ${containerId}, Type: ${component.getType()}`);
+  
+  // Rerender specific components
+  if (component.getType() === 'product') {
+    component.rerender();
+  }
+});
+
+// Get all components of a specific type
+const productComponents = Array.from(injectedComponents.values())
+  .filter(component => component.getType() === 'product');
+
+// Rerender all components of a type
+productComponents.forEach(component => component.rerender());
+```
+
+**Returns:** `Map<string, IInjectedComponent>` - Map of container IDs to component wrappers
+
+**Use cases:** 
+- Debugging and inspecting injected components
+- Bulk operations on multiple components
+- Component management and cleanup
+
 ### UI Helpers
 
 Create standalone UI elements that integrate with the SDK.
@@ -661,10 +721,12 @@ client.builder.updateCheckoutComponent(checkoutTheme);
 client.builder.updateAddressComponent(addressTheme);
 
 // Builder injection methods (same as regular methods)
-await client.builder.injectProductElement(params);
-await client.builder.injectCartElement(containerId);
-await client.builder.injectCheckoutElement(containerId);
-await client.builder.injectAddressElement(containerId);
+const components = await client.builder.injectProductElement(params);
+const component = await client.builder.injectCartElement(containerId);
+const checkoutComponent = await client.builder.injectCheckoutElement(containerId);
+const addressComponent = await client.builder.injectAddressElement(containerId);
+
+// All return IInjectedComponent wrapper objects with rerender(), getElement(), getType() methods
 ```
 
 ## 🎬 Actions
@@ -683,7 +745,8 @@ const actions = window.elements.actions;
 ```js
 // Get product details
 const product = actions.product.getDetails('product-123');
-console.log(product.productName, product.price, product.isAvailable);
+console.log(product.name, product.brand, product.region, product.variety);
+console.log(product.priceInfo, product.description, product.tastingNotes);
 ```
 
 ### Address Actions
@@ -784,7 +847,7 @@ await actions.cart.removePromoCode();
 
 // Get cart details
 const cart = actions.cart.getDetails();
-console.log(cart.total, cart.items.length);
+console.log(cart.itemCount, cart.amounts.total, cart.amounts.giftCardTotal);
 
 // Reset cart
 await actions.cart.resetCart();
@@ -856,12 +919,10 @@ window.addEventListener('lce:actions.checkout_gift_card_failed', function(event)
 
 // Get checkout details (safe, non-sensitive data only)
 const checkout = actions.checkout.getDetails();
-console.log('Total:', checkout.amounts.total);
-console.log('Items:', checkout.itemCount);
-console.log('Is gift:', checkout.isGift);
-console.log('Has age verification:', checkout.hasAgeVerify);
-console.log('Has promo code:', checkout.hasPromoCode);
-console.log('Has gift cards:', checkout.hasGiftCards);
+console.log(checkout.itemCount, checkout.amounts.total, checkout.isGift);
+console.log(checkout.hasAgeVerify, checkout.hasPromoCode, checkout.hasGiftCards);
+console.log(checkout.acceptedAccountCreation, checkout.billingSameAsShipping);
+console.log(checkout.marketingPreferences);
 
 // Configure checkout options
 await actions.checkout.toggleBillingSameAsShipping(true);
@@ -877,13 +938,14 @@ The SDK emits real-time events for all user interactions. Listen to these events
 ```js
 // Listen for specific events
 window.addEventListener('lce:actions.product_add_to_cart', function(event) {
-  const product = event.detail.data;
-  console.log('Added to cart:', product.productName);
+  const data = event.detail.data;
+  console.log('Added to cart:', data.identifier);
   
   // Your custom logic here
   analytics.track('Product Added', {
-    product: product.productName,
-    price: product.price
+    identifier: data.identifier,
+    quantity: data.quantity,
+    upc: data.upc
   });
 });
 
@@ -900,7 +962,7 @@ window.elements.onAllActions((data, metadata) => {
 ### Available Events
 
 #### Product Events
-- `lce:actions.product_loaded` - Product component loaded
+- `lce:actions.product_loaded` - Product component loaded with comprehensive product details (region, country, abv, proof, age, variety, vintage, descriptions, tasting notes)
 - `lce:actions.product_add_to_cart` - Item added to cart
 - `lce:actions.product_quantity_increase` - Quantity increased
 - `lce:actions.product_quantity_decrease` - Quantity decreased
@@ -908,6 +970,7 @@ window.elements.onAllActions((data, metadata) => {
 - `lce:actions.product_fulfillment_type_changed` - Delivery method changed
 
 #### Cart Events
+- `lce:actions.cart_loaded` - Cart data loaded with complete cart information (itemCount, all amounts including giftCardTotal, detailed item data)
 - `lce:actions.cart_opened` - Cart displayed
 - `lce:actions.cart_closed` - Cart hidden
 - `lce:actions.cart_updated` - Cart contents changed
@@ -916,6 +979,7 @@ window.elements.onAllActions((data, metadata) => {
 - `lce:actions.cart_reset` - Cart cleared
 
 #### Checkout Events
+- `lce:actions.checkout_loaded` - Checkout data loaded with comprehensive details (acceptedAccountCreation, hasSubstitutionPolicy, billingSameAsShipping, marketing preferences, detailed items)
 - `lce:actions.checkout_opened` - Checkout started
 - `lce:actions.checkout_closed` - Checkout abandoned
 - `lce:actions.checkout_submit_started` - Order submission began
@@ -928,7 +992,7 @@ window.elements.onAllActions((data, metadata) => {
 - `lce:actions.address_updated` - Address information changed
 - `lce:actions.address_cleared` - Address removed
 
-See [`docs/EVENTS.md`](docs/EVENTS.md) for complete event reference with implementation examples.
+See [`docs/EVENTS.md`](docs/EVENTS.md) for complete event reference with all available fields and implementation examples.
 
 ## 🎨 Themes & Customization
 
@@ -1376,11 +1440,12 @@ The SDK uses a centralized store for all state management. Access state data via
 ```js
 // Get current cart state
 const cart = await client.actions.cart.getDetails();
-console.log(cart.items, cart.subtotal, cart.itemCount);
+console.log(cart.itemCount, cart.amounts.total, cart.amounts.giftCardTotal);
 
 // Get current checkout state
 const checkout = await client.actions.checkout.getDetails();
-console.log(checkout.total, checkout.customerInfo, checkout.isGift);
+console.log(checkout.amounts.total, checkout.isGift, checkout.acceptedAccountCreation);
+console.log(checkout.billingSameAsShipping, checkout.marketingPreferences);
 
 // Get current address
 const address = await client.actions.address.getDetails();
@@ -1388,7 +1453,8 @@ console.log(address.formattedAddress, address.coordinates);
 
 // Get product details
 const product = await client.actions.product.getDetails('00619947000020');
-console.log(product.name, product.price, product.variants);
+console.log(product.name, product.region, product.variety, product.vintage);
+console.log(product.description, product.tastingNotes);
 ```
 
 **State is persistent:** Cart and address data persist across page reloads using localStorage.
@@ -1400,8 +1466,8 @@ All SDK interactions emit events through a centralized event system:
 ```js
 // Subscribe to specific event
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  const cartData = event.detail.data;
-  console.log('Cart changed:', cartData);
+  const { previous, current } = event.detail.data;
+  console.log('Cart changed from', previous.amounts.total, 'to', current.amounts.total);
 });
 
 // Subscribe to all action events
@@ -1579,9 +1645,10 @@ Components are created on-demand using a factory pattern:
 
 ```js
 // When you call:
-await client.injectProductElement([
+const components = await client.injectProductElement([
   { containerId: 'pdp-1', identifier: 'product-123' }
 ]);
+// Returns: IInjectedComponent[] - Array of component wrappers
 
 // The SDK:
 // 1. Creates a ProductComponent instance
@@ -1713,7 +1780,7 @@ export default function ProductPage({ productId }: { productId: string }) {
         env: 'production'
       });
 
-      await client.injectProductElement([
+      const components = await client.injectProductElement([
         { containerId: 'product-container', identifier: productId }
       ]);
 
@@ -1785,7 +1852,7 @@ await client.injectProductElement([
 
 // cart-page.js
 const client = await getElementsClient();
-await client.injectCartElement('cart-container');
+const cartComponent = await client.injectCartElement('cart-container');
 ```
 
 ---
@@ -2074,7 +2141,7 @@ await client.actions.cart.addProduct([...]);
 // ❌ Don't repeatedly fetch the same data
 async function showCartTotal() {
   const cart = await client.actions.cart.getDetails();
-  return cart.total;
+  return cart.amounts.total;
 }
 
 // ✅ Use UI helpers that auto-update
@@ -2084,7 +2151,7 @@ client.ui.cartItemsCount('cart-count-display');
 // Or cache and listen to updates
 let cachedCart = await client.actions.cart.getDetails();
 window.addEventListener('lce:actions.cart_updated', (event) => {
-  cachedCart = event.detail.data;
+  cachedCart = event.detail.data.current;
 });
 ```