@liquidcommerce/elements-sdk 2.7.30 → 2.7.31

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

@@ -14,6 +14,7 @@ export interface IInjectProductListParams {
     columns?: number;
     filters?: ProductListFilterType[];
     productUrl?: PLCProductUrl;
+    productOrder?: string[];
 }
 export interface IInjectProductListSearchParams {
     containerId: string;

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

@@ -25,6 +25,7 @@ export declare class ProductListCardComponent extends BaseComponent<IProductList
     private getSelectedSize;
     private getDisplayPrice;
     protected template(): HTMLElement[];
+    protected afterRender(): void;
     private updatePriceDisplay;
     private updateFulfillmentText;
     private updateImage;

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

@@ -0,0 +1,3 @@
+import type { IPLProductStore } from '@/core/store/interfaces/product-list.interface';
+export declare function buildProductOrderIndex(productOrder: string[]): Map<string, number>;
+export declare function sortProductsByOrder(products: IPLProductStore[], orderIndex: Map<string, number>): IPLProductStore[];

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

@@ -8,6 +8,7 @@ export interface IProductListComponentParams {
     columns: number;
     filters: ProductListFilterType[];
     productUrl?: PLCProductUrl;
+    productOrder?: string[];
 }
 export declare class ProductListComponent extends BaseComponent<IProductListComponentParams, IProductListComponent> {
     private products;
@@ -17,6 +18,7 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     private loadingState;
     private scrollObserver;
     private initializationPromise;
+    private productOrderIndex;
     private unsubscribeFromState?;
     get hostClasses(): string[];
     constructor();
@@ -24,6 +26,8 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     protected afterRender(): void;
     disconnected(): void;
     private initializeComponent;
+    private getProductOrderIndex;
+    private hasProductOrder;
     private toProductArray;
     private setLoadingState;
     private renderCurrentState;
@@ -35,6 +39,7 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     private lastAnnouncedSentinelState;
     private renderProducts;
     private announceResultCount;
+    private insertOrderedProducts;
     private appendNewProducts;
     private setupInfiniteScroll;
     private createScrollSentinel;

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

@@ -134,6 +134,7 @@ interface IInjectProductListParams {
   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.
@@ -177,6 +178,39 @@ await client.injectProductList({
 });
 ```
 
+### 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()

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

@@ -197,6 +197,7 @@ interface IInjectProductListParams {
   columns?: number;
   filters?: ProductListFilterType[];
   productUrl?: PLCProductUrl;
+  productOrder?: string[];  // display order, by UPC or grouping ID
 }
 ```
 

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

@@ -43,6 +43,7 @@ Use data attributes to configure the product list:
 - `data-columns`: Number of columns (default: 4)
 - `data-filters`: Comma-separated filter types
 - `data-product-url`: URL pattern for product detail pages (optional)
+- `data-product-order`: Comma-separated product identifiers setting the display order (optional) — see [Product Order](#product-order)
 
 `data-product-url` accepts a string template with one of two placeholders:
 - `{grouping}` — replaced with the product's salsifyGrouping ID
@@ -227,6 +228,66 @@ await client.injectProductList({
 
 Total products per page = rows × columns (e.g., 5 × 4 = 20 products)
 
+## Product Order
+
+By default the grid renders products in the order the API returns them for the
+list's slug. `productOrder` overrides that with an explicit order you control
+from the page.
+
+```javascript
+await client.injectProductList({
+  containerId: 'products',
+  slug: 'my-collection-slug',
+  productOrder: [
+    '00832889005513',
+    'GROUPING-33277',
+    '00619947000020',
+  ],
+});
+```
+
+```html
+<div
+  data-liquid-commerce-elements-products-list="my-collection-slug"
+  data-product-order="00832889005513,GROUPING-33277,00619947000020"
+></div>
+```
+
+**Identifiers.** Each entry is a UPC or a `salsifyGrouping` ID — the same identifier
+concept the [Product URL Map](#product-url-map) keys on and `injectProductElement`
+accepts. The two forms mix freely in one array. A UPC identifies a single size, so
+naming any size of a product positions that product.
+
+**It reorders; it does not select.** The slug still decides which products the list
+contains. An identifier for a product outside the list matches nothing, and no error
+is raised. Products the array doesn't name render after the ones it does, keeping
+their API order among themselves — so a partial list reorders only what it names.
+
+**Pagination.** A product named early keeps its position even if the API returns it on
+a later page. Each new page is spliced into the grid at the right slots rather than
+appended, so cards already on screen are left untouched — scroll position and keyboard
+focus survive loading a page. For a small curated set, size `rows × columns` to cover
+it in a single page so no scroll is needed at all.
+
+**Search and filters** re-query the API for a narrower result set. The order is
+re-applied to whatever comes back, so named products keep their relative order among
+the results that survive.
+
+**Nothing about `productOrder` throws.** Ordering is presentational and the grid
+renders fine without it, so a malformed value costs you the ordering and nothing
+else — never the product list itself.
+
+- An entry that isn't a non-empty string is skipped with a console warning, the way
+  an unrecognized `filters` value is. The surviving entries keep their relative
+  order, so the rest of your ordering still applies around the dropped one.
+- A `productOrder` that isn't an array is ignored entirely with a warning, and the
+  list renders in the order the API returns.
+
+> The warning goes through the SDK logger, which is silent in production and at the
+> default `debugMode: 'none'`. On a live storefront a dropped entry produces no
+> console output at all, so validate the array you generate rather than relying on
+> the warning to surface a bad one.
+
 ## Infinite Scroll
 
 ### How It Works
@@ -274,6 +335,32 @@ Product card images automatically have their white/near-white backgrounds remove
 
 **Click on image:** Navigate to the configured `productUrl` (only when `productUrl` is set — otherwise the image is not a link)
 
+### Card Identifiers
+
+Each `product-list-card-lc` host carries the product's identifiers as data
+attributes, so a card can be traced back to catalogue data while inspecting the
+page:
+
+```html
+<product-list-card-lc data-grouping="GROUPING-33277" data-upc="00832889005513">
+```
+
+- `data-grouping` — the product's `salsifyGrouping` ID. Fixed for the life of the card.
+- `data-upc` — the **selected size's** UPC, the same value `{upc}` resolves to in a
+  `productUrl` template. It updates when the shopper changes size.
+
+Both use the identifier forms accepted everywhere else in the SDK, so a value read
+off a card can be pasted straight into `productOrder`, a `productUrl` map key, or
+`injectProductElement`.
+
+> **These are for inspection, not for scripting.** Cards render inside the SDK's
+> shadow root, which is **always closed in production** — `openShadowDom` is forced
+> to `false` there and only has effect in development. Chrome DevTools displays
+> closed shadow roots, so the attributes are visible when inspecting the page, but
+> `document.querySelector('[data-upc]')` from partner JavaScript will not reach them
+> on a live storefront. To react to card activity from your own code, use the
+> [events](#events) instead.
+
 ## Customization
 
 ### Theme Configuration

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.30",
+  "version": "2.7.31",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",