npm - @liquidcommerce/elements-sdk - Versions diffs - 2.7.0 → 2.7.2 - Mend

@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

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 (81) hide show

package/README.md +83 -2750
package/dist/index.checkout.esm.js +6898 -6837
package/dist/index.esm.js +11463 -10993
package/dist/types/auto-initialize/shared-utils.d.ts +5 -0
package/dist/types/constants/core.constant.d.ts +0 -4
package/dist/types/core/base-component.service.d.ts +2 -1
package/dist/types/core/pubsub/interfaces/checkout.interface.d.ts +1 -0
package/dist/types/enums/core.enum.d.ts +11 -0
package/dist/types/interfaces/configs/product-list.interface.d.ts +2 -2
package/dist/types/interfaces/core.interface.d.ts +5 -4
package/dist/types/modules/address/address-input.component.d.ts +11 -0
package/dist/types/modules/checkout/components/checkout-stripe-form.component.d.ts +2 -1
package/dist/types/modules/product-list/components/card-components/index.d.ts +3 -0
package/dist/types/modules/product-list/components/card-components/product-badge.d.ts +8 -0
package/dist/types/modules/product-list/components/card-components/product-fulfillments.d.ts +2 -0
package/dist/types/modules/product-list/components/card-components/product-price-and-personalization.d.ts +13 -0
package/dist/types/modules/product-list/components/card-components/product-title.d.ts +6 -0
package/dist/types/modules/product-list/components/index.d.ts +1 -0
package/dist/types/modules/product-list/components/product-list-engraving.component.d.ts +5 -1
package/dist/types/modules/product-list/components/product-list-product-pre-cart.component.d.ts +28 -0
package/dist/types/modules/product-list/components/product-list-retailers.component.d.ts +10 -2
package/dist/types/modules/product-list/product-list-card.component.d.ts +0 -5
package/dist/types/modules/product-list/product-list.commands.d.ts +11 -2
package/dist/types/modules/product-list/product-list.interface.d.ts +1 -0
package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts +11 -2
package/dist/types/modules/ui-components/lce-element/lce-element.component.d.ts +2 -1
package/dist/types/utils/dom-compat.d.ts +2 -0
package/docs/gitbook/actions.md +964 -0
package/docs/gitbook/address.md +48 -0
package/docs/gitbook/cart.md +65 -0
package/docs/gitbook/checkout.md +131 -0
package/docs/gitbook/events.md +1765 -0
package/docs/gitbook/overview.md +166 -0
package/docs/gitbook/product.md +64 -0
package/docs/gitbook/quick-start-guide.md +393 -0
package/docs/v1/README.md +210 -0
package/docs/v1/api/actions/address-actions.md +281 -0
package/docs/v1/api/actions/cart-actions.md +337 -0
package/docs/v1/api/actions/checkout-actions.md +387 -0
package/docs/v1/api/actions/product-actions.md +115 -0
package/docs/v1/api/client.md +482 -0
package/docs/v1/api/configuration.md +1 -0
package/docs/v1/api/injection-methods.md +247 -0
package/docs/v1/api/typescript-types.md +1 -0
package/docs/v1/api/ui-helpers.md +200 -0
package/docs/v1/examples/advanced-patterns.md +96 -0
package/docs/v1/examples/checkout-flow.md +91 -0
package/docs/v1/examples/custom-theming.md +63 -0
package/docs/v1/examples/multi-product-page.md +90 -0
package/docs/v1/examples/simple-product-page.md +89 -0
package/docs/v1/getting-started/concepts.md +507 -0
package/docs/v1/getting-started/installation.md +328 -0
package/docs/v1/getting-started/quick-start.md +405 -0
package/docs/v1/guides/address-component.md +431 -0
package/docs/v1/guides/best-practices.md +324 -0
package/docs/v1/guides/cart-component.md +737 -0
package/docs/v1/guides/checkout-component.md +672 -0
package/docs/v1/guides/events.md +926 -0
package/docs/v1/guides/product-component.md +686 -0
package/docs/v1/guides/product-list-component.md +598 -0
package/docs/v1/guides/theming.md +216 -0
package/docs/v1/integration/angular.md +39 -0
package/docs/v1/integration/laravel.md +41 -0
package/docs/v1/integration/nextjs.md +60 -0
package/docs/v1/integration/proxy-setup.md +89 -0
package/docs/v1/integration/react.md +64 -0
package/docs/v1/integration/vanilla-js.md +84 -0
package/docs/v1/integration/vue.md +34 -0
package/docs/v1/reference/browser-support.md +44 -0
package/docs/v1/reference/error-handling.md +70 -0
package/docs/v1/reference/performance.md +54 -0
package/docs/v1/reference/troubleshooting.md +64 -0
package/package.json +1 -1
package/docs/ACTIONS.md +0 -1301
package/docs/BROWSER_SUPPORT.md +0 -279
package/docs/CONFIGURATION.md +0 -997
package/docs/DOCUMENTATION_INDEX.md +0 -319
package/docs/EVENTS.md +0 -798
package/docs/PROXY.md +0 -228
package/docs/THEMING.md +0 -681
package/docs/TROUBLESHOOTING.md +0 -793

package/docs/v1/getting-started/quick-start.md ADDED Viewed

