@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/predictive-search/store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"store.mjs","names":[],"sources":["../../../src/core/predictive-search/store.ts"],"sourcesContent":["import type {\n  PredictiveSearchLimitScope,\n  PredictiveSearchType,\n  SearchUnavailableProductsType,\n  SearchableField,\n} from \"../../graphql/generated/storefront-api-types\";\nimport { createObservable } from \"../observable\";\nimport { PREDICTIVE_SEARCH_API_PATH, PREDICTIVE_SEARCH_QUERY_PARAM } from \"./constants\";\nimport { getEmptyPredictiveSearchResult, type PredictiveSearchData } from \"./search\";\n\n/** Default delay before predictive search sends a request after a term changes. */\nexport const DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS = 150;\n\n/** Default minimum trimmed term length required before predictive search sends a request. */\nconst DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH = 1;\n\n/** Lifecycle state for the predictive search client store. */\nexport type PredictiveSearchStatus = \"idle\" | \"loading\" | \"success\" | \"error\";\n\n/** Current predictive search snapshot exposed to UI bindings. */\nexport type PredictiveSearchState<TData extends PredictiveSearchData = PredictiveSearchData> = {\n  /** Latest trimmed search term known to the store. */\n  term: string;\n  /** Request lifecycle state for the current term. */\n  status: PredictiveSearchStatus;\n  /** Predictive search data for the current term, or an empty result while idle. */\n  result: TData;\n  /** Error message for the latest failed request, or null when there is no active error. */\n  error: string | null;\n};\n\n/** Options for creating a framework-neutral predictive search client store. */\nexport type CreatePredictiveSearchStoreOptions = {\n  /**\n   * Same-origin JSON endpoint used for browser predictive-search requests.\n   *\n   * The endpoint must return JSON matching the data payload from\n   * `await predictiveSearchHandlers.get(...)`.\n   */\n  predictiveSearchEndpoint?: string;\n  /** Delay before sending a request after the term changes. */\n  debounceInMs?: number;\n  /** Minimum trimmed term length required before searching. */\n  minTermLength?: number;\n  /** Fetch implementation, injectable for tests and non-browser runtimes. */\n  fetch?: typeof globalThis.fetch;\n  /** Maximum result count requested from the Storefront API. */\n  limit?: number;\n  /** Whether `limit` applies to each result type or all result types combined. */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Storefront API result types to include in predictive search. */\n  types?: PredictiveSearchType[];\n  /** Storefront API fields to search. */\n  searchableFields?: SearchableField[];\n  /** Storefront API unavailable-product behavior. */\n  unavailableProducts?: SearchUnavailableProductsType;\n};\n\n/** Framework-neutral predictive search store used by UI bindings. */\nexport type PredictiveSearchStore<TData extends PredictiveSearchData = PredictiveSearchData> = {\n  /** Reactivates store updates after destroy(). */\n  connect(): void;\n  /** Returns the current predictive search state snapshot. */\n  getState(): PredictiveSearchState<TData>;\n  /** Subscribes to state changes and returns an unsubscribe callback. */\n  subscribe(listener: (state: PredictiveSearchState<TData>) => void): () => void;\n  /** Searches for a term using the configured debounce and request lifecycle. */\n  search(term: string): Promise<void>;\n  /** Cancels pending work and resets the store to an empty state. */\n  clear(): void;\n  /** Cancels pending work and pauses store updates until reconnect. */\n  destroy(): void;\n};\n\n/** Search methods exposed by the predictive search store. */\nexport type PredictiveSearchActions = Pick<PredictiveSearchStore, \"search\" | \"clear\">;\n\ntype PredictiveSearchStoreContext<TData extends PredictiveSearchData> = {\n  observable: ReturnType<typeof createObservable<PredictiveSearchState<TData>>>;\n  // API route used to fetch predictive search results.\n  predictiveSearchEndpoint: string;\n  // Delay before firing a search request after the term changes.\n  debounceInMs: number;\n  // Minimum term length required before searching.\n  minTermLength: number;\n  // Fetch implementation, injectable for tests and non-browser runtimes.\n  fetch: typeof globalThis.fetch;\n  // Storefront API search options forwarded to the server handler.\n  searchOptions: StoreSearchOptions;\n  abortController: AbortController | null;\n  // Active debounce timer waiting to start the next search.\n  debounceTimer: ReturnType<typeof setTimeout> | null;\n  // Monotonic counter used to ignore responses from older requests.\n  requestId: number;\n  // Resolver for the current debounced search promise.\n  pendingResolve: (() => void) | null;\n  // Prevents future work after the store has been torn down.\n  destroyed: boolean;\n};\n\ntype StoreSearchOptions = Pick<\n  CreatePredictiveSearchStoreOptions,\n  \"limit\" | \"limitScope\" | \"types\" | \"searchableFields\" | \"unavailableProducts\"\n>;\n\nexport function createPredictiveSearchStore<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n>(options: CreatePredictiveSearchStoreOptions = {}): PredictiveSearchStore<TData> {\n  // Prefer an injected fetch for tests and non-browser runtimes, then fall back to the ambient runtime fetch.\n  const resolvedFetch = options.fetch ?? resolveGlobalFetch();\n  if (typeof resolvedFetch !== \"function\") {\n    throw new Error(\n      \"No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.\",\n    );\n  }\n\n  const context: PredictiveSearchStoreContext<TData> = {\n    observable: createObservable(createInitialState<TData>()),\n    predictiveSearchEndpoint: options.predictiveSearchEndpoint ?? PREDICTIVE_SEARCH_API_PATH,\n    debounceInMs: sanitizeDebounceInMs(options.debounceInMs),\n    minTermLength: sanitizeMinTermLength(options.minTermLength),\n    fetch: resolvedFetch,\n    searchOptions: {\n      limit: options.limit,\n      limitScope: options.limitScope,\n      types: options.types,\n      searchableFields: options.searchableFields,\n      unavailableProducts: options.unavailableProducts,\n    },\n    abortController: null,\n    debounceTimer: null,\n    requestId: 0,\n    pendingResolve: null,\n    destroyed: false,\n  };\n\n  return {\n    connect: () => connect(context),\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    search: (term) => search(context, term),\n    clear: () => clear(context),\n    destroy: () => destroy(context),\n  };\n}\n\nfunction connect<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.destroyed = false;\n}\n\nfunction resolveGlobalFetch(): typeof globalThis.fetch | undefined {\n  if (typeof globalThis.fetch !== \"function\") return undefined;\n  return globalThis.fetch.bind(globalThis);\n}\n\nfunction sanitizeDebounceInMs(debounceInMs: number | undefined): number {\n  if (typeof debounceInMs !== \"number\") return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  if (!Number.isFinite(debounceInMs)) return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  if (debounceInMs < 0) return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  return Math.trunc(debounceInMs);\n}\n\nfunction sanitizeMinTermLength(minTermLength: number | undefined): number {\n  if (typeof minTermLength !== \"number\") return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  if (!Number.isFinite(minTermLength)) return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  if (minTermLength < 0) return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  return Math.trunc(minTermLength);\n}\n\nfunction createInitialState<TData extends PredictiveSearchData>(): PredictiveSearchState<TData> {\n  return {\n    term: \"\",\n    status: \"idle\",\n    result: getEmptyPredictiveSearchResult(\"\") as TData,\n    error: null,\n  };\n}\n\nfunction search<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): Promise<void> {\n  resolvePending(context);\n  cancelScheduledWork(context);\n\n  if (context.destroyed) return Promise.resolve();\n\n  const trimmedTerm = term.trim();\n  if (trimmedTerm.length < context.minTermLength) {\n    resetState(context, trimmedTerm);\n    return Promise.resolve();\n  }\n\n  return new Promise((resolve) => {\n    context.pendingResolve = resolve;\n    context.requestId += 1;\n    context.observable.setState({\n      ...context.observable.state,\n      term: trimmedTerm,\n      status: \"loading\",\n      error: null,\n    });\n    scheduleSearch(context, trimmedTerm, context.requestId);\n  });\n}\n\nfunction clear<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.requestId += 1;\n  resolvePending(context);\n  cancelScheduledWork(context);\n  resetState(context, \"\");\n}\n\nfunction destroy<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.destroyed = true;\n  context.requestId += 1;\n  resolvePending(context);\n  cancelScheduledWork(context);\n}\n\nfunction scheduleSearch<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n  requestId: number,\n): void {\n  if (context.debounceInMs === 0) {\n    void executeSearch(context, term, requestId);\n    return;\n  }\n\n  context.debounceTimer = setTimeout(() => {\n    context.debounceTimer = null;\n    void executeSearch(context, term, requestId);\n  }, context.debounceInMs);\n}\n\nasync function executeSearch<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n  requestId: number,\n): Promise<void> {\n  const abortController = new AbortController();\n  context.abortController = abortController;\n\n  try {\n    const response = await context.fetch(buildRequestUrl(context, term), {\n      signal: abortController.signal,\n    });\n    const result = await readResponse<TData>(response);\n    settleSuccess(context, requestId, result);\n  } catch (error) {\n    if (isAbortError(error)) return;\n    settleError(context, requestId, getErrorMessage(error));\n  }\n}\n\nasync function readResponse<TData extends PredictiveSearchData>(\n  response: Response,\n): Promise<TData> {\n  const body = await readJson(response);\n  if (response.ok) return body as TData;\n  throw new Error(getResponseErrorMessage(body, response));\n}\n\nasync function readJson(response: Response): Promise<unknown> {\n  try {\n    return await response.json();\n  } catch {\n    return null;\n  }\n}\n\nfunction settleSuccess<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n  result: TData,\n): void {\n  if (!isActiveRequest(context, requestId)) return;\n  context.observable.setState({\n    term: result.term,\n    status: \"success\",\n    result,\n    error: null,\n  });\n  finishActiveRequest(context);\n}\n\nfunction settleError<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n  message: string,\n): void {\n  if (!isActiveRequest(context, requestId)) return;\n  context.observable.setState({\n    ...context.observable.state,\n    status: \"error\",\n    error: message,\n  });\n  finishActiveRequest(context);\n}\n\nfunction finishActiveRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.abortController = null;\n  resolvePending(context);\n}\n\nfunction resetState<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): void {\n  context.observable.setState({\n    term,\n    status: \"idle\",\n    result: getEmptyPredictiveSearchResult(term) as TData,\n    error: null,\n  });\n}\n\nfunction cancelScheduledWork<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  clearDebounceTimer(context);\n  abortRequest(context);\n}\n\nfunction clearDebounceTimer<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  if (context.debounceTimer === null) return;\n  clearTimeout(context.debounceTimer);\n  context.debounceTimer = null;\n}\n\nfunction abortRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.abortController?.abort();\n  context.abortController = null;\n}\n\nfunction resolvePending<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.pendingResolve?.();\n  context.pendingResolve = null;\n}\n\nfunction isActiveRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n): boolean {\n  return !context.destroyed && context.requestId === requestId;\n}\n\nfunction buildRequestUrl<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): string {\n  const url = new URL(context.predictiveSearchEndpoint, \"https://hydrogen.local\");\n  url.searchParams.set(PREDICTIVE_SEARCH_QUERY_PARAM, term);\n  appendSearchOptions(url.searchParams, context.searchOptions);\n  if (URL.canParse(context.predictiveSearchEndpoint)) return url.href;\n  return `${url.pathname}${url.search}`;\n}\n\nfunction appendSearchOptions(searchParams: URLSearchParams, options: StoreSearchOptions): void {\n  setOptionalParam(searchParams, \"limit\", options.limit);\n  setOptionalParam(searchParams, \"limitScope\", options.limitScope);\n  setOptionalParam(searchParams, \"types\", options.types?.join(\",\"));\n  setOptionalParam(searchParams, \"searchableFields\", options.searchableFields?.join(\",\"));\n  setOptionalParam(searchParams, \"unavailableProducts\", options.unavailableProducts);\n}\n\nfunction setOptionalParam(\n  searchParams: URLSearchParams,\n  name: string,\n  value: number | string | undefined,\n): void {\n  if (value === undefined) return;\n  searchParams.set(name, String(value));\n}\n\nfunction getResponseErrorMessage(body: unknown, response: Response): string {\n  const message = getNestedErrorMessage(body);\n  if (message) return message;\n  return `Predictive search request failed with status ${response.status}`;\n}\n\nfunction getNestedErrorMessage(body: unknown): string | null {\n  if (!body || typeof body !== \"object\") return null;\n  if (!(\"error\" in body)) return null;\n\n  const error = body.error;\n  if (!error || typeof error !== \"object\") return null;\n  if (!(\"message\" in error)) return null;\n\n  return typeof error.message === \"string\" ? error.message : null;\n}\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : \"Predictive search request failed\";\n}\n\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof DOMException && error.name === \"AbortError\";\n}\n"],"mappings":"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"}
+{"version":3,"file":"store.mjs","names":[],"sources":["../../../src/core/predictive-search/store.ts"],"sourcesContent":["import type {\n  PredictiveSearchLimitScope,\n  PredictiveSearchType,\n  SearchUnavailableProductsType,\n  SearchableField,\n} from \"../../graphql/generated/storefront-api-types\";\nimport { createObservable } from \"../observable\";\nimport { PREDICTIVE_SEARCH_API_PATH, PREDICTIVE_SEARCH_QUERY_PARAM } from \"./constants\";\nimport { getEmptyPredictiveSearchResult, type PredictiveSearchData } from \"./search\";\n\n/** Default wait, in milliseconds, between the latest term change and the search request. */\nexport const DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS = 150;\n\n/** Default minimum trimmed term length required before predictive search sends a request. */\nconst DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH = 1;\n\n/** Status of the current search. */\nexport type PredictiveSearchStatus = \"idle\" | \"loading\" | \"success\" | \"error\";\n\n/** Current search term, status, results, and error of a predictive search. */\nexport type PredictiveSearchState<TData extends PredictiveSearchData = PredictiveSearchData> = {\n  /** Latest search term, without surrounding whitespace. */\n  term: string;\n  /** Status of the search for the current term. */\n  status: PredictiveSearchStatus;\n  /** Results of the latest successful search. Previous results stay in place while a new search loads and after a search fails. The idle state holds empty results. */\n  result: TData;\n  /** Message from the latest failed search, or `null` when the current search hasn't failed. A custom endpoint sets the message with a JSON body of `{error: {message}}`. */\n  error: string | null;\n};\n\n/**\n * Endpoint, timing, and search settings for a predictive search store.\n *\n * The store sends each search setting to the endpoint as a URL parameter of the same name. The server handlers apply their own defaults to omitted settings.\n */\nexport type CreatePredictiveSearchStoreOptions = {\n  /**\n   * Route that returns predictive search results as JSON, in the shape that `createPredictiveSearchServerHandlers` returns.\n   *\n   * Defaults to `/api/predictive-search`.\n   */\n  predictiveSearchEndpoint?: string;\n  /**\n   * Milliseconds to wait after the latest term change before searching.\n   *\n   * Defaults to `150`. Pass `0` to search right away. Negative and non-finite values use the default.\n   */\n  debounceInMs?: number;\n  /**\n   * Number of characters a term needs, after trimming, before the store searches.\n   *\n   * Defaults to `1`. Negative and non-finite values use the default.\n   */\n  minTermLength?: number;\n  /** Function that sends search requests. Defaults to the global `fetch`. Pass a function for tests or for runtimes without a global `fetch`. */\n  fetch?: typeof globalThis.fetch;\n  /** Maximum number of results, from 1 to 10. The server handlers clamp other values to that range. */\n  limit?: number;\n  /** Whether the limit applies to each result type or to all result types combined. */\n  limitScope?: PredictiveSearchLimitScope;\n  /** Result types to include. */\n  types?: PredictiveSearchType[];\n  /** Fields to search for page, article, and collection results. */\n  searchableFields?: SearchableField[];\n  /** Whether results hide unavailable products, show them, or list them last. */\n  unavailableProducts?: SearchUnavailableProductsType;\n};\n\n/** Holds the search term, status, and results, and runs searches as the customer types. */\nexport type PredictiveSearchStore<TData extends PredictiveSearchData = PredictiveSearchData> = {\n  /** Restarts a store after `destroy()`. A new store doesn't need this call. */\n  connect(): void;\n  /** Returns the current search term, status, results, and error. */\n  getState(): PredictiveSearchState<TData>;\n  /** Calls your function with the new state on every change. Returns a function that stops the calls. */\n  subscribe(listener: (state: PredictiveSearchState<TData>) => void): () => void;\n  /**\n   * Searches for a term after the debounce delay. Call the method on every keystroke.\n   *\n   * Each call cancels the previous pending search. A term shorter than the minimum length, after trimming, returns the store to `idle` with empty results. Otherwise, the status changes to `loading` until the search ends with `success` or `error`. Responses for earlier terms never replace newer results.\n   *\n   * The returned promise resolves when the search ends, or when a later search, `clear()`, or `destroy()` cancels the search.\n   */\n  search(term: string): Promise<void>;\n  /**\n   * Cancels any pending search and returns the store to the idle state with no term and empty results.\n   *\n   * Call `clear()` when the customer closes the search UI.\n   */\n  clear(): void;\n  /**\n   * Stops the store. Call `destroy()` when the search UI unmounts.\n   *\n   * The store cancels any pending search, keeps its current state, and ignores searches until you call `connect()`.\n   */\n  destroy(): void;\n};\n\n/** Methods that search for a term and clear the results. */\nexport type PredictiveSearchActions = Pick<PredictiveSearchStore, \"search\" | \"clear\">;\n\ntype PredictiveSearchStoreContext<TData extends PredictiveSearchData> = {\n  observable: ReturnType<typeof createObservable<PredictiveSearchState<TData>>>;\n  // API route used to fetch predictive search results.\n  predictiveSearchEndpoint: string;\n  // Delay before firing a search request after the term changes.\n  debounceInMs: number;\n  // Minimum term length required before searching.\n  minTermLength: number;\n  // Fetch implementation, injectable for tests and non-browser runtimes.\n  fetch: typeof globalThis.fetch;\n  // Storefront API search options forwarded to the server handler.\n  searchOptions: StoreSearchOptions;\n  abortController: AbortController | null;\n  // Active debounce timer waiting to start the next search.\n  debounceTimer: ReturnType<typeof setTimeout> | null;\n  // Monotonic counter used to ignore responses from older requests.\n  requestId: number;\n  // Resolver for the current debounced search promise.\n  pendingResolve: (() => void) | null;\n  // Prevents future work after the store has been torn down.\n  destroyed: boolean;\n};\n\ntype StoreSearchOptions = Pick<\n  CreatePredictiveSearchStoreOptions,\n  \"limit\" | \"limitScope\" | \"types\" | \"searchableFields\" | \"unavailableProducts\"\n>;\n\n/**\n * Creates a store that searches as the customer types and holds the latest predictive search results. Use the store in DOM code or in UI frameworks without Hydrogen bindings. In React and Vue, use `PredictiveSearchProvider`.\n *\n * Call `search()` with each new term, read results with `getState()` or `subscribe()`, and call `destroy()` when the search UI unmounts. By default, the store requests results from the route that `createPredictiveSearchServerHandlers` serves.\n *\n * The function throws an error when you omit the `fetch` option in a runtime without a global `fetch`.\n *\n * @param options Endpoint, timing, and search settings for the store.\n * @returns A store with no term and empty results, ready to search.\n * @publicDocs\n */\nexport function createPredictiveSearchStore<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n>(options: CreatePredictiveSearchStoreOptions = {}): PredictiveSearchStore<TData> {\n  // Prefer an injected fetch for tests and non-browser runtimes, then fall back to the ambient runtime fetch.\n  const resolvedFetch = options.fetch ?? resolveGlobalFetch();\n  if (typeof resolvedFetch !== \"function\") {\n    throw new Error(\n      \"No fetch function available. Pass a fetch option or ensure globalThis.fetch exists.\",\n    );\n  }\n\n  const context: PredictiveSearchStoreContext<TData> = {\n    observable: createObservable(createInitialState<TData>()),\n    predictiveSearchEndpoint: options.predictiveSearchEndpoint ?? PREDICTIVE_SEARCH_API_PATH,\n    debounceInMs: sanitizeDebounceInMs(options.debounceInMs),\n    minTermLength: sanitizeMinTermLength(options.minTermLength),\n    fetch: resolvedFetch,\n    searchOptions: {\n      limit: options.limit,\n      limitScope: options.limitScope,\n      types: options.types,\n      searchableFields: options.searchableFields,\n      unavailableProducts: options.unavailableProducts,\n    },\n    abortController: null,\n    debounceTimer: null,\n    requestId: 0,\n    pendingResolve: null,\n    destroyed: false,\n  };\n\n  return {\n    connect: () => connect(context),\n    getState: () => context.observable.state,\n    subscribe: (listener) => context.observable.subscribe(listener),\n    search: (term) => search(context, term),\n    clear: () => clear(context),\n    destroy: () => destroy(context),\n  };\n}\n\nfunction connect<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.destroyed = false;\n}\n\nfunction resolveGlobalFetch(): typeof globalThis.fetch | undefined {\n  if (typeof globalThis.fetch !== \"function\") return undefined;\n  return globalThis.fetch.bind(globalThis);\n}\n\nfunction sanitizeDebounceInMs(debounceInMs: number | undefined): number {\n  if (typeof debounceInMs !== \"number\") return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  if (!Number.isFinite(debounceInMs)) return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  if (debounceInMs < 0) return DEFAULT_PREDICTIVE_SEARCH_DEBOUNCE_IN_MS;\n  return Math.trunc(debounceInMs);\n}\n\nfunction sanitizeMinTermLength(minTermLength: number | undefined): number {\n  if (typeof minTermLength !== \"number\") return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  if (!Number.isFinite(minTermLength)) return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  if (minTermLength < 0) return DEFAULT_PREDICTIVE_SEARCH_MIN_TERM_LENGTH;\n  return Math.trunc(minTermLength);\n}\n\nfunction createInitialState<TData extends PredictiveSearchData>(): PredictiveSearchState<TData> {\n  return {\n    term: \"\",\n    status: \"idle\",\n    result: getEmptyPredictiveSearchResult(\"\") as TData,\n    error: null,\n  };\n}\n\nfunction search<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): Promise<void> {\n  resolvePending(context);\n  cancelScheduledWork(context);\n\n  if (context.destroyed) return Promise.resolve();\n\n  const trimmedTerm = term.trim();\n  if (trimmedTerm.length < context.minTermLength) {\n    resetState(context, trimmedTerm);\n    return Promise.resolve();\n  }\n\n  return new Promise((resolve) => {\n    context.pendingResolve = resolve;\n    context.requestId += 1;\n    context.observable.setState({\n      ...context.observable.state,\n      term: trimmedTerm,\n      status: \"loading\",\n      error: null,\n    });\n    scheduleSearch(context, trimmedTerm, context.requestId);\n  });\n}\n\nfunction clear<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.requestId += 1;\n  resolvePending(context);\n  cancelScheduledWork(context);\n  resetState(context, \"\");\n}\n\nfunction destroy<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.destroyed = true;\n  context.requestId += 1;\n  resolvePending(context);\n  cancelScheduledWork(context);\n}\n\nfunction scheduleSearch<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n  requestId: number,\n): void {\n  if (context.debounceInMs === 0) {\n    void executeSearch(context, term, requestId);\n    return;\n  }\n\n  context.debounceTimer = setTimeout(() => {\n    context.debounceTimer = null;\n    void executeSearch(context, term, requestId);\n  }, context.debounceInMs);\n}\n\nasync function executeSearch<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n  requestId: number,\n): Promise<void> {\n  const abortController = new AbortController();\n  context.abortController = abortController;\n\n  try {\n    const response = await context.fetch(buildRequestUrl(context, term), {\n      signal: abortController.signal,\n    });\n    const result = await readResponse<TData>(response);\n    settleSuccess(context, requestId, result);\n  } catch (error) {\n    if (isAbortError(error)) return;\n    settleError(context, requestId, getErrorMessage(error));\n  }\n}\n\nasync function readResponse<TData extends PredictiveSearchData>(\n  response: Response,\n): Promise<TData> {\n  const body = await readJson(response);\n  if (response.ok) return body as TData;\n  throw new Error(getResponseErrorMessage(body, response));\n}\n\nasync function readJson(response: Response): Promise<unknown> {\n  try {\n    return await response.json();\n  } catch {\n    return null;\n  }\n}\n\nfunction settleSuccess<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n  result: TData,\n): void {\n  if (!isActiveRequest(context, requestId)) return;\n  context.observable.setState({\n    term: result.term,\n    status: \"success\",\n    result,\n    error: null,\n  });\n  finishActiveRequest(context);\n}\n\nfunction settleError<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n  message: string,\n): void {\n  if (!isActiveRequest(context, requestId)) return;\n  context.observable.setState({\n    ...context.observable.state,\n    status: \"error\",\n    error: message,\n  });\n  finishActiveRequest(context);\n}\n\nfunction finishActiveRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.abortController = null;\n  resolvePending(context);\n}\n\nfunction resetState<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): void {\n  context.observable.setState({\n    term,\n    status: \"idle\",\n    result: getEmptyPredictiveSearchResult(term) as TData,\n    error: null,\n  });\n}\n\nfunction cancelScheduledWork<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  clearDebounceTimer(context);\n  abortRequest(context);\n}\n\nfunction clearDebounceTimer<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  if (context.debounceTimer === null) return;\n  clearTimeout(context.debounceTimer);\n  context.debounceTimer = null;\n}\n\nfunction abortRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.abortController?.abort();\n  context.abortController = null;\n}\n\nfunction resolvePending<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n): void {\n  context.pendingResolve?.();\n  context.pendingResolve = null;\n}\n\nfunction isActiveRequest<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  requestId: number,\n): boolean {\n  return !context.destroyed && context.requestId === requestId;\n}\n\nfunction buildRequestUrl<TData extends PredictiveSearchData>(\n  context: PredictiveSearchStoreContext<TData>,\n  term: string,\n): string {\n  const url = new URL(context.predictiveSearchEndpoint, \"https://hydrogen.local\");\n  url.searchParams.set(PREDICTIVE_SEARCH_QUERY_PARAM, term);\n  appendSearchOptions(url.searchParams, context.searchOptions);\n  if (URL.canParse(context.predictiveSearchEndpoint)) return url.href;\n  return `${url.pathname}${url.search}`;\n}\n\nfunction appendSearchOptions(searchParams: URLSearchParams, options: StoreSearchOptions): void {\n  setOptionalParam(searchParams, \"limit\", options.limit);\n  setOptionalParam(searchParams, \"limitScope\", options.limitScope);\n  setOptionalParam(searchParams, \"types\", options.types?.join(\",\"));\n  setOptionalParam(searchParams, \"searchableFields\", options.searchableFields?.join(\",\"));\n  setOptionalParam(searchParams, \"unavailableProducts\", options.unavailableProducts);\n}\n\nfunction setOptionalParam(\n  searchParams: URLSearchParams,\n  name: string,\n  value: number | string | undefined,\n): void {\n  if (value === undefined) return;\n  searchParams.set(name, String(value));\n}\n\nfunction getResponseErrorMessage(body: unknown, response: Response): string {\n  const message = getNestedErrorMessage(body);\n  if (message) return message;\n  return `Predictive search request failed with status ${response.status}`;\n}\n\nfunction getNestedErrorMessage(body: unknown): string | null {\n  if (!body || typeof body !== \"object\") return null;\n  if (!(\"error\" in body)) return null;\n\n  const error = body.error;\n  if (!error || typeof error !== \"object\") return null;\n  if (!(\"message\" in error)) return null;\n\n  return typeof error.message === \"string\" ? error.message : null;\n}\n\nfunction getErrorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : \"Predictive search request failed\";\n}\n\nfunction isAbortError(error: unknown): boolean {\n  return error instanceof DOMException && error.name === \"AbortError\";\n}\n"],"mappings":"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"}

