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

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

@@ -3,6 +3,7 @@ import type { IProductListComponent } from '@/interfaces/configs';
 import type { IProductListComponentParams } from '@/modules/product-list/product-list.component';
 export declare class ProductListCardLoadingComponent extends BaseComponent<IProductListComponentParams, IProductListComponent> {
     get hostClasses(): string[];
+    protected get hostAttributes(): Record<string, string>;
     private createSkeletonCard;
     protected template(): HTMLElement[];
 }

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/docs/v1/api/injection-methods.md

@@ -151,6 +151,11 @@ await client.injectProductList({
 });
 ```
 
+> 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

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

@@ -128,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

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.76",
+  "version": "2.6.0-beta.78",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -78,8 +78,8 @@
   ],
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
-    "@commitlint/cli": "^20.5.3",
-    "@commitlint/config-conventional": "^20.5.3",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-json": "^6.1.0",
@@ -93,7 +93,7 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.6.2",
     "conventional-changelog": "^7.2.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",