@liquidcommerce/elements-sdk 2.6.7 → 2.7.1

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>
+```

package/docs/v1/README.md

@@ -0,0 +1,210 @@
+# Elements SDK v1 Documentation
+
+Welcome to the comprehensive documentation for the LiquidCommerce Elements SDK v1.
+
+## What is Elements SDK?
+
+The Elements SDK is a Web Components-based e-commerce SDK that allows you to add product displays, shopping carts, and checkout flows to any website with minimal code.
+
+## Quick Links
+
+- **[Installation](./getting-started/installation.md)** - Get started in minutes
+- **[Quick Start](./getting-started/quick-start.md)** - Build your first product page
+- **[API Reference](./api/client.md)** - Complete API documentation
+
+## Documentation Sections
+
+### Getting Started
+
+Essential guides for new users:
+
+- **[Installation](./getting-started/installation.md)** - CDN, NPM, and framework integration
+- **[Quick Start](./getting-started/quick-start.md)** - Your first product page in 5 minutes
+- **[Core Concepts](./getting-started/concepts.md)** - Understand how the SDK works
+
+### Component Guides
+
+In-depth guides for each major component:
+
+- **[Product Component](./guides/product-component.md)** - Display products with add-to-cart functionality
+- **[Cart Component](./guides/cart-component.md)** - Shopping cart and item management
+- **[Checkout Component](./guides/checkout-component.md)** - Complete purchase flow
+- **[Address Component](./guides/address-component.md)** - Delivery location management
+- **[Product List Component](./guides/product-list-component.md)** - Filterable product catalogs
+- **[Theming](./guides/theming.md)** - Customize appearance and branding
+- **[Events](./guides/events.md)** - Event system and subscriptions
+- **[Best Practices](./guides/best-practices.md)** - Patterns, tips, and recommendations
+
+### API Reference
+
+Complete API documentation:
+
+**Core API:**
+- **[Client API](./api/client.md)** - Main SDK client interface
+- **[Injection Methods](./api/injection-methods.md)** - Component injection
+- **[UI Helpers](./api/ui-helpers.md)** - Cart buttons and UI elements
+- **[Configuration](./api/configuration.md)** - All configuration options
+- **[TypeScript Types](./api/typescript-types.md)** - Type definitions
+
+**Actions API:**
+- **[Product Actions](./api/actions/product-actions.md)** - `actions.product.*`
+- **[Address Actions](./api/actions/address-actions.md)** - `actions.address.*`
+- **[Cart Actions](./api/actions/cart-actions.md)** - `actions.cart.*`
+- **[Checkout Actions](./api/actions/checkout-actions.md)** - `actions.checkout.*`
+
+### Architecture (To Be Done In Future Versions)
+
+Deep dive into SDK internals:
+
+- **[Overview](./architecture/overview.md)** - System architecture
+- **[Initialization](./architecture/initialization.md)** - Phased initialization process
+- **[State Management](./architecture/state-management.md)** - Store service and persistence
+- **[Event System](./architecture/event-system.md)** - PubSub architecture
+- **[Web Components](./architecture/web-components.md)** - Component factory and Shadow DOM
+- **[Build System](./architecture/build-system.md)** - Bundles and tree-shaking
+
+### Framework Integration
+
+Integration guides for popular frameworks:
+
+- **[React](./integration/react.md)** - React integration patterns and hooks
+- **[Next.js](./integration/nextjs.md)** - Next.js setup with SSR considerations
+- **[Vue](./integration/vue.md)** - Vue component integration
+- **[Angular](./integration/angular.md)** - Angular client-only setup
+- **[Laravel](./integration/laravel.md)** - Blade + CDN integration
+- **[Vanilla JavaScript](./integration/vanilla-js.md)** - Pure JavaScript integration
+- **[Proxy Setup](./integration/proxy-setup.md)** - Ad blocker avoidance
+
+### Reference
+
+Technical reference and troubleshooting:
+
+- **[Browser Support](./reference/browser-support.md)** - Compatibility matrix
+- **[Troubleshooting](./reference/troubleshooting.md)** - Common issues and solutions
+- **[Error Handling](./reference/error-handling.md)** - Error types and debugging
+- **[Performance](./reference/performance.md)** - Optimization tips and best practices
+
+### Examples
+
+Practical examples with working code:
+
+- **[Simple Product Page](./examples/simple-product-page.md)** - Basic PDP implementation
+- **[Multi-Product Page](./examples/multi-product-page.md)** - Multiple products on one page
+- **[Complete Checkout Flow](./examples/checkout-flow.md)** - Full e-commerce flow
+- **[Custom Theming](./examples/custom-theming.md)** - Brand customization examples
+- **[Advanced Patterns](./examples/advanced-patterns.md)** - Complex integration scenarios
+
+## Common Tasks
+
+### Adding a Product
+
+**Declarative (HTML):**
+```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>
+```
+
+**Programmatic (JavaScript):**
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+### Opening the Cart
+
+```javascript
+window.elements.actions.cart.openCart();
+```
+
+### Adding to Cart Programmatically
+
+```javascript
+await window.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // true = open cart after adding
+```
+
+### Listening for Events
+
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added to cart:', event.detail.data);
+});
+```
+
+### Customizing Theme
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px'
+      }
+    }
+  }
+});
+```
+
+## Key Concepts
+
+### Web Components
+The SDK uses native Web Components for framework-agnostic integration and style encapsulation.
+
+### Shadow DOM
+Components use Shadow DOM to prevent CSS conflicts and ensure consistent styling.
+
+### Auto-Initialization
+When using the CDN, the SDK automatically initializes based on HTML data attributes.
+
+### Event-Driven
+The SDK publishes events for all user interactions, allowing you to react to changes.
+
+### State Persistence
+Cart and address data persist across sessions using localStorage with API fallback.
+
+## Browser Requirements
+
+- Chrome 66+ (March 2018)
+- Firefox 60+ (May 2018)
+- Safari 12+ (September 2018)
+- Edge 79+ (January 2020)
+
+Requires Web Components and Shadow DOM support.
+
+## Support
+
+For assistance, contact your LiquidCommerce representative.
+
+## Version History
+
+This is the v1 documentation. Future versions will be documented in separate directories (`v2/`, `v3/`, etc.).
+
+## Contributing
+
+Found an issue in the documentation? Contact your LiquidCommerce representative with suggestions.
+
+---
+
+## Navigation
+
+- [← Back to Repository](../)
+- [Getting Started →](./getting-started/installation.md)