@liquidcommerce/elements-sdk 2.7.30 → 2.7.32

package/dist/types/constants/core.constant.d.ts

@@ -3,19 +3,19 @@ export declare const API_CLIENT_URL: {
     production: string;
 };
 export declare const PRODUCT_LIST_FILTER_TYPES: {
-    ENGRAVING: string;
-    FULFILLMENT: string;
-    PRICE: string;
-    BRANDS: string;
-    CATEGORIES: string;
-    FLAVOR: string;
-    REGION: string;
-    VARIETY: string;
-    VINTAGE: string;
-    COUNTRY: string;
-    APPELLATION: string;
-    MATERIALS: string;
-    SIZES: string;
+    readonly ENGRAVING: "engraving";
+    readonly FULFILLMENT: "fulfillment";
+    readonly PRICE: "price";
+    readonly BRANDS: "brands";
+    readonly CATEGORIES: "categories";
+    readonly FLAVOR: "flavor";
+    readonly REGION: "region";
+    readonly VARIETY: "variety";
+    readonly VINTAGE: "vintage";
+    readonly COUNTRY: "country";
+    readonly APPELLATION: "appellation";
+    readonly MATERIALS: "materials";
+    readonly SIZES: "sizes";
 };
 export declare const Z_INDEX: {
     readonly DRAWER_WRAPPER: 2147483640;

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

@@ -21,7 +21,7 @@ export interface IFilterParams {
 export type FacetFilterKeys = typeof FILTER_KEYS.BRANDS | typeof FILTER_KEYS.CATEGORIES | typeof FILTER_KEYS.FLAVOR | typeof FILTER_KEYS.REGION | typeof FILTER_KEYS.VARIETY | typeof FILTER_KEYS.VINTAGE | typeof FILTER_KEYS.COUNTRY | typeof FILTER_KEYS.APPELLATION | typeof FILTER_KEYS.TAGS | typeof FILTER_KEYS.MATERIALS | typeof FILTER_KEYS.SIZES | typeof FILTER_KEYS.ENGRAVING | typeof FILTER_KEYS.FULFILLMENT | typeof FILTER_KEYS.PRICE | typeof FILTER_KEYS.AVAILABILITY | typeof FILTER_KEYS.COLORS;
 export interface IFilterSchema {
     type: FacetFilterKeys;
-    values: IFilterValue[];
+    values: IFilterValue[] | string[];
 }
 export interface IFilterValue {
     value: string;

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/filter-components/product-list-checkbox-filter.d.ts

@@ -1,6 +1,7 @@
 import type { ICheckboxLabelStates, ICreateCheckboxFilterHeaderParams, ICreateCheckboxFilterSearchContainerParams, ICreateCheckboxItemParams, IHandleCheckboxFilterSearchParams, IRenderCheckboxItemsParams } from '../../product-list.interface';
 export declare function createCheckboxItem(params: ICreateCheckboxItemParams): HTMLElement;
 export declare function handleCheckboxFilterSearch(params: IHandleCheckboxFilterSearchParams): void;
+export declare function checkboxFilterContentId(filterType: string): string;
 export declare function createCheckboxFilterHeader(params: ICreateCheckboxFilterHeaderParams): HTMLElement;
 export declare function createCheckboxFilterSearchContainer(params: ICreateCheckboxFilterSearchContainerParams): HTMLElement;
 export declare function renderCheckboxItems(params: IRenderCheckboxItemsParams): void;

package/dist/types/modules/product-list/components/filter-components/product-list-price-filter.d.ts

@@ -19,4 +19,5 @@ export declare function createPriceFilter(params: ICreatePriceFilterParams): {
     elements: HTMLElement[];
     chevronContainer: HTMLElement;
     sliderContainer: HTMLElement;
+    headerButton: HTMLButtonElement;
 };

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

@@ -13,15 +13,13 @@ export declare class ProductListFiltersComponent extends BaseComponent<IProductL
     private isPriceFilterCollapsed;
     private isFulfillmentFilterCollapsed;
     private appliedFiltersChipsContainer;
-    private engravingFiltersContainer?;
-    private fulfillmentFilterContainer?;
-    private priceFiltersContainer?;
-    private dynamicFiltersContainer?;
+    private filterSectionsContainer?;
     private filterButtonContainer?;
     private fulfillmentOptionsList?;
     private priceFilterChevronIcon?;
     private fulfillmentFilterChevronIcon?;
     private priceSliderWrapper?;
+    private priceFilterHeaderButton;
     private boundDrawerClosedHandler;
     private priceFilterDebounceTimer;
     constructor();
@@ -35,7 +33,8 @@ export declare class ProductListFiltersComponent extends BaseComponent<IProductL
     private createFilterSection;
     private rebuildContainer;
     private refreshUIStates;
-    private transformFilterValue;
+    private buildFilterSections;
+    private refreshFilterButtonVisibility;
     private fetchFilters;
     private applyFiltersAndCloseDrawer;
     protected template(): HTMLElement[];
@@ -44,7 +43,10 @@ export declare class ProductListFiltersComponent extends BaseComponent<IProductL
     private buildFilterHeader;
     private clearAllActiveFilters;
     private removeSingleFilter;
+    private removeFacetValue;
     private getFilteredAndSanitizedFilters;
+    private isFilterConfigured;
+    private hasVisibleFilters;
     private buildAppliedFiltersChipsContainer;
     private handleFilterChange;
     private isEngravingCurrentlyDisabled;

package/dist/types/modules/product-list/product-list-filter.registry.d.ts

@@ -0,0 +1,42 @@
+import type { IFilterParamsValue } from '@/interfaces/api/product-list.interface';
+import type { ProductListFilterType } from '@/interfaces/injection.interface';
+import type { IProductListFilters } from './product-list.interface';
+export declare const FILTER_KIND: {
+    readonly FACET: "facet";
+    readonly TOGGLE: "toggle";
+    readonly CHOICE: "choice";
+    readonly RANGE: "range";
+};
+export type FilterKind = (typeof FILTER_KIND)[keyof typeof FILTER_KIND];
+interface IFilterDefinitionBase {
+    key: string;
+    type: ProductListFilterType;
+}
+export interface IFacetFilterDefinition extends IFilterDefinitionBase {
+    kind: typeof FILTER_KIND.FACET;
+}
+export interface IToggleFilterDefinition extends IFilterDefinitionBase {
+    kind: typeof FILTER_KIND.TOGGLE;
+    apiOn: string;
+}
+export interface IChoiceFilterDefinition extends IFilterDefinitionBase {
+    kind: typeof FILTER_KIND.CHOICE;
+    anyValue: string;
+    anyExpandsTo: string[];
+    values: string[];
+}
+export interface IRangeFilterDefinition extends IFilterDefinitionBase {
+    kind: typeof FILTER_KIND.RANGE;
+    defaultMin: string;
+    defaultMax: string;
+}
+export type IFilterDefinition = IFacetFilterDefinition | IToggleFilterDefinition | IChoiceFilterDefinition | IRangeFilterDefinition;
+export declare const FILTER_DEFINITIONS: IFilterDefinition[];
+export declare function getFilterDefinition(key: string): IFilterDefinition | undefined;
+export declare function getConfiguredFilterDefinitions(configuredFilters: ProductListFilterType[] | undefined): IFilterDefinition[];
+export declare function getDefaultFilterValue(definition: IFilterDefinition): IProductListFilters[string];
+export declare function createDefaultFilterValues(): IProductListFilters;
+export declare function isFilterValueApplied(definition: IFilterDefinition, value: IProductListFilters[string]): boolean;
+export declare function decodeStoredFilterValue(definition: IFilterDefinition, stored: unknown): IProductListFilters[string];
+export declare function encodeFilterValueForApi(definition: IFilterDefinition, value: IProductListFilters[string]): IFilterParamsValue;
+export {};

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

@@ -1,8 +1,7 @@
 import type { IFilterSchema, IProductSearchParams } from '@/interfaces/api/product-list.interface';
 import type { ProductListFilterType } from '@/interfaces/injection.interface';
 import type { IExtendedFilterSchema, IProductListFilters } from './product-list.interface';
-export declare const FILTER_TYPE_MAP: Record<string, string>;
 export declare function getSanitizedFilters(filters: IFilterSchema[], configuredFilters: ProductListFilterType[]): IExtendedFilterSchema[];
 export declare function syncFiltersToAppliedFormat(filters: IProductListFilters): Record<string, string[]>;
-export declare function buildSearchParams(slug: string, page: number, perPage: number, searchTerm: string, currentFilters: IProductListFilters, configuredFilters: ProductListFilterType[]): IProductSearchParams;
 export declare function buildCurrentFiltersFromState(stateFilters: Record<string, string[]>): IProductListFilters;
+export declare function buildSearchParams(slug: string, page: number, perPage: number, searchTerm: string, currentFilters: IProductListFilters, configuredFilters: ProductListFilterType[]): IProductSearchParams;

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,8 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     private lastAnnouncedSentinelState;
     private renderProducts;
     private announceResultCount;
+    private getListConfig;
+    private insertOrderedProducts;
     private appendNewProducts;
     private setupInfiniteScroll;
     private createScrollSentinel;

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

@@ -26,6 +26,7 @@ export interface ICheckboxLabelStates {
     filteredItems: IFilterValue[];
     contentElement: HTMLElement | null;
     iconElement: HTMLElement | null;
+    toggleButton: HTMLButtonElement | null;
     hasUserInteraction: boolean;
 }
 export interface ICreateCheckboxItemParams {

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()
@@ -240,6 +274,11 @@ await client.injectProductListFilters({
 });
 ```
 
+> **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

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
@@ -113,7 +114,7 @@ The following filter type values can be used in the `filters` array:
 | `'brands'`     | Checkboxes for available brands          |
 | `'categories'` | Category selection checkboxes            |
 | `'fulfillment'`| Shipping vs. on-demand delivery toggle   |
-| `'engraving'`  | Filter by personalization support        |
+| `'engraving'`  | Toggle: on shows only personalizable products, off shows all |
 | `'sizes'`      | Filter by product size/volume            |
 | `'flavor'`     | Filter by flavor profile                 |
 | `'region'`     | Filter by region of origin               |
@@ -128,6 +129,15 @@ The following filter type values can be used in the `filters` array:
 filters: ['price', 'brands', 'categories', 'fulfillment', 'sizes']
 ```
 
+Every section of the filters panel is opt-in — `'price'`, `'fulfillment'` and `'engraving'`
+included. A value you leave out of the array is not rendered, and an empty array draws no
+filters panel at all. Omit `filters` entirely and the list falls back to the server-configured
+defaults for that slug.
+
+Sections render **collapsed**; the shopper opens the ones they care about. Nothing is
+auto-expanded, not even a filter seeded from the URL — an applied value shows as a removable
+chip above the sections, so it stays visible without opening anything.
+
 ## 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.
@@ -150,6 +160,10 @@ Only filter keys that are configured for the list are honored — anything else
 | `engraving` | `true` or `false` | `?engraving=true` |
 | `price` | `min-max` range; `min-` or `-max` are accepted | `?price=20-150`, `?price=20-`, `?price=-150` |
 
+`engraving=true` narrows the list to products that support personalization. `engraving=false` is
+the filter's unset state and narrows nothing — it is equivalent to leaving the param off, not a
+request for products that cannot be personalized.
+
 Invalid values are dropped (e.g. `?fulfillment=garbage`, `?price=abc` — no error, the filter just isn't applied). Combining params is supported:
 
 ```
@@ -227,6 +241,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 +348,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.32",
   "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@11.21.0",
+  "packageManager": "pnpm@11.22.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -107,7 +107,7 @@
     "theming"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.5.8",
+    "@biomejs/biome": "^2.5.9",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
     "@rollup/plugin-alias": "^6.0.0",