package/dist/core/predictive-search/url.d.mts

@@ -3,73 +3,72 @@ import { PredictiveSearchData } from "./search.mjs";
 
 //#region src/core/predictive-search/url.d.ts
 type PredictiveSearchItems = PredictiveSearchData["items"];
-/** A product returned by predictive search. */
+/** A product result from predictive search. */
 type PredictiveSearchProductItem = PredictiveSearchItems["products"][number];
-/** A collection returned by predictive search. */
+/** A collection result from predictive search. */
 type PredictiveSearchCollectionItem = PredictiveSearchItems["collections"][number];
-/** A page returned by predictive search. */
+/** A page result from predictive search. */
 type PredictiveSearchPageItem = PredictiveSearchItems["pages"][number];
-/** An article returned by predictive search. Includes a nested `blog.handle` used for URL generation via {@link getPredictiveSearchItemUrl}. */
+/** An article result from predictive search. */
 type PredictiveSearchArticleItem = PredictiveSearchItems["articles"][number];
-/** A search query suggestion returned by predictive search. Uses `text` as the search term when generating its URL via {@link getPredictiveSearchItemUrl}. */
+/** A suggested search term from predictive search. */
 type PredictiveSearchQueryItem = PredictiveSearchItems["queries"][number];
-/** Union of product, collection, page, and article items. Excludes query suggestions. */
+/** A product, collection, page, or article result. Excludes query suggestions. */
 type PredictiveSearchResourceItem = PredictiveSearchProductItem | PredictiveSearchCollectionItem | PredictiveSearchPageItem | PredictiveSearchArticleItem;
