@liquidcommerce/elements-sdk 2.6.0-beta.12 → 2.6.0-beta.121

package/docs/v1/api/typescript-types.md

@@ -0,0 +1,501 @@
+# TypeScript Types Reference
+
+All public types are exported from the main package entry point. Import them using the `type` keyword for optimal tree-shaking.
+
+## Importing Types
+
+```typescript
+import { Elements } from '@liquidcommerce/elements-sdk';
+import type {
+  ILiquidCommerceElementsClient,
+  ILiquidCommerceElementsConfig,
+  IInjectProductElement,
+  IInjectedComponent
+} from '@liquidcommerce/elements-sdk';
+```
+
+For the checkout-only build:
+
+```typescript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+import type {
+  IElementsCheckoutClient,
+  IElementsCheckoutActions,
+  ILiquidCommerceElementsCheckoutClientConfig,
+  IInjectedComponent
+} from '@liquidcommerce/elements-sdk/checkout';
+```
+
+---
+
+## Client Types
+
+### ILiquidCommerceElementsClient
+
+Main SDK client interface returned by `Elements()`.
+
+```typescript
+interface ILiquidCommerceElementsClient {
+  injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
+  injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
+  injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
+  injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
+  injectProductList(params: IInjectProductListParams): Promise<void>;
+  injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>;
+  injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>;
+  ui: ILiquidCommerceElementsUIMethod;
+  actions: ILiquidCommerceElementsActions;
+  getInjectedComponents(): Map<string, IInjectedComponent>;
+  destroy(): void;
+}
+```
+
+### ILiquidCommerceElementsBuilderClient
+
+Builder-pattern client interface returned by `ElementsBuilder()`.
+
+```typescript
+interface ILiquidCommerceElementsBuilderClient {
+  updateComponentGlobalConfigs(configs: UpdateComponentGlobalConfigs): Promise<void>;
+  updateProductComponent(configs: UpdateProductComponent): Promise<void>;
+  updateAddressComponent(configs: UpdateAddressComponent): void;
+  updateCartComponent(configs: UpdateCartComponent): void;
+  updateCheckoutComponent(configs: UpdateCheckoutComponent): void;
+  updateProductListComponent(configs: UpdateProductListComponent): void;
+  injectElement(params: IBuilderInjectElementParams): Promise<IInjectedComponent | null>;
+  injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>;
+  injectAddressElement(containerId: string, options?: IAddressOptions): Promise<IInjectedComponent | null>;
+  injectCartElement(containerId: string): Promise<IInjectedComponent | null>;
+  injectCheckoutElement(params: IInjectCheckoutBuilderParams): Promise<IInjectedComponent | null>;
+  injectProductList(params: IInjectProductListParams): Promise<void>;
+  actions: ILiquidCommerceElementsActions;
+  destroy(): void;
+}
+```
+
+### IElementsCheckoutClient
+
+Checkout-only client interface returned by `ElementsCheckout()`.
+
+```typescript
+interface IElementsCheckoutClient {
+  injectCheckout(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>;
+  injectExpressCheckout(params: IInjectExpressCheckoutParams): Promise<IInjectedComponent | null>;
+  actions: { checkout: IElementsCheckoutActions };
+  destroy(): void;
+}
+
+interface IInjectExpressCheckoutParams {
+  containerId: string;
+  checkoutId?: string;              // omit to use the checkout already loaded
+  variant?: 'section' | 'buttons';  // 'buttons' is the default outside the checkout element
+}
+```
+
+---
+
+## Configuration Types
+
+### ILiquidCommerceElementsConfig
+
+```typescript
+interface ILiquidCommerceElementsConfig {
+  env?: ElementsEnv;
+  promoTicker?: IPromoTicker[];
+  customTheme?: IClientCustomThemeConfig;
+  debugMode?: DebugMode;
+  checkout?: ILiquidCommerceElementsCheckoutConfig;
+  proxy?: IElementsProxyConfig;
+  gtm?: IElementsGTMConfig;
+  development?: ILiquidCommerceElementsDevelopmentConfig;
+}
+```
+
+### ILiquidCommerceElementsBuilderConfig
+
+Same shape as `ILiquidCommerceElementsConfig`, used by `ElementsBuilder()`.
+
+### ILiquidCommerceElementsCheckoutClientConfig
+
+Same shape as `ILiquidCommerceElementsConfig`, used for the checkout-only client.
+
+### IClientCustomThemeConfig
+
+```typescript
+interface IClientCustomThemeConfig {
+  global?: UpdateComponentGlobalConfigs;
+  product?: UpdateProductComponent;
+  address?: UpdateAddressComponent;
+  cart?: UpdateCartComponent;
+  checkout?: UpdateCheckoutComponent;
+  productList?: UpdateProductListComponent;
+}
+```
+
+### IElementsProxyConfig
+
+```typescript
+interface IElementsProxyConfig {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+```
+
+### IElementsGTMConfig
+
+```typescript
+interface IElementsGTMConfig {
+  gatewayUrl?: string;
+}
+```
+
+`gatewayUrl` is the Google tag gateway path your own GTM container is served from (see [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway)).
+
+### ILiquidCommerceElementsDevelopmentConfig
+
+```typescript
+interface ILiquidCommerceElementsDevelopmentConfig {
+  customApiUrl?: string;
+  openShadowDom?: boolean;
+  mockMode?: boolean;  // when true, sends an 'X-Liquid-Api-Mock-Mode' header to receive mock data
+}
+```
+
+### ILiquidCommerceElementsCheckoutConfig
+
+```typescript
+interface ILiquidCommerceElementsCheckoutConfig {
+  pageUrl?: string;
+}
+```
+
+See [Configuration Reference](./configuration.md) for detailed property descriptions.
+
+---
+
+## Injection Types
+
+### IInjectProductElement
+
+```typescript
+interface IInjectProductElement {
+  containerId: string;
+  identifier: string;
+}
+```
+
+### IInjectCheckoutParams
+
+```typescript
+interface IInjectCheckoutParams {
+  containerId: string;
+  checkoutId?: string;
+  hideHeader?: boolean;
+}
+```
+
+### IInjectCheckoutBuilderParams
+
+`simulatePresale` and `presaleExpiresInMinutes` are builder-only preview controls (presale lock defaults to 15 minutes) and only take effect via `ElementsBuilder().injectCheckoutElement()`.
+
+```typescript
+interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
+  simulatePresale?: boolean;
+  presaleExpiresInMinutes?: number;
+}
+```
+
+### IInjectProductListParams
+
+```typescript
+interface IInjectProductListParams {
+  containerId: string;
+  slug: string;
+  rows?: number;
+  columns?: number;
+  filters?: ProductListFilterType[];
+  productUrl?: PLCProductUrl;
+  productOrder?: string[];  // display order, by UPC or grouping ID
+}
+```
+
+### PLCProductUrl
+
+```typescript
+/**
+ * Product card link configuration.
+ *
+ * - String: template with `{upc}` (selected size's UPC) or `{grouping}`
+ *   (product's salsifyGrouping ID). Replaced per product card.
+ * - Map: keyed by product identifier (UPC or salsifyGrouping ID — same
+ *   identifier types accepted by `injectProductElement`). The card looks up
+ *   UPC first, then grouping ID. Use this when partner PDPs have
+ *   hand-curated URLs that aren't derivable from a single token.
+ */
+type PLCProductUrl = string | Record<string, string>;
+```
+
+### IInjectProductListSearchParams
+
+```typescript
+interface IInjectProductListSearchParams {
+  containerId: string;
+  slug: string;
+  filters?: ProductListFilterType[];
+}
+```
+
+### IInjectProductListFiltersParams
+
+```typescript
+interface IInjectProductListFiltersParams {
+  containerId: string;
+  slug: string;
+  filters?: ProductListFilterType[];
+}
+```
+
+### IBuilderInjectElementParams
+
+```typescript
+interface IBuilderInjectElementParams {
+  type: ComponentType;
+  containerId: string;
+  [key: string]: any;
+}
+```
+
+---
+
+## Component Types
+
+### IInjectedComponent
+
+Returned by all injection methods. Provides control over the injected component.
+
+```typescript
+interface IInjectedComponent {
+  getType(): ComponentType;
+  getElement(): HTMLElement;
+  rerender(): void;
+  destroy(): void;
+}
+```
+
+---
+
+## UI Types
+
+### ILiquidCommerceElementsUIMethod
+
+```typescript
+interface ILiquidCommerceElementsUIMethod {
+  cartButton(containerId: string, showItemsCount?: boolean): void;
+  floatingCartButton(showItemsCount?: boolean): void;
+  cartSubtotal(elementId: string): void;
+  cartItemsCount(elementId: string, options?: { hideZero: boolean }): void;
+}
+```
+
+---
+
+## Action Types
+
+### ILiquidCommerceElementsActions
+
+```typescript
+interface ILiquidCommerceElementsActions {
+  product: IProductActions;
+  address: IAddressActions;
+  cart: ICartActions;
+  checkout: ICheckoutActions;
+}
+```
+
+### IElementsCheckoutActions
+
+Checkout actions available in the checkout-only client. This is `ICheckoutActions` with `openCheckout`, `closeCheckout`, and `toggleCheckout` omitted -- the checkout-only client renders checkout independently and has no drawer navigation to open, close, or toggle.
+
+```typescript
+interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
+```
+
+See [Actions API](./actions/) for detailed method signatures.
+
+---
+
+## Enum Types
+
+### ElementsEnv
+
+```typescript
+type ElementsEnv = 'staging' | 'production';
+```
+
+### DebugMode
+
+```typescript
+type DebugMode = 'none' | 'console' | 'panel';
+```
+
+### FulfillmentType
+
+```typescript
+type FulfillmentType = 'onDemand' | 'shipping';
+```
+
+### ComponentType
+
+```typescript
+type ComponentType =
+  | 'address' | 'product' | 'cart' | 'checkout'
+  | 'product-list' | 'product-list-card' | 'product-list-filters' | 'product-list-search'
+  | 'drawer' | 'input' | 'engraving-form' | 'engraving-view'
+  | 'buttons-cart-open' | 'powered-by' | 'lce-element'
+  | 'purchase-min-alert' | 'alert' | 'promo-code-ticker'
+  // ...and additional internal component types
+```
+
+### DisplayModeType
+
+```typescript
+type DisplayModeType = 'modal' | 'drawer';
+```
+
+---
+
+## Theme Configuration Types
+
+### UpdateComponentGlobalConfigs
+
+`DeepPartial<IComponentGlobalConfigs>` -- all properties optional.
+
+### UpdateProductComponent
+
+`DeepPartial<IProductComponent>` -- all properties optional.
+
+### UpdateCartComponent
+
+`DeepPartial<ICartComponent>` -- all properties optional.
+
+### UpdateCheckoutComponent
+
+`DeepPartial<ICheckoutComponent>` -- all properties optional.
+
+### UpdateAddressComponent
+
+`DeepPartial<IAddressComponent>` -- all properties optional.
+
+### UpdateProductListComponent
+
+Special structure for updating product list configuration by slug:
+
+```typescript
+interface UpdateProductListComponent {
+  theme?: { backgroundColor?: string };
+  layout?: {
+    lists?: Record<string, DeepPartial<IPLCList>>;
+  };
+}
+```
+
+These `Update*Component` types are the arguments to the `ElementsBuilder()` client's `update*Component` methods; see [Client API](./client.md) for their behavior and usage.
+
+See [Configuration Reference](./configuration.md) for detailed theme property descriptions.
+
+---
+
+## Promo Ticker Type
+
+### IPromoTicker
+
+```typescript
+interface IPromoTicker {
+  promoCode: string;
+  text: string[];
+  separator: string;
+  activeFrom: string;   // ISO 8601 UTC
+  activeUntil: string;  // ISO 8601 UTC
+}
+```
+
+---
+
+## Utility Types
+
+### DeepPartial
+
+Used internally for theme update types. Makes all properties in `T` recursively optional.
+
+```typescript
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+```
+
+---
+
+## See Also
+
+- [Client API](./client.md) - Client initialization and usage
+- [Configuration Reference](./configuration.md) - Detailed config options
+- [Injection Methods](./injection-methods.md) - Component injection API
+
+### Preparing complete account delivery details
+
+After `lce:actions.checkout_loaded`, call
+`await elements.actions.checkout.updateCustomerInfo(fields, { saveIfValid: true })`
+to validate and prepare complete account details, then show their editable summary.
+Supply names, email, a US phone number, and a real `birthDate` in `MM/DD/YYYY` format
+(age 21+, year 1930 or later). The `birthDate` may be blank when the partner does not require a
+date of birth (`checkout.layout.requireBirthDate: false`); a supplied one is still validated.
+A shipping street must already be selected.
+Omitted apartment and delivery instructions retain their existing checkout values.
+Partial or invalid details stay in the form; backend validation failures reject the
+promise, show the checkout error, and keep details editable. The host should handle that rejection.
+
+The option skips gifts, saved forms, in-flight saves, and customer forms the shopper
+has edited during the current checkout. It does not overwrite those forms. Edits or
+address/checkout changes during preparation prevent a stale response from closing
+the form. Without the option, this action only prefills fields, as before.
+
+Apple Pay and Google Pay selection displays **Continue with Apple Pay** or
+**Continue with Google Pay**. This opens the wallet to save a payment method; the
+shopper still reviews and places the order afterward. It is not express checkout.
+
+After wallet cancellation, the same Continue action remains available. If authorization
+succeeded but saving the method failed, **Retry saving Apple Pay/Google Pay** reuses
+the existing authorization rather than opening the wallet again.
+
+### Saved account marketing preferences
+
+```ts
+setSavedMarketingPreferences(preferences: { canEmail?: boolean; canSms?: boolean }): Promise<void>
+clearSavedMarketingPreferences(): void
+```
+
+Call `actions.checkout.setSavedMarketingPreferences()` with known recorded account
+choices, including `false`, before checkout loads. Only boolean values are used;
+missing/null/unrecognized values remain unknown. The first checkout prepare uses
+saved values instead of tenant defaults. Each channel's prompt is hidden only
+after the server confirms that saved choice. Unknown channels retain their normal
+checkout prompts. The actions are available in both full and checkout-only clients.
+
+Calling the setter during an active checkout prepares untouched channels and
+preserves shopper checkbox edits. Backend failure rejects the promise, displays
+an error, and leaves prompts available; the host should catch the rejection.
+The same call can retry. Applying values does not call a subscription service.
+It supplies the account's recorded choices to this checkout.
+
+Saved choices persist across cart resets in the same SDK session. Call
+`clearSavedMarketingPreferences()` on sign-out, account change, and host cleanup.
+Clearing reveals the prompts and restores configured guest defaults. It invalidates
+stale responses while draining outstanding preference requests; checkout completion
+prepares the current choices before submitting the checkout token. A load already
+in progress still finishes and reconciles the current account's values. Bind a new
+account only to its own checkout; the host remains responsible for account/cart
+ownership and for reloading checkout when identity changes.
+
+Order completion waits for queued preference work. It cannot race a late saved
+opt-out or proceed with an unconfirmed saved choice. If applying a known choice
+fails, the shopper can retry or explicitly choose the visible channel preference.

