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

package/docs/v1/api/injection-methods.md

@@ -0,0 +1,331 @@
+# Injection Methods API
+
+Methods for injecting SDK components into your page.
+
+## injectProductElement()
+
+Inject one or more product displays.
+
+### Signature
+
+```typescript
+injectProductElement(params: IInjectProductElement[]): Promise<IInjectedComponent[]>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductElement {
+  containerId: string;  // ID of container element
+  identifier: string;   // Product Identifier
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' }
+]);
+```
+
+### Returns
+
+Array of injected component objects.
+
+---
+
+## injectAddressElement()
+
+Inject standalone address component.
+
+### Signature
+
+```typescript
+injectAddressElement(
+  containerId: string,
+  options?: IAddressOptions
+): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectAddressElement('address-container', {
+  showLabel: true
+});
+
+// Listen for address changes via the published event (dispatched on window)
+window.addEventListener('lce:actions.address_updated', (event) => {
+  console.log('Address set:', event.detail.data);
+});
+```
+
+---
+
+## injectCartElement()
+
+Inject standalone cart (rarely needed - cart drawer is automatic).
+
+### Signature
+
+```typescript
+injectCartElement(containerId: string): Promise<IInjectedComponent | null>
+```
+
+### Example
+
+```javascript
+await client.injectCartElement('cart-container');
+```
+
+---
+
+## injectCheckoutElement()
+
+Inject hosted checkout page.
+
+### Signature
+
+```typescript
+injectCheckoutElement(params: IInjectCheckoutParams): Promise<IInjectedComponent | null>
+```
+
+### Parameters
+
+```typescript
+interface IInjectCheckoutParams {
+  containerId: string;
+  checkoutId?: string;   // Optional checkout token to load
+  hideHeader?: boolean;  // Hide checkout header
+}
+```
+
+### Example
+
+```javascript
+await client.injectCheckoutElement({
+  containerId: 'checkout',
+  checkoutId: 'cart_abc123',
+  hideHeader: false
+});
+```
+
+---
+
+## injectProductList()
+
+Inject product catalog/listing.
+
+### Signature
+
+```typescript
+injectProductList(params: IInjectProductListParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListParams {
+  containerId: string;
+  slug: string;              // Product list slug identifier
+  rows?: number;             // Default: 4
+  columns?: number;          // Default: 4
+  filters?: ProductListFilterType[];
+  productUrl?: PLCProductUrl;  // string template OR Record<identifier, url> map
+  productOrder?: string[];     // display order, by UPC or grouping ID
+}
+
+// String template: replace {upc} or {grouping} per product.
+// Map: keys are product identifiers (UPC or salsifyGrouping ID); UPC checked first.
+type PLCProductUrl = string | Record<string, string>;
+```
+
+### Example — string template
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  slug: 'best-sellers',
+  rows: 4,
+  columns: 3,
+  filters: ['price', 'brands', 'categories'],
+  productUrl: '/product/{grouping}'
+});
+```
+
+> The `filters` array also acts as the whitelist for **URL query param filtering** —
+> the product list reads `?brands=...&price=...` etc. from `window.location.search`
+> on first mount and applies them. See
+> [URL Query Param Filters](../guides/product-list-component.md#url-query-param-filters).
+
+### Example — URL map (partner-owned dedicated PDPs)
+
+Use this form when each product has a hand-curated URL that can't be derived
+from a single `{upc}` or `{grouping}` token. See the
+[Product List guide](../guides/product-list-component.md#product-url-map) for
+the equivalent declarative `<script type="application/json">` pattern.
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  slug: 'best-sellers',
+  productUrl: {
+    'GROUPING-33277': '/wines/macallan-12-special-edition',
+    '00832889005513': '/spirits/cabernet-2018-club-only',
+  },
+});
+```
+
+### Example — explicit product order
+
+`productOrder` sets the display order of the grid. Entries are the same product
+identifiers `productUrl` maps and `injectProductElement` accepts — a UPC (any size
+of the product) or a `salsifyGrouping` ID — and may be mixed freely.
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  slug: 'best-sellers',
+  productOrder: [
+    '00832889005513',
+    'GROUPING-33277',
+    '00619947000020',
+  ],
+});
+```
+
+It **reorders, it does not select.** The list's `slug` still decides which products
+are returned; an identifier for a product outside the list matches nothing. Products
+the array doesn't name render after the ones it does, in the order the API returned
+them, so a partial list reorders only what it names.
+
+Ordering also applies across pagination: a product named early in the array takes its
+place even if the API returns it on a later page. Each new page is spliced into the
+existing grid rather than appended, so cards already on screen are never re-rendered
+and the scroll position holds. If the curated set is small, size `rows × columns` to
+cover it in one page so no scroll is needed at all.
+
+> A search term or an applied filter re-queries the API for a narrower result set.
+> `productOrder` is re-applied to whatever comes back, so named products keep their
+> relative order among the results that survive.
+
+---
+
+## injectProductListSearch()
+
+Inject product search box.
+
+### Signature
+
+```typescript
+injectProductListSearch(params: IInjectProductListSearchParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListSearchParams {
+  containerId: string;
+  slug: string;  // Product list slug identifier
+  filters?: ProductListFilterType[];
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListSearch({
+  containerId: 'search-box',
+  slug: 'best-sellers'
+});
+```
+
+---
+
+## injectProductListFilters()
+
+Inject product filter panel.
+
+### Signature
+
+```typescript
+injectProductListFilters(params: IInjectProductListFiltersParams): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IInjectProductListFiltersParams {
+  containerId: string;
+  slug: string;  // Product list slug identifier
+  filters?: ProductListFilterType[];
+}
+```
+
+### Example
+
+```javascript
+await client.injectProductListFilters({
+  containerId: 'filters',
+  slug: 'best-sellers',
+  filters: ['price', 'brands', 'fulfillment']
+});
+```
+
+> **Note:** Every section of the panel is opt-in — a filter type absent from `filters` is not
+> rendered, `'price'`, `'fulfillment'` and `'engraving'` included — and all sections render
+> collapsed. See
+> [Available Filters](../guides/product-list-component.md#available-filters).
+
+---
+
+## Component Management
+
+### getInjectedComponents()
+
+Retrieve all injected components.
+
+```typescript
+getInjectedComponents(): Map<string, IInjectedComponent>
+```
+
+```javascript
+const components = client.getInjectedComponents();
+
+// Get specific component
+const product = components.get('product-1');
+
+// Rerender component
+product.rerender();
+
+// Get container element
+const container = product.getElement();
+
+// Get component type
+const type = product.getType(); // 'product'
+```
+
+### IInjectedComponent Interface
+
+```typescript
+interface IInjectedComponent {
+  getType(): ComponentType;
+  getElement(): HTMLElement;
+  rerender(): void;
+  destroy(): void;
+}
+```
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `getType()` | `ComponentType` | Returns the type of the injected component |
+| `getElement()` | `HTMLElement` | Returns the container element where the component is injected |
+| `rerender()` | `void` | Re-renders the component with the latest data and configurations |
+| `destroy()` | `void` | Removes the component from the DOM and cleans up internal tracking |
+
+## See Also
+
+- [Client API](./client.md)
+- [Component Guides](../guides/)