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/installation.md ADDED Viewed

@@ -0,0 +1,328 @@
+# Installation
+The LiquidCommerce Elements SDK can be integrated into your website using either a CDN script tag or as an NPM package.
+## Browser Requirements
+The SDK requires:
+- Modern browser with Web Components support (Chrome 66+, Firefox 60+, Safari 12+, Edge 79+)
+- Shadow DOM support
+- JavaScript enabled
+For older browsers, you'll need to include Web Components and Shadow DOM polyfills.
+## CDN Installation (Recommended)
+The simplest way to get started is by adding the SDK script tag to your HTML.
+### Basic Setup
+Add the following script tag to your page's `<head>` section:
+```html
+<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 Attributes
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-liquid-commerce-elements` | Yes | Identifies this as the Elements SDK script |
+| `data-token` | Yes | Your LiquidCommerce API key |
+| `data-env` | Yes | Environment: `development`, `staging`, or `production` |
+| `defer` | Recommended | Allows non-blocking script loading |
+### Where to Place the Script
+While the `<head>` section is recommended, the script can be placed anywhere on your page:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Store</title>
+  <!-- SDK script in head (recommended) -->
+  <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>
+  <!-- Your content -->
+</body>
+</html>
+```
+The `defer` attribute ensures the script loads asynchronously without blocking page content, keeping your site fast regardless of placement.
+### Checkout-Only Build
+If you only need checkout functionality (without product displays or cart), use the lighter checkout-only build:
+```html
+<script
+  defer
+  data-liquid-commerce-elements-checkout
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+This build is tree-shaken and significantly smaller, ideal for dedicated checkout pages.
+## NPM Installation
+For JavaScript/TypeScript projects using a bundler (Webpack, Rollup, Vite, etc.), install via NPM:
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+### Basic Usage
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+// Initialize the client
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production'
+});
+// Client is ready to use
+console.log('Elements SDK initialized');
+```
+### Checkout-Only Import
+For tree-shaking benefits in checkout-only scenarios:
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+```
+### TypeScript Support
+The SDK includes full TypeScript definitions. Import types as needed:
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement
+} from '@liquidcommerce/elements-sdk';
+const config: ILiquidCommerceElementsConfig = {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff'
+      }
+    }
+  }
+};
+const client: ILiquidCommerceElementsClient = await Elements('YOUR_API_KEY', config);
+```
+## Framework Integration
+### React
+```jsx
+import { Elements } from '@liquidcommerce/elements-sdk';
+import { useEffect, useState } from 'react';
+function App() {
+  const [elementsClient, setElementsClient] = useState(null);
+  useEffect(() => {
+    async function initElements() {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production'
+      });
+      setElementsClient(client);
+    }
+    initElements();
+  }, []);
+  useEffect(() => {
+    if (elementsClient) {
+      elementsClient.injectProductElement([
+        { containerId: 'product-1', identifier: '00619947000020' }
+      ]);
+    }
+  }, [elementsClient]);
+  return (
+    <div>
+      <div id="product-1"></div>
+    </div>
+  );
+}
+```
+### Vue
+```vue
+<template>
+  <div id="product-1"></div>
+</template>
+<script>
+import { Elements } from '@liquidcommerce/elements-sdk';
+export default {
+  async mounted() {
+    const client = await Elements('YOUR_API_KEY', {
+      env: 'production'
+    });
+    await client.injectProductElement([
+      { containerId: 'product-1', identifier: '00619947000020' }
+    ]);
+  }
+}
+</script>
+```
+### Next.js
+In Next.js, initialize the SDK in a client component:
+```jsx
+'use client';
+import { Elements } from '@liquidcommerce/elements-sdk';
+import { useEffect } from 'react';
+export default function ProductPage() {
+  useEffect(() => {
+    async function init() {
+      const client = await Elements('YOUR_API_KEY', {
+        env: 'production',
+        proxy: {
+          baseUrl: '/api/elements-proxy'
+        }
+      });
+      await client.injectProductElement([
+        { containerId: 'product', identifier: '00619947000020' }
+      ]);
+    }
+    init();
+  }, []);
+  return <div id="product"></div>;
+}
+```
+> **Note:** When using Next.js or other frameworks with server-side rendering, the SDK must be initialized on the client side only. The SDK requires browser APIs (Window, Document, Web Components) and cannot run server-side.
+## Configuration Options
+The SDK accepts a configuration object during initialization:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',           // Required: 'development' | 'staging' | 'production'
+  debugMode: 'console',         // Optional: 'none' | 'console' | 'panel'
+  customTheme: { /* ... */ },   // Optional: Theme customization
+  promoTicker: [ /* ... */ ],   // Optional: Promo ticker configuration
+  proxy: { /* ... */ },         // Optional: Proxy configuration
+  checkout: { /* ... */ },      // Optional: Checkout configuration
+  development: { /* ... */ }    // Optional: Development/testing options
+});
+```
+See [Configuration Reference](../api/configuration.md) for complete configuration options.
+## Verification
+After installation, verify the SDK is loaded correctly:
+### CDN Verification
+Open your browser's console and check for:
+```javascript
+// The client is available globally
+console.log(window.elements);
+// Should output: { injectProductElement: ƒ, ui: {...}, actions: {...}, ... }
+```
+### NPM Verification
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+console.log(client); // Should output the client object
+```
+## Troubleshooting Installation
+### Script Not Loading
+If the SDK script fails to load:
+1. **Check the network tab** in browser DevTools for 404 or CORS errors
+2. **Verify the script URL** is correct and accessible
+3. **Check ad blockers** - they may block scripts with "commerce" in the name (see [Proxy Setup](../integration/proxy-setup.md))
+### Web Components Not Supported
+If you see an error about Web Components:
+```
+[LiquidCommerce Elements] SDK requires support for Web Components
+```
+Include a Web Components polyfill before the SDK script:
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+### TypeScript Errors
+If you encounter TypeScript errors:
+1. Ensure TypeScript version is 4.5 or higher
+2. Check that `@liquidcommerce/elements-sdk` is in your `dependencies` (not `devDependencies`)
+3. Verify your `tsconfig.json` includes:
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
+```
+## Next Steps
+- **Quick Start**: [Build your first product page in 5 minutes](./quick-start.md)
+- **Core Concepts**: [Understand how the SDK works](./concepts.md)
+- **Component Guides**: [Product](../guides/product-component.md), [Cart](../guides/cart-component.md), [Checkout](../guides/checkout-component.md)
+- **API Reference**: [Full API documentation](../api/client.md)