@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/dist/development/core/collection/reconciler.mjs

@@ -0,0 +1,89 @@
+import { collectionSearchEqual, mergeCollectionParams, normalizeCollectionSearch } from "./url.mjs";
+
+//#region src/core/collection/reconciler.ts
+/**
+* Creates a framework-agnostic reconciler that manages the state machine for
+* keeping the URL, server data, and store in sync during browse-change chains.
+*
+* Framework adapters delegate to this so the reconciliation logic
+* lives in one place.
+*/
+function createCollectionReconciler(callbacks, initialPrevUrlSearch = "") {
+	let pendingFilter = null;
+	let pendingUrls = /* @__PURE__ */ new Set();
+	let prevUrlSearch = initialPrevUrlSearch;
+	return {
+		handleBrowseChange() {
+			const store = callbacks.getStore();
+			const searchString = mergeCollectionParams(new URLSearchParams(callbacks.readUrlSearch()), store.getState()).toString();
+			pendingFilter = searchString;
+			pendingUrls.add(searchString);
+			callbacks.emitChange(searchString ? `?${searchString}` : "");
+		},
+		reset(newPrevUrlSearch) {
+			pendingFilter = null;
+			pendingUrls = /* @__PURE__ */ new Set();
+			prevUrlSearch = newPrevUrlSearch;
+		},
+		reconcile(urlSearch, dataSearch) {
+			const store = callbacks.getStore();
+			const pendingSearchEquals = (search) => [...pendingUrls].some((pending) => collectionSearchEqual(pending, search));
+			const pendingTargetMatchesUrl = pendingFilter != null && collectionSearchEqual(pendingFilter, urlSearch);
+			const trySettleFromServer = () => {
+				if (store.getState().status !== "loading") return false;
+				if (!collectionSearchEqual(dataSearch, urlSearch)) return false;
+				const incomingParams = new URLSearchParams(urlSearch);
+				if (!store.matchesParams(incomingParams)) store.syncFromParams(incomingParams);
+				store.settle();
+				return true;
+			};
+			const clearPendingIfSettled = () => {
+				if (!trySettleFromServer()) return false;
+				pendingFilter = null;
+				pendingUrls.clear();
+				return true;
+			};
+			if (clearPendingIfSettled()) return;
+			const urlSearchChanged = normalizeCollectionSearch(urlSearch) !== normalizeCollectionSearch(prevUrlSearch);
+			prevUrlSearch = urlSearch;
+			const reDispatchToPendingTarget = () => {
+				if (pendingFilter == null) return;
+				callbacks.emitChange(pendingFilter ? `?${pendingFilter}` : "");
+			};
+			const routerSettledOnIntermediateWithStaleTarget = pendingFilter != null && pendingSearchEquals(urlSearch) && !pendingTargetMatchesUrl && collectionSearchEqual(dataSearch, urlSearch);
+			const serverConfirmedIntermediateWhileTargeting = pendingFilter != null && pendingSearchEquals(dataSearch) && !collectionSearchEqual(dataSearch, pendingFilter) && !collectionSearchEqual(dataSearch, urlSearch);
+			if (pendingTargetMatchesUrl) {
+				if (trySettleFromServer()) {
+					pendingFilter = null;
+					pendingUrls.clear();
+				} else if (store.getState().status === "loading" && serverConfirmedIntermediateWhileTargeting) reDispatchToPendingTarget();
+				return;
+			}
+			if (pendingFilter != null) {
+				if (!urlSearchChanged) {
+					if (clearPendingIfSettled()) return;
+					if (routerSettledOnIntermediateWithStaleTarget) reDispatchToPendingTarget();
+					return;
+				}
+				if (pendingSearchEquals(urlSearch)) {
+					if (clearPendingIfSettled()) return;
+					if (routerSettledOnIntermediateWithStaleTarget) reDispatchToPendingTarget();
+					return;
+				}
+				pendingFilter = null;
+				pendingUrls.clear();
+			}
+			const incomingParams = new URLSearchParams(urlSearch);
+			if (store.matchesParams(incomingParams)) {
+				trySettleFromServer();
+				return;
+			}
+			store.syncFromParams(incomingParams);
+			trySettleFromServer();
+		}
+	};
+}
+
+//#endregion
+export { createCollectionReconciler };
+//# sourceMappingURL=reconciler.mjs.map

