@liquidcommerce/elements-sdk 2.7.1 → 2.7.3

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

@@ -1,393 +0,0 @@
-# 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>
-```