package/docs/v1/api/ui-helpers.md

@@ -0,0 +1,200 @@
+# UI Helpers API
+
+UI helper methods for creating cart buttons and displaying cart information.
+
+## ui.cartButton()
+
+Create a cart button in a specific container.
+
+### Signature
+
+```typescript
+cartButton(containerId: string, showItemsCount?: boolean): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerId` | string | Yes | ID of container element |
+| `showItemsCount` | boolean | No | Show item count badge (default: false) |
+
+### Example
+
+```javascript
+// Simple cart button
+window.LiquidCommerce.elements.ui.cartButton('header-cart');
+
+// Cart button with item count badge
+window.LiquidCommerce.elements.ui.cartButton('header-cart', true);
+```
+
+---
+
+## ui.floatingCartButton()
+
+Create a floating cart button (bottom-right corner).
+
+### Signature
+
+```typescript
+floatingCartButton(showItemsCount?: boolean): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `showItemsCount` | boolean | No | Show item count badge (default: false) |
+
+### Example
+
+```javascript
+// Floating button without badge
+window.LiquidCommerce.elements.ui.floatingCartButton();
+
+// Floating button with badge
+window.LiquidCommerce.elements.ui.floatingCartButton(true);
+```
+
+---
+
+## ui.cartSubtotal()
+
+Display cart subtotal in an element.
+
+### Signature
+
+```typescript
+cartSubtotal(elementId: string): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `elementId` | string | Yes | ID of element to update |
+
+### Example
+
+```html
+<div>Total: <span id="cart-total"></span></div>
+```
+
+```javascript
+window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
+// Element now shows: "$49.99"
+// Updates automatically when cart changes
+```
+
+---
+
+## ui.cartItemsCount()
+
+Display number of items in cart.
+
+### Signature
+
+```typescript
+cartItemsCount(elementId: string, options?: { hideZero: boolean }): void
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `elementId` | string | Yes | ID of element to update |
+| `options.hideZero` | boolean | No | Hide when cart is empty (default: true) |
+
+### Example
+
+```html
+<div>Cart (<span id="items-count"></span>)</div>
+```
+
+```javascript
+// Hide when cart is empty
+window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: true });
+
+// Always show count (even "0")
+window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: false });
+```
+
+## Use Cases
+
+### Header Cart Button
+
+```html
+<header>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/products">Products</a>
+    <div id="cart-btn"></div>
+  </nav>
+</header>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartButton('cart-btn', true);
+}, { once: true });
+</script>
+```
+
+### Cart Summary Widget
+
+```html
+<aside class="cart-summary">
+  <h3>Your Cart</h3>
+  <p>Items: <span id="item-count"></span></p>
+  <p>Total: <span id="cart-total"></span></p>
+</aside>
+
+<script>
+window.addEventListener('lce:actions.client_ready', () => {
+  window.LiquidCommerce.elements.ui.cartItemsCount('item-count');
+  window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
+}, { once: true });
+</script>
+```
+
+### Floating Cart for Mobile
+
+```javascript
+// Show floating button only on mobile
+if (window.innerWidth < 768) {
+  window.LiquidCommerce.elements.ui.floatingCartButton(true);
+}
+```
+
+## Styling
+
+Cart buttons and UI elements can be styled with CSS:
+
+```css
+/* Cart button container */
+.lce-cart-desktop-button-container {
+  /* Your styles */
+}
+
+/* Cart items count */
+.lce-cart-items-count {
+  font-weight: bold;
+  color: #007bff;
+}
+
+/* When cart is empty */
+.lce-cart-items-count.no-items {
+  opacity: 0.5;
+}
+
+/* Cart subtotal */
+.lce-cart-subtotal {
+  font-size: 1.2em;
+  font-weight: bold;
+}
+```
+
+## See Also
+
+- [Cart Component Guide](../guides/cart-component.md)
+- [Cart Actions](./actions/cart-actions.md)