package/dist/development/core/collection/reconciler.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciler.mjs","names":[],"sources":["../../../../src/core/collection/reconciler.ts"],"sourcesContent":["import type { CollectionStore } from \"./collection\";\nimport { collectionSearchEqual, mergeCollectionParams, normalizeCollectionSearch } from \"./url\";\n\nexport type ReconcilerCallbacks = {\n  getStore: () => CollectionStore;\n  readUrlSearch: () => string;\n  emitChange: (searchString: string) => void;\n};\n\nexport type CollectionReconciler = {\n  /**\n   * URL ↔ store reconciliation state machine. Call whenever urlSearch,\n   * dataSearch, or store state changes.\n   */\n  reconcile(urlSearch: string, dataSearch: string): void;\n  /**\n   * Callback for {@link CollectionStore.setOnBrowseChange}. Merges current\n   * URL params with store state, tracks the pending navigation, and emits.\n   */\n  handleBrowseChange(): void;\n  /** Clears pending navigation state (call when the store is recreated). */\n  reset(newPrevUrlSearch: string): void;\n};\n\n/**\n * Creates a framework-agnostic reconciler that manages the state machine for\n * keeping the URL, server data, and store in sync during browse-change chains.\n *\n * Framework adapters delegate to this so the reconciliation logic\n * lives in one place.\n */\nexport function createCollectionReconciler(\n  callbacks: ReconcilerCallbacks,\n  initialPrevUrlSearch = \"\",\n): CollectionReconciler {\n  let pendingFilter: string | null = null;\n  let pendingUrls = new Set<string>();\n  let prevUrlSearch = initialPrevUrlSearch;\n\n  return {\n    handleBrowseChange() {\n      const store = callbacks.getStore();\n      const merged = mergeCollectionParams(\n        new URLSearchParams(callbacks.readUrlSearch()),\n        store.getState(),\n      );\n      const searchString = merged.toString();\n      pendingFilter = searchString;\n      pendingUrls.add(searchString);\n      callbacks.emitChange(searchString ? `?${searchString}` : \"\");\n    },\n\n    reset(newPrevUrlSearch: string) {\n      pendingFilter = null;\n      pendingUrls = new Set();\n      prevUrlSearch = newPrevUrlSearch;\n    },\n\n    // State machine — four states:\n    //\n    //   ┌─────────────────────────────────────────────────────────────────────┐\n    //   │ State A: No pending navigation (pendingFilter === null)            │\n    //   │  • URL matches store → try settle if server data caught up         │\n    //   │  • URL differs from store → syncFromParams, then try settle        │\n    //   ├─────────────────────────────────────────────────────────────────────┤\n    //   │ State B: Pending — URL matches target (pendingTargetMatchesUrl)    │\n    //   │  • Server data matches URL → settle, clear pending state           │\n    //   │  • Server data stale (intermediate) → re-dispatch to target        │\n    //   │  • Server data not yet arrived → wait (keep pending set)           │\n    //   ├─────────────────────────────────────────────────────────────────────┤\n    //   │ State C: Pending — URL is intermediate (in pendingUrls)            │\n    //   │  • Ignore URL change; if router settled here with server data      │\n    //   │    confirming the intermediate, re-dispatch to the real target     │\n    //   ├─────────────────────────────────────────────────────────────────────┤\n    //   │ State D: Pending — URL is unknown (not in pendingUrls)             │\n    //   │  • External navigation (back/forward, <Link>)                     │\n    //   │  • Abandon pending state, fall through to State A                  │\n    //   └─────────────────────────────────────────────────────────────────────┘\n    //\n    // Rapid toggles (A on → B on → A off) produce multiple in-flight navigations.\n    // pendingFilter tracks the latest target; pendingUrls tracks every URL\n    // dispatched in the chain so intermediates can be distinguished from external navs.\n    reconcile(urlSearch: string, dataSearch: string) {\n      const store = callbacks.getStore();\n\n      const pendingSearchEquals = (search: string): boolean =>\n        [...pendingUrls].some((pending) => collectionSearchEqual(pending, search));\n\n      const pendingTargetMatchesUrl =\n        pendingFilter != null && collectionSearchEqual(pendingFilter, urlSearch);\n\n      const trySettleFromServer = (): boolean => {\n        if (store.getState().status !== \"loading\") return false;\n        if (!collectionSearchEqual(dataSearch, urlSearch)) return false;\n\n        const incomingParams = new URLSearchParams(urlSearch);\n        if (!store.matchesParams(incomingParams)) {\n          store.syncFromParams(incomingParams);\n        }\n\n        store.settle();\n        return true;\n      };\n\n      const clearPendingIfSettled = (): boolean => {\n        if (!trySettleFromServer()) return false;\n        pendingFilter = null;\n        pendingUrls.clear();\n        return true;\n      };\n\n      if (clearPendingIfSettled()) return;\n\n      const normalizedUrlSearch = normalizeCollectionSearch(urlSearch);\n      const normalizedPrevUrlSearch = normalizeCollectionSearch(prevUrlSearch);\n      const urlSearchChanged = normalizedUrlSearch !== normalizedPrevUrlSearch;\n      prevUrlSearch = urlSearch;\n\n      const reDispatchToPendingTarget = () => {\n        if (pendingFilter == null) return;\n        callbacks.emitChange(pendingFilter ? `?${pendingFilter}` : \"\");\n      };\n\n      const routerSettledOnIntermediateWithStaleTarget =\n        pendingFilter != null &&\n        pendingSearchEquals(urlSearch) &&\n        !pendingTargetMatchesUrl &&\n        collectionSearchEqual(dataSearch, urlSearch);\n\n      const serverConfirmedIntermediateWhileTargeting =\n        pendingFilter != null &&\n        pendingSearchEquals(dataSearch) &&\n        !collectionSearchEqual(dataSearch, pendingFilter) &&\n        !collectionSearchEqual(dataSearch, urlSearch);\n\n      if (pendingTargetMatchesUrl) {\n        if (trySettleFromServer()) {\n          pendingFilter = null;\n          pendingUrls.clear();\n        } else if (\n          store.getState().status === \"loading\" &&\n          serverConfirmedIntermediateWhileTargeting\n        ) {\n          reDispatchToPendingTarget();\n        }\n        return;\n      }\n\n      if (pendingFilter != null) {\n        if (!urlSearchChanged) {\n          if (clearPendingIfSettled()) return;\n          if (routerSettledOnIntermediateWithStaleTarget) {\n            reDispatchToPendingTarget();\n          }\n          return;\n        }\n\n        if (pendingSearchEquals(urlSearch)) {\n          if (clearPendingIfSettled()) return;\n          if (routerSettledOnIntermediateWithStaleTarget) {\n            reDispatchToPendingTarget();\n          }\n          return;\n        }\n\n        pendingFilter = null;\n        pendingUrls.clear();\n      }\n\n      const incomingParams = new URLSearchParams(urlSearch);\n\n      if (store.matchesParams(incomingParams)) {\n        trySettleFromServer();\n        return;\n      }\n\n      store.syncFromParams(incomingParams);\n      trySettleFromServer();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;AA+BA,SAAgB,2BACd,WACA,uBAAuB,IACD;CACtB,IAAI,gBAA+B;CACnC,IAAI,8BAAc,IAAI,KAAa;CACnC,IAAI,gBAAgB;AAEpB,QAAO;EACL,qBAAqB;GACnB,MAAM,QAAQ,UAAU,UAAU;GAKlC,MAAM,eAJS,sBACb,IAAI,gBAAgB,UAAU,eAAe,CAAC,EAC9C,MAAM,UAAU,CAES,CAAC,UAAU;AACtC,mBAAgB;AAChB,eAAY,IAAI,aAAa;AAC7B,aAAU,WAAW,eAAe,IAAI,iBAAiB,GAAG;;EAG9D,MAAM,kBAA0B;AAC9B,mBAAgB;AAChB,iCAAc,IAAI,KAAK;AACvB,mBAAgB;;EA2BlB,UAAU,WAAmB,YAAoB;GAC/C,MAAM,QAAQ,UAAU,UAAU;GAElC,MAAM,uBAAuB,WAC3B,CAAC,GAAG,YAAY,CAAC,MAAM,YAAY,sBAAsB,SAAS,OAAO,CAAC;GAE5E,MAAM,0BACJ,iBAAiB,QAAQ,sBAAsB,eAAe,UAAU;GAE1E,MAAM,4BAAqC;AACzC,QAAI,MAAM,UAAU,CAAC,WAAW,UAAW,QAAO;AAClD,QAAI,CAAC,sBAAsB,YAAY,UAAU,CAAE,QAAO;IAE1D,MAAM,iBAAiB,IAAI,gBAAgB,UAAU;AACrD,QAAI,CAAC,MAAM,cAAc,eAAe,CACtC,OAAM,eAAe,eAAe;AAGtC,UAAM,QAAQ;AACd,WAAO;;GAGT,MAAM,8BAAuC;AAC3C,QAAI,CAAC,qBAAqB,CAAE,QAAO;AACnC,oBAAgB;AAChB,gBAAY,OAAO;AACnB,WAAO;;AAGT,OAAI,uBAAuB,CAAE;GAI7B,MAAM,mBAFsB,0BAA0B,UAEV,KADZ,0BAA0B,cACc;AACxE,mBAAgB;GAEhB,MAAM,kCAAkC;AACtC,QAAI,iBAAiB,KAAM;AAC3B,cAAU,WAAW,gBAAgB,IAAI,kBAAkB,GAAG;;GAGhE,MAAM,6CACJ,iBAAiB,QACjB,oBAAoB,UAAU,IAC9B,CAAC,2BACD,sBAAsB,YAAY,UAAU;GAE9C,MAAM,4CACJ,iBAAiB,QACjB,oBAAoB,WAAW,IAC/B,CAAC,sBAAsB,YAAY,cAAc,IACjD,CAAC,sBAAsB,YAAY,UAAU;AAE/C,OAAI,yBAAyB;AAC3B,QAAI,qBAAqB,EAAE;AACzB,qBAAgB;AAChB,iBAAY,OAAO;eAEnB,MAAM,UAAU,CAAC,WAAW,aAC5B,0CAEA,4BAA2B;AAE7B;;AAGF,OAAI,iBAAiB,MAAM;AACzB,QAAI,CAAC,kBAAkB;AACrB,SAAI,uBAAuB,CAAE;AAC7B,SAAI,2CACF,4BAA2B;AAE7B;;AAGF,QAAI,oBAAoB,UAAU,EAAE;AAClC,SAAI,uBAAuB,CAAE;AAC7B,SAAI,2CACF,4BAA2B;AAE7B;;AAGF,oBAAgB;AAChB,gBAAY,OAAO;;GAGrB,MAAM,iBAAiB,IAAI,gBAAgB,UAAU;AAErD,OAAI,MAAM,cAAc,eAAe,EAAE;AACvC,yBAAqB;AACrB;;AAGF,SAAM,eAAe,eAAe;AACpC,wBAAqB;;EAExB"}

