@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

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

@@ -3,25 +3,27 @@ import { ProductFilter } from "../../vendor/standard-events.mjs";
 import { CollectionState } from "./state.mjs";
 
 //#region src/core/collection/collection.d.ts
-/** Snapshot from the framework loader for a single collection fetch. */
+/** The collection handle and the search string that your loader fetched products for. */
 type CollectionData = {
-  /** URL-safe collection slug (e.g. `"shoes"`). */handle: string;
   /**
-   * Search string this data snapshot was fetched for (with or without leading `?`).
-   * Compared against live {@link CreateCollectionStoreOptions.urlSearch} before settling.
+   * Collection handle, such as `shoes`.
+   *
+   * On search pages, pass a handle such as `search:${term}` to keep separate filter and sort state for each search term. When the handle changes, the collection provider reads the filters and sort from the URL again.
+   */
+  handle: string;
+  /**
+   * Search string that your loader used for the Storefront API query, with or without a leading `?`.
+   *
+   * Pass the exact string. The status stays `loading` until this string and the URL search hold the same filters, sort key, and sort direction.
    */
   dataSearch: string;
 };
 /**
- * A reactive, framework-agnostic store for collection browse state.
+ * Holds the customer's filter and sort choices for a collection or search page, and reports when new results are loading.
  *
- * Manages filters and sorting — the user's *intent*. Server response
- * data (products, productsCount, availableFilters) lives in the framework's
- * loader data, not here.
+ * Each change updates the state right away and sets the status to `loading`. Your app then navigates, your loader fetches the new products, and you call `settle()` when the data arrives. The collection provider navigates and settles the store for you.
  *
- * Mutations are synchronous state changes that set `status: "loading"`.
- * The framework adapter navigates (URL change), the framework loader re-runs,
- * and the adapter calls {@link settle} when fresh data arrives.
+ * The store keeps the sort direction only for the price, title, created, and ID sort keys. For other sort keys, `reverse` reads `false`. The store keeps at most one availability filter. Adding a second availability filter removes both availability filters.
  *
  * @example
  * ```ts
@@ -35,104 +37,100 @@ type CollectionData = {
  * ```
  */
 type CollectionStore = {
-  /** Returns the current snapshot of collection browse state. */getState(): CollectionState;
+  /** Returns the current filter and sort state. */getState(): CollectionState;
   /**
-   * Registers a listener invoked on every state change. Returns an unsubscribe function.
-   * @param listener - Callback receiving the new state snapshot
+   * Calls the listener on every state change. Returns a function that unsubscribes the listener.
+   * @param listener - Callback that receives the new state.
    */
   subscribe(listener: (state: CollectionState) => void): () => void;
   /**
-   * Replaces the active product filters.
-   * Sets `status: "loading"` — call {@link settle} when the framework fetch completes.
+   * Replaces the active filters and sets the status to `loading`.
    */
   setFilters(filters: ProductFilter[]): void;
   /**
-   * Adds the filter if not active, removes it if already active.
-   * Sets `status: "loading"` — call {@link settle} when the framework fetch completes.
+   * Adds the filter when it's inactive and removes the filter when it's active, then sets the status to `loading`.
    */
   toggleFilter(filter: ProductFilter): void;
   /**
-   * Changes the sort order.
-   * Sets `status: "loading"` — call {@link settle} when the framework fetch completes.
+   * Changes the sort key and direction, then sets the status to `loading`.
+   * Omit `reverse` to sort in ascending order.
    */
   setSortKey(sortKey: ProductCollectionSortKeys, reverse?: boolean): void;
   /**
-   * Resets filters and sort to defaults.
-   * Sets `status: "loading"` — call {@link settle} when the framework fetch completes.
+   * Clears all filters, restores the collection's default sort, and sets the status to `loading`.
    */
   reset(): void;
   /**
-   * Returns `true` when URL params and current browse state describe the same filters and sort.
+   * Returns `true` when the URL search params hold the same filters and sort as the store.
    */
   matchesParams(searchParams: URLSearchParams): boolean;
   /**
-   * Applies URL search params to the store when they differ from current state.
-   * Used when the framework router reports an external URL change (back/forward).
+   * Updates the store from URL search params that differ from the current state.
+   * Call the method when the URL changes outside the store, such as on back or forward navigation. The method sets the status to `loading` and skips the browse change callback.
    */
   syncFromParams(searchParams: URLSearchParams): void;
   /**
-   * Signals that the framework fetch completed and fresh data is available.
-   * Resets `status` to `"idle"`.
+   * Sets the status to `idle`. Call the method when your loader returns the new products.
    */
   settle(): void;
   /**
-   * Serializes the store's current filter/sort state into URL search params.
-   * Only includes store-owned keys (`filter.*`, `sort_by`).
+   * Returns the filters and sort as URL search params.
+   * The result holds only the `filter.*` and `sort_by` keys.
    */
   serializeToParams(): URLSearchParams;
   /**
-   * Builds a URL string that removes the given filter from the current params.
-   * Useful for rendering "remove filter" links/buttons.
+   * Returns a query string with the store's filters and sort, minus the given filter.
+   * Use the query string in remove-filter links and buttons.
+   *
+   * The string starts with `?` and leaves out URL params that the store doesn't manage.
    */
   getFilterRemovalUrl(filter: ProductFilter): string;
   /**
-   * Parses `FormData` from the submitted form into collection params and applies them.
-   * Doesn't cancel the event: call `event.preventDefault()` first, or the browser
-   * submits the form natively and navigates away.
+   * Applies a submitted filter form to the store.
+   * The form's filter fields replace the active filters. The sort changes only when the form includes a `sort_by` field.
    *
-   * @throws {TypeError} If `event.target` is not an `HTMLFormElement`.
+   * Call `event.preventDefault()` first, or the browser submits the form and leaves the page. The method throws a `TypeError` when the event target isn't a form element.
    */
   handleFormSubmit(event: SubmitEvent): void;
   /**
-   * Replaces the callback that runs after user filter/sort changes. Framework
-   * adapters use this to trigger navigation. Pass `null` to remove.
+   * Sets the callback that runs after each filter or sort change. Navigate to the new URL in the callback.
+   * Pass `null` to remove the callback.
    */
   setOnBrowseChange(callback: (() => void) | null): void;
   /**
-   * Parses a Storefront API filter input JSON string (e.g. from
-   * `FilterValue.input`) and toggles the resulting filter.
-   * No-op if `input` is not valid JSON.
+   * Toggles the filter in a filter value's `input` JSON string from the Storefront API.
+   * The method does nothing when the string isn't valid JSON.
    */
   toggleFilterInput(input: string): void;
   /**
-   * Parses a Liquid-compatible `sort_by` value (e.g. `"price-ascending"`) and
-   * applies the corresponding sort key and direction.
+   * Applies the sort key and direction from a Liquid-compatible `sort_by` value, such as `price-ascending`.
+   * An unrecognized value sets the sort key to `COLLECTION_DEFAULT`.
    */
   setSortByValue(sortByValue: string): void;
 };
