@liquidcommerce/elements-sdk 2.6.0-beta.9 → 2.6.0-beta.90

package/docs/v1/guides/best-practices.md

@@ -0,0 +1,365 @@
+# Best Practices
+
+Recommended patterns and practices for working with the Elements SDK.
+
+## Initialization
+
+### Initialize Once
+
+Create a single client instance and reuse it:
+
+```javascript
+// Good
+const client = await Elements('KEY', { env: 'production' });
+await client.injectProductElement([...]);
+await client.injectCartElement('cart');
+
+// Bad - creates multiple instances
+await Elements('KEY', { env: 'production' });
+await Elements('KEY', { env: 'production' });
+```
+
+### Use Global Access
+
+After initialization, use `window.LiquidCommerce.elements`:
+
+```javascript
+// Initialize once
+await Elements('KEY', { env: 'production' });
+
+// Use globally throughout your app
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+### Wait for Client Ready
+
+```javascript
+if (window.LiquidCommerce.elements) {
+  // Client already ready
+  window.LiquidCommerce.elements.actions.cart.openCart();
+} else {
+  // Wait for initialization
+  window.addEventListener('lce:actions.client_ready', () => {
+    window.LiquidCommerce.elements.actions.cart.openCart();
+  });
+}
+```
+
+## Component Injection
+
+### Verify Container Exists
+
+```javascript
+// Check container before injection
+if (document.getElementById('product')) {
+  await client.injectProductElement([
+    { containerId: 'product', identifier: '123' }
+  ]);
+}
+```
+
+### Provide Adequate Space
+
+```css
+#product-container {
+  min-height: 600px;  /* Prevent layout shift */
+  max-width: 1200px;
+}
+```
+
+### Handle Loading States
+
+```javascript
+showLoader('product-container');
+
+await client.injectProductElement([...]);
+
+// Loader automatically replaced when product loads
+```
+
+## Error Handling
+
+### Catch Errors Appropriately
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.cart.addProduct([...]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+
+### Provide Fallbacks
+
+```javascript
+const client = await Elements('KEY', { env: 'production' });
+
+if (!client) {
+  // Initialization failed
+  showFallbackUI();
+  return;
+}
+```
+
+## Performance
+
+### Lazy Load Products
+
+```javascript
+const observer = new IntersectionObserver(async (entries) => {
+  for (const entry of entries) {
+    if (entry.isIntersecting) {
+      const container = entry.target;
+      await client.injectProductElement([
+        { containerId: container.id, identifier: container.dataset.productId }
+      ]);
+      observer.unobserve(container);
+    }
+  }
+});
+
+document.querySelectorAll('.product-placeholder').forEach(el => {
+  observer.observe(el);
+});
+```
+
+### Use Checkout-Only Build
+
+For checkout pages:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+
+Reduces bundle size by ~60%.
+
+### Defer Non-Critical Operations
+
+```javascript
+// Load visible products first
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+
+// Load others after delay
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' }
+  ]);
+}, 1000);
+```
+
+## State Management
+
+### Pre-fill Known Data
+
+```javascript
+// Set address if known
+if (userSavedAddress) {
+  await window.LiquidCommerce.elements.actions.address.setAddressManually(
+    userSavedAddress,
+    userCoordinates
+  );
+}
+
+// Pre-fill checkout info
+window.addEventListener('lce:actions.checkout_opened', () => {
+  if (userIsLoggedIn) {
+    window.LiquidCommerce.elements.actions.checkout.updateCustomerInfo({
+      firstName: user.firstName,
+      email: user.email
+    });
+  }
+});
+```
+
+### Don't Clear Cart Unnecessarily
+
+Cart persists across sessions - avoid clearing unless intentional:
+
+```javascript
+// Only clear when user explicitly requests
+document.getElementById('clear-cart-btn').addEventListener('click', async () => {
+  if (confirm('Clear cart?')) {
+    await window.LiquidCommerce.elements.actions.cart.resetCart();
+  }
+});
+```
+
+## Cleanup
+
+### Destroy Components When Done
+
+In single-page applications, clean up when navigating away:
+
+```javascript
+// Destroy individual component
+const component = client.getInjectedComponents().get('product-1');
+component?.destroy();
+
+// Destroy entire client (on route change)
+client.destroy();
+```
+
+### Avoid Leaking References
+
+```javascript
+// Good - clean up on unmount
+useEffect(() => {
+  const init = async () => {
+    const c = await Elements('KEY', { env: 'production' });
+    clientRef.current = c;
+  };
+  init();
+  return () => clientRef.current?.destroy();
+}, []);
+```
+
+## Events
+
+### Use Events for Reactive Updates
+
+```javascript
+// Update UI when cart changes
+window.addEventListener('lce:actions.cart_updated', () => {
+  const cart = window.LiquidCommerce.elements.actions.cart.getDetails();
+  updateHeaderCartCount(cart.itemCount);
+});
+```
+
+### Track Important Events
+
+```javascript
+window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
+  const { orderNumber, orderTotal } = event.detail.data;
+  
+  // Analytics
+  gtag('event', 'purchase', {
+    transaction_id: orderNumber,
+    value: orderTotal / 100
+  });
+  
+  // Backend tracking
+  fetch('/api/track-order', {
+    method: 'POST',
+    body: JSON.stringify({ orderNumber, orderTotal })
+  });
+});
+```
+
+## Security
+
+### Use Proxy in Production
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  proxy: {
+    baseUrl: 'https://yoursite.com/api/elements-proxy'
+  }
+});
+```
+
+Prevents ad blockers and protects API keys.
+
+### Separate API Keys by Environment
+
+```javascript
+const apiKey = process.env.NODE_ENV === 'production'
+  ? 'prod_key_xyz'
+  : 'dev_key_abc';
+
+const client = await Elements(apiKey, {
+  env: process.env.NODE_ENV === 'production' ? 'production' : 'development'
+});
+```
+
+## Testing
+
+### Use Development Mode
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'development',
+  debugMode: 'console',  // or 'panel'
+  development: {
+    openShadowDom: true  // Makes debugging easier
+  }
+});
+```
+
+### Skip card entry in checkout tests
+
+Pre-select a saved payment method so the checkout payment step shows a read-only summary and never mounts the Stripe card form. Pass a payment method id the backend already has for the checkout's customer:
+
+```javascript
+window.LiquidCommerce.elements.actions.checkout.setSavedPaymentMethod({
+  id: 'pm_123',
+  card: { brand: 'Visa', last4: '4242', expMonth: '12', expYear: '30' }
+});
+```
+
+`setSavedPaymentMethod` is a production action (also exposed on the checkout-only client), not test-only — beyond tests, use it to pre-fill a returning shopper's saved card. See [Checkout Actions](../api/actions/checkout-actions.md#actionscheckoutsetsavedpaymentmethod).
+
+### Handle Test Scenarios
+
+```javascript
+// Test empty cart
+if (isDevelopment) {
+  await window.LiquidCommerce.elements.actions.cart.resetCart();
+}
+
+// Test with specific product
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  { identifier: testProductId, fulfillmentType: 'shipping', quantity: 1 }
+]);
+```
+
+## Accessibility
+
+### Provide Labels
+
+```html
+<label for="cart-toggle">Shopping Cart</label>
+<button id="cart-toggle" data-lce-cart-toggle-button>
+  Cart (<span data-lce-cart-items-count></span>)
+</button>
+```
+
+### Use Semantic HTML
+
+```html
+<nav aria-label="Main navigation">
+  <div id="cart-button"></div>
+</nav>
+```
+
+## Mobile Optimization
+
+### Responsive Containers
+
+```css
+@media (max-width: 768px) {
+  #product-container {
+    padding: 10px;
+  }
+}
+```
+
+### Mobile-Specific Cart Button
+
+```javascript
+if (window.innerWidth < 768) {
+  window.LiquidCommerce.elements.ui.floatingCartButton(true);
+} else {
+  window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
+}
+```
+
+## See Also
+
+- [Performance Guide](../reference/performance.md)
+- [Troubleshooting](../reference/troubleshooting.md)
+- [Component Guides](../guides/)