package/dist/development/core/collection/state.d.mts

@@ -0,0 +1,66 @@
+import { ProductCollectionSortKeys } from "../../graphql/generated/storefront-api-types.mjs";
+import { ProductFilter } from "../../vendor/standard-events.mjs";
+
+//#region src/core/collection/state.d.ts
+/** How a filter option is visually presented in the storefront UI. */
+type FilterPresentation = "IMAGE" | "SWATCH" | "TEXT";
+/** The input mechanism a filter uses — boolean toggle, multi-select list, or price slider. */
+type FilterType = "BOOLEAN" | "LIST" | "PRICE_RANGE" | (string & {});
+interface BaseAvailableFilterValue {
+  /** Unique identifier for this filter value. */
+  id: string;
+  /** Human-readable label (e.g. "Red", "Nike", "$50–$100"). */
+  label: string;
+  /** Number of products matching this value in the current result set. */
+  count: number;
+  /** JSON-encoded `ProductFilter` input to apply this value. */
+  input: string;
+}
+type PickIfPresent<TValue, TKey extends PropertyKey> = TKey extends keyof TValue ? Pick<TValue, TKey> : {};
+/**
+ * A single selectable value within an {@link AvailableFilter}.
+ *
+ * Pass your Storefront API query value type as `TValue` to expose query-selected
+ * visual fields such as `swatch`.
+ */
+type AvailableFilterValue<TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue> = BaseAvailableFilterValue & PickIfPresent<TValue, "swatch">;
+/**
+ * A filter facet available for the current collection, returned by the
+ * Storefront API. Used to render filter UI (checkboxes, swatches, sliders).
+ */
+interface AvailableFilter<TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue> {
+  id: string;
+  label: string;
+  type: FilterType;
+  presentation?: FilterPresentation | null;
+  values: AvailableFilterValue<TValue>[];
+}
+/**
+ * Pure browse-intent state for a collection store. Represents what the user
+ * wants to see (filters, sort), not what the server returned.
+ *
+ * Server response data (productsCount, availableFilters, collection id) lives
+ * in the framework's loader data, not in the store.
+ */
+interface CollectionState {
+  /** URL-safe slug identifying the collection (e.g. `"shoes"`). */
+  handle: string;
+  /** Active product filters, synced bidirectionally with URL params (`filter.*`). */
+  filters: ProductFilter[];
+  /** Storefront API sort key. `undefined` means the collection's default sort order. */
+  sortKey: ProductCollectionSortKeys | undefined;
+  /** When `true`, the sort direction is descending (maps to `sort_by` suffix `-descending`). */
+  reverse: boolean;
+  /** `"idle"` when browse state matches the last-loaded data, `"loading"` after a browse change before the framework fetch settles. */
+  status: "idle" | "loading";
+}
+/**
+ * Creates a blank {@link CollectionState} for the given collection handle.
+ * All browse fields start at their zero values.
+ *
+ * @param handle - URL-safe collection slug (e.g. `"shoes"`)
+ */
+declare function createInitialCollectionState(handle: string): CollectionState;
+//#endregion
+export { AvailableFilter, AvailableFilterValue, CollectionState, FilterPresentation, FilterType, createInitialCollectionState };
+//# sourceMappingURL=state.d.mts.map

