@liquidcommerce/elements-sdk 2.2.0-beta.23 → 2.2.0-beta.25

package/README.md

@@ -961,13 +961,12 @@ const client = await Elements('YOUR_API_KEY', {
         }
       },
       layout: {
-        enablePersonalization: true,
-        personalizationText: 'Customize your product',
-        personalizationCardStyle: 'outlined',
-        allowPromoCodes: true,
-        inputFieldStyle: 'outlined',
-        showPoweredBy: false,
-        poweredByMode: 'light'
+      enablePersonalization: true,
+      personalizationText: 'Customize your product',
+      personalizationCardStyle: 'outlined',
+      allowPromoCodes: true,
+      inputFieldStyle: 'outlined',
+      poweredByMode: 'light'
       }
     }
   }
@@ -1100,21 +1099,79 @@ client.builder.updateAddressComponent({
 
 ## 🎁 Features Deep Dive
 
-### Product Engraving
+### Product Personalization (Engraving)
+
+The SDK provides a comprehensive personalization/engraving feature for products that support it. The personalization experience varies based on context:
 
-Engraving is automatically enabled for products that support it:
+#### Product View
+When browsing products, customers can add personalization through an enhanced form that includes:
+- Product information with pricing
+- Fulfillment/retailer selection (with pricing comparison)
+- Multi-line engraving inputs with character limits
+- Real-time price updates as customers select different retailers
+- Add-to-cart with personalization in one step
 
 ```js
-// Engraving appears automatically for engravable products
+// Personalization appears automatically for engravable products
+// Customers can add engraving text and select which retailer to fulfill from
+
+// Listen for when personalization is added via add-to-cart
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { hasEngraving, engravingLines } = event.detail.data;
+  if (hasEngraving) {
+    console.log('Customer personalized:', engravingLines);
+  }
+});
+```
+
+#### Cart View
+In the cart, personalized items display:
+- Personalization text lines
+- Engraving fee (per item and total for quantity)
+- **Edit** button to modify the personalization
+- **Remove** button to remove personalization
 
-// Listen for engraving updates
-window.addEventListener('lce:actions.product_engraving_updated', (event) => {
-  const { productId, engravingLines } = event.detail.data;
-  console.log('Customer wants:', engravingLines);
+```js
+// Customers can edit or remove engraving from cart items
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { identifier, engravingLines } = event.detail.data;
+  console.log('Cart item engraving updated:', engravingLines);
 });
 ```
 
-Engraving input appears automatically for products that support it.
+#### Checkout View
+During checkout, personalized items show:
+- Personalization text lines (read-only)
+- Engraving fee included in pricing
+- **Remove** button only (editing not allowed in checkout)
+
+**Design Decision:** Editing personalization during checkout is intentionally disabled to prevent order processing complications. Customers must return to the cart to make changes.
+
+#### Theming & Configuration
+
+Control personalization display through global configuration:
+
+```js
+customTheme: {
+  global: {
+    layout: {
+      enablePersonalization: true,
+      personalizationText: 'Personalize your product',
+      personalizationCardStyle: 'outlined' // or 'filled'
+    }
+  }
+}
+```
+
+#### Key Features
+- **Smart pricing:** Automatically includes engraving fees in product price
+- **Retailer selection:** Compare prices from different retailers during personalization
+- **Character limits:** Enforces maximum characters per line
+- **Uppercase conversion:** Engraving text is automatically converted to uppercase
+- **Multi-line support:** Products can support 1 or more engraving lines
+- **Fee transparency:** Shows per-item and total fees (e.g., "$5.00 ($2.50 ea)")
+
+**Note:** Personalization is automatically enabled for products that support it. The SDK handles all UI, validation, and state management.
 
 ### Gift Options