@liquidcommerce/elements-sdk 2.6.0-beta.75 → 2.6.0-beta.76

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/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,7 +17,7 @@ export interface IPLCProductCard {
     showQuantityCounter: boolean;
     enablePreCart: boolean;
     showCollectionTags: boolean;
-    productUrl: string | null;
+    productUrl: PLCProductUrl | null;
     noAvailabilityText: string;
 }
 export interface IPLCList {

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-list/components/product-list-card.component.d.ts

@@ -1,9 +1,10 @@
 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;

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/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,25 @@ await client.injectProductList({
   rows: 4,
   columns: 3,
   filters: ['price', 'brands', 'categories'],
-  productUrl: '/product/{identifier}'
+  productUrl: '/product/{grouping}'
+});
+```
+
+### 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)
@@ -213,7 +219,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 +304,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 +345,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 +363,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.6.0-beta.75",
+  "version": "2.6.0-beta.76",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",