package/dist/development/core/collection/state.mjs

@@ -0,0 +1,20 @@
+//#region src/core/collection/state.ts
+/**
+* Creates a blank {@link CollectionState} for the given collection handle.
+* All browse fields start at their zero values.
+*
+* @param handle - URL-safe collection slug (e.g. `"shoes"`)
+*/
+function createInitialCollectionState(handle) {
+	return {
+		handle,
+		filters: [],
+		sortKey: void 0,
+		reverse: false,
+		status: "idle"
+	};
+}
+
+//#endregion
+export { createInitialCollectionState };
+//# sourceMappingURL=state.mjs.map

package/dist/development/core/collection/state.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.mjs","names":[],"sources":["../../../../src/core/collection/state.ts"],"sourcesContent":["import type { ProductFilter } from \"../../../vendor/standard-events\";\nimport type { ProductCollectionSortKeys } from \"../../graphql/generated/storefront-api-types\";\n\nexport type { ProductCollectionSortKeys, ProductFilter };\n\n/** How a filter option is visually presented in the storefront UI. */\nexport type FilterPresentation = \"IMAGE\" | \"SWATCH\" | \"TEXT\";\n\n/** The input mechanism a filter uses — boolean toggle, multi-select list, or price slider. */\nexport type FilterType = \"BOOLEAN\" | \"LIST\" | \"PRICE_RANGE\" | (string & {});\n\ninterface BaseAvailableFilterValue {\n  /** Unique identifier for this filter value. */\n  id: string;\n  /** Human-readable label (e.g. \"Red\", \"Nike\", \"$50–$100\"). */\n  label: string;\n  /** Number of products matching this value in the current result set. */\n  count: number;\n  /** JSON-encoded `ProductFilter` input to apply this value. */\n  input: string;\n}\n\ntype PickIfPresent<TValue, TKey extends PropertyKey> = TKey extends keyof TValue\n  ? Pick<TValue, TKey>\n  : {};\n\n/**\n * A single selectable value within an {@link AvailableFilter}.\n *\n * Pass your Storefront API query value type as `TValue` to expose query-selected\n * visual fields such as `swatch`.\n */\nexport type AvailableFilterValue<\n  TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue,\n> = BaseAvailableFilterValue & PickIfPresent<TValue, \"swatch\">;\n\n/**\n * A filter facet available for the current collection, returned by the\n * Storefront API. Used to render filter UI (checkboxes, swatches, sliders).\n */\nexport interface AvailableFilter<\n  TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue,\n> {\n  id: string;\n  label: string;\n  type: FilterType;\n  presentation?: FilterPresentation | null;\n  values: AvailableFilterValue<TValue>[];\n}\n\n/**\n * Pure browse-intent state for a collection store. Represents what the user\n * wants to see (filters, sort), not what the server returned.\n *\n * Server response data (productsCount, availableFilters, collection id) lives\n * in the framework's loader data, not in the store.\n */\nexport interface CollectionState {\n  /** URL-safe slug identifying the collection (e.g. `\"shoes\"`). */\n  handle: string;\n\n  /** Active product filters, synced bidirectionally with URL params (`filter.*`). */\n  filters: ProductFilter[];\n  /** Storefront API sort key. `undefined` means the collection's default sort order. */\n  sortKey: ProductCollectionSortKeys | undefined;\n  /** When `true`, the sort direction is descending (maps to `sort_by` suffix `-descending`). */\n  reverse: boolean;\n  /** `\"idle\"` when browse state matches the last-loaded data, `\"loading\"` after a browse change before the framework fetch settles. */\n  status: \"idle\" | \"loading\";\n}\n\n/**\n * Creates a blank {@link CollectionState} for the given collection handle.\n * All browse fields start at their zero values.\n *\n * @param handle - URL-safe collection slug (e.g. `\"shoes\"`)\n */\nexport function createInitialCollectionState(handle: string): CollectionState {\n  return {\n    handle,\n    filters: [],\n    sortKey: undefined,\n    reverse: false,\n    status: \"idle\",\n  };\n}\n"],"mappings":";;;;;;;AA6EA,SAAgB,6BAA6B,QAAiC;AAC5E,QAAO;EACL;EACA,SAAS,EAAE;EACX,SAAS;EACT,SAAS;EACT,QAAQ;EACT"}