-/** Mutation methods exposed by the collection store. */
+/** Collection store methods that change the filters and sort. The `useCollectionActions` hook returns these methods. */
 type CollectionActions = Pick<CollectionStore, "setFilters" | "toggleFilter" | "toggleFilterInput" | "setSortKey" | "setSortByValue" | "reset" | "handleFormSubmit">;
-/** Options for creating a new {@link CollectionStore}. */
+/** Options for `createCollectionStore`. */
 type CreateCollectionStoreOptions = {
-  /** Collection metadata from the framework loader. */data: CollectionData;
+  /** The collection handle and the search string that your loader fetched products for. */data: CollectionData;
   /**
-   * Live URL search string from the framework router (with or without leading `?`).
-   * Falls back to `data.dataSearch` when omitted.
+   * Current URL search string from your router, with or without a leading `?`.
+   * Defaults to the `dataSearch` string from `data`.
    */
   urlSearch?: string;
   /**
-   * Called after user-initiated filter/sort changes.
-   * Framework adapters use this to trigger navigation. Not called by
-   * {@link CollectionStore.syncFromParams} or {@link CollectionStore.settle}.
+   * Runs after each filter or sort change from a store method. Navigate to the new URL in the callback.
+   * Syncing from URL params and settling the store don't run the callback.
    */
   onBrowseChange?: () => void;
 };
 /**
- * Creates a new collection store for the given collection handle.
+ * Creates a store that holds the customer's filter and sort choices for one collection. Your loader fetches the products.
  *
- * The store manages browse intent (filters, sort) only.
- * Server response data lives in the framework's loader.
+ * The store reads its starting filters and sort from `urlSearch`, or from `dataSearch` when you omit `urlSearch`. In React, use `CollectionProvider`, which creates the store for you and keeps the store in sync with the URL.
  *
+ * @param options The collection data, the current URL search string, and the browse change callback.
+ * @returns A store with methods that change the filters and sort and report the loading status.
  * @example
  * ```ts
  * const store = createCollectionStore({
@@ -143,6 +141,7 @@ type CreateCollectionStoreOptions = {
  *
  * store.subscribe((state) => renderFilters(state.filters));
  * ```
+ * @publicDocs
  */
 declare function createCollectionStore(options: CreateCollectionStoreOptions): CollectionStore;
 //#endregion

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