-/** Any item returned by predictive search, including query suggestions. */
+/** Any predictive search result, including query suggestions. */
 type PredictiveSearchItem = PredictiveSearchResourceItem | PredictiveSearchQueryItem;
 /**
- * Options for generating URLs for resource items (products, collections,
- * pages, articles) via {@link getPredictiveSearchItemUrl}.
+ * Options for the link of a product, collection, page, or article result.
  *
- * Required for resource items because their URLs depend on route templates
- * and the current search term.
+ * Pass the route templates and the customer's search term.
  */
 type PredictiveSearchItemUrlOptions = {
-  /** Optional path prefix prepended to the generated route (e.g., a locale prefix). */pathPrefix?: string; /** Route templates used to resolve the resource's URL pattern. */
-  routes: ShopifyRouteTemplates; /** Search term appended as a query parameter to the generated URL. */
+  /** Prefix to add before the route path, such as a locale prefix. */pathPrefix?: string; /** Route templates for product, collection, page, and article paths, from `createShopifyRouteTemplates`. */
+  routes: ShopifyRouteTemplates; /** Search term that the customer typed. The link carries the term in the `q` URL parameter. */
   term: string;
 };
 /**
- * Options for generating URLs for query suggestion items via
- * {@link getPredictiveSearchItemUrl}.
+ * Options for the link of a query suggestion.
  *
- * Optional because query suggestions use their own `text` as the search
- * term and default to the standard search route.
+ * By default, a suggestion links to the standard search route and searches for the suggestion's text.
  */
 type PredictiveSearchQueryItemUrlOptions = {
-  /** Optional path prefix prepended to the search route (e.g., a locale prefix). Ignored when `searchPath` is set. */pathPrefix?: string; /** Route templates. When omitted, the standard search route is used. */
-  routes?: ShopifyRouteTemplates; /** Custom search page path, used as-is (no `pathPrefix` applied). Takes precedence over `routes` and `pathPrefix`. */
+  /** Prefix to add before the search route, such as a locale prefix. Has no effect when you set a search path. */pathPrefix?: string; /** Route templates that set the search page path. Defaults to Hydrogen's standard search route. */
+  routes?: ShopifyRouteTemplates; /** Search page path or URL to use as is, without the route templates or the path prefix. */
   searchPath?: string;
 };