package/dist/development/core/collection/url.d.mts

@@ -0,0 +1,71 @@
+import { ProductCollectionSortKeys } from "../../graphql/generated/storefront-api-types.mjs";
+import { ProductFilter } from "../../vendor/standard-events.mjs";
+import { CollectionState } from "./state.mjs";
+
+//#region src/core/collection/url.d.ts
+/**
+ * Parsed collection URL parameters — the subset of {@link CollectionState}
+ * that is derived from the URL query string.
+ */
+interface CollectionParams {
+  filters: ProductFilter[];
+  sortKey: ProductCollectionSortKeys | undefined;
+  reverse: boolean;
+}
+/**
+ * Extracts collection state from URL search params.
+ *
+ * Handles Liquid-compatible filter keys (`filter.p.*`, `filter.v.*`)
+ * and the `sort_by` param (with optional `-descending`/`-ascending` suffix).
+ *
+ * @param searchParams - URL search params to parse
+ */
+declare function parseCollectionParams(searchParams: URLSearchParams): CollectionParams;
+/**
+ * Serializes collection state into URL search params using Liquid-compatible keys.
+ *
+ * Only emits store-owned keys (`filter.*`, `sort_by`).
+ * Omits `sort_by` when `sortKey` is `undefined` (collection default).
+ *
+ * @param state - The filter/sort slice of collection state
+ */
+declare function serializeCollectionParams(state: Pick<CollectionState, "filters" | "sortKey" | "reverse">): URLSearchParams;
+/** Normalizes a router search string for comparison (strips a leading `?`). */
+declare function normalizeCollectionSearch(search: string): string;
+/**
+ * Builds a URL query string with the given filter removed from the current params.
+ *
+ * Clears pagination cursors so the changed filter state starts from its first page.
+ * Returns `"?"` when removing the filter leaves no params. Useful for
+ * rendering "remove filter" links without updating store state.
+ */
+declare function getFilterRemovalUrl(currentParams: URLSearchParams, filter: ProductFilter): string;
+/**
+ * Converts a Storefront API sort key and direction into the Liquid-compatible
+ * `sort_by` param value (e.g. `"price-ascending"`, `"best-selling"`).
+ *
+ * Direction suffixes are only appended for sort keys that support them
+ * (`PRICE`, `TITLE`, `CREATED`, `ID`). Others (like `BEST_SELLING`) return
+ * the base value regardless of the `reverse` flag.
+ *
+ * @param sortKey - Storefront API `ProductCollectionSortKeys` enum value
+ * @param reverse - `true` for descending, `false` for ascending
+ */
+declare function getSortByValue(sortKey: ProductCollectionSortKeys, reverse: boolean): string;
+/**
+ * Parses a Liquid-compatible `sort_by` value back into the Storefront API
+ * sort key and direction. Inverse of {@link getSortByValue}.
+ *
+ * @param value - A `sort_by` param value (e.g. `"price-ascending"`, `"best-selling"`)
+ */
+declare function parseSortByValue(value: string): {
+  sortKey: ProductCollectionSortKeys | undefined;
+  reverse: boolean;
+};
+/** Compares two individual {@link ProductFilter} objects for semantic equality. */
+declare function filterEquals(a: ProductFilter, b: ProductFilter): boolean;
+/** Returns `true` when `input` (a Storefront API filter JSON string) matches an active filter. */
+declare function isFilterInputActive(activeFilters: ProductFilter[], input: string): boolean;
+//#endregion
+export { CollectionParams, filterEquals, getFilterRemovalUrl, getSortByValue, isFilterInputActive, normalizeCollectionSearch, parseCollectionParams, parseSortByValue, serializeCollectionParams };
+//# sourceMappingURL=url.d.mts.map

package/dist/development/core/collection/url.mjs