@@ -0,0 +1,405 @@
+# Quick Start
+Get a product display with add-to-cart functionality working on your page in under 5 minutes.
+## What You'll Build
+A fully functional product page with:
+- Product images and details
+- Size selection
+- Fulfillment options (shipping/on-demand delivery)
+- Add to cart button
+- Shopping cart drawer
+- Complete checkout flow
+## Prerequisites
+- A LiquidCommerce API key (contact your LiquidCommerce representative)
+- A product identifier
+- A web page or HTML file
+## Step 1: Add the SDK Script
+Add the Elements SDK script tag to your HTML `<head>`:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+</head>
+<body>
+  <!-- We'll add the product here -->
+</body>
+</html>
+```
+**Replace `YOUR_API_KEY`** with your actual API key.
+## Step 2: Add a Product Container
+Create a container where the product will be displayed:
+```html
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <!-- Product will be injected here -->
+  <div id="product-display"></div>
+</body>
+```
+## Step 3: Configure the Product (Declarative)
+Add product configuration using HTML data attributes on the script tag:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-display"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+**New attributes:**
+- `data-container-1="product-display"` - Points to the container ID
+- `data-product-1="00619947000020"` - The product identifier
+The numbers (1) connect the container to its product. For multiple products, increment the number:
+- `data-container-2` with `data-product-2`
+- `data-container-3` with `data-product-3`
+- etc.
+## Complete Example
+Here's the complete HTML for a working product page:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Premium Whiskey - Buy Online</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product-display"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    h1 {
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+That's it! Save the file and open it in a browser. You should see:
+1. Product images in a carousel
+2. Product name and description
+3. Size selector
+4. Fulfillment type selector (shipping/delivery)
+5. Retailer selection
+6. Add to cart button
+When you click "Add to Cart," a cart drawer slides in from the right with checkout functionality.
+## Alternative: Programmatic Setup
+If you prefer JavaScript over HTML attributes:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+  <script defer>
+    // Wait for SDK to be ready
+    window.addEventListener('lce:actions.client_ready', async (event) => {
+      const client = window.elements;
+      // Inject the product
+      await client.injectProductElement([
+        {
+          containerId: 'product-display',
+          identifier: '00619947000020'
+        }
+      ]);
+    });
+  </script>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+Or with NPM:
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+async function initProduct() {
+  const client = await Elements('YOUR_API_KEY', {
+    env: 'production'
+  });
+  await client.injectProductElement([
+    {
+      containerId: 'product-display',
+      identifier: '00619947000020'
+    }
+  ]);
+}
+initProduct();
+```
+## Multiple Products
+To display multiple products on one page:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-1"
+  data-product-1="00619947000020"
+  data-container-2="product-2"
+  data-product-2="08504405135"
+  data-container-3="product-3"
+  data-product-3="08068660001"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+<div id="product-1"></div>
+<div id="product-2"></div>
+<div id="product-3"></div>
+```
+Or programmatically:
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' },
+  { containerId: 'product-3', identifier: '08068660001' }
+]);
+```
+## What Happens Automatically
+The SDK handles everything for you:
+1. **Address Collection** - If needed, prompts for delivery location
+2. **Availability Check** - Shows only available fulfillment options
+3. **Cart Management** - Maintains cart across page refreshes and tabs
+4. **Checkout Flow** - Complete payment and order processing
+5. **Error Handling** - Graceful error messages and recovery
+6. **Mobile Responsiveness** - Works on all screen sizes
+## Customization
+Want to customize the look, visit the Elements Builder in our [Partner Portal](https://app.liquidcommerce.co/)? Want to manually override your theme, you can pass a `customTheme: IClientCustomThemeConfig` configuration:
+```html
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.elements;
+  // You can customize after initialization
+  // See Theming Guide for more options
+});
+</script>
+```
+Or with NPM:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600]
+        }
+      }
+    }
+  }
+});
+```
+## Testing Different Products
+To test with different products, simply change the product identifier:
+```html
+<!-- Replace with your product UPC -->
+data-product-1="YOUR_PRODUCT_IDENTIFIER"
+```
+Contact your LiquidCommerce representative for available product identifiers.
+## Troubleshooting
+### Product Not Showing
+1. **Check the browser console** for errors
+2. **Verify your API key** is correct
+3. **Confirm the product identifier** exists in your catalog
+4. **Check the container ID** matches your HTML
+### Styling Issues
+The product uses Shadow DOM for style encapsulation. To customize:
+- Use the `customTheme` configuration option
+- See [Theming Guide](../guides/theming.md) for detailed customization
+### Cart Not Opening
+The cart should open automatically after adding a product. If it doesn't:
+1. Check browser console for JavaScript errors
+2. Verify no other scripts are conflicting
+3. Try manually opening: `window.elements.actions.cart.openCart()`
+## Next Steps
+Now that you have a basic product working:
+- **[Core Concepts](./concepts.md)** - Understand how the SDK works
+- **[Product Component Guide](../guides/product-component.md)** - Deep dive into product features
+- **[Cart Component Guide](../guides/cart-component.md)** - Learn about cart functionality
+- **[Checkout Component Guide](../guides/checkout-component.md)** - Customize the checkout experience
+- **[Theming Guide](../guides/theming.md)** - Make it match your brand
+- **[Events](../guides/events.md)** - React to user actions
+- **[API Reference](../api/client.md)** - Explore all available methods
+## Complete Working Example
+Try this complete example with your API key:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Whiskey Shop</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://assets-elements.liquidcommerce.us/all/elements.js"
+  ></script>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
+      background: #f5f5f5;
+    }
+    header {
+      background: white;
+      padding: 20px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      margin-bottom: 40px;
+    }
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 0 20px;
+    }
+    h1 {
+      text-align: center;
+      color: #333;
+    }
+    #product {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="container">
+      <h1>🥃 Premium Spirits Collection</h1>
+    </div>
+  </header>
+  <div class="container">
+    <div id="product"></div>
+  </div>
+</body>
+</html>
+```
+Replace `YOUR_API_KEY` with your actual key and you're ready to go!