@liquidcommerce/elements-sdk 2.6.7 → 2.7.0

package/README.md

@@ -9,12 +9,11 @@ Elements SDK
 
 [![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![npm](https://img.shields.io/badge/npm-10+-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/)
-[![pnpm](https://img.shields.io/badge/pnpm-8+-F69220?style=for-the-badge&logo=pnpm&logoColor=white)](https://pnpm.io/)
+[![pnpm](https://img.shields.io/badge/pnpm-10+-F69220?style=for-the-badge&logo=pnpm&logoColor=white)](https://pnpm.io/)
 [![Rollup](https://img.shields.io/badge/Rollup-4+-EC4A3F?style=for-the-badge&logo=rollup.js&logoColor=white)](https://rollupjs.org/)
+![BiomeJs 2+](https://img.shields.io/badge/BiomeJs-2+-60a5fa?style=for-the-badge&logo=biome&logoColor=white)
 
 [![License: UNLICENSED](https://img.shields.io/badge/License-UNLICENSED-red.svg)](LICENSE)
-[![Bundle Size](https://img.shields.io/badge/Bundle%20Size-~150KB-blue)](./umd)
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen)](./package.json)
 [![Browser Support](https://img.shields.io/badge/Browsers-2018+-4285F4?logo=googlechrome&logoColor=white)](./docs/BROWSER_SUPPORT.md)
 
@@ -69,8 +68,9 @@ The LiquidCommerce Elements SDK is a **production-ready JavaScript library** tha
 
 **🛍️ Complete E-commerce**
 - Product display components
+- Product list with filters and search
 - Shopping cart with real-time updates
-- Full checkout flow
+- Full checkout flow (drawer or hosted page)
 - Address management
 
 </td>
@@ -200,10 +200,9 @@ Add a product list to any page with a data attribute:
 
 ```html
 <div data-liquid-commerce-elements-products-list
-     data-card="standard"
      data-rows="3"
      data-columns="4"
-     data-filters="personalization,pre-order,delivery-options"
+     data-filters="engraving,presale,fulfillment,price,brands"
      data-product-url="/product/{upc}">
 </div>
 
@@ -217,13 +216,13 @@ Add a product list to any page with a data attribute:
 
 **Attributes:**
 - `data-liquid-commerce-elements-products-list` - Enables product list on this div
-- `data-card` - Card variant: `standard` (default)
-- `data-rows` - Number of rows per page (default: `3`)
-- `data-columns` - Number of columns (default: `4`)
-- `data-card-fill` - Makes cards fill available space (optional flag)
-- `data-filters` - Comma-separated filters: `personalization`, `pre-order`, `delivery-options`
+- `data-rows` - Number of rows per page (1-10, default: `3`)
+- `data-columns` - Number of columns (1-4, default: `4`)
+- `data-filters` - Comma-separated filters (see available filters below)
 - `data-product-url` - Product URL template with `{upc}` or `{grouping}` placeholder
 
+**Available filters:** `engraving`, `presale`, `fulfillment`, `price`, `brands`, `categories`, `flavor`, `region`, `variety`, `vintage`, `country`, `appellation`, `materials`, `sizes`
+
 **Use case:** Category pages, catalog pages, search results, filtered product browsing
 
 ### Customizing the Cart Button
@@ -293,7 +292,53 @@ If no cart button attribute is provided, or if the target element is not found,
 ></script>
 ```
 
-#### Option 3: No Cart Button (Manual Control)
+#### Option 3: Separate Mobile Cart Button
+
+Configure different cart button placements for desktop and mobile:
+
+```html
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-badge-button="above:.desktop-nav"
+  data-cart-mobile-badge-button="below:.mobile-header"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+**Mobile button attributes:**
+- `data-cart-mobile-button` - Mobile cart button (no badge)
+- `data-cart-mobile-badge-button` - Mobile cart button with item count badge
+
+These support the same position prefixes as the desktop attributes (`above:`, `below:`, `replace:`, `inside:`).
+
+**Use case:** Different navigation layouts for desktop and mobile
+
+#### Option 4: Custom Cart Toggle Button
+
+Use your own button element to toggle the cart:
+
+```html
+<button data-lce-cart-toggle-button>My Cart</button>
+<span data-lce-cart-items-count>0</span>
+
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-cart-button-hidden
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+**Attributes:**
+- `data-lce-cart-toggle-button` - Any element with this attribute becomes a cart toggle
+- `data-lce-cart-items-count` - Auto-updates with cart item count. Use value `"keep-zero"` to show count even when cart is empty
+
+**Use case:** Fully custom cart button with your own styling
+
+#### Option 5: No Cart Button (Manual Control)
 
 Hide the cart button completely when you want to manage cart access manually:
 
@@ -400,65 +445,151 @@ Here's every available data attribute:
 ```html
 <script
   data-liquid-commerce-elements
-  
+
   <!-- Required -->
   data-token="YOUR_API_KEY"
-  
+
   <!-- Environment -->
   data-env="production|staging|development|local"
-  
-  <!-- Cart Button -->
+
+  <!-- Cart Button (Desktop) -->
   data-cart-button="container-id"              <!-- Simple cart button (no badge) -->
   data-cart-badge-button="container-id"        <!-- Cart button with badge -->
   data-cart-button-hidden                      <!-- Hide cart button completely -->
-  
+
+  <!-- Cart Button (Mobile) -->
+  data-cart-mobile-button="container-id"       <!-- Mobile cart button (no badge) -->
+  data-cart-mobile-badge-button="container-id" <!-- Mobile cart button with badge -->
+
   <!-- Cart Button with Position Prefixes -->
   data-cart-button="above:.logo"               <!-- Place above target -->
   data-cart-badge-button="below:#header"       <!-- Place below target -->
   data-cart-button="inside:.nav"               <!-- Place inside target (default) -->
   data-cart-badge-button="replace:.old-cart"   <!-- Replace target -->
-  
+
   <!-- Cart Button Floating (empty values) -->
   data-cart-button=""                          <!-- Floating button without badge -->
   data-cart-badge-button=""                    <!-- Floating button with badge -->
-  
+
   <!-- Products (Method 1: Direct) -->
   data-container-1="div-id"
   data-product-1="identifier"
   data-container-2="div-id"
   data-product-2="identifier"
-  
-  <!-- Product List -->
-  <div data-liquid-commerce-elements-products-list
-       data-card="standard"
-       data-rows="3"
-       data-columns="4"
-       data-card-fill
-       data-filters="personalization,pre-order,delivery-options"
-       data-product-url="/product/{upc}">
-  </div>
-  
+
   <!-- URL Parameters -->
   data-product-param="lce_product"
   data-product-fulfillment-type-param="lce_fulfillment"
   data-promo-code-param="lce_promo"
-  
+
   <!-- Promo Ticker -->
   data-promo-code="CODE"
   data-promo-text="Message 1|Message 2"
   data-promo-separator="•"
   data-promo-active-from="2025-01-01T00:00:00Z"
   data-promo-active-until="2025-12-31T23:59:59Z"
-  
+
+  <!-- Checkout Page (Hosted Checkout) -->
+  data-checkout-url="https://yoursite.com/checkout?id={id}"
+
   <!-- Debugging (dev only) -->
   data-debug-mode="console|panel"
-  
+
   src="https://assets-elements.liquidcommerce.us/all/elements.js"
 ></script>
+
+<!-- Product List (on separate div element) -->
+<div data-liquid-commerce-elements-products-list
+     data-rows="3"
+     data-columns="4"
+     data-filters="engraving,presale,fulfillment,price,brands"
+     data-product-url="/product/{upc}">
+</div>
+
+<!-- Custom Cart Toggle Button (on any button/element) -->
+<button data-lce-cart-toggle-button>My Cart</button>
+
+<!-- Custom Cart Items Count Display (on any element) -->
+<span data-lce-cart-items-count>0</span>
+<!-- Use "keep-zero" value to always show count, even when 0 -->
+<span data-lce-cart-items-count="keep-zero">0</span>
 ```
 
 **📖 For complete auto-init options:** See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for all data attributes and configuration details.
 
+### Hosted Checkout (External Checkout Page)
+
+Instead of using the default checkout drawer, you can redirect customers to a dedicated checkout page on your site. This is useful when you want a full-page checkout experience.
+
+#### Auto-Init Setup
+
+```html
+<!-- On your product/cart pages -->
+<script
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-checkout-url="https://yoursite.com/checkout?id={id}"
+  src="https://assets-elements.liquidcommerce.us/all/elements.js"
+></script>
+```
+
+When `data-checkout-url` is set, the "Go to Checkout" button in the cart will redirect to that URL instead of opening the checkout drawer. The `{id}` placeholder is replaced with the checkout token generated by the SDK.
+
+#### Checkout Page Setup
+
+On your dedicated checkout page, use the **checkout-only build** for a smaller bundle:
+
+```html
+<div id="checkout-container"></div>
+
+<script
+  data-liquid-commerce-checkout
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  src="https://assets-elements.liquidcommerce.us/checkout/elements.js"
+></script>
+```
+
+Or initialize programmatically:
+
+```js
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+
+const client = await ElementsCheckout('YOUR_API_KEY', {
+  env: 'production'
+});
+
+// Inject checkout, optionally passing the checkout token from the URL
+const urlParams = new URLSearchParams(window.location.search);
+const component = await client.injectCheckout({
+  containerId: 'checkout-container',
+  checkoutId: urlParams.get('id'),  // The checkout token from the URL
+  hideHeader: true
+});
+```
+
+**Checkout-only build features:**
+- Smaller bundle size (tree-shaken, no product/cart/PLP components)
+- All checkout actions available (`actions.checkout.*`)
+- Same theming and event system as the full SDK
+- Auto-initialization via `data-liquid-commerce-checkout` attribute
+
+**Use case:** Dedicated checkout pages, custom checkout flows, multi-page checkout
+
+#### Programmatic Setup (Full SDK)
+
+You can also configure hosted checkout programmatically with the full SDK:
+
+```js
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  checkout: {
+    pageUrl: 'https://yoursite.com/checkout?id={id}'
+  }
+});
+```
+
 ---
 
 ## 🔧 Advanced Usage
@@ -548,7 +679,10 @@ const client = await Elements('YOUR_API_KEY', {
   debugMode: 'none',           // Debug mode
   customTheme: { },            // Theme overrides
   proxy: { },                  // Proxy configuration
-  promoTicker: [ ]             // Promotional messages
+  promoTicker: [ ],            // Promotional messages
+  checkout: {                  // Hosted checkout configuration
+    pageUrl: 'https://yoursite.com/checkout?id={id}'
+  }
 });
 ```
 
@@ -697,7 +831,11 @@ const component = await client.injectCartElement('cart-container');
 #### Checkout
 
 ```js
-const component = await client.injectCheckoutElement('checkout-container');
+const component = await client.injectCheckoutElement({
+  containerId: 'checkout-container',
+  checkoutId: 'checkout-token',    // Optional: load specific checkout by checkout token
+  hideHeader: false                // Optional: hide checkout header in standalone mode
+});
 
 // Returns: IInjectedComponent | null - Component wrapper or null if failed
 // component.rerender() - Rerender the component
@@ -705,7 +843,12 @@ const component = await client.injectCheckoutElement('checkout-container');
 // component.getType() - Get component type
 ```
 
-**Use case:** Dedicated checkout page
+**Parameters:**
+- `containerId` (required) - Where to inject the checkout
+- `checkoutId` (optional) - Checkout token to load a specific checkout session
+- `hideHeader` (optional) - Hide the checkout header when used in standalone/hosted mode
+
+**Use case:** Dedicated checkout page, hosted checkout
 
 #### Address
 
@@ -725,31 +868,40 @@ const component = await client.injectAddressElement('address-container');
 ```js
 await client.injectProductList({
   containerId: 'product-list-container',
-  rows: 3,                    // Number of rows per page
-  columns: 4,                  // Number of columns
-  cardVariant: 'standard',    // Card style variant
-  fillCard: false,            // Fill card to available space
-  filters: [                  // Optional filters
-    'personalization',        // Show personalized products
-    'pre-order',              // Show pre-order products
-    'delivery-options'         // Show delivery type filters
+  rows: 3,                       // Number of rows per page (1-10)
+  columns: 4,                    // Number of columns (1-4)
+  filters: [                     // Optional filters
+    'engraving',                 // Engravable/personalizable products
+    'presale',                   // Pre-order products
+    'fulfillment',               // Delivery type filter (shipping, onDemand)
+    'price',                     // Price range filter
+    'brands',                    // Brand filter
+    'categories',                // Category filter
+    'flavor',                    // Flavor filter
+    'region',                    // Region filter
+    'variety',                   // Variety filter
+    'vintage',                   // Vintage filter
+    'country',                   // Country filter
+    'appellation',               // Appellation filter
+    'materials',                 // Materials filter
+    'sizes'                      // Size filter
   ],
-  productUrl: '/product/{upc}' // Optional: Product detail page URL template
+  productUrl: '/product/{upc}'   // Optional: Product detail page URL template
 });
 ```
 
 **Parameters:**
 - `containerId` - Where to inject the product list
-- `rows` - Number of rows to display per page (default: `3`)
-- `columns` - Number of columns in the grid (default: `4`)
-- `cardVariant` - Card display style: `'standard'` (default)
-- `fillCard` - Whether cards should fill available space (default: `false`)
-- `filters` - Array of filter types to enable: `'personalization'`, `'pre-order'`, `'delivery-options'`
+- `rows` - Number of rows to display per page (1-10, default: `3`)
+- `columns` - Number of columns in the grid (1-4, default: `4`)
+- `filters` - Array of filter types to enable (see available filters below)
 - `productUrl` - Optional URL template for product links. Use `{upc}` or `{grouping}` placeholder
 
+**Available filters:** `engraving`, `presale`, `fulfillment`, `price`, `brands`, `categories`, `flavor`, `region`, `variety`, `vintage`, `country`, `appellation`, `materials`, `sizes`
+
 **Features:**
 - ✅ Infinite scroll pagination
-- ✅ Filter by personalization, pre-order, delivery options
+- ✅ Rich filtering (14 filter types)
 - ✅ Address-aware (reloads when address changes)
 - ✅ Loading states and error handling
 - ✅ Automatic GTM tracking (`view_item_list`, `select_item`)
@@ -760,6 +912,35 @@ await client.injectProductList({
 
 **Note:** The product list automatically reloads when the address changes to show availability for the new location.
 
+#### Product List Search
+
+```js
+await client.injectProductListSearch({
+  containerId: 'search-container'
+});
+```
+
+Injects a search input component that works with the product list to filter products by keyword.
+
+**Use case:** Search bars on catalog/category pages
+
+#### Product List Filters
+
+```js
+await client.injectProductListFilters({
+  containerId: 'filters-container',
+  filters: ['price', 'brands', 'categories', 'variety']
+});
+```
+
+Injects a standalone filter panel component that works with the product list. Use this when you want the filters in a separate container from the product grid (e.g., a sidebar).
+
+**Parameters:**
+- `containerId` - Where to inject the filter panel
+- `filters` - Array of filter types to display
+
+**Use case:** Sidebar filter panels on category pages
+
 #### Access All Injected Components
 
 ```js
@@ -878,7 +1059,11 @@ client.builder.updateAddressComponent(addressTheme);
 // Builder injection methods (same as regular methods)
 const components = await client.builder.injectProductElement(params);
 const component = await client.builder.injectCartElement(containerId);
-const checkoutComponent = await client.builder.injectCheckoutElement(containerId);
+const checkoutComponent = await client.builder.injectCheckoutElement({
+  containerId,
+  checkoutId,     // Optional
+  hideHeader      // Optional
+});
 const addressComponent = await client.builder.injectAddressElement(containerId);
 
 // All return IInjectedComponent wrapper objects with rerender(), getElement(), getType() methods
@@ -1043,6 +1228,7 @@ await actions.cart.resetCart();
 actions.checkout.openCheckout();
 actions.checkout.closeCheckout();
 actions.checkout.toggleCheckout();
+actions.checkout.exitCheckout();       // Exit checkout (return to cart)
 
 // Pre-fill customer information
 actions.checkout.updateCustomerInfo({
@@ -1624,10 +1810,27 @@ Add a product list to any page with data attributes:
 
 ```html
 <div data-liquid-commerce-elements-products-list
-     data-card="standard"
      data-rows="3"
      data-columns="4"
-     data-filters="personalization,pre-order,delivery-options"
+     data-filters="engraving,presale,fulfillment,price,brands"
+     data-product-url="/product/{upc}">
+</div>
+```
+
+You can also add separate search and filter containers:
+
+```html
+<!-- Search bar -->
+<div data-search-container></div>
+
+<!-- Sidebar filters -->
+<div data-filters-container></div>
+
+<!-- Product grid -->
+<div data-liquid-commerce-elements-products-list
+     data-rows="4"
+     data-columns="4"
+     data-filters="price,brands,categories,variety"
      data-product-url="/product/{upc}">
 </div>
 ```
@@ -1639,23 +1842,42 @@ await client.injectProductList({
   containerId: 'product-list-container',
   rows: 3,
   columns: 4,
-  cardVariant: 'standard',
-  fillCard: false,
-  filters: ['personalization', 'pre-order', 'delivery-options'],
+  filters: ['engraving', 'presale', 'fulfillment', 'price', 'brands'],
   productUrl: '/product/{upc}'
 });
+
+// Optional: inject search and filters in separate containers
+await client.injectProductListSearch({
+  containerId: 'search-container'
+});
+
+await client.injectProductListFilters({
+  containerId: 'filters-sidebar',
+  filters: ['price', 'brands', 'categories', 'variety']
+});
 ```
 
 #### Features
 
-**Filtering:**
-- **Personalization filter** - Show only products that support engraving/personalization
-- **Pre-order filter** - Show only pre-order products
-- **Delivery options filter** - Filter by `all`, `shipping`, or `onDemand`
+**Filtering (14 filter types):**
+- **engraving** - Show only products that support engraving/personalization
+- **presale** - Show only pre-order products
+- **fulfillment** - Filter by delivery type (shipping, onDemand)
+- **price** - Filter by price range
+- **brands** - Filter by brand
+- **categories** - Filter by category
+- **flavor** - Filter by flavor profile
+- **region** - Filter by region
+- **variety** - Filter by variety (e.g., Cabernet Sauvignon)
+- **vintage** - Filter by vintage year
+- **country** - Filter by country of origin
+- **appellation** - Filter by appellation
+- **materials** - Filter by material type
+- **sizes** - Filter by product size
 
 **Smart Filter Logic:**
-- When "Same-Day Delivery" is selected, personalization and pre-order filters are automatically disabled
-- When personalization or pre-order is enabled, same-day delivery is automatically disabled
+- When "Same-Day Delivery" is selected, engraving and presale filters are automatically disabled
+- When engraving or presale is enabled, same-day delivery is automatically disabled
 - Filters work together intelligently to show only compatible product combinations
 
 **Infinite Scroll:**
@@ -1695,10 +1917,9 @@ await client.injectProductList({
 ```html
 <div id="category-products"
      data-liquid-commerce-elements-products-list
-     data-card="standard"
      data-rows="4"
      data-columns="4"
-     data-filters="personalization,delivery-options"
+     data-filters="engraving,fulfillment,price,brands"
      data-product-url="/products/{upc}">
 </div>
 
@@ -1710,22 +1931,32 @@ await client.injectProductList({
 ></script>
 ```
 
-#### Example: Search Results
+#### Example: Search Results with Sidebar Filters
 
 ```js
 const client = await Elements('YOUR_API_KEY', {
   env: 'production'
 });
 
+// Inject search bar
+await client.injectProductListSearch({
+  containerId: 'search-bar'
+});
+
+// Inject product grid
 await client.injectProductList({
   containerId: 'search-results',
   rows: 6,
   columns: 3,
-  cardVariant: 'standard',
-  fillCard: true,
-  filters: ['delivery-options'],
+  filters: ['fulfillment', 'price', 'brands', 'categories'],
   productUrl: '/search?q={grouping}'
 });
+
+// Inject sidebar filters
+await client.injectProductListFilters({
+  containerId: 'filters-sidebar',
+  filters: ['price', 'brands', 'categories', 'variety']
+});
 ```
 
 **Use cases:**
@@ -2282,7 +2513,7 @@ Only inject components when needed:
 // ❌ Don't inject all components upfront
 await client.injectProductElement([/* 50 products */]);
 await client.injectCartElement('cart');
-await client.injectCheckoutElement('checkout');
+await client.injectCheckoutElement({ containerId: 'checkout' });
 
 // ✅ Inject components as user navigates
 // On product page:
@@ -2292,7 +2523,7 @@ await client.injectProductElement([{ containerId: 'pdp', identifier: productId }
 await client.injectCartElement('cart');
 
 // On checkout (when user proceeds):
-await client.injectCheckoutElement('checkout');
+await client.injectCheckoutElement({ containerId: 'checkout' });
 ```
 
 ### Reuse Client Instance