@@ -0,0 +1,376 @@
+//#region src/core/collection/url.ts
+const SORT_BY_DESCENDING_SUFFIX = "-descending";
+const SORT_BY_ASCENDING_SUFFIX = "-ascending";
+const PAGINATION_CURSOR_PARAMS = ["before", "after"];
+const SORT_KEY_TO_SORT_BY = {
+	BEST_SELLING: "best-selling",
+	CREATED: "created",
+	PRICE: "price",
+	TITLE: "title",
+	MANUAL: "manual",
+	ID: "id",
+	RELEVANCE: "relevance",
+	COLLECTION_DEFAULT: "collection-default"
+};
+const SORT_BY_TO_SORT_KEY = Object.fromEntries(Object.entries(SORT_KEY_TO_SORT_BY).map(([key, value]) => [value, key]));
+const STANDARD_EVENTS_COLLECTION_SORT_KEY = {
+	"best-selling": "BEST_SELLING",
+	"created-ascending": "CREATED",
+	"created-descending": "CREATED",
+	"price-ascending": "PRICE",
+	"price-descending": "PRICE",
+	"title-ascending": "TITLE",
+	"title-descending": "TITLE",
+	manual: "MANUAL"
+};
+/**
+* Extracts collection state from URL search params.
+*
+* Handles Liquid-compatible filter keys (`filter.p.*`, `filter.v.*`)
+* and the `sort_by` param (with optional `-descending`/`-ascending` suffix).
+*
+* @param searchParams - URL search params to parse
+*/
+function parseCollectionParams(searchParams) {
+	return {
+		filters: parseProductFilters(searchParams),
+		sortKey: parseCollectionSortKey(searchParams),
+		reverse: searchParams.get("sort_by")?.endsWith(SORT_BY_DESCENDING_SUFFIX) ?? false
+	};
+}
+/**
+* Serializes collection state into URL search params using Liquid-compatible keys.
+*
+* Only emits store-owned keys (`filter.*`, `sort_by`).
+* Omits `sort_by` when `sortKey` is `undefined` (collection default).
+*
+* @param state - The filter/sort slice of collection state
+*/
+function serializeCollectionParams(state) {
+	const params = new URLSearchParams();
+	for (const filter of state.filters) serializeFilter(params, filter);
+	if (state.sortKey) params.set("sort_by", getSortByValue(state.sortKey, state.reverse));
+	return params;
+}
+/** Returns `true` when the param key is owned by the collection store. */
+function isStoreOwnedParam(key) {
+	return key === "sort_by" || key.startsWith("filter.");
+}
+/** Normalizes a router search string for comparison (strips a leading `?`). */
+function normalizeCollectionSearch(search) {
+	return search.startsWith("?") ? search.slice(1) : search;
+}
+/**
+* Merges store-owned params from `state` into `existing`, preserving
+* unrelated keys (e.g. `grid`, `view`) already present in the URL. Collection
+* pagination cursors (`before`, `after`) are cleared so changed browse intent
+* starts from the first page.
+*/
+function mergeCollectionParams(existing, state) {
+	const merged = new URLSearchParams(existing);
+	for (const key of Array.from(merged.keys())) if (isStoreOwnedParam(key)) merged.delete(key);
+	clearPaginationCursors(merged);
+	for (const [key, value] of serializeCollectionParams(state)) merged.append(key, value);
+	return merged;
+}
+/** Returns `true` when two router search strings describe the same collection filters and sort. */
+function collectionSearchEqual(a, b) {
+	const parsedA = parseCollectionParams(new URLSearchParams(normalizeCollectionSearch(a)));
+	const parsedB = parseCollectionParams(new URLSearchParams(normalizeCollectionSearch(b)));
+	return parsedA.sortKey === parsedB.sortKey && parsedA.reverse === parsedB.reverse && filtersEqual(parsedA.filters, parsedB.filters);
+}
+/** Returns `true` when URL params and collection browse state describe the same filters and sort. */
+function collectionParamsMatchState(searchParams, state) {
+	const parsed = parseCollectionParams(searchParams);
+	return parsed.sortKey === state.sortKey && parsed.reverse === state.reverse && filtersEqual(parsed.filters, state.filters);
+}
+/**
+* Builds a URL query string with the given filter removed from the current params.
+*
+* Clears pagination cursors so the changed filter state starts from its first page.
+* Returns `"?"` when removing the filter leaves no params. Useful for
+* rendering "remove filter" links without updating store state.
+*/
+function getFilterRemovalUrl(currentParams, filter) {
+	const result = new URLSearchParams(currentParams);
+	removeFilterParams(result, filter);
+	clearPaginationCursors(result);
+	const serialized = result.toString();
+	return serialized ? `?${serialized}` : "?";
+}
+/** Returns `true` when the sort key supports ascending/descending direction suffixes. */
+function isDirectionalSortKey(sortKey) {
+	return sortKey === "PRICE" || sortKey === "TITLE" || sortKey === "CREATED" || sortKey === "ID";
+}
+/**
+* Converts a Storefront API sort key and direction into the Liquid-compatible
+* `sort_by` param value (e.g. `"price-ascending"`, `"best-selling"`).
+*
+* Direction suffixes are only appended for sort keys that support them
+* (`PRICE`, `TITLE`, `CREATED`, `ID`). Others (like `BEST_SELLING`) return
+* the base value regardless of the `reverse` flag.
+*
+* @param sortKey - Storefront API `ProductCollectionSortKeys` enum value
+* @param reverse - `true` for descending, `false` for ascending
+*/
+function getSortByValue(sortKey, reverse) {
+	const base = SORT_KEY_TO_SORT_BY[sortKey] ?? sortKey.toLowerCase();
+	if (!isDirectionalSortKey(sortKey)) return base;
+	return reverse ? `${base}-descending` : `${base}-ascending`;
+}
+/**
+* Parses a Liquid-compatible `sort_by` value back into the Storefront API
+* sort key and direction. Inverse of {@link getSortByValue}.
+*
+* @param value - A `sort_by` param value (e.g. `"price-ascending"`, `"best-selling"`)
+*/
+function parseSortByValue(value) {
+	if (value.endsWith(SORT_BY_DESCENDING_SUFFIX)) return {
+		sortKey: SORT_BY_TO_SORT_KEY[value.slice(0, -11)],
+		reverse: true
+	};
+	if (value.endsWith(SORT_BY_ASCENDING_SUFFIX)) return {
+		sortKey: SORT_BY_TO_SORT_KEY[value.slice(0, -10)],
+		reverse: false
+	};
+	return {
+		sortKey: SORT_BY_TO_SORT_KEY[value],
+		reverse: false
+	};
+}
+/**
+* Mirrors `parseProductFilters` from storefront-standard-events.
+*
+* Keep this local because Hydrogen only vendors Standard Events
+* declarations, so importing CollectionUpdateEvent would require runtime JS.
+*/
+function parseProductFilters(searchParams) {
+	const filters = [];
+	const price = {};
+	const minPrice = searchParams.get("filter.v.price.gte");
+	const maxPrice = searchParams.get("filter.v.price.lte");
+	if (minPrice) price.min = parseLocalizedNumber(minPrice);
+	if (maxPrice) price.max = parseLocalizedNumber(maxPrice);
+	if (price.min !== void 0 || price.max !== void 0) filters.push({ price });
+	const availability = searchParams.getAll("filter.v.availability");
+	const inStock = availability.includes("1");
+	const outOfStock = availability.includes("0");
+	if (inStock && !outOfStock) filters.push({ available: true });
+	if (outOfStock && !inStock) filters.push({ available: false });
+	for (const productType of searchParams.getAll("filter.p.product_type")) filters.push({ productType });
+	for (const productVendor of searchParams.getAll("filter.p.vendor")) filters.push({ productVendor });
+	for (const tag of searchParams.getAll("filter.p.tag")) filters.push({ tag });
+	for (const [key, value] of searchParams) {
+		let match;
+		if (match = key.match(/^filter\.v\.option\.(.+)$/)) {
+			filters.push({ variantOption: {
+				name: decodeFilterKeyPart(match[1]),
+				value
+			} });
+			continue;
+		}
+		if (match = key.match(/^filter\.p\.m\.([^.]+)\.(.+)$/)) {
+			filters.push({ productMetafield: {
+				namespace: decodeFilterKeyPart(match[1]),
+				key: decodeFilterKeyPart(match[2]),
+				value
+			} });
+			continue;
+		}
+		if (match = key.match(/^filter\.v\.m\.([^.]+)\.(.+)$/)) {
+			filters.push({ variantMetafield: {
+				namespace: decodeFilterKeyPart(match[1]),
+				key: decodeFilterKeyPart(match[2]),
+				value
+			} });
+			continue;
+		}
+		if (match = key.match(/^filter\.v\.t\.([^.]+)\.(.+)$/)) filters.push({ taxonomyMetafield: {
+			key: `${decodeFilterKeyPart(match[1])}.${decodeFilterKeyPart(match[2])}`,
+			value
+		} });
+	}
+	return filters;
+}
+/** Mirrors `getCollectionSortKey` from storefront-standard-events. */
+function parseCollectionSortKey(searchParams) {
+	const rawSortBy = searchParams.get("sort_by");
+	return rawSortBy ? STANDARD_EVENTS_COLLECTION_SORT_KEY[rawSortBy] : void 0;
+}
+function parseLocalizedNumber(value) {
+	try {
+		const locale = typeof window !== "undefined" ? window.Shopify?.locale : void 0;
+		const parts = new Intl.NumberFormat(locale ?? "en").formatToParts(1234.5);
+		const group = parts.find((part) => part.type === "group")?.value ?? ",";
+		const decimal = parts.find((part) => part.type === "decimal")?.value ?? ".";
+		const normalized = value.split(group).join("").replace(decimal, ".");
+		const number = Number(normalized);
+		if (!Number.isNaN(number)) return number;
+	} catch {}
+	return Number(value.replace(/[^\d.]/g, "")) || 0;
+}
+function decodeFilterKeyPart(value) {
+	return decodeURIComponent(value.replace(/\+/g, " "));
+}
+function getFilterParamEntries(filter) {
+	const entries = [];
+	if (filter.available != null) entries.push({
+		key: "filter.v.availability",
+		value: filter.available ? "1" : "0"
+	});
+	if (filter.price) {
+		if (filter.price.min != null) entries.push({
+			key: "filter.v.price.gte",
+			value: String(filter.price.min)
+		});
+		if (filter.price.max != null) entries.push({
+			key: "filter.v.price.lte",
+			value: String(filter.price.max)
+		});
+	}
+	if (filter.productType != null) entries.push({
+		key: "filter.p.product_type",
+		value: filter.productType
+	});
+	if (filter.productVendor != null) entries.push({
+		key: "filter.p.vendor",
+		value: filter.productVendor
+	});
+	if (filter.tag != null) entries.push({
+		key: "filter.p.tag",
+		value: filter.tag
+	});
+	if (filter.variantOption) entries.push({
+		key: `filter.v.option.${encodeURIComponent(filter.variantOption.name)}`,
+		value: filter.variantOption.value ?? ""
+	});
+	if (filter.productMetafield) {
+		const { namespace, key, value } = filter.productMetafield;
+		entries.push({
+			key: `filter.p.m.${encodeURIComponent(namespace)}.${encodeURIComponent(key)}`,
+			value: value ?? ""
+		});
+	}
+	if (filter.variantMetafield) {
+		const { namespace, key, value } = filter.variantMetafield;
+		entries.push({
+			key: `filter.v.m.${encodeURIComponent(namespace)}.${encodeURIComponent(key)}`,
+			value: value ?? ""
+		});
+	}
+	if (filter.taxonomyMetafield) {
+		const fullKey = filter.taxonomyMetafield.key;
+		const dotIdx = fullKey.indexOf(".");
+		const ns = dotIdx >= 0 ? fullKey.slice(0, dotIdx) : fullKey;
+		const k = dotIdx >= 0 ? fullKey.slice(dotIdx + 1) : "";
+		entries.push({
+			key: `filter.v.t.${encodeURIComponent(ns)}.${encodeURIComponent(k)}`,
+			value: filter.taxonomyMetafield.value
+		});
+	}
+	if (filter.category) entries.push({
+		key: "filter.p.category",
+		value: filter.category.id
+	});
+	return entries;
+}
+function serializeFilter(params, filter) {
+	for (const { key, value } of getFilterParamEntries(filter)) params.append(key, value);
+}
+function removeFilterParams(params, filter) {
+	for (const { key, value } of getFilterParamEntries(filter)) removeParamValue(params, key, value);
+}
+function clearPaginationCursors(params) {
+	for (const key of PAGINATION_CURSOR_PARAMS) params.delete(key);
+}
+/** Compares two individual {@link ProductFilter} objects for semantic equality. */
+function filterEquals(a, b) {
+	const kindA = filterKind(a);
+	if (kindA !== filterKind(b) || kindA == null) return false;
+	switch (kindA) {
+		case "tag": return a.tag === b.tag;
+		case "available": return a.available === b.available;
+		case "price": return priceRangeEquals(a.price, b.price);
+		case "productType": return a.productType === b.productType;
+		case "productVendor": return a.productVendor === b.productVendor;
+		case "variantOption": {
+			const aOpt = a.variantOption;
+			const bOpt = b.variantOption;
+			if (aOpt == null || bOpt == null) return false;
+			return aOpt.name === bOpt.name && (aOpt.value ?? "") === (bOpt.value ?? "");
+		}
+		case "productMetafield": {
+			const aMeta = a.productMetafield;
+			const bMeta = b.productMetafield;
+			if (aMeta == null || bMeta == null) return false;
+			return metafieldEquals(aMeta, bMeta);
+		}
+		case "variantMetafield": {
+			const aMeta = a.variantMetafield;
+			const bMeta = b.variantMetafield;
+			if (aMeta == null || bMeta == null) return false;
+			return metafieldEquals(aMeta, bMeta);
+		}
+		case "taxonomyMetafield": {
+			const aMeta = a.taxonomyMetafield;
+			const bMeta = b.taxonomyMetafield;
+			if (aMeta == null || bMeta == null) return false;
+			return aMeta.key === bMeta.key && aMeta.value === bMeta.value;
+		}
+		case "category": {
+			const aCat = a.category;
+			const bCat = b.category;
+			if (aCat == null || bCat == null) return false;
+			return aCat.id === bCat.id;
+		}
+	}
+}
+/** Returns `true` when `input` (a Storefront API filter JSON string) matches an active filter. */
+function isFilterInputActive(activeFilters, input) {
+	let parsed;
+	try {
+		parsed = JSON.parse(input);
+	} catch {
+		return false;
+	}
+	return activeFilters.some((filter) => filterEquals(filter, parsed));
+}
+function filterKind(filter) {
+	if (filter.tag != null) return "tag";
+	if (filter.available != null) return "available";
+	if (filter.price != null) return "price";
+	if (filter.productType != null) return "productType";
+	if (filter.productVendor != null) return "productVendor";
+	if (filter.variantOption != null) return "variantOption";
+	if (filter.productMetafield != null) return "productMetafield";
+	if (filter.variantMetafield != null) return "variantMetafield";
+	if (filter.taxonomyMetafield != null) return "taxonomyMetafield";
+	if (filter.category != null) return "category";
+	return null;
+}
+function priceRangeEquals(a, b) {
+	if (a == null || b == null) return a === b;
+	return a.min === b.min && a.max === b.max;
+}
+function metafieldEquals(a, b) {
+	return a.namespace === b.namespace && a.key === b.key && (a.value ?? "") === (b.value ?? "");
+}
+function filtersEqual(a, b) {
+	if (a.length !== b.length) return false;
+	const remaining = [...b];
+	for (const filter of a) {
+		const index = remaining.findIndex((candidate) => filterEquals(filter, candidate));
+		if (index === -1) return false;
+		remaining.splice(index, 1);
+	}
+	return true;
+}
+function removeParamValue(params, name, value) {
+	const remaining = params.getAll(name).filter((v) => v !== value);
+	params.delete(name);
+	for (const v of remaining) params.append(name, v);
+}
+
+//#endregion
+export { collectionParamsMatchState, collectionSearchEqual, filterEquals, getFilterRemovalUrl, getSortByValue, isDirectionalSortKey, isFilterInputActive, mergeCollectionParams, normalizeCollectionSearch, parseCollectionParams, parseSortByValue, serializeCollectionParams };
+//# sourceMappingURL=url.mjs.map