@liquidcommerce/elements-sdk 2.4.1 → 2.4.3

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
@@ -1583,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
@@ -1717,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 }
       ]);
 
@@ -1789,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');
 ```
 
 ---