+/** Options for a search result URL. */
 type SearchResultUrlOptions = {
-  /** Search page path or absolute URL. */baseUrl: string; /** Search term, set under `searchParamName`. */
-  term: string; /** Storefront API `trackingParameters` query string, appended after the other parameters. */
-  trackingParameters?: string | null; /** Extra query parameters, set before the term, so a key matching `searchParamName` is overwritten. */
-  params?: Record<string, string>; /** Query parameter for the term. Defaults to `"q"`. */
+  /** Search page path or absolute URL. */baseUrl: string; /** Search term to add to the URL. */
+  term: string; /** Tracking parameters from a Storefront API search result. Pass the result's `trackingParameters` value unchanged. */
+  trackingParameters?: string | null; /** Extra URL parameters, such as a result type filter. The search term replaces an extra parameter with the same name. */
+  params?: Record<string, string>; /** URL parameter that carries the search term. Defaults to `q`. */
   searchParamName?: string;
 };
 /**
- * Generates a URL for a predictive search result item.
+ * Builds the link for a predictive search result. A product, collection, page, or
+ * article result links to the resource's page with the search term. A query suggestion links to
+ * the search page and searches for the suggestion's text. Every link keeps the
+ * result's tracking parameters.
  *
- * For query suggestions, builds a search page URL using the suggestion's
- * `text` as the search term. For resource items (products, collections,
- * pages, articles), builds the resource URL using the provided route
- * templates and appends the given search term as a query parameter.
+ * For a product, collection, page, or article, pass the route templates and the search term. The function throws an error without them.
  *
- * Always appends the item's `trackingParameters` when present.
- *
- * @throws {Error} When a resource item is passed without `routes` and `term` in options.
+ * @throws {Error} When you pass a resource item without `routes` and `term` in the options.
+ * @publicDocs
  */
 declare function getPredictiveSearchItemUrl(item: PredictiveSearchQueryItem, options?: PredictiveSearchQueryItemUrlOptions): string;
 declare function getPredictiveSearchItemUrl(item: PredictiveSearchResourceItem, options: PredictiveSearchItemUrlOptions): string;
 /**
- * Builds a search result URL from a base URL, search term, and optional
- * extra parameters.
+ * Builds a search page URL from a path, a search term, and optional extra
+ * parameters. Use the function for search page links, such as a link to every
+ * result for the current term.
+ *
+ * The search term and the extra parameters replace values with the same names in the base URL.
+ *
+ * @param options - The base URL, the search term, the extra and tracking parameters, and the search parameter name.
+ * @returns A relative URL, or an absolute URL when the base URL is absolute.
  *
- * Sets the term under `searchParamName` (defaults to `"q"`), replacing any
- * existing value. `params` are set the same way, and `trackingParameters`
- * are appended. Returns a relative URL unless the base
- * URL is absolute.
+ * @publicDocs
  */
 declare function getSearchResultUrl({
   baseUrl,

package/dist/core/predictive-search/url.mjs

@@ -2,6 +2,11 @@ import { getStandardRoute } from "../standard-routes/build.mjs";
 
 //#region src/core/predictive-search/url.ts
 const RELATIVE_URL_BASE = "https://hydrogen.local";
+/**
+* @param item The predictive search result to link to.
+* @param options Route templates, search term, and path settings for the link.
+* @returns The link URL. The URL is relative unless you pass an absolute search path.
+*/
 function getPredictiveSearchItemUrl(item, options) {
 	return getSearchResultUrl({
 		baseUrl: getPredictiveSearchItemBaseUrl(item, options),
@@ -10,13 +15,16 @@ function getPredictiveSearchItemUrl(item, options) {
 	});
 }
 /**
-* Builds a search result URL from a base URL, search term, and optional
-* extra parameters.
+* Builds a search page URL from a path, a search term, and optional extra
+* parameters. Use the function for search page links, such as a link to every
+* result for the current term.
+*
+* The search term and the extra parameters replace values with the same names in the base URL.
+*
+* @param options - The base URL, the search term, the extra and tracking parameters, and the search parameter name.
+* @returns A relative URL, or an absolute URL when the base URL is absolute.
 *
-* Sets the term under `searchParamName` (defaults to `"q"`), replacing any
-* existing value. `params` are set the same way, and `trackingParameters`
-* are appended. Returns a relative URL unless the base
-* URL is absolute.
+* @publicDocs
 */
 function getSearchResultUrl({ baseUrl, term, trackingParameters, params, searchParamName = "q" }) {
 	const url = new URL(baseUrl, RELATIVE_URL_BASE);

package/dist/core/predictive-search/url.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"url.mjs","names":[],"sources":["../../../src/core/predictive-search/url.ts"],"sourcesContent":["import { getStandardRoute, type ShopifyRouteTemplates } from \"../standard-routes/index\";\nimport type { PredictiveSearchData } from \"./search\";\n\nconst RELATIVE_URL_BASE = \"https://hydrogen.local\";\n\ntype PredictiveSearchItems = PredictiveSearchData[\"items\"];\n\n/** A product returned by predictive search. */\nexport type PredictiveSearchProductItem = PredictiveSearchItems[\"products\"][number];\n/** A collection returned by predictive search. */\nexport type PredictiveSearchCollectionItem = PredictiveSearchItems[\"collections\"][number];\n/** A page returned by predictive search. */\nexport type PredictiveSearchPageItem = PredictiveSearchItems[\"pages\"][number];\n/** An article returned by predictive search. Includes a nested `blog.handle` used for URL generation via {@link getPredictiveSearchItemUrl}. */\nexport type PredictiveSearchArticleItem = PredictiveSearchItems[\"articles\"][number];\n/** A search query suggestion returned by predictive search. Uses `text` as the search term when generating its URL via {@link getPredictiveSearchItemUrl}. */\nexport type PredictiveSearchQueryItem = PredictiveSearchItems[\"queries\"][number];\n\n/** Union of product, collection, page, and article items. Excludes query suggestions. */\nexport type PredictiveSearchResourceItem =\n  | PredictiveSearchProductItem\n  | PredictiveSearchCollectionItem\n  | PredictiveSearchPageItem\n  | PredictiveSearchArticleItem;\n\n/** Any item returned by predictive search, including query suggestions. */\nexport type PredictiveSearchItem = PredictiveSearchResourceItem | PredictiveSearchQueryItem;\n\n/**\n * Options for generating URLs for resource items (products, collections,\n * pages, articles) via {@link getPredictiveSearchItemUrl}.\n *\n * Required for resource items because their URLs depend on route templates\n * and the current search term.\n */\nexport type PredictiveSearchItemUrlOptions = {\n  /** Optional path prefix prepended to the generated route (e.g., a locale prefix). */\n  pathPrefix?: string;\n  /** Route templates used to resolve the resource's URL pattern. */\n  routes: ShopifyRouteTemplates;\n  /** Search term appended as a query parameter to the generated URL. */\n  term: string;\n};\n\n/**\n * Options for generating URLs for query suggestion items via\n * {@link getPredictiveSearchItemUrl}.\n *\n * Optional because query suggestions use their own `text` as the search\n * term and default to the standard search route.\n */\nexport type PredictiveSearchQueryItemUrlOptions = {\n  /** Optional path prefix prepended to the search route (e.g., a locale prefix). Ignored when `searchPath` is set. */\n  pathPrefix?: string;\n  /** Route templates. When omitted, the standard search route is used. */\n  routes?: ShopifyRouteTemplates;\n  /** Custom search page path, used as-is (no `pathPrefix` applied). Takes precedence over `routes` and `pathPrefix`. */\n  searchPath?: string;\n};\n\ntype AnyPredictiveSearchItemUrlOptions =\n  | PredictiveSearchItemUrlOptions\n  | PredictiveSearchQueryItemUrlOptions;\n\ntype SearchResultUrlOptions = {\n  /** Search page path or absolute URL. */\n  baseUrl: string;\n  /** Search term, set under `searchParamName`. */\n  term: string;\n  /** Storefront API `trackingParameters` query string, appended after the other parameters. */\n  trackingParameters?: string | null;\n  /** Extra query parameters, set before the term, so a key matching `searchParamName` is overwritten. */\n  params?: Record<string, string>;\n  /** Query parameter for the term. Defaults to `\"q\"`. */\n  searchParamName?: string;\n};\n\n/**\n * Generates a URL for a predictive search result item.\n *\n * For query suggestions, builds a search page URL using the suggestion's\n * `text` as the search term. For resource items (products, collections,\n * pages, articles), builds the resource URL using the provided route\n * templates and appends the given search term as a query parameter.\n *\n * Always appends the item's `trackingParameters` when present.\n *\n * @throws {Error} When a resource item is passed without `routes` and `term` in options.\n */\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchQueryItem,\n  options?: PredictiveSearchQueryItemUrlOptions,\n): string;\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchResourceItem,\n  options: PredictiveSearchItemUrlOptions,\n): string;\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchItem,\n  options?: AnyPredictiveSearchItemUrlOptions,\n): string {\n  return getSearchResultUrl({\n    baseUrl: getPredictiveSearchItemBaseUrl(item, options),\n    term: getPredictiveSearchItemSearchTerm(item, options),\n    trackingParameters: item.trackingParameters,\n  });\n}\n\n/**\n * Builds a search result URL from a base URL, search term, and optional\n * extra parameters.\n *\n * Sets the term under `searchParamName` (defaults to `\"q\"`), replacing any\n * existing value. `params` are set the same way, and `trackingParameters`\n * are appended. Returns a relative URL unless the base\n * URL is absolute.\n */\nexport function getSearchResultUrl({\n  baseUrl,\n  term,\n  trackingParameters,\n  params,\n  searchParamName = \"q\",\n}: SearchResultUrlOptions): string {\n  const url = new URL(baseUrl, RELATIVE_URL_BASE);\n\n  for (const [name, value] of Object.entries(params ?? {})) {\n    url.searchParams.set(name, value);\n  }\n\n  url.searchParams.set(searchParamName, term);\n  appendTrackingParameters(url.searchParams, trackingParameters);\n\n  if (isAbsoluteUrl(baseUrl)) return url.href;\n  return `${url.pathname}${url.search}${url.hash}`;\n}\n\nfunction getPredictiveSearchItemBaseUrl(\n  item: PredictiveSearchItem,\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): string {\n  if (item.__typename === \"SearchQuerySuggestion\") return getQueryBaseUrl(options);\n\n  const { pathPrefix, routes } = requirePredictiveSearchItemUrlOptions(options);\n  return getResourceBaseUrl(item, routes, pathPrefix);\n}\n\nfunction getQueryBaseUrl(options: AnyPredictiveSearchItemUrlOptions | undefined): string {\n  if (options && \"searchPath\" in options && options.searchPath) return options.searchPath;\n\n  return getStandardRoute(\n    options?.routes ?? {},\n    \"search\",\n    {},\n    {\n      pathPrefix: options?.pathPrefix,\n    },\n  );\n}\n\nfunction getResourceBaseUrl(\n  item: PredictiveSearchResourceItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  switch (item.__typename) {\n    case \"Product\":\n      return getProductBaseUrl(item, routes, pathPrefix);\n    case \"Collection\":\n      return getCollectionBaseUrl(item, routes, pathPrefix);\n    case \"Page\":\n      return getPageBaseUrl(item, routes, pathPrefix);\n    case \"Article\":\n      return getArticleBaseUrl(item, routes, pathPrefix);\n  }\n}\n\nfunction getProductBaseUrl(\n  product: PredictiveSearchProductItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(routes, \"product\", { productHandle: product.handle }, { pathPrefix });\n}\n\nfunction getCollectionBaseUrl(\n  collection: PredictiveSearchCollectionItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(\n    routes,\n    \"collection\",\n    { collectionHandle: collection.handle },\n    { pathPrefix },\n  );\n}\n\nfunction getPageBaseUrl(\n  page: PredictiveSearchPageItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(routes, \"page\", { pageHandle: page.handle }, { pathPrefix });\n}\n\nfunction getArticleBaseUrl(\n  article: PredictiveSearchArticleItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(\n    routes,\n    \"article\",\n    { articleHandle: article.handle, blogHandle: article.blog.handle },\n    { pathPrefix },\n  );\n}\n\nfunction getPredictiveSearchItemSearchTerm(\n  item: PredictiveSearchItem,\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): string {\n  if (item.__typename === \"SearchQuerySuggestion\") return item.text;\n  return requirePredictiveSearchItemUrlOptions(options).term;\n}\n\nfunction requirePredictiveSearchItemUrlOptions(\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): PredictiveSearchItemUrlOptions {\n  if (options && \"term\" in options && \"routes\" in options) return options;\n\n  throw new Error(\n    \"Predictive search resource URLs require route templates and the typed search term.\",\n  );\n}\n\nfunction appendTrackingParameters(params: URLSearchParams, trackingParameters?: string | null) {\n  if (!trackingParameters) return;\n\n  const tracking = new URLSearchParams(trackingParameters);\n  for (const [name, value] of tracking) {\n    params.append(name, value);\n  }\n}\n\nfunction isAbsoluteUrl(url: string): boolean {\n  return URL.canParse(url);\n}\n"],"mappings":";;;AAGA,MAAM,oBAAoB;AA8F1B,SAAgB,2BACd,MACA,SACQ;AACR,QAAO,mBAAmB;EACxB,SAAS,+BAA+B,MAAM,QAAQ;EACtD,MAAM,kCAAkC,MAAM,QAAQ;EACtD,oBAAoB,KAAK;EAC1B,CAAC;;;;;;;;;;;AAYJ,SAAgB,mBAAmB,EACjC,SACA,MACA,oBACA,QACA,kBAAkB,OACe;CACjC,MAAM,MAAM,IAAI,IAAI,SAAS,kBAAkB;AAE/C,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,UAAU,EAAE,CAAC,CACtD,KAAI,aAAa,IAAI,MAAM,MAAM;AAGnC,KAAI,aAAa,IAAI,iBAAiB,KAAK;AAC3C,0BAAyB,IAAI,cAAc,mBAAmB;AAE9D,KAAI,cAAc,QAAQ,CAAE,QAAO,IAAI;AACvC,QAAO,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI;;AAG5C,SAAS,+BACP,MACA,SACQ;AACR,KAAI,KAAK,eAAe,wBAAyB,QAAO,gBAAgB,QAAQ;CAEhF,MAAM,EAAE,YAAY,WAAW,sCAAsC,QAAQ;AAC7E,QAAO,mBAAmB,MAAM,QAAQ,WAAW;;AAGrD,SAAS,gBAAgB,SAAgE;AACvF,KAAI,WAAW,gBAAgB,WAAW,QAAQ,WAAY,QAAO,QAAQ;AAE7E,QAAO,iBACL,SAAS,UAAU,EAAE,EACrB,UACA,EAAE,EACF,EACE,YAAY,SAAS,YACtB,CACF;;AAGH,SAAS,mBACP,MACA,QACA,YACQ;AACR,SAAQ,KAAK,YAAb;EACE,KAAK,UACH,QAAO,kBAAkB,MAAM,QAAQ,WAAW;EACpD,KAAK,aACH,QAAO,qBAAqB,MAAM,QAAQ,WAAW;EACvD,KAAK,OACH,QAAO,eAAe,MAAM,QAAQ,WAAW;EACjD,KAAK,UACH,QAAO,kBAAkB,MAAM,QAAQ,WAAW;;;AAIxD,SAAS,kBACP,SACA,QACA,YACQ;AACR,QAAO,iBAAiB,QAAQ,WAAW,EAAE,eAAe,QAAQ,QAAQ,EAAE,EAAE,YAAY,CAAC;;AAG/F,SAAS,qBACP,YACA,QACA,YACQ;AACR,QAAO,iBACL,QACA,cACA,EAAE,kBAAkB,WAAW,QAAQ,EACvC,EAAE,YAAY,CACf;;AAGH,SAAS,eACP,MACA,QACA,YACQ;AACR,QAAO,iBAAiB,QAAQ,QAAQ,EAAE,YAAY,KAAK,QAAQ,EAAE,EAAE,YAAY,CAAC;;AAGtF,SAAS,kBACP,SACA,QACA,YACQ;AACR,QAAO,iBACL,QACA,WACA;EAAE,eAAe,QAAQ;EAAQ,YAAY,QAAQ,KAAK;EAAQ,EAClE,EAAE,YAAY,CACf;;AAGH,SAAS,kCACP,MACA,SACQ;AACR,KAAI,KAAK,eAAe,wBAAyB,QAAO,KAAK;AAC7D,QAAO,sCAAsC,QAAQ,CAAC;;AAGxD,SAAS,sCACP,SACgC;AAChC,KAAI,WAAW,UAAU,WAAW,YAAY,QAAS,QAAO;AAEhE,OAAM,IAAI,MACR,qFACD;;AAGH,SAAS,yBAAyB,QAAyB,oBAAoC;AAC7F,KAAI,CAAC,mBAAoB;CAEzB,MAAM,WAAW,IAAI,gBAAgB,mBAAmB;AACxD,MAAK,MAAM,CAAC,MAAM,UAAU,SAC1B,QAAO,OAAO,MAAM,MAAM;;AAI9B,SAAS,cAAc,KAAsB;AAC3C,QAAO,IAAI,SAAS,IAAI"}
+{"version":3,"file":"url.mjs","names":[],"sources":["../../../src/core/predictive-search/url.ts"],"sourcesContent":["import { getStandardRoute, type ShopifyRouteTemplates } from \"../standard-routes/index\";\nimport type { PredictiveSearchData } from \"./search\";\n\nconst RELATIVE_URL_BASE = \"https://hydrogen.local\";\n\ntype PredictiveSearchItems = PredictiveSearchData[\"items\"];\n\n/** A product result from predictive search. */\nexport type PredictiveSearchProductItem = PredictiveSearchItems[\"products\"][number];\n/** A collection result from predictive search. */\nexport type PredictiveSearchCollectionItem = PredictiveSearchItems[\"collections\"][number];\n/** A page result from predictive search. */\nexport type PredictiveSearchPageItem = PredictiveSearchItems[\"pages\"][number];\n/** An article result from predictive search. */\nexport type PredictiveSearchArticleItem = PredictiveSearchItems[\"articles\"][number];\n/** A suggested search term from predictive search. */\nexport type PredictiveSearchQueryItem = PredictiveSearchItems[\"queries\"][number];\n\n/** A product, collection, page, or article result. Excludes query suggestions. */\nexport type PredictiveSearchResourceItem =\n  | PredictiveSearchProductItem\n  | PredictiveSearchCollectionItem\n  | PredictiveSearchPageItem\n  | PredictiveSearchArticleItem;\n\n/** Any predictive search result, including query suggestions. */\nexport type PredictiveSearchItem = PredictiveSearchResourceItem | PredictiveSearchQueryItem;\n\n/**\n * Options for the link of a product, collection, page, or article result.\n *\n * Pass the route templates and the customer's search term.\n */\nexport type PredictiveSearchItemUrlOptions = {\n  /** Prefix to add before the route path, such as a locale prefix. */\n  pathPrefix?: string;\n  /** Route templates for product, collection, page, and article paths, from `createShopifyRouteTemplates`. */\n  routes: ShopifyRouteTemplates;\n  /** Search term that the customer typed. The link carries the term in the `q` URL parameter. */\n  term: string;\n};\n\n/**\n * Options for the link of a query suggestion.\n *\n * By default, a suggestion links to the standard search route and searches for the suggestion's text.\n */\nexport type PredictiveSearchQueryItemUrlOptions = {\n  /** Prefix to add before the search route, such as a locale prefix. Has no effect when you set a search path. */\n  pathPrefix?: string;\n  /** Route templates that set the search page path. Defaults to Hydrogen's standard search route. */\n  routes?: ShopifyRouteTemplates;\n  /** Search page path or URL to use as is, without the route templates or the path prefix. */\n  searchPath?: string;\n};\n\n/** URL options for any predictive search result, either resource options or query suggestion options. */\ntype AnyPredictiveSearchItemUrlOptions =\n  | PredictiveSearchItemUrlOptions\n  | PredictiveSearchQueryItemUrlOptions;\n\n/** Options for a search result URL. */\ntype SearchResultUrlOptions = {\n  /** Search page path or absolute URL. */\n  baseUrl: string;\n  /** Search term to add to the URL. */\n  term: string;\n  /** Tracking parameters from a Storefront API search result. Pass the result's `trackingParameters` value unchanged. */\n  trackingParameters?: string | null;\n  /** Extra URL parameters, such as a result type filter. The search term replaces an extra parameter with the same name. */\n  params?: Record<string, string>;\n  /** URL parameter that carries the search term. Defaults to `q`. */\n  searchParamName?: string;\n};\n\n/**\n * Builds the link for a predictive search result. A product, collection, page, or\n * article result links to the resource's page with the search term. A query suggestion links to\n * the search page and searches for the suggestion's text. Every link keeps the\n * result's tracking parameters.\n *\n * For a product, collection, page, or article, pass the route templates and the search term. The function throws an error without them.\n *\n * @throws {Error} When you pass a resource item without `routes` and `term` in the options.\n * @publicDocs\n */\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchQueryItem,\n  options?: PredictiveSearchQueryItemUrlOptions,\n): string;\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchResourceItem,\n  options: PredictiveSearchItemUrlOptions,\n): string;\n/**\n * @param item The predictive search result to link to.\n * @param options Route templates, search term, and path settings for the link.\n * @returns The link URL. The URL is relative unless you pass an absolute search path.\n */\nexport function getPredictiveSearchItemUrl(\n  item: PredictiveSearchItem,\n  options?: AnyPredictiveSearchItemUrlOptions,\n): string {\n  return getSearchResultUrl({\n    baseUrl: getPredictiveSearchItemBaseUrl(item, options),\n    term: getPredictiveSearchItemSearchTerm(item, options),\n    trackingParameters: item.trackingParameters,\n  });\n}\n\n/**\n * Builds a search page URL from a path, a search term, and optional extra\n * parameters. Use the function for search page links, such as a link to every\n * result for the current term.\n *\n * The search term and the extra parameters replace values with the same names in the base URL.\n *\n * @param options - The base URL, the search term, the extra and tracking parameters, and the search parameter name.\n * @returns A relative URL, or an absolute URL when the base URL is absolute.\n *\n * @publicDocs\n */\nexport function getSearchResultUrl({\n  baseUrl,\n  term,\n  trackingParameters,\n  params,\n  searchParamName = \"q\",\n}: SearchResultUrlOptions): string {\n  const url = new URL(baseUrl, RELATIVE_URL_BASE);\n\n  for (const [name, value] of Object.entries(params ?? {})) {\n    url.searchParams.set(name, value);\n  }\n\n  url.searchParams.set(searchParamName, term);\n  appendTrackingParameters(url.searchParams, trackingParameters);\n\n  if (isAbsoluteUrl(baseUrl)) return url.href;\n  return `${url.pathname}${url.search}${url.hash}`;\n}\n\nfunction getPredictiveSearchItemBaseUrl(\n  item: PredictiveSearchItem,\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): string {\n  if (item.__typename === \"SearchQuerySuggestion\") return getQueryBaseUrl(options);\n\n  const { pathPrefix, routes } = requirePredictiveSearchItemUrlOptions(options);\n  return getResourceBaseUrl(item, routes, pathPrefix);\n}\n\nfunction getQueryBaseUrl(options: AnyPredictiveSearchItemUrlOptions | undefined): string {\n  if (options && \"searchPath\" in options && options.searchPath) return options.searchPath;\n\n  return getStandardRoute(\n    options?.routes ?? {},\n    \"search\",\n    {},\n    {\n      pathPrefix: options?.pathPrefix,\n    },\n  );\n}\n\nfunction getResourceBaseUrl(\n  item: PredictiveSearchResourceItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  switch (item.__typename) {\n    case \"Product\":\n      return getProductBaseUrl(item, routes, pathPrefix);\n    case \"Collection\":\n      return getCollectionBaseUrl(item, routes, pathPrefix);\n    case \"Page\":\n      return getPageBaseUrl(item, routes, pathPrefix);\n    case \"Article\":\n      return getArticleBaseUrl(item, routes, pathPrefix);\n  }\n}\n\nfunction getProductBaseUrl(\n  product: PredictiveSearchProductItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(routes, \"product\", { productHandle: product.handle }, { pathPrefix });\n}\n\nfunction getCollectionBaseUrl(\n  collection: PredictiveSearchCollectionItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(\n    routes,\n    \"collection\",\n    { collectionHandle: collection.handle },\n    { pathPrefix },\n  );\n}\n\nfunction getPageBaseUrl(\n  page: PredictiveSearchPageItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(routes, \"page\", { pageHandle: page.handle }, { pathPrefix });\n}\n\nfunction getArticleBaseUrl(\n  article: PredictiveSearchArticleItem,\n  routes: ShopifyRouteTemplates,\n  pathPrefix: string | undefined,\n): string {\n  return getStandardRoute(\n    routes,\n    \"article\",\n    { articleHandle: article.handle, blogHandle: article.blog.handle },\n    { pathPrefix },\n  );\n}\n\nfunction getPredictiveSearchItemSearchTerm(\n  item: PredictiveSearchItem,\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): string {\n  if (item.__typename === \"SearchQuerySuggestion\") return item.text;\n  return requirePredictiveSearchItemUrlOptions(options).term;\n}\n\nfunction requirePredictiveSearchItemUrlOptions(\n  options: AnyPredictiveSearchItemUrlOptions | undefined,\n): PredictiveSearchItemUrlOptions {\n  if (options && \"term\" in options && \"routes\" in options) return options;\n\n  throw new Error(\n    \"Predictive search resource URLs require route templates and the typed search term.\",\n  );\n}\n\nfunction appendTrackingParameters(params: URLSearchParams, trackingParameters?: string | null) {\n  if (!trackingParameters) return;\n\n  const tracking = new URLSearchParams(trackingParameters);\n  for (const [name, value] of tracking) {\n    params.append(name, value);\n  }\n}\n\nfunction isAbsoluteUrl(url: string): boolean {\n  return URL.canParse(url);\n}\n"],"mappings":";;;AAGA,MAAM,oBAAoB;;;;;;AAgG1B,SAAgB,2BACd,MACA,SACQ;AACR,QAAO,mBAAmB;EACxB,SAAS,+BAA+B,MAAM,QAAQ;EACtD,MAAM,kCAAkC,MAAM,QAAQ;EACtD,oBAAoB,KAAK;EAC1B,CAAC;;;;;;;;;;;;;;AAeJ,SAAgB,mBAAmB,EACjC,SACA,MACA,oBACA,QACA,kBAAkB,OACe;CACjC,MAAM,MAAM,IAAI,IAAI,SAAS,kBAAkB;AAE/C,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,UAAU,EAAE,CAAC,CACtD,KAAI,aAAa,IAAI,MAAM,MAAM;AAGnC,KAAI,aAAa,IAAI,iBAAiB,KAAK;AAC3C,0BAAyB,IAAI,cAAc,mBAAmB;AAE9D,KAAI,cAAc,QAAQ,CAAE,QAAO,IAAI;AACvC,QAAO,GAAG,IAAI,WAAW,IAAI,SAAS,IAAI;;AAG5C,SAAS,+BACP,MACA,SACQ;AACR,KAAI,KAAK,eAAe,wBAAyB,QAAO,gBAAgB,QAAQ;CAEhF,MAAM,EAAE,YAAY,WAAW,sCAAsC,QAAQ;AAC7E,QAAO,mBAAmB,MAAM,QAAQ,WAAW;;AAGrD,SAAS,gBAAgB,SAAgE;AACvF,KAAI,WAAW,gBAAgB,WAAW,QAAQ,WAAY,QAAO,QAAQ;AAE7E,QAAO,iBACL,SAAS,UAAU,EAAE,EACrB,UACA,EAAE,EACF,EACE,YAAY,SAAS,YACtB,CACF;;AAGH,SAAS,mBACP,MACA,QACA,YACQ;AACR,SAAQ,KAAK,YAAb;EACE,KAAK,UACH,QAAO,kBAAkB,MAAM,QAAQ,WAAW;EACpD,KAAK,aACH,QAAO,qBAAqB,MAAM,QAAQ,WAAW;EACvD,KAAK,OACH,QAAO,eAAe,MAAM,QAAQ,WAAW;EACjD,KAAK,UACH,QAAO,kBAAkB,MAAM,QAAQ,WAAW;;;AAIxD,SAAS,kBACP,SACA,QACA,YACQ;AACR,QAAO,iBAAiB,QAAQ,WAAW,EAAE,eAAe,QAAQ,QAAQ,EAAE,EAAE,YAAY,CAAC;;AAG/F,SAAS,qBACP,YACA,QACA,YACQ;AACR,QAAO,iBACL,QACA,cACA,EAAE,kBAAkB,WAAW,QAAQ,EACvC,EAAE,YAAY,CACf;;AAGH,SAAS,eACP,MACA,QACA,YACQ;AACR,QAAO,iBAAiB,QAAQ,QAAQ,EAAE,YAAY,KAAK,QAAQ,EAAE,EAAE,YAAY,CAAC;;AAGtF,SAAS,kBACP,SACA,QACA,YACQ;AACR,QAAO,iBACL,QACA,WACA;EAAE,eAAe,QAAQ;EAAQ,YAAY,QAAQ,KAAK;EAAQ,EAClE,EAAE,YAAY,CACf;;AAGH,SAAS,kCACP,MACA,SACQ;AACR,KAAI,KAAK,eAAe,wBAAyB,QAAO,KAAK;AAC7D,QAAO,sCAAsC,QAAQ,CAAC;;AAGxD,SAAS,sCACP,SACgC;AAChC,KAAI,WAAW,UAAU,WAAW,YAAY,QAAS,QAAO;AAEhE,OAAM,IAAI,MACR,qFACD;;AAGH,SAAS,yBAAyB,QAAyB,oBAAoC;AAC7F,KAAI,CAAC,mBAAoB;CAEzB,MAAM,WAAW,IAAI,gBAAgB,mBAAmB;AACxD,MAAK,MAAM,CAAC,MAAM,UAAU,SAC1B,QAAO,OAAO,MAAM,MAAM;;AAI9B,SAAS,cAAc,KAAsB;AAC3C,QAAO,IAAI,SAAS,IAAI"}

package/dist/core/product/form.d.mts

@@ -1,54 +1,95 @@
 import { ProductVariantInput } from "./state.mjs";
 
 //#region src/core/product/form.d.ts
-/** Props returned by {@link ProductFormRegister} for the `merchandiseId` input. */
+/**
+ * Props for the hidden input that tells the cart which variant to add.
+ *
+ * @publicDocs
+ */
 interface ProductMerchandiseIdProps {
+  /** Field name that the cart reads as the variant to add. */
   name: "merchandiseId";
-  /** The currently selected variant ID, or an empty string when no variant is resolved. */
+  /** Selected variant ID. Empty when the selection doesn't resolve to a variant. */
   value: string;
 }
-/** Props returned by {@link ProductFormRegister} for a quantity input. */
+/**
+ * Props for a controlled quantity input.
+ *
+ * @publicDocs
+ */
 interface ProductQuantityProps {
+  /** Field name that the cart reads as the quantity to add. */
   name: "quantity";
+  /** Quantity to add. Defaults to `1`. */
   value: string;
 }
-/** Props returned by {@link ProductFormRegister} for an uncontrolled quantity input. */
+/**
+ * Props for an uncontrolled quantity input.
+ *
+ * @publicDocs
+ */
 interface ProductQuantityDefaultProps {
+  /** Field name that the cart reads as the quantity to add. */
   name: "quantity";
+  /** Starting quantity for the input. */
   defaultValue: string;
 }
-/** Props returned by {@link ProductFormRegister} for a variant option value control. */
+/**
+ * Props for a control that selects one option value, such as a swatch or a radio button.
+ *
+ * @publicDocs
+ */
 interface ProductOptionValueProps {
+  /** Option name, such as "Color". */
   name: string;
+  /** Option value that the control selects, such as "Red". */
   value: string;
+  /** Selects the option value in the product form. */
   onChange: () => void;
+  /** Selects the option value in the product form. Matches the change handler. */
   onClick: () => void;
 }
-/** Props returned by {@link ProductFormRegister} for the add-to-cart submit button. */
+/**
+ * Props for the button that submits the product form and adds the selected variant to the cart.
+ *
+ * @publicDocs
+ */
 interface ProductAddToCartProps {
+  /** Identifies the add-to-cart button. The button has no value, which tells the cart to add the variant from the merchandise ID field. */
   name: "add-to-cart";
+  /** Makes the button submit the product form. */
   type: "submit";
 }
+/** Line-item attribute field name. The cart uses the text after `attributes.` as the attribute key. */
 type AttributeValueName = `attributes.${string}`;
-/** Props returned by {@link ProductFormRegister} for a line-item attribute input. */
+/**
+ * Props for an input that adds a custom attribute to the cart line, such as a gift message.
+ *
+ * @publicDocs
+ */
 interface ProductAttributeValueProps {
+  /** Field name in the format `attributes.<key>`. The cart saves the key and value as an attribute of the cart line. */
   name: AttributeValueName;
+  /** Attribute value to save on the cart line. */
   value: string;
 }
-/** Props returned by {@link ProductFormRegister} for an uncontrolled line-item attribute input. */
+/**
+ * Props for an uncontrolled input that adds a custom attribute to the cart line.
+ *
+ * @publicDocs
+ */
 interface ProductAttributeDefaultValueProps {
+  /** Field name in the format `attributes.<key>`. The cart saves the key and value as an attribute of the cart line. */
   name: AttributeValueName;
+  /** Starting attribute value for the input. */
   defaultValue: string;
 }
 /**
- * Register function returned by `useProductForm`.
+ * Returns the props for one product form field. Spread the props on the matching input or button.
  *
- * Product forms only register product-relevant fields:
- * `merchandiseId`, `quantity`, `optionValue`, `attributeValue`, and `addToCart`.
+ * Pass `merchandiseId`, `quantity`, `optionValue`, `attributeValue`, or `addToCart` as the field. Any other field name throws an error. An attribute value field with an empty key throws a `TypeError`.
  *
- * Option values return form identity and activation handlers. UI props such as
- * `type`, `checked`, `disabled`, and `aria-pressed` belong to the caller — use
- * the state available on `options` (e.g. `value.selected`, `value.available`).
+ * Option value fields return the name, the value, and the selection handlers. Set the input type and the checked, disabled, and pressed states from the option state yourself.
  */
 type ProductFormRegister = {
   (field: "merchandiseId", opts: {}): ProductMerchandiseIdProps;
@@ -73,8 +114,14 @@ type ProductFormRegister = {
   (field: "addToCart", opts: {}): ProductAddToCartProps;
 };
 /**
- * Creates a {@link ProductFormRegister} function bound to the current variant
- * state and `selectOption` dispatcher.
+ * Creates the register function that returns props for each product form field.
+ *
+ * The merchandise ID field submits the variant that you pass at creation. Create a new register function each time the product form state changes. The product form hooks create a new register function for you.
+ *
+ * @param selectedVariant The variant that the merchandise ID field submits, or `null` when the selection doesn't resolve to a variant.
+ * @param selectOption The function that option value fields call with the option name and value.
+ * @returns A register function for the merchandise ID, quantity, option value, attribute, and add-to-cart fields.
+ * @publicDocs
  */
 declare function createProductFormRegister(selectedVariant: ProductVariantInput | null, selectOption: (name: string, value: string) => void): ProductFormRegister;
 //#endregion

package/dist/core/product/form.mjs

@@ -1,7 +1,13 @@
 //#region src/core/product/form.ts
 /**
-* Creates a {@link ProductFormRegister} function bound to the current variant
-* state and `selectOption` dispatcher.
+* Creates the register function that returns props for each product form field.
+*
+* The merchandise ID field submits the variant that you pass at creation. Create a new register function each time the product form state changes. The product form hooks create a new register function for you.
+*
+* @param selectedVariant The variant that the merchandise ID field submits, or `null` when the selection doesn't resolve to a variant.
+* @param selectOption The function that option value fields call with the option name and value.
+* @returns A register function for the merchandise ID, quantity, option value, attribute, and add-to-cart fields.
+* @publicDocs
 */
 function createProductFormRegister(selectedVariant, selectOption) {
 	return ((field, opts) => {

package/dist/core/product/form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"form.mjs","names":[],"sources":["../../../src/core/product/form.ts"],"sourcesContent":["import type { ProductVariantInput } from \"./state\";\n\n/** Props returned by {@link ProductFormRegister} for the `merchandiseId` input. */\nexport interface ProductMerchandiseIdProps {\n  name: \"merchandiseId\";\n  /** The currently selected variant ID, or an empty string when no variant is resolved. */\n  value: string;\n}\n\n/** Props returned by {@link ProductFormRegister} for a quantity input. */\nexport interface ProductQuantityProps {\n  name: \"quantity\";\n  value: string;\n}\n\n/** Props returned by {@link ProductFormRegister} for an uncontrolled quantity input. */\nexport interface ProductQuantityDefaultProps {\n  name: \"quantity\";\n  defaultValue: string;\n}\n\n/** Props returned by {@link ProductFormRegister} for a variant option value control. */\nexport interface ProductOptionValueProps {\n  name: string;\n  value: string;\n  onChange: () => void;\n  onClick: () => void;\n}\n\n/** Props returned by {@link ProductFormRegister} for the add-to-cart submit button. */\nexport interface ProductAddToCartProps {\n  name: \"add-to-cart\";\n  type: \"submit\";\n}\n\ntype AttributeValueName = `attributes.${string}`;\n\n/** Props returned by {@link ProductFormRegister} for a line-item attribute input. */\nexport interface ProductAttributeValueProps {\n  name: AttributeValueName;\n  value: string;\n}\n\n/** Props returned by {@link ProductFormRegister} for an uncontrolled line-item attribute input. */\nexport interface ProductAttributeDefaultValueProps {\n  name: AttributeValueName;\n  defaultValue: string;\n}\n\n/**\n * Register function returned by `useProductForm`.\n *\n * Product forms only register product-relevant fields:\n * `merchandiseId`, `quantity`, `optionValue`, `attributeValue`, and `addToCart`.\n *\n * Option values return form identity and activation handlers. UI props such as\n * `type`, `checked`, `disabled`, and `aria-pressed` belong to the caller — use\n * the state available on `options` (e.g. `value.selected`, `value.available`).\n */\nexport type ProductFormRegister = {\n  (field: \"merchandiseId\", opts: {}): ProductMerchandiseIdProps;\n  (field: \"quantity\", opts: { value: number }): ProductQuantityProps;\n  (field: \"quantity\", opts: { defaultValue: number }): ProductQuantityDefaultProps;\n  (field: \"optionValue\", opts: { optionName: string; value: string }): ProductOptionValueProps;\n  (field: \"attributeValue\", opts: { key: string; value: string }): ProductAttributeValueProps;\n  (\n    field: \"attributeValue\",\n    opts: { key: string; defaultValue: string },\n  ): ProductAttributeDefaultValueProps;\n  (field: \"addToCart\", opts: {}): ProductAddToCartProps;\n};\n\n/**\n * Creates a {@link ProductFormRegister} function bound to the current variant\n * state and `selectOption` dispatcher.\n */\nexport function createProductFormRegister(\n  selectedVariant: ProductVariantInput | null,\n  selectOption: (name: string, value: string) => void,\n): ProductFormRegister {\n  return ((field: string, opts?: Record<string, unknown>) => {\n    if (field === \"merchandiseId\") {\n      return { name: \"merchandiseId\", value: selectedVariant?.id ?? \"\" };\n    }\n\n    if (field === \"quantity\") {\n      if (typeof opts?.defaultValue === \"number\") {\n        return { name: \"quantity\" as const, defaultValue: String(opts.defaultValue) };\n      }\n      const value = typeof opts?.value === \"number\" ? opts.value : 1;\n      return { name: \"quantity\" as const, value: String(value) };\n    }\n\n    if (field === \"optionValue\") {\n      const optionName = String(opts?.optionName ?? \"\");\n      const value = String(opts?.value ?? \"\");\n      const handleSelect = () => selectOption(optionName, value);\n      return { name: optionName, value, onChange: handleSelect, onClick: handleSelect };\n    }\n\n    if (field === \"attributeValue\") {\n      const key = String(opts?.key ?? \"\");\n      if (!key) throw new TypeError('Product attribute values require a non-empty \"key\".');\n      const name = `attributes.${key}` as AttributeValueName;\n      if (opts && \"defaultValue\" in opts) {\n        return { name, defaultValue: String(opts.defaultValue) };\n      }\n      return { name, value: String(opts?.value ?? \"\") };\n    }\n\n    if (field === \"addToCart\") {\n      return { name: \"add-to-cart\", type: \"submit\" } satisfies ProductAddToCartProps;\n    }\n\n    throw new Error(`Unknown product form field: \"${field}\".`);\n  }) as ProductFormRegister;\n}\n"],"mappings":";;;;;AA4EA,SAAgB,0BACd,iBACA,cACqB;AACrB,UAAS,OAAe,SAAmC;AACzD,MAAI,UAAU,gBACZ,QAAO;GAAE,MAAM;GAAiB,OAAO,iBAAiB,MAAM;GAAI;AAGpE,MAAI,UAAU,YAAY;AACxB,OAAI,OAAO,MAAM,iBAAiB,SAChC,QAAO;IAAE,MAAM;IAAqB,cAAc,OAAO,KAAK,aAAa;IAAE;GAE/E,MAAM,QAAQ,OAAO,MAAM,UAAU,WAAW,KAAK,QAAQ;AAC7D,UAAO;IAAE,MAAM;IAAqB,OAAO,OAAO,MAAM;IAAE;;AAG5D,MAAI,UAAU,eAAe;GAC3B,MAAM,aAAa,OAAO,MAAM,cAAc,GAAG;GACjD,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAG;GACvC,MAAM,qBAAqB,aAAa,YAAY,MAAM;AAC1D,UAAO;IAAE,MAAM;IAAY;IAAO,UAAU;IAAc,SAAS;IAAc;;AAGnF,MAAI,UAAU,kBAAkB;GAC9B,MAAM,MAAM,OAAO,MAAM,OAAO,GAAG;AACnC,OAAI,CAAC,IAAK,OAAM,IAAI,UAAU,wDAAsD;GACpF,MAAM,OAAO,cAAc;AAC3B,OAAI,QAAQ,kBAAkB,KAC5B,QAAO;IAAE;IAAM,cAAc,OAAO,KAAK,aAAa;IAAE;AAE1D,UAAO;IAAE;IAAM,OAAO,OAAO,MAAM,SAAS,GAAG;IAAE;;AAGnD,MAAI,UAAU,YACZ,QAAO;GAAE,MAAM;GAAe,MAAM;GAAU;AAGhD,QAAM,IAAI,MAAM,gCAAgC,MAAM,IAAI"}
+{"version":3,"file":"form.mjs","names":[],"sources":["../../../src/core/product/form.ts"],"sourcesContent":["import type { ProductVariantInput } from \"./state\";\n\n/**\n * Props for the hidden input that tells the cart which variant to add.\n *\n * @publicDocs\n */\nexport interface ProductMerchandiseIdProps {\n  /** Field name that the cart reads as the variant to add. */\n  name: \"merchandiseId\";\n  /** Selected variant ID. Empty when the selection doesn't resolve to a variant. */\n  value: string;\n}\n\n/**\n * Props for a controlled quantity input.\n *\n * @publicDocs\n */\nexport interface ProductQuantityProps {\n  /** Field name that the cart reads as the quantity to add. */\n  name: \"quantity\";\n  /** Quantity to add. Defaults to `1`. */\n  value: string;\n}\n\n/**\n * Props for an uncontrolled quantity input.\n *\n * @publicDocs\n */\nexport interface ProductQuantityDefaultProps {\n  /** Field name that the cart reads as the quantity to add. */\n  name: \"quantity\";\n  /** Starting quantity for the input. */\n  defaultValue: string;\n}\n\n/**\n * Props for a control that selects one option value, such as a swatch or a radio button.\n *\n * @publicDocs\n */\nexport interface ProductOptionValueProps {\n  /** Option name, such as \"Color\". */\n  name: string;\n  /** Option value that the control selects, such as \"Red\". */\n  value: string;\n  /** Selects the option value in the product form. */\n  onChange: () => void;\n  /** Selects the option value in the product form. Matches the change handler. */\n  onClick: () => void;\n}\n\n/**\n * Props for the button that submits the product form and adds the selected variant to the cart.\n *\n * @publicDocs\n */\nexport interface ProductAddToCartProps {\n  /** Identifies the add-to-cart button. The button has no value, which tells the cart to add the variant from the merchandise ID field. */\n  name: \"add-to-cart\";\n  /** Makes the button submit the product form. */\n  type: \"submit\";\n}\n\n/** Line-item attribute field name. The cart uses the text after `attributes.` as the attribute key. */\ntype AttributeValueName = `attributes.${string}`;\n\n/**\n * Props for an input that adds a custom attribute to the cart line, such as a gift message.\n *\n * @publicDocs\n */\nexport interface ProductAttributeValueProps {\n  /** Field name in the format `attributes.<key>`. The cart saves the key and value as an attribute of the cart line. */\n  name: AttributeValueName;\n  /** Attribute value to save on the cart line. */\n  value: string;\n}\n\n/**\n * Props for an uncontrolled input that adds a custom attribute to the cart line.\n *\n * @publicDocs\n */\nexport interface ProductAttributeDefaultValueProps {\n  /** Field name in the format `attributes.<key>`. The cart saves the key and value as an attribute of the cart line. */\n  name: AttributeValueName;\n  /** Starting attribute value for the input. */\n  defaultValue: string;\n}\n\n/**\n * Returns the props for one product form field. Spread the props on the matching input or button.\n *\n * Pass `merchandiseId`, `quantity`, `optionValue`, `attributeValue`, or `addToCart` as the field. Any other field name throws an error. An attribute value field with an empty key throws a `TypeError`.\n *\n * Option value fields return the name, the value, and the selection handlers. Set the input type and the checked, disabled, and pressed states from the option state yourself.\n */\nexport type ProductFormRegister = {\n  (field: \"merchandiseId\", opts: {}): ProductMerchandiseIdProps;\n  (field: \"quantity\", opts: { value: number }): ProductQuantityProps;\n  (field: \"quantity\", opts: { defaultValue: number }): ProductQuantityDefaultProps;\n  (field: \"optionValue\", opts: { optionName: string; value: string }): ProductOptionValueProps;\n  (field: \"attributeValue\", opts: { key: string; value: string }): ProductAttributeValueProps;\n  (\n    field: \"attributeValue\",\n    opts: { key: string; defaultValue: string },\n  ): ProductAttributeDefaultValueProps;\n  (field: \"addToCart\", opts: {}): ProductAddToCartProps;\n};\n\n/**\n * Creates the register function that returns props for each product form field.\n *\n * The merchandise ID field submits the variant that you pass at creation. Create a new register function each time the product form state changes. The product form hooks create a new register function for you.\n *\n * @param selectedVariant The variant that the merchandise ID field submits, or `null` when the selection doesn't resolve to a variant.\n * @param selectOption The function that option value fields call with the option name and value.\n * @returns A register function for the merchandise ID, quantity, option value, attribute, and add-to-cart fields.\n * @publicDocs\n */\nexport function createProductFormRegister(\n  selectedVariant: ProductVariantInput | null,\n  selectOption: (name: string, value: string) => void,\n): ProductFormRegister {\n  return ((field: string, opts?: Record<string, unknown>) => {\n    if (field === \"merchandiseId\") {\n      return { name: \"merchandiseId\", value: selectedVariant?.id ?? \"\" };\n    }\n\n    if (field === \"quantity\") {\n      if (typeof opts?.defaultValue === \"number\") {\n        return { name: \"quantity\" as const, defaultValue: String(opts.defaultValue) };\n      }\n      const value = typeof opts?.value === \"number\" ? opts.value : 1;\n      return { name: \"quantity\" as const, value: String(value) };\n    }\n\n    if (field === \"optionValue\") {\n      const optionName = String(opts?.optionName ?? \"\");\n      const value = String(opts?.value ?? \"\");\n      const handleSelect = () => selectOption(optionName, value);\n      return { name: optionName, value, onChange: handleSelect, onClick: handleSelect };\n    }\n\n    if (field === \"attributeValue\") {\n      const key = String(opts?.key ?? \"\");\n      if (!key) throw new TypeError('Product attribute values require a non-empty \"key\".');\n      const name = `attributes.${key}` as AttributeValueName;\n      if (opts && \"defaultValue\" in opts) {\n        return { name, defaultValue: String(opts.defaultValue) };\n      }\n      return { name, value: String(opts?.value ?? \"\") };\n    }\n\n    if (field === \"addToCart\") {\n      return { name: \"add-to-cart\", type: \"submit\" } satisfies ProductAddToCartProps;\n    }\n\n    throw new Error(`Unknown product form field: \"${field}\".`);\n  }) as ProductFormRegister;\n}\n"],"mappings":";;;;;;;;;;;AA2HA,SAAgB,0BACd,iBACA,cACqB;AACrB,UAAS,OAAe,SAAmC;AACzD,MAAI,UAAU,gBACZ,QAAO;GAAE,MAAM;GAAiB,OAAO,iBAAiB,MAAM;GAAI;AAGpE,MAAI,UAAU,YAAY;AACxB,OAAI,OAAO,MAAM,iBAAiB,SAChC,QAAO;IAAE,MAAM;IAAqB,cAAc,OAAO,KAAK,aAAa;IAAE;GAE/E,MAAM,QAAQ,OAAO,MAAM,UAAU,WAAW,KAAK,QAAQ;AAC7D,UAAO;IAAE,MAAM;IAAqB,OAAO,OAAO,MAAM;IAAE;;AAG5D,MAAI,UAAU,eAAe;GAC3B,MAAM,aAAa,OAAO,MAAM,cAAc,GAAG;GACjD,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAG;GACvC,MAAM,qBAAqB,aAAa,YAAY,MAAM;AAC1D,UAAO;IAAE,MAAM;IAAY;IAAO,UAAU;IAAc,SAAS;IAAc;;AAGnF,MAAI,UAAU,kBAAkB;GAC9B,MAAM,MAAM,OAAO,MAAM,OAAO,GAAG;AACnC,OAAI,CAAC,IAAK,OAAM,IAAI,UAAU,wDAAsD;GACpF,MAAM,OAAO,cAAc;AAC3B,OAAI,QAAQ,kBAAkB,KAC5B,QAAO;IAAE;IAAM,cAAc,OAAO,KAAK,aAAa;IAAE;AAE1D,UAAO;IAAE;IAAM,OAAO,OAAO,MAAM,SAAS,GAAG;IAAE;;AAGnD,MAAI,UAAU,YACZ,QAAO;GAAE,MAAM;GAAe,MAAM;GAAU;AAGhD,QAAM,IAAI,MAAM,gCAAgC,MAAM,IAAI"}

package/dist/core/product/options.d.mts

@@ -2,20 +2,17 @@ import { SelectedOption } from "./state.mjs";
 
 //#region src/core/product/options.d.ts
 /**
- * Extracts selected product options from search params.
+ * Reads the customer's option selection from a product URL's search params.
  *
- * Each query parameter is treated as an option name/value pair
- * (e.g. `?Color=Red&Size=M` → `[{name:"Color",value:"Red"},{name:"Size",value:"M"}]`).
+ * Each param becomes an option name and value. For example, `?Color=Red&Size=M`
+ * becomes Color set to Red and Size set to M. The function always skips the `variant` param,
+ * which holds a numeric variant ID in Liquid storefront URLs.
  *
- * The `variant` param is reserved for numeric variant ids (Liquid parity) and is
- * never treated as an option name, even when listed in `allowedOptionNames`.
+ * Pass the result as the `selectedOptions` argument of your Storefront API product query, or as the starting selection of a product form store.
  *
- * When `allowedOptionNames` is provided, the search params are filtered to only
- * entries whose decoded param name exactly matches a product option name.
- * Passing an empty array filters out every option.
+ * @param input The search params to read and an optional list of allowed option names. With `allowedOptionNames`, the function keeps only params whose name exactly matches an allowed name, and an empty list keeps no params. Pass the product's option names to keep unrelated params out of the selection.
  *
- * Pass the result to `createProductFormStore` as `selectedOptions`. Used as a
- * fallback when the product has no `selectedOrFirstAvailableVariant`.
+ * @returns The selected options, in the order that they appear in the URL.
  *
  * @example
  * ```ts
@@ -30,6 +27,7 @@ import { SelectedOption } from "./state.mjs";
  *   allowedOptionNames: product.options.map((option) => option.name),
  * });
  * ```
+ * @publicDocs
  */
 declare function getSelectedProductOptions({
   searchParams,

package/dist/core/product/options.mjs

@@ -5,20 +5,17 @@ import { VARIANT_SEARCH_PARAM } from "./url.mjs";
 const log = getLogger("product");
 const INCLUSIVE_RANGE_END_OFFSET = 1;
 /**
-* Extracts selected product options from search params.
+* Reads the customer's option selection from a product URL's search params.
 *
-* Each query parameter is treated as an option name/value pair
-* (e.g. `?Color=Red&Size=M` → `[{name:"Color",value:"Red"},{name:"Size",value:"M"}]`).
+* Each param becomes an option name and value. For example, `?Color=Red&Size=M`
+* becomes Color set to Red and Size set to M. The function always skips the `variant` param,
+* which holds a numeric variant ID in Liquid storefront URLs.
 *
-* The `variant` param is reserved for numeric variant ids (Liquid parity) and is
-* never treated as an option name, even when listed in `allowedOptionNames`.
+* Pass the result as the `selectedOptions` argument of your Storefront API product query, or as the starting selection of a product form store.
 *
-* When `allowedOptionNames` is provided, the search params are filtered to only
-* entries whose decoded param name exactly matches a product option name.
-* Passing an empty array filters out every option.
+* @param input The search params to read and an optional list of allowed option names. With `allowedOptionNames`, the function keeps only params whose name exactly matches an allowed name, and an empty list keeps no params. Pass the product's option names to keep unrelated params out of the selection.
 *
-* Pass the result to `createProductFormStore` as `selectedOptions`. Used as a
-* fallback when the product has no `selectedOrFirstAvailableVariant`.
+* @returns The selected options, in the order that they appear in the URL.
 *
 * @example
 * ```ts
@@ -33,6 +30,7 @@ const INCLUSIVE_RANGE_END_OFFSET = 1;
 *   allowedOptionNames: product.options.map((option) => option.name),
 * });
 * ```
+* @publicDocs
 */
 function getSelectedProductOptions({ searchParams, allowedOptionNames }) {
 	const allowedOptionNameSet = allowedOptionNames ? new Set(allowedOptionNames) : null;