npm - @liquidcommerce/elements-sdk - Versions diffs - 2.6.0-beta.10 → 2.6.0-beta.101 - Mend

@liquidcommerce/elements-sdk 2.6.0-beta.10 → 2.6.0-beta.101

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (262) hide show

package/docs/v1/examples/simple-product-page.md ADDED Viewed

@@ -0,0 +1,89 @@
+# Simple Product Page
+A minimal, production-ready product page using the CDN build with a single Product component and the default cart drawer.
+## What You'll Build
+- One product component
+- Optional cart button with item count
+- Default cart and checkout flow
+## Prerequisites
+- LiquidCommerce API key
+- One product identifier (UPC or grouping ID)
+## HTML (CDN)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Simple Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    data-cart-badge-button="header-cart"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      margin: 0;
+      padding: 0;
+      background: #f7f7f7;
+    }
+    header {
+      background: #fff;
+      padding: 16px 24px;
+      box-shadow: 0 2px 6px rgba(0,0,0,0.08);
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+    main {
+      max-width: 1100px;
+      margin: 24px auto;
+      padding: 0 24px;
+    }
+    #product {
+      background: #fff;
+      border-radius: 10px;
+      padding: 20px;
+      min-height: 600px;
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Premium Spirits</h1>
+    <div id="header-cart"></div>
+  </header>
+  <main>
+    <div id="product"></div>
+  </main>
+</body>
+</html>
+```
+## What to Tweak Next
+- Change the product identifier: `data-product-1="YOUR_PRODUCT_ID"`
+- Add a second product (see [Multi-Product Page](./multi-product-page.md))
+- Customize styling via theming (see [Theming Guide](../guides/theming.md))
+## Related Docs
+- [Product Component](../guides/product-component.md)
+- [Cart Component](../guides/cart-component.md)
+- [Quick Start](../getting-started/quick-start.md)

package/docs/v1/getting-started/concepts.md ADDED Viewed

@@ -0,0 +1,521 @@
+# Core Concepts
+Understanding these fundamental concepts will help you work effectively with the LiquidCommerce Elements SDK.
+## Web Components Architecture
+The Elements SDK is built using **Web Components**, a set of web platform APIs that allow you to create custom, reusable HTML elements.
+### What Are Web Components?
+Web Components are native browser features that provide:
+1. **Custom Elements** - Define your own HTML tags
+2. **Shadow DOM** - Encapsulated styling and markup
+3. **HTML Templates** - Reusable DOM fragments
+### Why Web Components?
+**Framework Agnostic**
+Works with any JavaScript framework or plain HTML:
+- React, Vue, Angular, Svelte
+- Vanilla JavaScript
+- Static HTML pages
+- Server-rendered pages
+**Style Encapsulation**
+Shadow DOM prevents CSS conflicts:
+- SDK styles don't leak into your page
+- Your page styles don't affect the SDK
+- Components look consistent everywhere
+**Future-Proof**
+Built on web standards:
+- No framework lock-in
+- Works in modern browsers natively
+- Follows platform evolution
+### How It Works
+When you inject a product:
+```javascript
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+The SDK:
+1. Creates a custom element (e.g., `<product-lc>`)
+2. Attaches it to your container
+3. Renders content in Shadow DOM
+4. Registers event listeners
+## Client Initialization
+The SDK client is the main interface for all operations.
+### Initialization Modes
+#### Auto-Initialization (CDN)
+When using the CDN, the SDK auto-initializes on page load:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+The client becomes available globally under `window.LiquidCommerce.elements`.
+#### Programmatic Initialization (NPM)
+With NPM, you explicitly create the client:
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+### Phased Initialization
+The SDK uses a two-phase initialization strategy for optimal performance:
+**Phase 1: Essential Services (Immediate)**
+- Authentication
+- Configuration loading
+- Store initialization
+- Theme setup
+- Core component registration
+- Telemetry / logger wiring (see [Telemetry & Privacy](../reference/telemetry.md))
+- Debug panel (if enabled)
+**Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
+- Analytics (Google Tag Manager — see [Analytics (GTM/GA4)](../reference/analytics.md))
+- Cart pre-loading
+- Heavy component registration
+This ensures fast initial page loads while still providing full functionality.
+### Client Ready Event
+Listen for the client ready event to know when the SDK is initialized:
+```javascript
+window.addEventListener('lce:actions.client_ready', (event) => {
+  console.log('SDK version:', event.detail.data.version);
+  console.log('Ready at:', event.detail.data.timestamp);
+  // Safe to use client
+  window.LiquidCommerce.elements.actions.cart.openCart();
+}, { once: true });
+```
+## Declarative vs Programmatic
+The SDK offers two approaches for component injection.
+### Declarative (HTML Attributes)
+Configure components using HTML data attributes:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-container-1="product"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+<div id="product"></div>
+```
+**Advantages:**
+- No JavaScript required
+- Simple for static pages
+- Automatic initialization
+**Best for:**
+- Static HTML sites
+- CMS platforms (WordPress, Shopify)
+- Quick prototypes
+### Programmatic (JavaScript API)
+Use JavaScript methods to inject components:
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+**Advantages:**
+- Dynamic product selection
+- Conditional rendering
+- Framework integration
+- Full control over timing
+**Best for:**
+- Single-page applications
+- Dynamic content
+- React/Vue/Angular apps
+- Complex interactions
+### Mixing Both Approaches
+You can use declarative initialization and programmatic control:
+```html
+<!-- Auto-initialize SDK -->
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+<script>
+// Later, add products programmatically
+window.addEventListener('lce:actions.client_ready', async () => {
+  await window.LiquidCommerce.elements.injectProductElement([
+    { containerId: 'dynamic-product', identifier: selectedProductId }
+  ]);
+}, { once: true });
+</script>
+```
+## State Management
+The SDK maintains its own internal state for cart, checkout, and user data.
+### Store Service
+The SDK uses a centralized store service that:
+- Maintains reactive state (in-memory, within a single tab)
+- Persists data to localStorage
+- Falls back to API storage
+### State Persistence
+**Cart State:**
+- Saved to localStorage
+- Persists across sessions
+- Survives page refreshes
+- Other tabs pick up the persisted cart on their next load (no live cross-tab sync)
+**Address State:**
+- Saved when set by user
+- Used for availability checking
+- Cleared when user explicitly clears it
+**Checkout State:**
+- Created from cart
+- Exists during checkout flow
+- Cleared after order completion
+### Cross-Tab Persistence
+State is persisted to `localStorage` keyed by device ID. The SDK does **not** register a `storage` listener, `BroadcastChannel`, or other inter-tab subscription, so there is **no live cross-tab synchronization** — a change made in one tab is only reflected in another already-open tab after that tab reloads (which re-runs the persisted-state load and re-fetches by the persisted cart ID).
+## Component Lifecycle
+Understanding how components work helps with debugging and customization.
+### Injection Lifecycle
+1. **Validation** - Verify container exists
+2. **Creation** - Create Web Component
+3. **Attachment** - Add to DOM
+4. **Data Loading** - Fetch product/cart data
+5. **Rendering** - Display content
+6. **Event Setup** - Register listeners
+### Component Rerendering
+Components automatically rerender when data changes:
+```javascript
+// This triggers a rerender
+await window.LiquidCommerce.elements.actions.cart.addProduct([...]);
+// Cart component updates automatically
+```
+Manual rerendering:
+```javascript
+const components = window.LiquidCommerce.elements.getInjectedComponents();
+// The Map is keyed by the container ID passed to inject* (with any leading '#' stripped),
+// not a '<type>-<index>' string. For a component injected into id="product":
+const productComponent = components.get('product');
+// Force rerender
+productComponent?.rerender();
+```
+### Component Removal
+Components are removed when:
+- Their container is removed from DOM
+- Page navigation occurs
+- You explicitly remove them
+To clean up manually:
+```javascript
+const container = document.getElementById('product');
+container.innerHTML = ''; // Removes the component
+```
+## Event System
+The SDK uses a publish-subscribe pattern for events.
+### Event Namespaces
+All SDK events are namespaced to prevent conflicts:
+```javascript
+// Action events (user interactions)
+lce:actions.cart_opened
+lce:actions.product_add_to_cart
+// Form events (checkout forms)
+lce:forms.customer
+lce:forms.billing
+```
+### Event Flow
+1. User interacts with component
+2. Component publishes event
+3. SDK updates internal state
+4. Event bubbles to window
+5. Your code can listen and react
+### Subscribing to Events
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added:', event.detail.data);
+  // event.detail is { data, metadata }; payload fields live under .data:
+  // { cartId, itemId, fulfillmentId, partNumber, quantity, engravingLines? }
+});
+```
+See [Events Guide](../guides/events.md) for all available events.
+## Error Handling
+The SDK is designed to fail gracefully and not crash your site.
+### Error Isolation
+Most action failures are **not** thrown. Action methods take one of three paths, so `try/catch`
+alone is not enough to detect failure:
+| Situation | Behaviour |
+|---|---|
+| Malformed argument (missing `identifier`, invalid `fulfillmentType`, `quantity < 1`) | Throws `SDKError` — `try/catch` catches it |
+| Empty array or no arguments | Logs a warning and **resolves**. No event, no throw. |
+| Valid input that fails at runtime (product not found, unavailable variant, API error) | Publishes `lce:actions.cart_product_add_failed` and **resolves** |
+So listen for the `*_failed` event **and** wrap the call in `try/catch`:
+```javascript
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.log('Add to cart failed:', event.detail.data);
+});
+try {
+  // Throws only if the argument itself is malformed.
+  await window.LiquidCommerce.elements.actions.cart.addProduct([
+    { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+  ]);
+} catch (error) {
+  console.log('Malformed input rejected by the SDK');
+}
+// Either way, your page keeps working
+console.log('Page still functional');
+```
+See [Error Handling](../reference/error-handling.md) for the full matrix.
+### Error Types
+The SDK uses a custom `SDKError` class for all errors:
+```javascript
+class SDKError extends Error {
+  constructor(message, reThrow = false) {
+    super(message);
+    this.name = 'SDKError';
+    this.isSdk = true;
+    this.reThrow = reThrow; // Whether to re-throw to the user
+  }
+}
+```
+### Debug Mode
+Enable debug mode for detailed logging:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'development',
+  debugMode: 'console'  // or 'panel'
+});
+```
+**Debug Modes:**
+- `'none'` - No debug output (default)
+- `'console'` - Log to browser console
+- `'panel'` - Show debug panel on page
+> **Production note:** `debugMode` has no effect when `env` is `'production'`. All debug output — console logging and the debug panel — is disabled in production regardless of the `debugMode` you pass. `'console'` and `'panel'` only take effect in non-production environments.
+## Security & API Keys
+### API Key Protection
+Your API key is used for authentication but has limited privileges:
+- ✅ Read product catalog
+- ✅ Create carts and orders
+- ✅ Process payments
+- ❌ Access other merchants' data
+- ❌ Modify product catalog
+- ❌ Access admin functions
+### Environment Separation
+Use different API keys per environment:
+```javascript
+// Development
+const client = await Elements('dev_key_abc123', {
+  env: 'development'
+});
+// Production
+const client = await Elements('prod_key_xyz789', {
+  env: 'production'
+});
+```
+### Proxy Configuration
+To hide your API key and avoid ad blockers, use a proxy:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  proxy: {
+    baseUrl: 'https://yourdomain.com/api/elements-proxy'
+  }
+});
+```
+See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation details.
+## Browser Support
+The SDK requires modern browser features:
+**Minimum Versions:**
+- Chrome 66+ (March 2018)
+- Firefox 60+ (May 2018)
+- Safari 12+ (September 2018)
+- Edge 79+ (January 2020)
+**Required Features:**
+- Custom Elements (Web Components)
+- Shadow DOM
+- ES2018 JavaScript
+- Fetch API
+- LocalStorage
+For older browsers, include polyfills:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script data-liquid-commerce-elements ...></script>
+```
+See [Browser Support](../reference/browser-support.md) for details.
+## Performance Considerations
+The SDK is optimized for performance, but you can help:
+### Lazy Loading
+Load the SDK script with `defer`:
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+### Tree Shaking
+Use the checkout-only build when you don't need products:
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+This reduces bundle size by ~60%.
+### Component Injection Timing
+Inject components when needed, not all at once:
+```javascript
+// Good: Inject visible products first
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+// Then inject others after a delay
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+### Image Optimization
+The SDK automatically:
+- Lazy loads images
+- Uses responsive images
+- Implements carousel virtualization
+## Next Steps
+Now that you understand the core concepts:
+- **[Product Component](../guides/product-component.md)** - Learn about product displays
+- **[Cart Component](../guides/cart-component.md)** - Understand cart functionality
+- **[Checkout Component](../guides/checkout-component.md)** - Master the checkout flow
+- **[Theming](../guides/theming.md)** - Customize the look and feel
+- **[Events](../guides/events.md)** - React to user actions
+- **[API Reference](../api/client.md)** - Explore all available methods