@@ -4,11 +4,12 @@ import { collectionParamsMatchState, filterEquals, getFilterRemovalUrl, isDirect
 
 //#region src/core/collection/collection.ts
 /**
-* Creates a new collection store for the given collection handle.
+* Creates a store that holds the customer's filter and sort choices for one collection. Your loader fetches the products.
 *
-* The store manages browse intent (filters, sort) only.
-* Server response data lives in the framework's loader.
+* The store reads its starting filters and sort from `urlSearch`, or from `dataSearch` when you omit `urlSearch`. In React, use `CollectionProvider`, which creates the store for you and keeps the store in sync with the URL.
 *
+* @param options The collection data, the current URL search string, and the browse change callback.
+* @returns A store with methods that change the filters and sort and report the loading status.
 * @example
 * ```ts
 * const store = createCollectionStore({
@@ -19,6 +20,7 @@ import { collectionParamsMatchState, filterEquals, getFilterRemovalUrl, isDirect
 *
 * store.subscribe((state) => renderFilters(state.filters));
 * ```
+* @publicDocs
 */
 function createCollectionStore(options) {
 	const context = {

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

@@ -1 +1 @@
-{"version":3,"file":"collection.mjs","names":[],"sources":["../../../../src/core/collection/collection.ts"],"sourcesContent":["import type { ProductCollectionSortKeys } from \"../../graphql/generated/storefront-api-types\";\nimport { createObservable } from \"../observable\";\nimport type { CollectionState, ProductFilter } from \"./state\";\nimport { createInitialCollectionState } from \"./state\";\nimport {\n  collectionParamsMatchState,\n  filterEquals,\n  getFilterRemovalUrl,\n  isDirectionalSortKey,\n  parseCollectionParams,\n  parseSortByValue,\n  serializeCollectionParams,\n} from \"./url\";\n\n/** Snapshot from the framework loader for a single collection fetch. */\nexport type CollectionData = {\n  /** URL-safe collection slug (e.g. `\"shoes\"`). */\n  handle: string;\n  /**\n   * Search string this data snapshot was fetched for (with or without leading `?`).\n   * Compared against live {@link CreateCollectionStoreOptions.urlSearch} before settling.\n   */\n  dataSearch: string;\n};\n\n/**\n * A reactive, framework-agnostic store for collection browse state.\n *\n * Manages filters and sorting — the user's *intent*. Server response\n * data (products, productsCount, availableFilters) lives in the framework's\n * loader data, not here.\n *\n * Mutations are synchronous state changes that set `status: \"loading\"`.\n * The framework adapter navigates (URL change), the framework loader re-runs,\n * and the adapter calls {@link settle} when fresh data arrives.\n *\n * @example\n * ```ts\n * const store = createCollectionStore({\n *   data: { handle: \"shoes\", dataSearch: \"\" },\n * });\n *\n * store.setFilters([{ tag: \"sale\" }]); // status → \"loading\"\n * // ...framework fetches...\n * store.settle(); // status → \"idle\"\n * ```\n */\nexport type CollectionStore = {\n  /** Returns the current snapshot of collection browse state. */\n  getState(): CollectionState;\n\n  /**\n   * Registers a listener invoked on every state change. Returns an unsubscribe function.\n   * @param listener - Callback receiving the new state snapshot\n   */\n  subscribe(listener: (state: CollectionState) => void): () => void;\n\n  /**\n   * Replaces the active product filters.\n   * Sets `status: \"loading\"` — call {@link settle} when the framework fetch completes.\n   */\n  setFilters(filters: ProductFilter[]): void;\n\n  /**\n   * Adds the filter if not active, removes it if already active.\n   * Sets `status: \"loading\"` — call {@link settle} when the framework fetch completes.\n   */\n  toggleFilter(filter: ProductFilter): void;\n\n  /**\n   * Changes the sort order.\n   * Sets `status: \"loading\"` — call {@link settle} when the framework fetch completes.\n   */\n  setSortKey(sortKey: ProductCollectionSortKeys, reverse?: boolean): void;\n\n  /**\n   * Resets filters and sort to defaults.\n   * Sets `status: \"loading\"` — call {@link settle} when the framework fetch completes.\n   */\n  reset(): void;\n\n  /**\n   * Returns `true` when URL params and current browse state describe the same filters and sort.\n   */\n  matchesParams(searchParams: URLSearchParams): boolean;\n\n  /**\n   * Applies URL search params to the store when they differ from current state.\n   * Used when the framework router reports an external URL change (back/forward).\n   */\n  syncFromParams(searchParams: URLSearchParams): void;\n\n  /**\n   * Signals that the framework fetch completed and fresh data is available.\n   * Resets `status` to `\"idle\"`.\n   */\n  settle(): void;\n\n  /**\n   * Serializes the store's current filter/sort state into URL search params.\n   * Only includes store-owned keys (`filter.*`, `sort_by`).\n   */\n  serializeToParams(): URLSearchParams;\n\n  /**\n   * Builds a URL string that removes the given filter from the current params.\n   * Useful for rendering \"remove filter\" links/buttons.\n   */\n  getFilterRemovalUrl(filter: ProductFilter): string;\n\n  /**\n   * Parses `FormData` from the submitted form into collection params and applies them.\n   * Doesn't cancel the event: call `event.preventDefault()` first, or the browser\n   * submits the form natively and navigates away.\n   *\n   * @throws {TypeError} If `event.target` is not an `HTMLFormElement`.\n   */\n  handleFormSubmit(event: SubmitEvent): void;\n\n  /**\n   * Replaces the callback that runs after user filter/sort changes. Framework\n   * adapters use this to trigger navigation. Pass `null` to remove.\n   */\n  setOnBrowseChange(callback: (() => void) | null): void;\n\n  /**\n   * Parses a Storefront API filter input JSON string (e.g. from\n   * `FilterValue.input`) and toggles the resulting filter.\n   * No-op if `input` is not valid JSON.\n   */\n  toggleFilterInput(input: string): void;\n\n  /**\n   * Parses a Liquid-compatible `sort_by` value (e.g. `\"price-ascending\"`) and\n   * applies the corresponding sort key and direction.\n   */\n  setSortByValue(sortByValue: string): void;\n};\n\n/** Mutation methods exposed by the collection store. */\nexport type CollectionActions = Pick<\n  CollectionStore,\n  | \"setFilters\"\n  | \"toggleFilter\"\n  | \"toggleFilterInput\"\n  | \"setSortKey\"\n  | \"setSortByValue\"\n  | \"reset\"\n  | \"handleFormSubmit\"\n>;\n\n/** Options for creating a new {@link CollectionStore}. */\nexport type CreateCollectionStoreOptions = {\n  /** Collection metadata from the framework loader. */\n  data: CollectionData;\n  /**\n   * Live URL search string from the framework router (with or without leading `?`).\n   * Falls back to `data.dataSearch` when omitted.\n   */\n  urlSearch?: string;\n  /**\n   * Called after user-initiated filter/sort changes.\n   * Framework adapters use this to trigger navigation. Not called by\n   * {@link CollectionStore.syncFromParams} or {@link CollectionStore.settle}.\n   */\n  onBrowseChange?: () => void;\n};\n\ntype CollectionStoreContext = {\n  observable: ReturnType<typeof createObservable<CollectionState>>;\n  handle: string;\n  onBrowseChange: (() => void) | null;\n};\n\n/**\n * Creates a new collection store for the given collection handle.\n *\n * The store manages browse intent (filters, sort) only.\n * Server response data lives in the framework's loader.\n *\n * @example\n * ```ts\n * const store = createCollectionStore({\n *   data: loaderData.collection,\n *   urlSearch: window.location.search,\n *   onBrowseChange: () => navigate({ search: store.serializeToParams().toString() }),\n * });\n *\n * store.subscribe((state) => renderFilters(state.filters));\n * ```\n */\nexport function createCollectionStore(options: CreateCollectionStoreOptions): CollectionStore {\n  const initialState = buildInitialState(options);\n\n  const context: CollectionStoreContext = {\n    observable: createObservable<CollectionState>(initialState),\n    handle: options.data.handle,\n    onBrowseChange: options.onBrowseChange ?? null,\n  };\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    setFilters: (filters) => applyBrowseChange(context, { filters: normalizeFilters(filters) }),\n    toggleFilter: (filter) => toggleFilter(context, filter),\n    setSortKey: (sortKey, reverse) =>\n      applyBrowseChange(context, { sortKey, reverse: reverse ?? false }),\n    reset: () => resetStore(context),\n    matchesParams: (searchParams) => matchesParams(context, searchParams),\n    syncFromParams: (searchParams) => syncFromParams(context, searchParams),\n    settle: () => settleStore(context),\n    serializeToParams: () => serializeCollectionParams(context.observable.state),\n    getFilterRemovalUrl: (filter) =>\n      getFilterRemovalUrl(serializeCollectionParams(context.observable.state), filter),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n    setOnBrowseChange: (callback) => {\n      context.onBrowseChange = callback;\n    },\n    toggleFilterInput: (input) => toggleFilterInput(context, input),\n    setSortByValue: (sortByValue) => setSortByValue(context, sortByValue),\n  };\n}\n\nfunction buildInitialState(options: CreateCollectionStoreOptions): CollectionState {\n  const base = createInitialCollectionState(options.data.handle);\n\n  const search = options.urlSearch ?? options.data.dataSearch;\n  if (search) {\n    const parsed = parseCollectionParams(new URLSearchParams(search));\n    base.filters = parsed.filters;\n    base.sortKey = parsed.sortKey;\n    base.reverse = normalizeReverse(parsed.sortKey, parsed.reverse);\n  }\n\n  return base;\n}\n\ntype BrowseChange = Partial<Pick<CollectionState, \"filters\" | \"sortKey\" | \"reverse\">>;\n\n/**\n * Drops `reverse` for sort keys that do not support direction.\n * Only `PRICE`, `TITLE`, `CREATED`, and `ID` honor ascending/descending.\n *\n * @example normalizeReverse(\"BEST_SELLING\", true) // → false\n * @example normalizeReverse(\"PRICE\", true) // → true\n */\nfunction normalizeReverse(\n  sortKey: ProductCollectionSortKeys | undefined,\n  reverse: boolean,\n): boolean {\n  if (!sortKey || !isDirectionalSortKey(sortKey)) return false;\n  return reverse;\n}\n\nfunction applyBrowseChange(\n  context: CollectionStoreContext,\n  change: BrowseChange,\n  notify = true,\n): void {\n  context.observable.setState((prev) => {\n    const merged = { ...prev, ...change, status: \"loading\" as const };\n    merged.reverse = normalizeReverse(merged.sortKey, merged.reverse);\n    return merged;\n  });\n  if (notify) {\n    context.onBrowseChange?.();\n  }\n}\n\nfunction toggleFilter(context: CollectionStoreContext, filter: ProductFilter): void {\n  const current = context.observable.state.filters;\n  const isActive = current.some((f) => filterEquals(f, filter));\n\n  const next = isActive\n    ? current.filter((f) => !filterEquals(f, filter))\n    : normalizeFilters([...current, filter]);\n\n  applyBrowseChange(context, { filters: next });\n}\n\nfunction normalizeFilters(filters: ProductFilter[]): ProductFilter[] {\n  const normalized: ProductFilter[] = [];\n\n  for (const filter of filters) {\n    if (filter.available != null) {\n      // Availability is a single boolean facet. Duplicate availability params\n      // (filter.v.availability=1&filter.v.availability=0) mean no filter, so\n      // keeping both values here prevents the provider from settling navigation.\n      const existingAvailabilityIndex = normalized.findIndex((candidate) => {\n        return candidate.available != null;\n      });\n\n      if (existingAvailabilityIndex !== -1) {\n        normalized.splice(existingAvailabilityIndex, 1);\n        continue;\n      }\n    }\n\n    normalized.push(filter);\n  }\n\n  return normalized;\n}\n\nfunction resetStore(context: CollectionStoreContext): void {\n  const initial = createInitialCollectionState(context.handle);\n  applyBrowseChange(context, {\n    filters: initial.filters,\n    sortKey: initial.sortKey,\n    reverse: initial.reverse,\n  });\n}\n\nfunction matchesParams(context: CollectionStoreContext, searchParams: URLSearchParams): boolean {\n  return collectionParamsMatchState(searchParams, context.observable.state);\n}\n\nfunction syncFromParams(context: CollectionStoreContext, searchParams: URLSearchParams): void {\n  if (matchesParams(context, searchParams)) return;\n\n  const parsed = parseCollectionParams(searchParams);\n\n  // URL caught up to an in-flight browse change — align state without re-entering loading.\n  if (context.observable.state.status === \"loading\") {\n    context.observable.setState((prev) => ({\n      ...prev,\n      filters: parsed.filters,\n      sortKey: parsed.sortKey,\n      reverse: normalizeReverse(parsed.sortKey, parsed.reverse),\n      status: \"loading\",\n    }));\n    return;\n  }\n\n  /**\n   * URL already changes, so we don't need to notify to call onBrowseChange\n   * again which would cause a double navigate.\n   */\n  applyBrowseChange(\n    context,\n    {\n      filters: parsed.filters,\n      sortKey: parsed.sortKey,\n      reverse: parsed.reverse,\n    },\n    false,\n  );\n}\n\nfunction settleStore(context: CollectionStoreContext): void {\n  context.observable.setState((prev) => {\n    if (prev.status === \"idle\") return prev;\n    return { ...prev, status: \"idle\" };\n  });\n}\n\nfunction handleFormSubmit(context: CollectionStoreContext, event: SubmitEvent): void {\n  if (!(event.target instanceof HTMLFormElement)) {\n    throw new TypeError(`Expected event.target to be an HTMLFormElement, got ${event.target}`);\n  }\n\n  const formData = new FormData(event.target);\n  const formParams = new URLSearchParams();\n\n  for (const [key, value] of formData.entries()) {\n    if (typeof value === \"string\") {\n      formParams.append(key, value);\n    }\n  }\n\n  const parsed = parseCollectionParams(formParams);\n\n  const change: BrowseChange = {\n    filters: normalizeFilters(parsed.filters),\n  };\n\n  if (formParams.has(\"sort_by\")) {\n    change.sortKey = parsed.sortKey;\n    change.reverse = parsed.reverse;\n  }\n\n  applyBrowseChange(context, change);\n}\n\nfunction toggleFilterInput(context: CollectionStoreContext, input: string): void {\n  let parsed: ProductFilter;\n  try {\n    parsed = JSON.parse(input) as ProductFilter;\n  } catch {\n    return;\n  }\n  toggleFilter(context, parsed);\n}\n\nfunction setSortByValue(context: CollectionStoreContext, sortByValue: string): void {\n  const { sortKey, reverse } = parseSortByValue(sortByValue);\n  applyBrowseChange(context, {\n    sortKey: sortKey ?? \"COLLECTION_DEFAULT\",\n    reverse: reverse ?? false,\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"collection.mjs","names":[],"sources":["../../../../src/core/collection/collection.ts"],"sourcesContent":["import type { ProductCollectionSortKeys } from \"../../graphql/generated/storefront-api-types\";\nimport { createObservable } from \"../observable\";\nimport type { CollectionState, ProductFilter } from \"./state\";\nimport { createInitialCollectionState } from \"./state\";\nimport {\n  collectionParamsMatchState,\n  filterEquals,\n  getFilterRemovalUrl,\n  isDirectionalSortKey,\n  parseCollectionParams,\n  parseSortByValue,\n  serializeCollectionParams,\n} from \"./url\";\n\n/** The collection handle and the search string that your loader fetched products for. */\nexport type CollectionData = {\n  /**\n   * Collection handle, such as `shoes`.\n   *\n   * On search pages, pass a handle such as `search:${term}` to keep separate filter and sort state for each search term. When the handle changes, the collection provider reads the filters and sort from the URL again.\n   */\n  handle: string;\n  /**\n   * Search string that your loader used for the Storefront API query, with or without a leading `?`.\n   *\n   * Pass the exact string. The status stays `loading` until this string and the URL search hold the same filters, sort key, and sort direction.\n   */\n  dataSearch: string;\n};\n\n/**\n * Holds the customer's filter and sort choices for a collection or search page, and reports when new results are loading.\n *\n * Each change updates the state right away and sets the status to `loading`. Your app then navigates, your loader fetches the new products, and you call `settle()` when the data arrives. The collection provider navigates and settles the store for you.\n *\n * The store keeps the sort direction only for the price, title, created, and ID sort keys. For other sort keys, `reverse` reads `false`. The store keeps at most one availability filter. Adding a second availability filter removes both availability filters.\n *\n * @example\n * ```ts\n * const store = createCollectionStore({\n *   data: { handle: \"shoes\", dataSearch: \"\" },\n * });\n *\n * store.setFilters([{ tag: \"sale\" }]); // status → \"loading\"\n * // ...framework fetches...\n * store.settle(); // status → \"idle\"\n * ```\n */\nexport type CollectionStore = {\n  /** Returns the current filter and sort state. */\n  getState(): CollectionState;\n\n  /**\n   * Calls the listener on every state change. Returns a function that unsubscribes the listener.\n   * @param listener - Callback that receives the new state.\n   */\n  subscribe(listener: (state: CollectionState) => void): () => void;\n\n  /**\n   * Replaces the active filters and sets the status to `loading`.\n   */\n  setFilters(filters: ProductFilter[]): void;\n\n  /**\n   * Adds the filter when it's inactive and removes the filter when it's active, then sets the status to `loading`.\n   */\n  toggleFilter(filter: ProductFilter): void;\n\n  /**\n   * Changes the sort key and direction, then sets the status to `loading`.\n   * Omit `reverse` to sort in ascending order.\n   */\n  setSortKey(sortKey: ProductCollectionSortKeys, reverse?: boolean): void;\n\n  /**\n   * Clears all filters, restores the collection's default sort, and sets the status to `loading`.\n   */\n  reset(): void;\n\n  /**\n   * Returns `true` when the URL search params hold the same filters and sort as the store.\n   */\n  matchesParams(searchParams: URLSearchParams): boolean;\n\n  /**\n   * Updates the store from URL search params that differ from the current state.\n   * Call the method when the URL changes outside the store, such as on back or forward navigation. The method sets the status to `loading` and skips the browse change callback.\n   */\n  syncFromParams(searchParams: URLSearchParams): void;\n\n  /**\n   * Sets the status to `idle`. Call the method when your loader returns the new products.\n   */\n  settle(): void;\n\n  /**\n   * Returns the filters and sort as URL search params.\n   * The result holds only the `filter.*` and `sort_by` keys.\n   */\n  serializeToParams(): URLSearchParams;\n\n  /**\n   * Returns a query string with the store's filters and sort, minus the given filter.\n   * Use the query string in remove-filter links and buttons.\n   *\n   * The string starts with `?` and leaves out URL params that the store doesn't manage.\n   */\n  getFilterRemovalUrl(filter: ProductFilter): string;\n\n  /**\n   * Applies a submitted filter form to the store.\n   * The form's filter fields replace the active filters. The sort changes only when the form includes a `sort_by` field.\n   *\n   * Call `event.preventDefault()` first, or the browser submits the form and leaves the page. The method throws a `TypeError` when the event target isn't a form element.\n   */\n  handleFormSubmit(event: SubmitEvent): void;\n\n  /**\n   * Sets the callback that runs after each filter or sort change. Navigate to the new URL in the callback.\n   * Pass `null` to remove the callback.\n   */\n  setOnBrowseChange(callback: (() => void) | null): void;\n\n  /**\n   * Toggles the filter in a filter value's `input` JSON string from the Storefront API.\n   * The method does nothing when the string isn't valid JSON.\n   */\n  toggleFilterInput(input: string): void;\n\n  /**\n   * Applies the sort key and direction from a Liquid-compatible `sort_by` value, such as `price-ascending`.\n   * An unrecognized value sets the sort key to `COLLECTION_DEFAULT`.\n   */\n  setSortByValue(sortByValue: string): void;\n};\n\n/** Collection store methods that change the filters and sort. The `useCollectionActions` hook returns these methods. */\nexport type CollectionActions = Pick<\n  CollectionStore,\n  | \"setFilters\"\n  | \"toggleFilter\"\n  | \"toggleFilterInput\"\n  | \"setSortKey\"\n  | \"setSortByValue\"\n  | \"reset\"\n  | \"handleFormSubmit\"\n>;\n\n/** Options for `createCollectionStore`. */\nexport type CreateCollectionStoreOptions = {\n  /** The collection handle and the search string that your loader fetched products for. */\n  data: CollectionData;\n  /**\n   * Current URL search string from your router, with or without a leading `?`.\n   * Defaults to the `dataSearch` string from `data`.\n   */\n  urlSearch?: string;\n  /**\n   * Runs after each filter or sort change from a store method. Navigate to the new URL in the callback.\n   * Syncing from URL params and settling the store don't run the callback.\n   */\n  onBrowseChange?: () => void;\n};\n\ntype CollectionStoreContext = {\n  observable: ReturnType<typeof createObservable<CollectionState>>;\n  handle: string;\n  onBrowseChange: (() => void) | null;\n};\n\n/**\n * Creates a store that holds the customer's filter and sort choices for one collection. Your loader fetches the products.\n *\n * The store reads its starting filters and sort from `urlSearch`, or from `dataSearch` when you omit `urlSearch`. In React, use `CollectionProvider`, which creates the store for you and keeps the store in sync with the URL.\n *\n * @param options The collection data, the current URL search string, and the browse change callback.\n * @returns A store with methods that change the filters and sort and report the loading status.\n * @example\n * ```ts\n * const store = createCollectionStore({\n *   data: loaderData.collection,\n *   urlSearch: window.location.search,\n *   onBrowseChange: () => navigate({ search: store.serializeToParams().toString() }),\n * });\n *\n * store.subscribe((state) => renderFilters(state.filters));\n * ```\n * @publicDocs\n */\nexport function createCollectionStore(options: CreateCollectionStoreOptions): CollectionStore {\n  const initialState = buildInitialState(options);\n\n  const context: CollectionStoreContext = {\n    observable: createObservable<CollectionState>(initialState),\n    handle: options.data.handle,\n    onBrowseChange: options.onBrowseChange ?? null,\n  };\n\n  return {\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    setFilters: (filters) => applyBrowseChange(context, { filters: normalizeFilters(filters) }),\n    toggleFilter: (filter) => toggleFilter(context, filter),\n    setSortKey: (sortKey, reverse) =>\n      applyBrowseChange(context, { sortKey, reverse: reverse ?? false }),\n    reset: () => resetStore(context),\n    matchesParams: (searchParams) => matchesParams(context, searchParams),\n    syncFromParams: (searchParams) => syncFromParams(context, searchParams),\n    settle: () => settleStore(context),\n    serializeToParams: () => serializeCollectionParams(context.observable.state),\n    getFilterRemovalUrl: (filter) =>\n      getFilterRemovalUrl(serializeCollectionParams(context.observable.state), filter),\n    handleFormSubmit: (event) => handleFormSubmit(context, event),\n    setOnBrowseChange: (callback) => {\n      context.onBrowseChange = callback;\n    },\n    toggleFilterInput: (input) => toggleFilterInput(context, input),\n    setSortByValue: (sortByValue) => setSortByValue(context, sortByValue),\n  };\n}\n\nfunction buildInitialState(options: CreateCollectionStoreOptions): CollectionState {\n  const base = createInitialCollectionState(options.data.handle);\n\n  const search = options.urlSearch ?? options.data.dataSearch;\n  if (search) {\n    const parsed = parseCollectionParams(new URLSearchParams(search));\n    base.filters = parsed.filters;\n    base.sortKey = parsed.sortKey;\n    base.reverse = normalizeReverse(parsed.sortKey, parsed.reverse);\n  }\n\n  return base;\n}\n\ntype BrowseChange = Partial<Pick<CollectionState, \"filters\" | \"sortKey\" | \"reverse\">>;\n\n/**\n * Drops `reverse` for sort keys that do not support direction.\n * Only `PRICE`, `TITLE`, `CREATED`, and `ID` honor ascending/descending.\n *\n * @example normalizeReverse(\"BEST_SELLING\", true) // → false\n * @example normalizeReverse(\"PRICE\", true) // → true\n */\nfunction normalizeReverse(\n  sortKey: ProductCollectionSortKeys | undefined,\n  reverse: boolean,\n): boolean {\n  if (!sortKey || !isDirectionalSortKey(sortKey)) return false;\n  return reverse;\n}\n\nfunction applyBrowseChange(\n  context: CollectionStoreContext,\n  change: BrowseChange,\n  notify = true,\n): void {\n  context.observable.setState((prev) => {\n    const merged = { ...prev, ...change, status: \"loading\" as const };\n    merged.reverse = normalizeReverse(merged.sortKey, merged.reverse);\n    return merged;\n  });\n  if (notify) {\n    context.onBrowseChange?.();\n  }\n}\n\nfunction toggleFilter(context: CollectionStoreContext, filter: ProductFilter): void {\n  const current = context.observable.state.filters;\n  const isActive = current.some((f) => filterEquals(f, filter));\n\n  const next = isActive\n    ? current.filter((f) => !filterEquals(f, filter))\n    : normalizeFilters([...current, filter]);\n\n  applyBrowseChange(context, { filters: next });\n}\n\nfunction normalizeFilters(filters: ProductFilter[]): ProductFilter[] {\n  const normalized: ProductFilter[] = [];\n\n  for (const filter of filters) {\n    if (filter.available != null) {\n      // Availability is a single boolean facet. Duplicate availability params\n      // (filter.v.availability=1&filter.v.availability=0) mean no filter, so\n      // keeping both values here prevents the provider from settling navigation.\n      const existingAvailabilityIndex = normalized.findIndex((candidate) => {\n        return candidate.available != null;\n      });\n\n      if (existingAvailabilityIndex !== -1) {\n        normalized.splice(existingAvailabilityIndex, 1);\n        continue;\n      }\n    }\n\n    normalized.push(filter);\n  }\n\n  return normalized;\n}\n\nfunction resetStore(context: CollectionStoreContext): void {\n  const initial = createInitialCollectionState(context.handle);\n  applyBrowseChange(context, {\n    filters: initial.filters,\n    sortKey: initial.sortKey,\n    reverse: initial.reverse,\n  });\n}\n\nfunction matchesParams(context: CollectionStoreContext, searchParams: URLSearchParams): boolean {\n  return collectionParamsMatchState(searchParams, context.observable.state);\n}\n\nfunction syncFromParams(context: CollectionStoreContext, searchParams: URLSearchParams): void {\n  if (matchesParams(context, searchParams)) return;\n\n  const parsed = parseCollectionParams(searchParams);\n\n  // URL caught up to an in-flight browse change — align state without re-entering loading.\n  if (context.observable.state.status === \"loading\") {\n    context.observable.setState((prev) => ({\n      ...prev,\n      filters: parsed.filters,\n      sortKey: parsed.sortKey,\n      reverse: normalizeReverse(parsed.sortKey, parsed.reverse),\n      status: \"loading\",\n    }));\n    return;\n  }\n\n  /**\n   * URL already changes, so we don't need to notify to call onBrowseChange\n   * again which would cause a double navigate.\n   */\n  applyBrowseChange(\n    context,\n    {\n      filters: parsed.filters,\n      sortKey: parsed.sortKey,\n      reverse: parsed.reverse,\n    },\n    false,\n  );\n}\n\nfunction settleStore(context: CollectionStoreContext): void {\n  context.observable.setState((prev) => {\n    if (prev.status === \"idle\") return prev;\n    return { ...prev, status: \"idle\" };\n  });\n}\n\nfunction handleFormSubmit(context: CollectionStoreContext, event: SubmitEvent): void {\n  if (!(event.target instanceof HTMLFormElement)) {\n    throw new TypeError(`Expected event.target to be an HTMLFormElement, got ${event.target}`);\n  }\n\n  const formData = new FormData(event.target);\n  const formParams = new URLSearchParams();\n\n  for (const [key, value] of formData.entries()) {\n    if (typeof value === \"string\") {\n      formParams.append(key, value);\n    }\n  }\n\n  const parsed = parseCollectionParams(formParams);\n\n  const change: BrowseChange = {\n    filters: normalizeFilters(parsed.filters),\n  };\n\n  if (formParams.has(\"sort_by\")) {\n    change.sortKey = parsed.sortKey;\n    change.reverse = parsed.reverse;\n  }\n\n  applyBrowseChange(context, change);\n}\n\nfunction toggleFilterInput(context: CollectionStoreContext, input: string): void {\n  let parsed: ProductFilter;\n  try {\n    parsed = JSON.parse(input) as ProductFilter;\n  } catch {\n    return;\n  }\n  toggleFilter(context, parsed);\n}\n\nfunction setSortByValue(context: CollectionStoreContext, sortByValue: string): void {\n  const { sortKey, reverse } = parseSortByValue(sortByValue);\n  applyBrowseChange(context, {\n    sortKey: sortKey ?? \"COLLECTION_DEFAULT\",\n    reverse: reverse ?? false,\n  });\n}\n"],"mappings":"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"}

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

@@ -2,38 +2,45 @@ import { CollectionStore } from "./collection.mjs";
 
 //#region src/core/collection/reconciler.d.ts
 /**
- * Adapter-supplied hooks that let the reconciler read framework state and
- * push navigation side-effects without depending on any specific framework.
+ * Functions that connect a collection reconciler to your router and your collection store.
  */
 type ReconcilerCallbacks = {
-  /** Returns the current collection store instance. */getStore: () => CollectionStore; /** Reads the live URL search string from the framework router. */
-  readUrlSearch: () => string; /** Delivers a serialized search string for the framework adapter to handle. */
+  /** Returns the collection store. */getStore: () => CollectionStore; /** Returns the current URL search string from your router. */
+  readUrlSearch: () => string; /** Navigates your router to the search string. The string starts with `?`, or is empty when no params remain. */
   emitChange: (searchString: string) => void;
 };
 /**
- * State machine that keeps the URL, server data, and `CollectionStore` in
- * sync during browse-change chains. Created by `createCollectionReconciler`.
+ * Keeps the URL, your loader data, and a collection store in sync while the customer changes filters and sort.
  */
 type CollectionReconciler = {
   /**
-   * URL ↔ store reconciliation state machine. Call whenever `urlSearch` or
-   * `dataSearch` changes. Store changes go through
-   * {@link CollectionReconciler.handleBrowseChange} instead.
+   * Brings the store in line with the URL. Call the method each time the URL search or the `dataSearch` string changes.
+   *
+   * The method settles the store when your loader data matches the URL. During rapid filter changes, the method skips intermediate URLs. A URL that the reconciler didn't request counts as external navigation, such as back or forward.
    */
   reconcile(urlSearch: string, dataSearch: string): void;
   /**
-   * Callback for {@link CollectionStore.setOnBrowseChange}. Merges current
-   * URL params with store state, tracks the pending navigation, and emits.
+   * Builds the next search string from the store's filters and sort, and passes the string to `emitChange`. Register the method as the store's browse change callback.
+   *
+   * The new search string keeps every URL param that the store doesn't manage and drops the `before` and `after` pagination cursors.
+   */
+  handleBrowseChange(): void;
+  /**
+   * Clears pending navigation. Call the method when you replace the store.
+   * @param newPrevUrlSearch - Current URL search string, which the next `reconcile()` call compares against.
    */
-  handleBrowseChange(): void; /** Clears pending navigation state (call when the store is recreated). */
   reset(newPrevUrlSearch: string): void;
 };
 /**
- * Creates a framework-agnostic reconciler that manages the state machine for
- * keeping the URL, server data, and store in sync during browse-change chains.
+ * Creates a reconciler that keeps the URL, your loader data, and a collection store in sync while the customer changes filters and sort.
+ *
+ * Use a reconciler to connect a collection store to a router that has no Hydrogen binding. In React, use `CollectionProvider`.
+ *
+ * @param callbacks The functions that return the store and the URL search string and navigate your router.
+ * @param initialPrevUrlSearch The current URL search string, which the first `reconcile()` call compares against. Defaults to an empty string.
+ * @returns A reconciler. Call `reconcile()` on URL changes, and register `handleBrowseChange()` as the store's browse change callback.
  *
- * Framework adapters delegate to this so the reconciliation logic
- * lives in one place.
+ * @publicDocs
  */
 declare function createCollectionReconciler(callbacks: ReconcilerCallbacks, initialPrevUrlSearch?: string): CollectionReconciler;
 //#endregion

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

@@ -2,11 +2,15 @@ import { collectionSearchEqual, mergeCollectionParams, normalizeCollectionSearch
 
 //#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.
+* Creates a reconciler that keeps the URL, your loader data, and a collection store in sync while the customer changes filters and sort.
 *
-* Framework adapters delegate to this so the reconciliation logic
-* lives in one place.
+* Use a reconciler to connect a collection store to a router that has no Hydrogen binding. In React, use `CollectionProvider`.
+*
+* @param callbacks The functions that return the store and the URL search string and navigate your router.
+* @param initialPrevUrlSearch The current URL search string, which the first `reconcile()` call compares against. Defaults to an empty string.
+* @returns A reconciler. Call `reconcile()` on URL changes, and register `handleBrowseChange()` as the store's browse change callback.
+*
+* @publicDocs
 */
 function createCollectionReconciler(callbacks, initialPrevUrlSearch = "") {
 	let pendingFilter = null;

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

@@ -1 +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\n/**\n * Adapter-supplied hooks that let the reconciler read framework state and\n * push navigation side-effects without depending on any specific framework.\n */\nexport type ReconcilerCallbacks = {\n  /** Returns the current collection store instance. */\n  getStore: () => CollectionStore;\n  /** Reads the live URL search string from the framework router. */\n  readUrlSearch: () => string;\n  /** Delivers a serialized search string for the framework adapter to handle. */\n  emitChange: (searchString: string) => void;\n};\n\n/**\n * State machine that keeps the URL, server data, and `CollectionStore` in\n * sync during browse-change chains. Created by `createCollectionReconciler`.\n */\nexport type CollectionReconciler = {\n  /**\n   * URL ↔ store reconciliation state machine. Call whenever `urlSearch` or\n   * `dataSearch` changes. Store changes go through\n   * {@link CollectionReconciler.handleBrowseChange} instead.\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":";;;;;;;;;;AA2CA,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"}
+{"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\n/**\n * Functions that connect a collection reconciler to your router and your collection store.\n */\nexport type ReconcilerCallbacks = {\n  /** Returns the collection store. */\n  getStore: () => CollectionStore;\n  /** Returns the current URL search string from your router. */\n  readUrlSearch: () => string;\n  /** Navigates your router to the search string. The string starts with `?`, or is empty when no params remain. */\n  emitChange: (searchString: string) => void;\n};\n\n/**\n * Keeps the URL, your loader data, and a collection store in sync while the customer changes filters and sort.\n */\nexport type CollectionReconciler = {\n  /**\n   * Brings the store in line with the URL. Call the method each time the URL search or the `dataSearch` string changes.\n   *\n   * The method settles the store when your loader data matches the URL. During rapid filter changes, the method skips intermediate URLs. A URL that the reconciler didn't request counts as external navigation, such as back or forward.\n   */\n  reconcile(urlSearch: string, dataSearch: string): void;\n  /**\n   * Builds the next search string from the store's filters and sort, and passes the string to `emitChange`. Register the method as the store's browse change callback.\n   *\n   * The new search string keeps every URL param that the store doesn't manage and drops the `before` and `after` pagination cursors.\n   */\n  handleBrowseChange(): void;\n  /**\n   * Clears pending navigation. Call the method when you replace the store.\n   * @param newPrevUrlSearch - Current URL search string, which the next `reconcile()` call compares against.\n   */\n  reset(newPrevUrlSearch: string): void;\n};\n\n/**\n * Creates a reconciler that keeps the URL, your loader data, and a collection store in sync while the customer changes filters and sort.\n *\n * Use a reconciler to connect a collection store to a router that has no Hydrogen binding. In React, use `CollectionProvider`.\n *\n * @param callbacks The functions that return the store and the URL search string and navigate your router.\n * @param initialPrevUrlSearch The current URL search string, which the first `reconcile()` call compares against. Defaults to an empty string.\n * @returns A reconciler. Call `reconcile()` on URL changes, and register `handleBrowseChange()` as the store's browse change callback.\n *\n * @publicDocs\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":";;;;;;;;;;;;;;AAiDA,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

@@ -2,68 +2,73 @@ import { ProductCollectionSortKeys } from "../../graphql/generated/storefront-ap
 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. */
+/** How the storefront displays a filter's values. */
 type FilterPresentation = "IMAGE" | "SWATCH" | "TEXT";
-/** The input mechanism a filter uses — e.g. boolean toggle, multi-select list, or price range. */
+/** The kind of input a filter takes, such as a boolean toggle, a multi-select list, or a price range. */
 type FilterType = "BOOLEAN" | "LIST" | "PRICE_RANGE" | (string & {});
+/** The ID, label, product count, and filter input that every filter value has. */
 interface BaseAvailableFilterValue {
+  /** ID of the filter value. */
   id: string;
-  /** Human-readable label (e.g. "Red", "Nike", "$50–$100"). */
+  /** Label to display, such as "Red" or "Nike". */
   label: string;
-  /** Number of products matching this value in the current result set. */
+  /** Number of products in the current results that match the value. */
   count: number;
-  /** JSON-encoded `ProductFilter` input to apply this value. */
+  /** Filter input as a JSON string. Pass the string to `toggleFilterInput()` or `isFilterInputActive`. */
   input: string;
 }
+/** Copies a field from your query's value type when your query selects the field. Otherwise, the type adds no fields. */
 type PickIfPresent<TValue, TKey extends PropertyKey> = TKey extends keyof TValue ? Pick<TValue, TKey> : {};
 /**
- * A single selectable value within an {@link AvailableFilter}.
+ * A value that a customer can select within an available filter.
  *
- * Pass your Storefront API query value type as `TValue` to expose query-selected
- * visual fields such as `swatch`.
+ * Pass your Storefront API query's value type as `TValue` to include the `swatch` field when your query selects it.
  */
 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).
+ * A filter that the Storefront API returns for the current collection or search results.
+ * Render filter controls, such as checkboxes, swatches, and sliders, from the filter's values.
+ *
+ * @publicDocs
  */
 interface AvailableFilter<TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue> {
+  /** ID of the filter. */
   id: string;
-  /** Human-readable name (e.g. "Color", "Size", "Price"). */
+  /** Name to display, such as "Color", "Size", or "Price". */
   label: string;
-  /** Input mechanism — e.g. boolean toggle, multi-select list, or price range. */
+  /** Kind of input, such as a boolean toggle, a multi-select list, or a price range. */
   type: FilterType;
   /**
-   * Visual presentation hint for the storefront UI. Populated only for `LIST`
-   * filters; `null` otherwise.
+   * How the storefront displays the filter's values. The Storefront API
+   * returns a value only for `LIST` filters and `null` for other filters.
    */
   presentation?: FilterPresentation | null;
+  /** Values that a customer can select, each with a label, a product count, and a filter input. */
   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.
+ * The customer's filter and sort choices and the loading status.
  *
- * Server response data (productsCount, availableFilters, collection id) lives
- * in the framework's loader data, not in the store.
+ * Products, product counts, available filters, and the collection ID come from your loader data.
  */
 interface CollectionState {
-  /** URL-safe slug identifying the collection (e.g. `"shoes"`). */
+  /** Collection handle, such as `shoes`. */
   handle: string;
-  /** Active product filters, synced bidirectionally with URL params (`filter.*`). */
+  /** Active product filters, matching the `filter.*` URL params. */
   filters: ProductFilter[];
-  /** Storefront API sort key. `undefined` means the collection's default sort order. */
+  /** Storefront API sort key, or `undefined` for the collection's default sort. */
   sortKey: ProductCollectionSortKeys | undefined;
-  /** When `true`, the sort direction is descending (maps to `sort_by` suffix `-descending`). */
+  /** `true` for a descending sort. The URL's sort value then ends in `-descending`. */
   reverse: boolean;
-  /** `"idle"` when browse state matches the last-loaded data, `"loading"` after a browse change before the framework fetch settles. */
+  /** Reads `loading` from a filter or sort change until the store settles, and `idle` when the results match the filters and sort. Show a loading state while the value is `loading`. */
   status: "idle" | "loading";
 }
 /**
- * Creates a blank {@link CollectionState} for the given collection handle.
- * All browse fields start at their zero values.
+ * Creates collection state with no filters and the default sort for a collection handle.
  *
- * @param handle - URL-safe collection slug (e.g. `"shoes"`)
+ * @param handle - Collection handle, such as `shoes`.
+ * @returns A state with no filters, the collection's default sort, an ascending direction, and an idle status.
+ * @publicDocs
  */
 declare function createInitialCollectionState(handle: string): CollectionState;
 //#endregion

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

@@ -1,9 +1,10 @@
 //#region src/core/collection/state.ts
 /**
-* Creates a blank {@link CollectionState} for the given collection handle.
-* All browse fields start at their zero values.
+* Creates collection state with no filters and the default sort for a collection handle.
 *
-* @param handle - URL-safe collection slug (e.g. `"shoes"`)
+* @param handle - Collection handle, such as `shoes`.
+* @returns A state with no filters, the collection's default sort, an ascending direction, and an idle status.
+* @publicDocs
 */
 function createInitialCollectionState(handle) {
 	return {

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

@@ -1 +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 — e.g. boolean toggle, multi-select list, or price range. */\nexport type FilterType = \"BOOLEAN\" | \"LIST\" | \"PRICE_RANGE\" | (string & {});\n\ninterface BaseAvailableFilterValue {\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  /** Human-readable name (e.g. \"Color\", \"Size\", \"Price\"). */\n  label: string;\n  /** Input mechanism — e.g. boolean toggle, multi-select list, or price range. */\n  type: FilterType;\n  /**\n   * Visual presentation hint for the storefront UI. Populated only for `LIST`\n   * filters; `null` otherwise.\n   */\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":";;;;;;;AAkFA,SAAgB,6BAA6B,QAAiC;AAC5E,QAAO;EACL;EACA,SAAS,EAAE;EACX,SAAS;EACT,SAAS;EACT,QAAQ;EACT"}
+{"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 the storefront displays a filter's values. */\nexport type FilterPresentation = \"IMAGE\" | \"SWATCH\" | \"TEXT\";\n\n/** The kind of input a filter takes, such as a boolean toggle, a multi-select list, or a price range. */\nexport type FilterType = \"BOOLEAN\" | \"LIST\" | \"PRICE_RANGE\" | (string & {});\n\n/** The ID, label, product count, and filter input that every filter value has. */\ninterface BaseAvailableFilterValue {\n  /** ID of the filter value. */\n  id: string;\n  /** Label to display, such as \"Red\" or \"Nike\". */\n  label: string;\n  /** Number of products in the current results that match the value. */\n  count: number;\n  /** Filter input as a JSON string. Pass the string to `toggleFilterInput()` or `isFilterInputActive`. */\n  input: string;\n}\n\n/** Copies a field from your query's value type when your query selects the field. Otherwise, the type adds no fields. */\ntype PickIfPresent<TValue, TKey extends PropertyKey> = TKey extends keyof TValue\n  ? Pick<TValue, TKey>\n  : {};\n\n/**\n * A value that a customer can select within an available filter.\n *\n * Pass your Storefront API query's value type as `TValue` to include the `swatch` field when your query selects it.\n */\nexport type AvailableFilterValue<\n  TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue,\n> = BaseAvailableFilterValue & PickIfPresent<TValue, \"swatch\">;\n\n/**\n * A filter that the Storefront API returns for the current collection or search results.\n * Render filter controls, such as checkboxes, swatches, and sliders, from the filter's values.\n *\n * @publicDocs\n */\nexport interface AvailableFilter<\n  TValue extends BaseAvailableFilterValue = BaseAvailableFilterValue,\n> {\n  /** ID of the filter. */\n  id: string;\n  /** Name to display, such as \"Color\", \"Size\", or \"Price\". */\n  label: string;\n  /** Kind of input, such as a boolean toggle, a multi-select list, or a price range. */\n  type: FilterType;\n  /**\n   * How the storefront displays the filter's values. The Storefront API\n   * returns a value only for `LIST` filters and `null` for other filters.\n   */\n  presentation?: FilterPresentation | null;\n  /** Values that a customer can select, each with a label, a product count, and a filter input. */\n  values: AvailableFilterValue<TValue>[];\n}\n\n/**\n * The customer's filter and sort choices and the loading status.\n *\n * Products, product counts, available filters, and the collection ID come from your loader data.\n */\nexport interface CollectionState {\n  /** Collection handle, such as `shoes`. */\n  handle: string;\n\n  /** Active product filters, matching the `filter.*` URL params. */\n  filters: ProductFilter[];\n  /** Storefront API sort key, or `undefined` for the collection's default sort. */\n  sortKey: ProductCollectionSortKeys | undefined;\n  /** `true` for a descending sort. The URL's sort value then ends in `-descending`. */\n  reverse: boolean;\n  /** Reads `loading` from a filter or sort change until the store settles, and `idle` when the results match the filters and sort. Show a loading state while the value is `loading`. */\n  status: \"idle\" | \"loading\";\n}\n\n/**\n * Creates collection state with no filters and the default sort for a collection handle.\n *\n * @param handle - Collection handle, such as `shoes`.\n * @returns A state with no filters, the collection's default sort, an ascending direction, and an idle status.\n * @publicDocs\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":";;;;;;;;AAuFA,SAAgB,6BAA6B,QAAiC;AAC5E,QAAO;EACL;EACA,SAAS,EAAE;EACX,SAAS;EACT,SAAS;EACT,QAAQ;EACT"}