@liquidcommerce/elements-sdk 2.7.13 → 2.7.15

package/dist/types/auto-initialize/shared-utils.d.ts

@@ -28,11 +28,14 @@ export declare const SHARED_ATTR: {
     readonly JSON_SCRIPT: {
         readonly DEVELOPMENT: "data-liquid-commerce-elements-development";
         readonly CUSTOM_THEME: "data-liquid-commerce-elements-custom-theme";
+        readonly PRODUCT_URLS: "data-liquid-commerce-elements-product-urls";
     };
 };
+export type ProductUrlsConfig = Record<string, Record<string, string>>;
 export declare function startsWithLcePrefix(value: string | null): boolean;
 export declare function getDevelopmentConfigs(): ILiquidCommerceElementsDevelopmentConfig | undefined;
 export declare function getCustomThemeConfig(): IClientCustomThemeConfig | undefined;
+export declare function getProductUrlsConfig(): ProductUrlsConfig | undefined;
 export declare function triggerAutoInit(initFunction: () => Promise<void>, errorPrefix: string): void;
 export declare function setupCheckout(script: HTMLScriptElement, injectFn: (params: IInjectCheckoutParams) => Promise<IInjectedComponent | null>, exitCheckoutFn: () => void, options: {
     errorPrefix: string;

package/dist/types/clients/helpers.d.ts

@@ -1,5 +1,4 @@
 import { type ComponentType } from '@/enums';
-export declare function applyConfigDefaults<T extends Record<string, any>>(data: T): T;
 export declare function normalizeProductListLists<T extends Record<string, any>>(data: T): T;
 export declare function deepMergeConfigs<T extends Record<string, any>>(target: T, source: Partial<T>, currentPath?: string): T;
 export declare const layoutFieldToComponentTypes: Map<string, ComponentType[]>;

package/dist/types/core/client/actions/base-action.service.d.ts

@@ -3,6 +3,7 @@ import { LoggerFactory } from '@/core/logger/logger-factory';
 import { PubSubService } from '@/core/pubsub/pubsub.service';
 import { StoreService } from '@/core/store/store.service';
 import type { ILocation } from '@/interfaces/api/address.interface';
+import type { IProductSizeEngraving, IProductVariant } from '@/interfaces/api/product.interface';
 import { ThemeProviderService } from '@/modules/theme-provider/theme-provider.service';
 export declare abstract class BaseActionService {
     protected readonly pubSub: PubSubService;
@@ -12,4 +13,10 @@ export declare abstract class BaseActionService {
     protected readonly logger: ReturnType<typeof LoggerFactory.get>;
     constructor(loggerName: string);
     protected getLocation(): ILocation | undefined;
+    protected sanitizeEngravingInput(rawLines: string[] | undefined, identifier: string): string[] | undefined;
+    protected clampEngravingToSizeLimits(requestedLines: string[], sizeEngraving: IProductSizeEngraving | undefined, identifier: string): string[] | undefined;
+    protected findVariantForFulfillment(variants: (IProductVariant | undefined)[], wantsEngraving: boolean): {
+        variant: IProductVariant | null;
+        engravingDropped: boolean;
+    };
 }

package/dist/types/core/client/actions/client-cart-action.service.d.ts

@@ -5,6 +5,7 @@ export interface IAddProductParams {
     identifier: string;
     fulfillmentType: FulfillmentType;
     quantity: number;
+    engravingLines?: string[];
 }
 export interface ICartActions {
     openCart: () => void;

package/dist/types/interfaces/configs/product-list.interface.d.ts

@@ -3,6 +3,7 @@ import type { ProductListFilterType } from '@/interfaces/injection.interface';
 export type PLCPresentationModeType = 'drawer' | 'modal';
 export type PLCListType = 'curated' | 'dynamic';
 export type PLCCardStyle = 'card' | 'ghost';
+export type PLCProductUrl = string | Record<string, string>;
 export interface IPLCProductCard {
     style: PLCCardStyle;
     cornerRadius: string;
@@ -16,6 +17,8 @@ export interface IPLCProductCard {
     showQuantityCounter: boolean;
     enablePreCart: boolean;
     showCollectionTags: boolean;
+    productUrl: PLCProductUrl | null;
+    noAvailabilityText: string;
 }
 export interface IPLCList {
     type: PLCListType;
@@ -27,7 +30,6 @@ export interface IPLCList {
     availableFilters: ProductListFilterType[];
     rows: number;
     columns: number;
-    productUrl: string | null;
 }
 export interface IProductListLayout {
     lists: IPLCList[];

package/dist/types/interfaces/configs/product.interface.d.ts

@@ -1,12 +1,12 @@
 import type { DeepPartial } from '@/interfaces/config.interface';
 export type FulfillmentDisplayType = 'carousel' | 'popup';
-export type DescriptionPosition = 'above' | 'below';
+export type DescriptionPositionType = 'above' | 'below';
 export interface IProductLayout {
     showImages: boolean;
     showOnlyMainImage: boolean;
     showTitle: boolean;
     showDescription: boolean;
-    descriptionPosition: DescriptionPosition;
+    descriptionPosition: DescriptionPositionType;
     showQuantityCounter: boolean;
     showOffHours: boolean;
     quantityCounterStyle: 'outlined' | 'ghost';

package/dist/types/interfaces/injection.interface.d.ts

@@ -1,5 +1,6 @@
 import type { PRODUCT_LIST_FILTER_TYPES } from '@/constants';
 import type { ComponentType } from '@/enums';
+import type { PLCProductUrl } from '@/interfaces/configs/product-list.interface';
 import type { IAddressOptions } from '@/modules/address/address.interface';
 export interface IInjectProductElement {
     containerId: string;
@@ -12,7 +13,7 @@ export interface IInjectProductListParams {
     rows?: number;
     columns?: number;
     filters?: ProductListFilterType[];
-    productUrl?: string;
+    productUrl?: PLCProductUrl;
 }
 export interface IInjectProductListSearchParams {
     containerId: string;

package/dist/types/modules/product/product.commands.d.ts

@@ -13,6 +13,7 @@ export declare class ProductCommands extends BaseCommand {
     createProductInstance(productId: string, firstTime?: boolean): Promise<void>;
     loadMultipleProducts(productIds: string[]): Promise<void>;
     loadProduct(productId: string, customProductData?: IProductAvailabilityResponse | null): Promise<void>;
+    cacheProductFromApiData(identifier: string, apiData: IProductAvailabilityResponse): void;
     selectSize(productId: string, sizeId: string): Promise<void>;
     selectFulfillment(productId: string, selectedFulfillmentId: string): Promise<void>;
     updateQuantity(productId: string, delta: number): Promise<void>;

package/dist/types/modules/product-list/components/product-list-card.component.d.ts

@@ -1,16 +1,19 @@
 import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
 import type { IProductListComponent } from '@/interfaces/configs';
+import type { PLCProductUrl } from '@/interfaces/configs/product-list.interface';
 export interface IProductListCardParams {
     slug: string;
     productId: string;
-    productUrl?: string;
+    productUrl?: PLCProductUrl;
 }
 export declare class ProductListCardComponent extends BaseComponent<IProductListCardParams, IProductListComponent> {
     private imageElement;
     private priceElement;
     private personalizeElement;
     private fulfillmentTextElement;
+    private fulfillmentWrapperElement;
     private addToCartButton;
+    private noAvailabilityElement;
     private previousSelectedSizeId;
     private previousSelectedFulfillmentId;
     constructor();
@@ -27,10 +30,13 @@ export declare class ProductListCardComponent extends BaseComponent<IProductList
     private updateImage;
     private updatePersonalizeVisibility;
     private updateAddToCartButton;
+    private syncFulfillmentWrapperContent;
     private generateProductUrl;
     private createImageSection;
     private createContentSection;
+    private createNoAvailabilityMessage;
     private createFulfillmentSectionWrapper;
+    private createDeliveryOptionsButton;
     private createFulfillmentTextSection;
     private createAddToCartSection;
 }

package/dist/types/modules/product-list/product-list-query-params.utils.d.ts

@@ -0,0 +1,3 @@
+import type { ProductListFilterType } from '@/interfaces/injection.interface';
+import type { IProductListFilters } from './product-list.interface';
+export declare function parseQueryParamsToFilters(configuredFilters: ProductListFilterType[], search?: string): IProductListFilters | null;

package/dist/types/modules/product-list/product-list.commands.d.ts

@@ -9,7 +9,7 @@ export declare class ProductListCommands extends BaseCommand {
     private readonly cartCommands;
     constructor();
     static getInstance(): ProductListCommands;
-    initializeListStore(slug: string): void;
+    initializeListStore(slug: string, configuredFilters?: ProductListFilterType[]): void;
     updateSearchTerm(slug: string, searchTerm: string): void;
     setLoading(slug: string, isLoading: boolean): void;
     rerenderProductLists(): void;

package/dist/types/modules/product-list/product-list.component.d.ts

@@ -1,12 +1,13 @@
 import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
 import type { IProductListComponent } from '@/interfaces/configs';
+import type { PLCProductUrl } from '@/interfaces/configs/product-list.interface';
 import type { ProductListFilterType } from '@/interfaces/injection.interface';
 export interface IProductListComponentParams {
     slug: string;
     rows: number;
     columns: number;
     filters: ProductListFilterType[];
-    productUrl?: string;
+    productUrl?: PLCProductUrl;
 }
 export declare class ProductListComponent extends BaseComponent<IProductListComponentParams, IProductListComponent> {
     private products;

package/docs/v1/api/actions/cart-actions.md

@@ -81,9 +81,20 @@ interface IAddProductParams {
   identifier: string;      // Product UPC, SKU, or ID
   fulfillmentType: FulfillmentType;  // 'shipping' or 'onDemand'
   quantity: number;        // Number of items
+  engravingLines?: string[]; // Optional engraving (see below)
 }
 ```
 
+#### `engravingLines` (optional)
+
+Pre-fills an engraving for the added item. The SDK enforces the product's engraving rules and degrades silently rather than failing the call:
+
+- Non-string-array input is ignored (warning logged).
+- Blank/whitespace-only entries are stripped; an empty result is treated as no engraving.
+- If the product/size doesn't support engraving, lines are dropped.
+- Lines beyond `maxLines` are sliced off; any line longer than `maxCharsPerLine` is truncated.
+- If no engravable variant is available for the chosen fulfillment, lines are dropped and the item is still added.
+
 ### Example
 
 ```javascript
@@ -109,6 +120,16 @@ await window.LiquidCommerce.elements.actions.cart.addProduct([
     quantity: 1
   }
 ]);
+
+// Add a product with engraving
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1,
+    engravingLines: ['Happy Birthday', 'Love, Sam']
+  }
+], true);
 ```
 
 ### Address Requirement

package/docs/v1/api/actions/checkout-actions.md

@@ -62,6 +62,8 @@ addProduct(params: IAddProductParams[], openCheckout?: boolean): Promise<void>
 
 Add products directly to checkout, bypassing the cart.
 
+`IAddProductParams.engravingLines?: string[]` — optional engraving. Same rules as [`actions.cart.addProduct()`](./cart-actions.md#actionscartaddproduct): invalid input is ignored, blanks stripped, lines clamped to the product's `maxLines` / `maxCharsPerLine`, and engraving is dropped (without failing) when the product, variant, or fulfillment doesn't support it.
+
 ```javascript
 await window.LiquidCommerce.elements.actions.checkout.addProduct([
   {
@@ -70,6 +72,16 @@ await window.LiquidCommerce.elements.actions.checkout.addProduct([
     quantity: 1
   }
 ], true);  // Open checkout after adding
+
+// With engraving
+await window.LiquidCommerce.elements.actions.checkout.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1,
+    engravingLines: ['For Dad']
+  }
+], true);
 ```
 
 ### actions.checkout.addAnonymousProduct()

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

@@ -130,11 +130,15 @@ interface IInjectProductListParams {
   rows?: number;             // Default: 3
   columns?: number;          // Default: 4
   filters?: ProductListFilterType[];
-  productUrl?: string;       // URL pattern with {identifier}
+  productUrl?: PLCProductUrl;  // string template OR Record<identifier, url> map
 }
+
+// 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
+### Example — string template
 
 ```javascript
 await client.injectProductList({
@@ -143,7 +147,30 @@ await client.injectProductList({
   rows: 4,
   columns: 3,
   filters: ['price', 'brands', 'categories'],
-  productUrl: '/product/{identifier}'
+  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',
+  },
 });
 ```
 

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

@@ -190,10 +190,26 @@ interface IInjectProductListParams {
   rows?: number;
   columns?: number;
   filters?: ProductListFilterType[];
-  productUrl?: string;
+  productUrl?: PLCProductUrl;
 }
 ```
 
+### 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

package/docs/v1/examples/advanced-patterns.md

@@ -177,7 +177,7 @@ await client.injectProductList({
   slug: 'whiskey-collection',
   rows: 4,
   columns: 3,
-  productUrl: '/products/{identifier}'
+  productUrl: '/products/{grouping}'
 });
 ```
 

package/docs/v1/guides/product-list-component.md

@@ -33,7 +33,7 @@ Use data attributes to configure the product list:
   data-rows="3"
   data-columns="4"
   data-filters="price,brands,categories"
-  data-product-url="/product/{identifier}"
+  data-product-url="/product/{grouping}"
 ></div>
 ```
 
@@ -44,7 +44,13 @@ Use data attributes to configure the product list:
 - `data-filters`: Comma-separated filter types
 - `data-product-url`: URL pattern for product detail pages (optional)
 
-The `{identifier}` placeholder in `data-product-url` is replaced with the product's identifier.
+`data-product-url` accepts a string template with one of two placeholders:
+- `{grouping}` — replaced with the product's salsifyGrouping ID
+- `{upc}` — replaced with the selected size's UPC
+
+If your PDP URLs aren't derivable from a single placeholder (e.g. each
+product has a hand-curated marketing slug), use the
+[Product URL Map](#product-url-map) instead.
 
 ### With Search and Filters
 
@@ -62,7 +68,7 @@ Separate containers for search and filters:
   data-liquid-commerce-elements-products-list="my-collection-slug"
   data-rows="4"
   data-columns="3"
-  data-product-url="/products/{identifier}"
+  data-product-url="/products/{grouping}"
 ></div>
 ```
 
@@ -80,7 +86,7 @@ await client.injectProductList({
   rows: 3,
   columns: 4,
   filters: ['price', 'brands', 'categories', 'fulfillment'],
-  productUrl: '/product/{identifier}'
+  productUrl: '/product/{grouping}'
 });
 
 // Inject search (optional)
@@ -122,6 +128,55 @@ The following filter type values can be used in the `filters` array:
 filters: ['price', 'brands', 'categories', 'fulfillment', 'sizes']
 ```
 
+## URL Query Param Filters
+
+The product list auto-applies filters from the page URL on first load. Useful for category landing pages, "shop the look" links, marketing emails, or any flow where you want to deep-link into a pre-filtered list.
+
+### Whitelist
+
+Only filter keys that are configured for the list are honored — anything else in the URL is silently ignored. The whitelist resolves in this priority order:
+
+1. `data-filters` on `<div data-liquid-commerce-elements-products-list>` (use this when the page does **not** mount a filters UI but you still want URL filtering — e.g. a curated category page).
+2. `data-filters` on the matching `<... -products-list-filters>` container (the common case when a filters panel is mounted).
+3. `availableFilters` from the theme config for the list slug.
+4. `filters` array passed to `injectProductList(...)` programmatically.
+
+### Supported formats
+
+| Filter | URL format | Example |
+| --- | --- | --- |
+| Multi-value (`brands`, `categories`, `flavor`, `region`, `variety`, `vintage`, `country`, `appellation`, `materials`, `sizes`) | Comma-separated **or** repeated keys | `?brands=Bacardi,Glenlivet` or `?brands=Bacardi&brands=Glenlivet` |
+| `fulfillment` | Single value: `all`, `shipping`, or `onDemand` | `?fulfillment=shipping` |
+| `engraving` | `true` or `false` | `?engraving=true` |
+| `price` | `min-max` range; `min-` or `-max` are accepted | `?price=20-150`, `?price=20-`, `?price=-150` |
+
+Invalid values are dropped (e.g. `?fulfillment=garbage`, `?price=abc` — no error, the filter just isn't applied). Combining params is supported:
+
+```
+https://yoursite.com/best-sellers?brands=Bacardi&categories=Wine&price=20-150&fulfillment=shipping
+```
+
+### Behavior
+
+- URL params win over any state persisted from a previous session.
+- Once the list mounts, the filters panel (if present) reflects the seeded values, and the initial product fetch is filtered.
+- Subsequent in-page interactions (toggling filters, scrolling, etc.) do not write back to the URL — the URL is read-only at load time.
+
+### Standalone use (no filters component)
+
+URL filtering works without injecting a filters panel. Declare the whitelist on the products-list container itself:
+
+```html
+<div
+  data-liquid-commerce-elements-products-list="curated-page"
+  data-filters="price,brands,categories"
+  data-rows="4"
+  data-columns="4"
+></div>
+```
+
+Now `https://yoursite.com/curated-page?brands=Bacardi&price=20-150` filters the list on load even though no filters UI is present.
+
 ## Search Functionality
 
 ### Search Box
@@ -213,7 +268,7 @@ Each product card shows:
 
 ### Card Interaction
 
-**Click on card:** Navigate to product detail page (if `productUrl` configured)
+**Click on card:** Navigate to product detail page (if `productUrl` configured — see [Product URL Map](#product-url-map) for partner-owned PDP URLs that aren't derivable from a token).
 
 **Quick Add:** Add product to cart directly from list view (if enabled)
 
@@ -298,7 +353,7 @@ See [Configuration Reference](../api/configuration.md#product-list-theme) for th
         data-liquid-commerce-elements-products-list="whiskey-collection"
         data-rows="4"
         data-columns="3"
-        data-product-url="/whiskey/{identifier}"
+        data-product-url="/whiskey/{grouping}"
       ></div>
     </main>
   </div>
@@ -339,13 +394,13 @@ const productType = getProductTypeFromData();
 let urlPattern;
 switch (productType) {
   case 'whiskey':
-    urlPattern = '/spirits/whiskey/{identifier}';
+    urlPattern = '/spirits/whiskey/{grouping}';
     break;
   case 'wine':
-    urlPattern = '/wine/{identifier}';
+    urlPattern = '/wine/{grouping}';
     break;
   default:
-    urlPattern = '/products/{identifier}';
+    urlPattern = '/products/{grouping}';
 }
 
 await client.injectProductList({
@@ -357,6 +412,76 @@ await client.injectProductList({
 });
 ```
 
+### Product URL Map
+
+For partners whose PDPs have hand-curated URLs that aren't derivable from a
+single placeholder (e.g. dedicated marketing pages, Shopify handles, WordPress
+slugs), pass a **map** instead of a string template. Keys are product
+identifiers — either a UPC or a salsifyGrouping ID, the same identifier types
+accepted by `injectProductElement`. The card looks up UPC first, then grouping
+ID; products not in the map render without a link.
+
+#### Declarative — JSON script tag
+
+Drop a single `<script type="application/json">` tag anywhere on the page,
+keyed by list slug → identifier → URL. Generate it server-side from your CMS.
+
+```html
+<script data-liquid-commerce-elements-product-urls type="application/json">
+{
+  "best-sellers": {
+    "GROUPING-33277": "/wines/macallan-12-special-edition",
+    "00832889005513": "/spirits/cabernet-2018-club-only"
+  },
+  "limited-releases": {
+    "GROUPING-78941": "/exclusive/pappy-23-allocation"
+  }
+}
+</script>
+
+<div data-liquid-commerce-elements-products-list="best-sellers"></div>
+```
+
+When both `data-product-url` and a slug entry in this script are present for
+the same list, the **map wins** — it's the more specific intent.
+
+##### Shopify Liquid
+
+```liquid
+<script data-liquid-commerce-elements-product-urls type="application/json">
+{
+  "best-sellers": {
+    {% for p in collections.best-sellers.products %}
+      "{{ p.metafields.lc.grouping_id }}": "{{ p.url }}"{% unless forloop.last %},{% endunless %}
+    {% endfor %}
+  }
+}
+</script>
+```
+
+##### WordPress / WooCommerce (PHP)
+
+```php
+<script data-liquid-commerce-elements-product-urls type="application/json">
+<?= json_encode(['best-sellers' => $lc_identifier_to_pdp_url_map]) ?>
+</script>
+```
+
+#### Programmatic
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  slug: 'best-sellers',
+  rows: 3,
+  columns: 4,
+  productUrl: {
+    'GROUPING-33277': '/wines/macallan-12-special-edition',
+    '00832889005513': '/spirits/cabernet-2018-club-only',
+  },
+});
+```
+
 ## Events
 
 While product list events are primarily internal, you can listen for cart events when users add products:

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.13",
+  "version": "2.7.15",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "module": "./dist/index.esm.js",
   "types": "./dist/types/index.d.ts",
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@10.33.4",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -77,9 +77,9 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.4.13",
-    "@commitlint/cli": "^20.5.0",
-    "@commitlint/config-conventional": "^20.5.0",
+    "@biomejs/biome": "^2.4.14",
+    "@commitlint/cli": "^20.5.3",
+    "@commitlint/config-conventional": "^20.5.3",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
@@ -97,7 +97,7 @@
     "conventional-changelog": "^7.2.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.60.2",
+    "rollup": "^4.60.3",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.37.0",
     "semantic-release": "^25.0.3",