@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

package/docs/gitbook/overview.md

@@ -0,0 +1,166 @@
+# Elements SDK
+
+A lightweight, developer-facing guide to integrate LiquidCommerce Elements SDK into your site or app.
+
+## What it is
+Elements SDK is a Web Components-based e-commerce SDK that embeds product, cart, address, and checkout experiences into any website. It works with plain HTML or any framework and exposes a simple client + actions API.
+
+## Core components
+- Product: product detail display + add to cart
+- Cart: slide-out cart drawer + promo codes
+- Checkout: full checkout flow (drawer or hosted page)
+- Address: delivery location and availability
+
+## Quick start (CDN)
+```html
+<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>
+
+<div id="product"></div>
+```
+
+## Quick start (NPM)
+```bash
+npm install @liquidcommerce/elements-sdk
+```
+
+```js
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+## Initialization modes
+- Declarative (CDN): data attributes on the script tag, auto-initialized
+- Programmatic (NPM or CDN): call `Elements(...)` and inject components
+
+The client is available globally as `window.elements` as soon as the SDK is ready.
+
+## Quick Start Guide (auto-setup)
+Most partners use the auto-setup approach because it is the fastest to implement. It supports rich configuration via data attributes, including product injection, cart buttons, checkout, query param handling, and more.
+
+See [Quick Start Guide](./quick-start-guide.md) for the complete list of supported attributes and combinations.
+
+## Configuration basics
+```js
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production', // development | staging | production
+});
+```
+
+## Client surface (exposed methods)
+After initialization, the client exposes three main groups: injection methods, `actions`, and `ui` helpers, plus component management.
+
+### Injection methods
+Use these to mount SDK components into your DOM. Each method is shown with a minimal example.
+
+#### `injectProductElement(params[])`
+Inject one or more product components by container ID + product identifier.
+```js
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' }
+]);
+```
+
+#### `injectAddressElement(containerId, options?)`
+Inject a standalone address component (optional callbacks like `onAddressSet`).
+```js
+await client.injectAddressElement('address', {
+  onAddressSet: (address) => console.log(address)
+});
+```
+
+#### `injectCartElement(containerId)`
+Inject a standalone cart component (rare; cart drawer is automatic).
+```js
+await client.injectCartElement('cart');
+```
+
+#### `injectCheckoutElement(params)`
+Inject a hosted checkout into a container.
+```js
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'checkout_abc123',
+  hideHeader: false
+});
+```
+
+
+### Actions (`client.actions.*`)
+Actions are programmatic controls for state changes and flows. The full list with details is in [Actions](./actions.md).
+
+```js
+// Example: add to cart and open cart
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+```
+
+### UI helpers (`client.ui.*`)
+Helpers for common cart UI elements that stay in sync automatically.
+
+#### `ui.cartButton(containerId, showItemsCount?)`
+Renders a cart button in a container.
+```js
+window.elements.ui.cartButton('header-cart', true);
+```
+
+#### `ui.floatingCartButton(showItemsCount?)`
+Renders a floating cart button (bottom-right).
+```js
+window.elements.ui.floatingCartButton(true);
+```
+
+#### `ui.cartSubtotal(elementId)`
+Keeps a DOM element updated with cart subtotal.
+```html
+<span id="cart-total"></span>
+```
+```js
+window.elements.ui.cartSubtotal('cart-total');
+```
+
+#### `ui.cartItemsCount(elementId, { hideZero })`
+Keeps a DOM element updated with item count.
+```html
+<span id="items-count"></span>
+```
+```js
+window.elements.ui.cartItemsCount('items-count', { hideZero: true });
+```
+
+### Component management
+You can inspect and re-render injected components.
+
+- `getInjectedComponents()`  
+  Returns a map of injected components keyed by container ID.
+
+```js
+const components = client.getInjectedComponents();
+const productComponent = components.get('product-1');
+
+productComponent.getType();    // 'product'
+productComponent.getElement(); // underlying element
+productComponent.rerender();   // force re-render
+```
+
+## Recommended flow
+1. Initialize the client
+2. Inject product(s)
+3. Let the cart drawer handle checkout by default
+4. Use actions + events to track analytics and UI updates
+
+For details, see the component pages: Product, Cart, Checkout, Address, Actions, Events.

package/docs/gitbook/product.md

@@ -0,0 +1,64 @@
+# Product
+
+The Product component renders a complete product view with images, pricing, fulfillment options, and add-to-cart.
+
+## What you get
+- Image carousel
+- Name, description, pricing
+- Size selection (if applicable)
+- Fulfillment type selection (shipping or on-demand)
+- Retailer selection (when multiple retailers are available)
+- Personalization/engraving (when supported)
+- Quantity controls
+- Location-based availability and pricing
+
+## Add a product (CDN, declarative)
+```html
+<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>
+
+<div id="product"></div>
+```
+
+## Add a product (programmatic)
+```js
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+## Identifiers
+Use any of the supported identifiers:
+- UPC
+- Grouping ID
+
+The SDK resolves the correct product automatically.
+
+## Product actions
+```js
+const product = window.elements.actions.product.getDetails('00619947000020');
+console.log(product.name, product.price);
+```
+
+## Product events (examples)
+```js
+window.addEventListener('lce:actions.product_loaded', (event) => {
+  const { identifier, name, price } = event.detail.data;
+});
+
+window.addEventListener('lce:actions.product_add_to_cart', (event) => {
+  const { identifier, quantity, fulfillmentType } = event.detail.data;
+});
+```
+
+## Address requirement
+If an address is required for availability, the SDK automatically prompts the user to set it before adding to cart.

package/docs/gitbook/quick-start-guide.md

@@ -0,0 +1,393 @@
+# Quick Start Guide (Auto-Setup)
+
+Most partners use the auto-setup approach because it is the fastest path to production. This guide covers the full data-attribute setup and all supported combinations.
+
+## 1) Main script tag
+The main SDK auto-initializes when it finds a script tag with `data-liquid-commerce-elements`.
+
+```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>
+```
+
+### Core configuration
+**Attribute:** `data-liquid-commerce-elements`  
+Marks the script tag for auto-initialization.
+
+**Attribute:** `data-token` (required)  
+Your API key.
+
+**Attribute:** `data-env` (optional)  
+`development`, `staging`, or `production` (default: `production`).
+
+## 2) Product injection options
+You can inject products in three different ways. All can be used together.
+
+### A) Paired attributes on the main script tag
+Use `data-product-*` with `data-container-*` pairs.
+
+**Attribute:** `data-product-*` + `data-container-*`  
+Pairs product identifiers to container IDs by matching the numeric suffix.
+
+```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"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div id="product-1"></div>
+<div id="product-2"></div>
+```
+
+### B) Attributed product elements
+Any `div` with `data-lce-product` is treated as a product container.
+
+**Attribute:** `data-lce-product`  
+Injects a product into the element and auto-generates a container ID.
+
+```html
+<div data-lce-product="00619947000020"></div>
+<div data-lce-product="08504405135"></div>
+```
+
+The SDK auto-generates unique container IDs for these elements.
+
+### C) JSON script tag
+Provide an array of objects with `containerId` and `identifier`.
+
+**Attribute:** `data-liquid-commerce-elements-products`  
+Reads a JSON array of product definitions.
+
+```html
+<script data-liquid-commerce-elements-products type="application/json">
+[
+  { "containerId": "product-1", "identifier": "00619947000020" },
+  { "containerId": "product-2", "identifier": "08504405135" }
+]
+</script>
+```
+
+## 3) Cart options (auto-UI + custom UI)
+Cart buttons are configured from the main script tag.
+
+### Basic cart button
+**Attribute:** `data-cart-button`  
+Renders a cart button in the specified container (by ID or selector).
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-button="header-cart"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+
+<div id="header-cart"></div>
+```
+
+### Cart button with badge
+**Attribute:** `data-cart-badge-button`  
+Renders a cart button with item count badge.
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-badge-button="header-cart"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Floating cart button
+Provide the attribute with no value.
+
+**Attribute:** `data-cart-button` (no value)  
+Creates a floating cart button.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-button
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Positioning cart buttons
+You can position the cart button relative to any element using:
+- `inside:` (default)
+- `above:`
+- `below:`
+- `replace:`
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-button="above:.nav"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Mobile-specific cart buttons
+Use the mobile attributes to target mobile placement separately:
+- `data-cart-mobile-button`
+- `data-cart-mobile-badge-button`
+
+**Attribute:** `data-cart-mobile-button`  
+Places a mobile-specific cart button.
+
+**Attribute:** `data-cart-mobile-badge-button`  
+Places a mobile-specific cart button with badge.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-mobile-button="inside:#mobile-nav"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Hide cart buttons entirely
+**Attribute:** `data-cart-button-hidden`  
+Disables auto-created cart buttons.
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-cart-button-hidden
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Cart toggle buttons (custom UI)
+Any element with `data-lce-cart-toggle-button` will toggle the cart drawer.
+
+**Attribute:** `data-lce-cart-toggle-button`  
+Toggles the cart drawer on click.
+
+```html
+<button data-lce-cart-toggle-button>View Cart</button>
+```
+
+### Cart items count (custom UI)
+Use `data-lce-cart-items-count` on any element to show item count.
+
+**Attribute:** `data-lce-cart-items-count`  
+Renders a live cart item count.
+
+```html
+<span data-lce-cart-items-count></span>
+```
+
+By default it hides when the cart is empty. To keep it visible with `0`, set:
+
+```html
+<span data-lce-cart-items-count="keep-zero"></span>
+```
+
+## 4) Checkout (hosted injection + checkout-only build)
+Hosted checkout needs two things working together:
+1) A **checkout URL** so the cart can redirect to your hosted checkout page.
+2) A **checkout param name** so the hosted page can read the checkout ID from the URL and load it.
+
+### Checkout container
+**Attribute:** `data-lce-checkout`  
+Injects the hosted checkout into this container on the checkout page.
+```html
+<div data-lce-checkout></div>
+```
+
+### Hide checkout header
+**Attribute:** `hide-header`  
+Hides the SDK header so you can render your own header and layout.
+```html
+<div data-lce-checkout hide-header></div>
+```
+
+### Exit checkout button
+**Attribute:** `data-lce-exit-checkout`  
+Lets you build your own “Exit checkout” UI. The SDK wires the click to the checkout exit action.
+```html
+<button data-lce-exit-checkout>Exit checkout</button>
+```
+
+### Checkout ID from query params (required for hosted checkout)
+Use `data-checkout-param` on the script tag to control which query param provides the checkout ID.
+**Attribute:** `data-checkout-param`  
+Sets the query parameter name (must start with `lce_`). The hosted page reads this param to load the checkout.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-checkout-param="lce_checkout"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+Notes:
+- Query parameter names must start with `lce_` or they are ignored.
+- Default is `lce_checkout` if not provided.
+
+### Checkout redirect URL (required for hosted checkout)
+**Attribute:** `data-checkout-url`  
+Defines the hosted checkout page URL pattern. The cart drawer redirects to this URL and injects the checkout token into `{token}`.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout?lce_checkout={token}"
+  data-checkout-param="lce_checkout"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Checkout-only auto-initialize
+Use the checkout-only build when you only need checkout on the hosted checkout page. It supports the same hosted-checkout attributes (`data-lce-checkout`, `data-checkout-param`, `hide-header`, `data-lce-exit-checkout`) but ships a smaller script for faster load time.
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+
+Supported attributes on checkout-only script:
+- `data-token` (required)
+- `data-env` (optional)
+- `data-debug-mode` (optional, non-production only)
+- `data-checkout-url` (optional)
+
+The checkout-only build also supports `data-lce-checkout` containers and `data-checkout-param` query parameter handling.
+
+## 5) Auto actions from query parameters
+Auto-init can read query params to add a product or apply a promo code.
+
+### Add product to cart via query params
+- `data-product-param` (required)
+- `data-product-fulfillment-type-param` (optional, `shipping` or `onDemand`)
+
+**Attribute:** `data-product-param`  
+Name of query param that contains the product identifier (must start with `lce_`).
+
+**Attribute:** `data-product-fulfillment-type-param`  
+Name of query param that contains fulfillment type (must start with `lce_`).
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-product-param="lce_product"
+  data-product-fulfillment-type-param="lce_fulfillment"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+Example URL:
+```
+https://yoursite.com?lce_product=00619947000020&lce_fulfillment=shipping
+```
+
+### Apply promo code via query params
+- `data-promo-code-param`
+
+**Attribute:** `data-promo-code-param`  
+Name of query param that contains the promo code (must start with `lce_`).
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-promo-code-param="lce_promo"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+Example URL:
+```
+https://yoursite.com?lce_promo=SUMMER20
+```
+
+Notes:
+- Query parameter names must start with `lce_` or they are ignored.
+
+## 6) Advanced script options (optional)
+These are supported but not required for most implementations.
+
+### Promo ticker
+All four of these must be present to enable the promo ticker.
+
+**Attributes:** `data-promo-code`, `data-promo-text`, `data-promo-separator`, `data-promo-active-from`, `data-promo-active-until`  
+Enables the promo ticker. `data-promo-text` is pipe-separated (e.g. `"Text A|Text B"`).
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-promo-code="SUMMER20"
+  data-promo-text="20% Off|Free shipping over $50"
+  data-promo-separator="•"
+  data-promo-active-from="2026-06-01T00:00:00Z"
+  data-promo-active-until="2026-08-31T23:59:59Z"
+  type="text/javascript"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+### Development config
+For local development or testing, you can inject development overrides via a JSON script tag:
+
+**Attribute:** `data-liquid-commerce-elements-development`  
+Reads JSON for development overrides.
+
+```html
+<script data-liquid-commerce-elements-development type="application/json">
+{
+  "customApiUrl": "http://localhost:3000/api",
+  "paymentMethodId": "pm_test_123",
+  "openShadowDom": true
+}
+</script>
+```