@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/react/predictive-search.d.mts

@@ -10,47 +10,69 @@ type PredictiveSearchContextValue = {
   actions: PredictiveSearchActions;
   searchAction?: string;
 };
-/** Props for the {@link PredictiveSearchProvider} component. */
-type PredictiveSearchProviderProps = CreatePredictiveSearchStoreOptions & {
-  children?: ReactNode; /** Form action URL for progressive enhancement. Used by {@link usePredictiveSearchForm} to set the form's `action` attribute so the search works without JavaScript. Falls back to `"/search"` when omitted. */
-  searchAction?: string;
-};
 /**
- * Options for the form props builder returned by {@link usePredictiveSearchForm}.
+ * Store options, the search page path, and the content that uses the predictive search hooks.
  *
- * Accepts all standard form HTML attributes except `onSubmit`, which is
- * replaced by a version that provides the extracted search term.
+ * Changing a store option clears the current term and results. The provider compares `types` and `searchableFields` by value, which lets you pass new arrays on each render.
  */
-type PredictiveSearchFormPropsOptions = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & {
-  /** When `true`, prevents the native form submission and triggers a client-side search instead. */preventDefault?: boolean; /** Called on submit with the submit event and the extracted search term. Calling `event.preventDefault()` cancels both the native submission and Hydrogen's client-side search. */
+interface PredictiveSearchProviderProps extends CreatePredictiveSearchStoreOptions {
+  /** Content that uses the predictive search hooks. */
+  children?: ReactNode;
+  /** Search page path that forms from `usePredictiveSearchForm` submit to. Defaults to `/search`. */
+  searchAction?: string;
+}
+/** Submit behavior for the search form. */
+interface PredictiveSearchFormSubmitOptions {
+  /** Pass `true` to run the search in the browser on submit and stay on the current page. Defaults to `false`. */
+  preventDefault?: boolean;
+  /** Runs on submit with the event and the search term. Call `event.preventDefault()` to cancel both the page navigation and the browser search. */
   onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;
-};
+}
 /**
- * Options for the query input props builder returned by
- * {@link usePredictiveSearchForm}'s `register` method.
+ * Form attributes and submit behavior for the search form.
  *
- * Accepts all standard input HTML attributes except those controlled by the
- * form registration.
+ * Any standard form attribute works. Attributes that you pass override the default action, method, and role.
  */
-type PredictiveSearchQueryInputPropsOptions = Omit<InputHTMLAttributes<HTMLInputElement>, "autoCapitalize" | "autoComplete" | "name" | "onChange" | "spellCheck" | "type"> & {
-  /** Called on change with the change event and the current input value. Call `event.preventDefault()` to skip the automatic search trigger. */onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;
-};
+type PredictiveSearchFormPropsOptions = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & PredictiveSearchFormSubmitOptions;
+/**
+ * Input attributes and a change callback for the search input.
+ *
+ * Any standard input attribute works except the name, type, autocomplete, autocapitalize, and spell check attributes, which the register function sets.
+ */
+type PredictiveSearchQueryInputPropsOptions = Omit<InputHTMLAttributes<HTMLInputElement>, "autoCapitalize" | "autoComplete" | "name" | "onChange" | "spellCheck" | "type"> & PredictiveSearchQueryInputChangeOptions;
+/** Change behavior for the search input. */
+interface PredictiveSearchQueryInputChangeOptions {
+  /** Runs on every change with the event and the input value. Call `event.preventDefault()` to skip the search for that change. */
+  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;
+}
 type PredictiveSearchFormField = Parameters<PredictiveSearchFormRegister$1>[0];
-/** Generates input element attributes for a named form field. */
+/** Returns the search input attributes, merged with the attributes that you pass. */
 type PredictiveSearchFormRegister = (field: PredictiveSearchFormField, options?: PredictiveSearchQueryInputPropsOptions) => InputHTMLAttributes<HTMLInputElement>;
-/** Return type of {@link usePredictiveSearchForm}, providing methods to build a progressively-enhanced search form. */
+/** Functions that return attributes for a predictive search form and its search input. */
 type PredictiveSearchFormResult = {
-  /** Generates form element attributes including the search action and submit handler. */formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>; /** Generates input element attributes for a named form field and wires up the search trigger. */
+  /**
+   * Returns the attributes for the search form.
+   *
+   * By default, submitting the form opens the search page at the provider's search action.
+   * Pass `preventDefault: true` to run the search in the browser and stay on the current page.
+   */
+  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;
+  /**
+   * Returns the attributes for the search input, which searches as the customer types.
+   *
+   * Pass `query`. Any other field name throws an error.
+   */
   register: PredictiveSearchFormRegister;
 };
 /**
- * Creates and manages a predictive search store, providing it to descendant
- * hooks via React context.
+ * Runs predictive search for the components inside the provider. Wrap your search UI in the provider. Inside the provider, `usePredictiveSearch` reads the results, `usePredictiveSearchActions` searches and clears, and `usePredictiveSearchForm` builds the search form.
  *
- * Recreates the store when configuration props change. Connects the store
- * on mount and destroys it on unmount.
+ * The provider throws an error when you omit the `fetch` prop in a runtime without a global `fetch`.
  *
- * @throws {Error} When no `fetch` implementation is available (neither passed as a prop nor available on `globalThis`).
+ * @param props - The store options, the search page path, and the content that uses the predictive search hooks.
+ * @returns The provider element that wraps your search UI.
+ * @throws {Error} When neither the fetch prop nor a global fetch function exists.
+ * @publicDocs
  */
 declare function PredictiveSearchProvider({
   children,
@@ -66,43 +88,36 @@ declare function PredictiveSearchProvider({
   unavailableProducts
 }: PredictiveSearchProviderProps): _$react.FunctionComponentElement<_$react.ProviderProps<PredictiveSearchContextValue | null>>;
 /**
- * Subscribes to the predictive search store's state.
+ * Returns the search term, status, results, and error, and re-renders the component on each change.
  *
- * Without arguments, returns the full {@link PredictiveSearchState}. With a
- * `selector`, returns a derived value that only triggers re-renders when the
- * selected value changes (reference equality by default, or a custom
- * `isEqual`).
+ * Pass a selector to read one value, such as the status, and re-render only when that value changes. The hook compares selected values by reference unless you pass an equality function.
+ * The hook throws an error outside a `PredictiveSearchProvider`.
  *
- * Must be used inside a {@link PredictiveSearchProvider}.
- *
- * @throws {Error} When called outside a PredictiveSearchProvider.
+ * @throws {Error} When you call the hook outside a PredictiveSearchProvider.
+ * @publicDocs
  */
 declare function usePredictiveSearch<TData extends PredictiveSearchData = PredictiveSearchData>(): PredictiveSearchState<TData>;
 declare function usePredictiveSearch<TData extends PredictiveSearchData = PredictiveSearchData, S = PredictiveSearchState<TData>>(selector: (state: PredictiveSearchState<TData>) => S, isEqual?: (a: S, b: S) => boolean): S;
 /**
- * Returns `search` and `clear` methods that always target the provider's
- * current store. Their identity is stable across re-renders, even
- * when a config prop change recreates the store.
+ * Returns methods that search for a term and clear the results of the provider's predictive search. Use the hook in components that start searches without reading results.
  *
- * Must be used inside a {@link PredictiveSearchProvider}.
+ * The methods keep the same identity across re-renders and keep working after a store option changes.
+ * The hook throws an error outside a `PredictiveSearchProvider`.
  *
- * @throws {Error} When called outside a PredictiveSearchProvider.
+ * @returns Methods that search for a term and clear the results.
+ * @throws {Error} When you call the hook outside a PredictiveSearchProvider.
+ * @publicDocs
  */
 declare function usePredictiveSearchActions(): PredictiveSearchActions;
 /**
- * Returns `formProps` and `register` for building a progressively-enhanced
- * search form.
- *
- * `formProps()` generates form element attributes including the search
- * action URL. `register("query")` generates input attributes and calls the
- * store's search action on every change event. The store debounces requests
- * and resets state for terms shorter than `minTermLength`.
- * Both support an optional callback that receives the event and extracted
- * term, and respect `event.preventDefault()` to cancel the automatic behavior.
+ * Returns functions that connect a search form and its search input to the provider's predictive search. The form submits to the search page without JavaScript, and the search input searches as the customer types.
  *
- * Must be used inside a {@link PredictiveSearchProvider}.
+ * Spread `formProps()` on the form and `register("query")` on the input. In the `onSubmit` and `onChange` callbacks, call `event.preventDefault()` to skip the automatic submission or search.
+ * The hook throws an error outside a `PredictiveSearchProvider`.
  *
- * @throws {Error} When called outside a PredictiveSearchProvider.
+ * @returns Functions that return the search form attributes and the search input attributes.
+ * @throws {Error} When you call the hook outside a PredictiveSearchProvider.
+ * @publicDocs
  */
 declare function usePredictiveSearchForm(): PredictiveSearchFormResult;
 //#endregion

package/dist/react/predictive-search.mjs

@@ -8,13 +8,14 @@ import { createContext, createElement, useCallback, useContext, useEffect, useIn
 const CONFIG_ARRAY_SEPARATOR = "\0";
 const PredictiveSearchContext = createContext(null);
 /**
-* Creates and manages a predictive search store, providing it to descendant
-* hooks via React context.
+* Runs predictive search for the components inside the provider. Wrap your search UI in the provider. Inside the provider, `usePredictiveSearch` reads the results, `usePredictiveSearchActions` searches and clears, and `usePredictiveSearchForm` builds the search form.
 *
-* Recreates the store when configuration props change. Connects the store
-* on mount and destroys it on unmount.
+* The provider throws an error when you omit the `fetch` prop in a runtime without a global `fetch`.
 *
-* @throws {Error} When no `fetch` implementation is available (neither passed as a prop nor available on `globalThis`).
+* @param props - The store options, the search page path, and the content that uses the predictive search hooks.
+* @returns The provider element that wraps your search UI.
+* @throws {Error} When neither the fetch prop nor a global fetch function exists.
+* @publicDocs
 */
 function PredictiveSearchProvider({ children, predictiveSearchEndpoint, searchAction, debounceInMs, minTermLength, fetch, limit, limitScope, types, searchableFields, unavailableProducts }) {
 	const store = useMemo(() => createPredictiveSearchStore({
@@ -74,6 +75,11 @@ function useRequiredContext(hookName) {
 	if (!context) throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);
 	return context;
 }
+/**
+* @param selector - Function that picks the value to return from the search state.
+* @param isEqual - Function that compares two selected values. Return `true` to skip the re-render.
+* @returns The search state, or the value that your selector picks.
+*/
 function usePredictiveSearch(selector, isEqual) {
 	const store = useRequiredStore("usePredictiveSearch");
 	const cachedRef = useRef(null);
@@ -107,31 +113,27 @@ function usePredictiveSearch(selector, isEqual) {
 	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
 }
 /**
-* Returns `search` and `clear` methods that always target the provider's
-* current store. Their identity is stable across re-renders, even
-* when a config prop change recreates the store.
+* Returns methods that search for a term and clear the results of the provider's predictive search. Use the hook in components that start searches without reading results.
 *
-* Must be used inside a {@link PredictiveSearchProvider}.
+* The methods keep the same identity across re-renders and keep working after a store option changes.
+* The hook throws an error outside a `PredictiveSearchProvider`.
 *
-* @throws {Error} When called outside a PredictiveSearchProvider.
+* @returns Methods that search for a term and clear the results.
+* @throws {Error} When you call the hook outside a PredictiveSearchProvider.
+* @publicDocs
 */
 function usePredictiveSearchActions() {
 	return useRequiredContext("usePredictiveSearchActions").actions;
 }
 /**
-* Returns `formProps` and `register` for building a progressively-enhanced
-* search form.
-*
-* `formProps()` generates form element attributes including the search
-* action URL. `register("query")` generates input attributes and calls the
-* store's search action on every change event. The store debounces requests
-* and resets state for terms shorter than `minTermLength`.
-* Both support an optional callback that receives the event and extracted
-* term, and respect `event.preventDefault()` to cancel the automatic behavior.
+* Returns functions that connect a search form and its search input to the provider's predictive search. The form submits to the search page without JavaScript, and the search input searches as the customer types.
 *
-* Must be used inside a {@link PredictiveSearchProvider}.
+* Spread `formProps()` on the form and `register("query")` on the input. In the `onSubmit` and `onChange` callbacks, call `event.preventDefault()` to skip the automatic submission or search.
+* The hook throws an error outside a `PredictiveSearchProvider`.
 *
-* @throws {Error} When called outside a PredictiveSearchProvider.
+* @returns Functions that return the search form attributes and the search input attributes.
+* @throws {Error} When you call the hook outside a PredictiveSearchProvider.
+* @publicDocs
 */
 function usePredictiveSearchForm() {
 	const { searchAction, actions } = useRequiredContext("usePredictiveSearchForm");

package/dist/react/predictive-search.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"predictive-search.mjs","names":[],"sources":["../../src/react/predictive-search.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useInsertionEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ChangeEvent,\n  type FormHTMLAttributes,\n  type InputHTMLAttributes,\n  type ReactNode,\n  type SubmitEvent,\n} from \"react\";\n\nimport {\n  createPredictiveSearchFormRegister,\n  createPredictiveSearchStore,\n  getPredictiveSearchFormAttributes,\n  readPredictiveSearchFormTerm,\n  type CreatePredictiveSearchStoreOptions,\n  type PredictiveSearchActions,\n  type PredictiveSearchFormRegister as CorePredictiveSearchFormRegister,\n  type PredictiveSearchData,\n  type PredictiveSearchState,\n  type PredictiveSearchStore,\n} from \"../core/predictive-search\";\n\nconst CONFIG_ARRAY_SEPARATOR = \"\\u0000\";\n\ntype PredictiveSearchContextValue = {\n  store: PredictiveSearchStore;\n  actions: PredictiveSearchActions;\n  searchAction?: string;\n};\n\nconst PredictiveSearchContext = createContext<PredictiveSearchContextValue | null>(null);\n\n/** Props for the {@link PredictiveSearchProvider} component. */\nexport type PredictiveSearchProviderProps = CreatePredictiveSearchStoreOptions & {\n  children?: ReactNode;\n  /** Form action URL for progressive enhancement. Used by {@link usePredictiveSearchForm} to set the form's `action` attribute so the search works without JavaScript. Falls back to `\"/search\"` when omitted. */\n  searchAction?: string;\n};\n\nexport type { PredictiveSearchActions };\n\n/**\n * Options for the form props builder returned by {@link usePredictiveSearchForm}.\n *\n * Accepts all standard form HTML attributes except `onSubmit`, which is\n * replaced by a version that provides the extracted search term.\n */\nexport type PredictiveSearchFormPropsOptions = Omit<\n  FormHTMLAttributes<HTMLFormElement>,\n  \"onSubmit\"\n> & {\n  /** When `true`, prevents the native form submission and triggers a client-side search instead. */\n  preventDefault?: boolean;\n  /** Called on submit with the submit event and the extracted search term. Calling `event.preventDefault()` cancels both the native submission and Hydrogen's client-side search. */\n  onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;\n};\n\n/**\n * Options for the query input props builder returned by\n * {@link usePredictiveSearchForm}'s `register` method.\n *\n * Accepts all standard input HTML attributes except those controlled by the\n * form registration.\n */\nexport type PredictiveSearchQueryInputPropsOptions = Omit<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"autoCapitalize\" | \"autoComplete\" | \"name\" | \"onChange\" | \"spellCheck\" | \"type\"\n> & {\n  /** Called on change with the change event and the current input value. Call `event.preventDefault()` to skip the automatic search trigger. */\n  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;\n};\n\ntype PredictiveSearchFormField = Parameters<CorePredictiveSearchFormRegister>[0];\n\n/** Generates input element attributes for a named form field. */\nexport type PredictiveSearchFormRegister = (\n  field: PredictiveSearchFormField,\n  options?: PredictiveSearchQueryInputPropsOptions,\n) => InputHTMLAttributes<HTMLInputElement>;\n\n/** Return type of {@link usePredictiveSearchForm}, providing methods to build a progressively-enhanced search form. */\nexport type PredictiveSearchFormResult = {\n  /** Generates form element attributes including the search action and submit handler. */\n  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;\n  /** Generates input element attributes for a named form field and wires up the search trigger. */\n  register: PredictiveSearchFormRegister;\n};\n\n/**\n * Creates and manages a predictive search store, providing it to descendant\n * hooks via React context.\n *\n * Recreates the store when configuration props change. Connects the store\n * on mount and destroys it on unmount.\n *\n * @throws {Error} When no `fetch` implementation is available (neither passed as a prop nor available on `globalThis`).\n */\nexport function PredictiveSearchProvider({\n  children,\n  predictiveSearchEndpoint,\n  searchAction,\n  debounceInMs,\n  minTermLength,\n  fetch,\n  limit,\n  limitScope,\n  types,\n  searchableFields,\n  unavailableProducts,\n}: PredictiveSearchProviderProps) {\n  const typesKey = getArrayKey(types);\n  const searchableFieldsKey = getArrayKey(searchableFields);\n\n  const store = useMemo(\n    () =>\n      createPredictiveSearchStore({\n        predictiveSearchEndpoint,\n        debounceInMs,\n        minTermLength,\n        fetch,\n        limit,\n        limitScope,\n        types,\n        searchableFields,\n        unavailableProducts,\n      }),\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- array keys are the semantic dependencies\n    [\n      predictiveSearchEndpoint,\n      debounceInMs,\n      minTermLength,\n      fetch,\n      limit,\n      limitScope,\n      typesKey,\n      searchableFieldsKey,\n      unavailableProducts,\n    ],\n  );\n\n  const storeRef = useRef(store);\n  // Actions outlive store swaps by reading the committed store at call time. Only an insertion\n  // effect is both commit-only and early enough: a render-phase write can point actions at a\n  // store from a render React never commits, and layout and passive effects run child-first,\n  // so a child effect searching in the same commit would still see the old store.\n  useInsertionEffect(() => {\n    storeRef.current = store;\n  }, [store]);\n  const actions = useMemo<PredictiveSearchActions>(\n    () => ({\n      search: (term) => storeRef.current.search(term),\n      clear: () => storeRef.current.clear(),\n    }),\n    [],\n  );\n\n  useEffect(() => {\n    store.connect();\n    return () => store.destroy();\n  }, [store]);\n\n  const contextValue = useMemo(\n    () => ({ store, actions, searchAction }),\n    [store, actions, searchAction],\n  );\n\n  return createElement(PredictiveSearchContext.Provider, { value: contextValue }, children);\n}\n\nfunction getArrayKey(values: readonly string[] | undefined): string {\n  return values?.join(CONFIG_ARRAY_SEPARATOR) ?? \"\";\n}\n\nfunction useRequiredStore<TData extends PredictiveSearchData>(\n  hookName: string,\n): PredictiveSearchStore<TData> {\n  const context = useContext(PredictiveSearchContext);\n  if (!context) {\n    throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);\n  }\n\n  // oxlint-disable-next-line @typescript-eslint/consistent-type-assertions -- context stores the runtime object while hooks preserve caller-provided result typing\n  return context.store as PredictiveSearchStore<TData>;\n}\n\nfunction useRequiredContext(hookName: string): PredictiveSearchContextValue {\n  const context = useContext(PredictiveSearchContext);\n  if (!context) {\n    throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);\n  }\n\n  return context;\n}\n\n/**\n * Subscribes to the predictive search store's state.\n *\n * Without arguments, returns the full {@link PredictiveSearchState}. With a\n * `selector`, returns a derived value that only triggers re-renders when the\n * selected value changes (reference equality by default, or a custom\n * `isEqual`).\n *\n * Must be used inside a {@link PredictiveSearchProvider}.\n *\n * @throws {Error} When called outside a PredictiveSearchProvider.\n */\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n>(): PredictiveSearchState<TData>;\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n  S = PredictiveSearchState<TData>,\n>(selector: (state: PredictiveSearchState<TData>) => S, isEqual?: (a: S, b: S) => boolean): S;\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n  S = PredictiveSearchState<TData>,\n>(\n  selector?: (state: PredictiveSearchState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): PredictiveSearchState<TData> | S {\n  const store = useRequiredStore<TData>(\"usePredictiveSearch\");\n  const cachedRef = useRef<{\n    state: unknown;\n    selector: typeof selector;\n    value: PredictiveSearchState<TData> | S;\n  } | null>(null);\n\n  const getSnapshot = () => {\n    const state = store.getState();\n\n    if (\n      cachedRef.current &&\n      cachedRef.current.state === state &&\n      cachedRef.current.selector === selector\n    ) {\n      return cachedRef.current.value;\n    }\n\n    if (!selector) {\n      cachedRef.current = { state, selector, value: state };\n      return state;\n    }\n\n    const next = selector(state);\n    if (cachedRef.current && isEqual?.(cachedRef.current.value as S, next)) {\n      cachedRef.current = { state, selector, value: cachedRef.current.value };\n      return cachedRef.current.value;\n    }\n\n    cachedRef.current = { state, selector, value: next };\n    return next;\n  };\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Returns `search` and `clear` methods that always target the provider's\n * current store. Their identity is stable across re-renders, even\n * when a config prop change recreates the store.\n *\n * Must be used inside a {@link PredictiveSearchProvider}.\n *\n * @throws {Error} When called outside a PredictiveSearchProvider.\n */\nexport function usePredictiveSearchActions(): PredictiveSearchActions {\n  return useRequiredContext(\"usePredictiveSearchActions\").actions;\n}\n\n/**\n * Returns `formProps` and `register` for building a progressively-enhanced\n * search form.\n *\n * `formProps()` generates form element attributes including the search\n * action URL. `register(\"query\")` generates input attributes and calls the\n * store's search action on every change event. The store debounces requests\n * and resets state for terms shorter than `minTermLength`.\n * Both support an optional callback that receives the event and extracted\n * term, and respect `event.preventDefault()` to cancel the automatic behavior.\n *\n * Must be used inside a {@link PredictiveSearchProvider}.\n *\n * @throws {Error} When called outside a PredictiveSearchProvider.\n */\nexport function usePredictiveSearchForm(): PredictiveSearchFormResult {\n  const { searchAction, actions } = useRequiredContext(\"usePredictiveSearchForm\");\n  const coreRegister = useMemo(() => createPredictiveSearchFormRegister(), []);\n\n  const register = useCallback<PredictiveSearchFormRegister>(\n    (field, props = {}) => {\n      const { onChange, ...attributes } = props;\n      const coreAttributes = coreRegister(field);\n\n      return {\n        ...attributes,\n        ...coreAttributes,\n        onChange: (event: ChangeEvent<HTMLInputElement>) => {\n          const term = event.currentTarget.value;\n          onChange?.(event, term);\n          if (event.defaultPrevented) return;\n          void actions.search(term);\n        },\n      };\n    },\n    [coreRegister, actions],\n  );\n\n  const formProps = useCallback(\n    (props: PredictiveSearchFormPropsOptions = {}): FormHTMLAttributes<HTMLFormElement> => {\n      const { onSubmit, preventDefault, ...attributes } = props;\n\n      return {\n        ...getPredictiveSearchFormAttributes(searchAction),\n        ...attributes,\n        onSubmit: (event: SubmitEvent<HTMLFormElement>) => {\n          const term = readPredictiveSearchFormTerm(new FormData(event.currentTarget));\n          onSubmit?.(event, term);\n          if (event.defaultPrevented) return;\n          if (!preventDefault) return;\n          event.preventDefault();\n          void actions.search(term);\n        },\n      };\n    },\n    [searchAction, actions],\n  );\n\n  return { formProps, register };\n}\n"],"mappings":"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"}
+{"version":3,"file":"predictive-search.mjs","names":[],"sources":["../../src/react/predictive-search.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useInsertionEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type ChangeEvent,\n  type FormHTMLAttributes,\n  type InputHTMLAttributes,\n  type ReactNode,\n  type SubmitEvent,\n} from \"react\";\n\nimport {\n  createPredictiveSearchFormRegister,\n  createPredictiveSearchStore,\n  getPredictiveSearchFormAttributes,\n  readPredictiveSearchFormTerm,\n  type CreatePredictiveSearchStoreOptions,\n  type PredictiveSearchActions,\n  type PredictiveSearchFormRegister as CorePredictiveSearchFormRegister,\n  type PredictiveSearchData,\n  type PredictiveSearchState,\n  type PredictiveSearchStore,\n} from \"../core/predictive-search\";\n\nconst CONFIG_ARRAY_SEPARATOR = \"\\u0000\";\n\ntype PredictiveSearchContextValue = {\n  store: PredictiveSearchStore;\n  actions: PredictiveSearchActions;\n  searchAction?: string;\n};\n\nconst PredictiveSearchContext = createContext<PredictiveSearchContextValue | null>(null);\n\n/**\n * Store options, the search page path, and the content that uses the predictive search hooks.\n *\n * Changing a store option clears the current term and results. The provider compares `types` and `searchableFields` by value, which lets you pass new arrays on each render.\n */\nexport interface PredictiveSearchProviderProps extends CreatePredictiveSearchStoreOptions {\n  /** Content that uses the predictive search hooks. */\n  children?: ReactNode;\n  /** Search page path that forms from `usePredictiveSearchForm` submit to. Defaults to `/search`. */\n  searchAction?: string;\n}\n\nexport type { PredictiveSearchActions };\n\n/** Submit behavior for the search form. */\ninterface PredictiveSearchFormSubmitOptions {\n  /** Pass `true` to run the search in the browser on submit and stay on the current page. Defaults to `false`. */\n  preventDefault?: boolean;\n  /** Runs on submit with the event and the search term. Call `event.preventDefault()` to cancel both the page navigation and the browser search. */\n  onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;\n}\n\n/**\n * Form attributes and submit behavior for the search form.\n *\n * Any standard form attribute works. Attributes that you pass override the default action, method, and role.\n */\nexport type PredictiveSearchFormPropsOptions = Omit<\n  FormHTMLAttributes<HTMLFormElement>,\n  \"onSubmit\"\n> &\n  PredictiveSearchFormSubmitOptions;\n\n/**\n * Input attributes and a change callback for the search input.\n *\n * Any standard input attribute works except the name, type, autocomplete, autocapitalize, and spell check attributes, which the register function sets.\n */\nexport type PredictiveSearchQueryInputPropsOptions = Omit<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"autoCapitalize\" | \"autoComplete\" | \"name\" | \"onChange\" | \"spellCheck\" | \"type\"\n> &\n  PredictiveSearchQueryInputChangeOptions;\n\n/** Change behavior for the search input. */\ninterface PredictiveSearchQueryInputChangeOptions {\n  /** Runs on every change with the event and the input value. Call `event.preventDefault()` to skip the search for that change. */\n  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;\n}\n\ntype PredictiveSearchFormField = Parameters<CorePredictiveSearchFormRegister>[0];\n\n/** Returns the search input attributes, merged with the attributes that you pass. */\nexport type PredictiveSearchFormRegister = (\n  field: PredictiveSearchFormField,\n  options?: PredictiveSearchQueryInputPropsOptions,\n) => InputHTMLAttributes<HTMLInputElement>;\n\n/** Functions that return attributes for a predictive search form and its search input. */\nexport type PredictiveSearchFormResult = {\n  /**\n   * Returns the attributes for the search form.\n   *\n   * By default, submitting the form opens the search page at the provider's search action.\n   * Pass `preventDefault: true` to run the search in the browser and stay on the current page.\n   */\n  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;\n  /**\n   * Returns the attributes for the search input, which searches as the customer types.\n   *\n   * Pass `query`. Any other field name throws an error.\n   */\n  register: PredictiveSearchFormRegister;\n};\n\n/**\n * Runs predictive search for the components inside the provider. Wrap your search UI in the provider. Inside the provider, `usePredictiveSearch` reads the results, `usePredictiveSearchActions` searches and clears, and `usePredictiveSearchForm` builds the search form.\n *\n * The provider throws an error when you omit the `fetch` prop in a runtime without a global `fetch`.\n *\n * @param props - The store options, the search page path, and the content that uses the predictive search hooks.\n * @returns The provider element that wraps your search UI.\n * @throws {Error} When neither the fetch prop nor a global fetch function exists.\n * @publicDocs\n */\nexport function PredictiveSearchProvider({\n  children,\n  predictiveSearchEndpoint,\n  searchAction,\n  debounceInMs,\n  minTermLength,\n  fetch,\n  limit,\n  limitScope,\n  types,\n  searchableFields,\n  unavailableProducts,\n}: PredictiveSearchProviderProps) {\n  const typesKey = getArrayKey(types);\n  const searchableFieldsKey = getArrayKey(searchableFields);\n\n  const store = useMemo(\n    () =>\n      createPredictiveSearchStore({\n        predictiveSearchEndpoint,\n        debounceInMs,\n        minTermLength,\n        fetch,\n        limit,\n        limitScope,\n        types,\n        searchableFields,\n        unavailableProducts,\n      }),\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- array keys are the semantic dependencies\n    [\n      predictiveSearchEndpoint,\n      debounceInMs,\n      minTermLength,\n      fetch,\n      limit,\n      limitScope,\n      typesKey,\n      searchableFieldsKey,\n      unavailableProducts,\n    ],\n  );\n\n  const storeRef = useRef(store);\n  // Actions outlive store swaps by reading the committed store at call time. Only an insertion\n  // effect is both commit-only and early enough: a render-phase write can point actions at a\n  // store from a render React never commits, and layout and passive effects run child-first,\n  // so a child effect searching in the same commit would still see the old store.\n  useInsertionEffect(() => {\n    storeRef.current = store;\n  }, [store]);\n  const actions = useMemo<PredictiveSearchActions>(\n    () => ({\n      search: (term) => storeRef.current.search(term),\n      clear: () => storeRef.current.clear(),\n    }),\n    [],\n  );\n\n  useEffect(() => {\n    store.connect();\n    return () => store.destroy();\n  }, [store]);\n\n  const contextValue = useMemo(\n    () => ({ store, actions, searchAction }),\n    [store, actions, searchAction],\n  );\n\n  return createElement(PredictiveSearchContext.Provider, { value: contextValue }, children);\n}\n\nfunction getArrayKey(values: readonly string[] | undefined): string {\n  return values?.join(CONFIG_ARRAY_SEPARATOR) ?? \"\";\n}\n\nfunction useRequiredStore<TData extends PredictiveSearchData>(\n  hookName: string,\n): PredictiveSearchStore<TData> {\n  const context = useContext(PredictiveSearchContext);\n  if (!context) {\n    throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);\n  }\n\n  // oxlint-disable-next-line @typescript-eslint/consistent-type-assertions -- context stores the runtime object while hooks preserve caller-provided result typing\n  return context.store as PredictiveSearchStore<TData>;\n}\n\nfunction useRequiredContext(hookName: string): PredictiveSearchContextValue {\n  const context = useContext(PredictiveSearchContext);\n  if (!context) {\n    throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);\n  }\n\n  return context;\n}\n\n/**\n * Returns the search term, status, results, and error, and re-renders the component on each change.\n *\n * Pass a selector to read one value, such as the status, and re-render only when that value changes. The hook compares selected values by reference unless you pass an equality function.\n * The hook throws an error outside a `PredictiveSearchProvider`.\n *\n * @throws {Error} When you call the hook outside a PredictiveSearchProvider.\n * @publicDocs\n */\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n>(): PredictiveSearchState<TData>;\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n  S = PredictiveSearchState<TData>,\n>(selector: (state: PredictiveSearchState<TData>) => S, isEqual?: (a: S, b: S) => boolean): S;\n/**\n * @param selector - Function that picks the value to return from the search state.\n * @param isEqual - Function that compares two selected values. Return `true` to skip the re-render.\n * @returns The search state, or the value that your selector picks.\n */\nexport function usePredictiveSearch<\n  TData extends PredictiveSearchData = PredictiveSearchData,\n  S = PredictiveSearchState<TData>,\n>(\n  selector?: (state: PredictiveSearchState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): PredictiveSearchState<TData> | S {\n  const store = useRequiredStore<TData>(\"usePredictiveSearch\");\n  const cachedRef = useRef<{\n    state: unknown;\n    selector: typeof selector;\n    value: PredictiveSearchState<TData> | S;\n  } | null>(null);\n\n  const getSnapshot = () => {\n    const state = store.getState();\n\n    if (\n      cachedRef.current &&\n      cachedRef.current.state === state &&\n      cachedRef.current.selector === selector\n    ) {\n      return cachedRef.current.value;\n    }\n\n    if (!selector) {\n      cachedRef.current = { state, selector, value: state };\n      return state;\n    }\n\n    const next = selector(state);\n    if (cachedRef.current && isEqual?.(cachedRef.current.value as S, next)) {\n      cachedRef.current = { state, selector, value: cachedRef.current.value };\n      return cachedRef.current.value;\n    }\n\n    cachedRef.current = { state, selector, value: next };\n    return next;\n  };\n\n  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);\n}\n\n/**\n * Returns methods that search for a term and clear the results of the provider's predictive search. Use the hook in components that start searches without reading results.\n *\n * The methods keep the same identity across re-renders and keep working after a store option changes.\n * The hook throws an error outside a `PredictiveSearchProvider`.\n *\n * @returns Methods that search for a term and clear the results.\n * @throws {Error} When you call the hook outside a PredictiveSearchProvider.\n * @publicDocs\n */\nexport function usePredictiveSearchActions(): PredictiveSearchActions {\n  return useRequiredContext(\"usePredictiveSearchActions\").actions;\n}\n\n/**\n * Returns functions that connect a search form and its search input to the provider's predictive search. The form submits to the search page without JavaScript, and the search input searches as the customer types.\n *\n * Spread `formProps()` on the form and `register(\"query\")` on the input. In the `onSubmit` and `onChange` callbacks, call `event.preventDefault()` to skip the automatic submission or search.\n * The hook throws an error outside a `PredictiveSearchProvider`.\n *\n * @returns Functions that return the search form attributes and the search input attributes.\n * @throws {Error} When you call the hook outside a PredictiveSearchProvider.\n * @publicDocs\n */\nexport function usePredictiveSearchForm(): PredictiveSearchFormResult {\n  const { searchAction, actions } = useRequiredContext(\"usePredictiveSearchForm\");\n  const coreRegister = useMemo(() => createPredictiveSearchFormRegister(), []);\n\n  const register = useCallback<PredictiveSearchFormRegister>(\n    (field, props = {}) => {\n      const { onChange, ...attributes } = props;\n      const coreAttributes = coreRegister(field);\n\n      return {\n        ...attributes,\n        ...coreAttributes,\n        onChange: (event: ChangeEvent<HTMLInputElement>) => {\n          const term = event.currentTarget.value;\n          onChange?.(event, term);\n          if (event.defaultPrevented) return;\n          void actions.search(term);\n        },\n      };\n    },\n    [coreRegister, actions],\n  );\n\n  const formProps = useCallback(\n    (props: PredictiveSearchFormPropsOptions = {}): FormHTMLAttributes<HTMLFormElement> => {\n      const { onSubmit, preventDefault, ...attributes } = props;\n\n      return {\n        ...getPredictiveSearchFormAttributes(searchAction),\n        ...attributes,\n        onSubmit: (event: SubmitEvent<HTMLFormElement>) => {\n          const term = readPredictiveSearchFormTerm(new FormData(event.currentTarget));\n          onSubmit?.(event, term);\n          if (event.defaultPrevented) return;\n          if (!preventDefault) return;\n          event.preventDefault();\n          void actions.search(term);\n        },\n      };\n    },\n    [searchAction, actions],\n  );\n\n  return { formProps, register };\n}\n\n/**\n * Returns the search term, status, results, and error, and re-renders the component on each change.\n *\n * Pass a selector to read one value, such as the status, and re-render only when that value changes. The hook compares selected values by reference unless you pass an equality function.\n * The hook throws an error outside a `PredictiveSearchProvider`.\n *\n * @throws {Error} When you call the hook outside a PredictiveSearchProvider.\n * @publicDocs\n */\nexport type UsePredictiveSearchForDocs =\n  /**\n   * @param selector - Function that picks the value to return from the search state.\n   * @param isEqual - Function that compares two selected values. Return `true` to skip the re-render.\n   * @returns The search state, or the value that your selector picks.\n   */\n  <S = PredictiveSearchState>(\n    selector?: (state: PredictiveSearchState) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ) => S;\n"],"mappings":"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"}

package/dist/react/product.d.mts

@@ -5,63 +5,92 @@ import { ProductFormRegister } from "../core/product/form.mjs";
 import { FormHTMLAttributes, ReactNode, SubmitEvent } from "react";
 
 //#region src/react/product.d.ts
-/** Options for {@link useProductForm}. */
+/** Options for the `useProductForm` hook. */
 interface UseProductFormOptions<TProduct extends ProductInput> {
+  /** Runs after each resolved or unresolved selection. Invalid selections skip the callback. */
   onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;
 }
-/** Return value of {@link useProductForm}. */
+/** Product form state and bindings that the product form hooks return. */
 interface UseProductFormResult<TProduct extends ProductInput> {
+  /** Each product option and its values, with the selection, existence, and availability of each value. */
   options: ProductFormOptions<TProduct>;
+  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */
   selectedVariant: ProductVariantFrom<TProduct> | null;
+  /** Returns the props for a product form field. Spread the props on the matching input or button. */
   register: ProductFormRegister;
+  /**
+   * Returns props for the product form element. Submitting the form adds the selected variant to the cart, and the form posts to the cart endpoint before JavaScript loads.
+   * Call `preventDefault()` in `beforeSubmit` to cancel the submission. The `afterSubmit` callback runs after the cart store handles the submission. Cart errors appear in the errors field. When the cart store throws an error, the hook logs the error and skips `afterSubmit`.
+   */
   formProps: (opts?: {
     beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
     afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
   }) => FormHTMLAttributes<HTMLFormElement>;
+  /** Cart errors and warnings to show near the add-to-cart button. */
   errors: ProductFormErrors;
+  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */
   matchedLineItem: CartLine | null;
-  /** Whether a form submission is currently in flight. */
+  /**
+   * Whether the cart is handling a form submission. Disable the add-to-cart button while the value is `true`.
+   */
   pending: boolean;
+  /** Selects an option value and returns the result. Resolved and unresolved selections run the `onSelect` callback. */
   selectOption: (name: string, value: string) => VariantSelectionResult<ProductVariantFrom<TProduct>>;
 }
-/** Props for the `ProductProvider` returned by {@link createProductComponents}. */
+/** Props for the product provider from `createProductComponents`. */
 interface ProductProviderProps<TProduct extends ProductInput> {
+  /**
+   * The product from your Storefront API query.
+   * The provider reloads the product into the store when the product ID or the selected or first available variant ID changes. The customer's selection persists through re-renders that keep both IDs.
+   */
   product: TProduct;
+  /**
+   * Runs after each resolved or unresolved selection. Invalid selections skip the callback. Navigate to the new product URL in this callback, and keep navigation out of option controls.
+   * Make the callback safe to run twice. A click on a hydrated option link runs the callback and also follows the link.
+   */
   onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;
+  /** Content that reads product state through the product hooks. */
   children?: ReactNode;
 }
-/** Return value of the `useProduct` hook from {@link createProductComponents}. */
+/** Product state that the `useProduct` hook from `createProductComponents` returns. */
 interface UseProductResult<TProduct extends ProductInput> {
+  /** Each product option and its values, with the selection, existence, and availability of each value. */
   options: ProductFormOptions<TProduct>;
+  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */
   selectedVariant: ProductVariantFrom<TProduct> | null;
+  /** Selects an option value and returns the result. Resolved and unresolved selections run the `onSelect` callback. */
   selectOption: (name: string, value: string) => VariantSelectionResult<ProductVariantFrom<TProduct>>;
+  /** Cart errors and warnings to show near the add-to-cart button. */
   errors: ProductFormErrors;
+  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */
   matchedLineItem: CartLine | null;
 }
 /**
- * Subscribes to a {@link ProductFormStore} and returns form-ready state.
+ * Returns product form state and bindings from a product form store that you manage, and re-renders when the state changes.
  *
- * This is a pure subscription hook — it does **not** manage store lifecycle.
- * Create the store with `createProductFormStore` and manage its lifecycle
- * (hydration, destruction) yourself, or use `createProductComponents` for a
- * provider-based approach.
+ * Create the store with `createProductFormStore`. Call `connect()` on mount, `hydrate()` when the product data changes, and `destroy()` on unmount. To skip the store setup, use the product provider from `createProductComponents`.
+ *
+ * @param store The store that `createProductFormStore` returns.
+ * @param options An `onSelect` callback that runs after each resolved or unresolved selection.
+ * @returns The option state, the selected variant, cart errors, the matching cart line, the pending state, the register function, and the form props.
+ * @publicDocs
  */
 declare function useProductForm<TProduct extends ProductInput>(store: ProductFormStore<TProduct>, options?: UseProductFormOptions<TProduct>): UseProductFormResult<TProduct>;
 /**
- * Creates a typed set of product components bound to a specific product type.
+ * Creates a product provider and product hooks typed to your product query.
+ *
+ * The provider creates the product form store, reloads the product into the store when the product changes, and destroys the store on unmount. The `useProduct` hook returns the option state and variant selection. The `useProductForm` hook adds field props, form props, and the pending state.
  *
- * Returns `{ ProductProvider, useProduct, useProductForm }` where:
- * - `ProductProvider` manages store lifecycle (creation, hydration, cleanup)
- * - `useProduct` provides read-only state and variant selection
- * - `useProductForm` provides form-binding utilities (register, formProps, pending)
+ * Pass your Storefront API product query type as the type argument to type the selected variant and option values. Render the provider inside a cart provider. The provider throws an error without a cart provider ancestor, and each hook throws an error outside the product provider.
  *
- * Requires a `<CartProvider>` ancestor.
+ * @returns The typed `ProductProvider` component and the `useProduct` and `useProductForm` hooks.
  *
  * @example
  * ```ts
  * const { ProductProvider, useProduct, useProductForm } =
  *   createProductComponents<MyProductType>();
  * ```
+ * @publicDocs
  */
 declare function createProductComponents<TProduct extends ProductInput>(): {
   ProductProvider: (props: ProductProviderProps<TProduct>) => ReactNode;

package/dist/react/product.mjs

@@ -9,12 +9,14 @@ import { createContext, createElement, useCallback, useContext, useEffect, useMe
 //#region src/react/product.tsx
 const log = getLogger("product");
 /**
-* Subscribes to a {@link ProductFormStore} and returns form-ready state.
+* Returns product form state and bindings from a product form store that you manage, and re-renders when the state changes.
 *
-* This is a pure subscription hook — it does **not** manage store lifecycle.
-* Create the store with `createProductFormStore` and manage its lifecycle
-* (hydration, destruction) yourself, or use `createProductComponents` for a
-* provider-based approach.
+* Create the store with `createProductFormStore`. Call `connect()` on mount, `hydrate()` when the product data changes, and `destroy()` on unmount. To skip the store setup, use the product provider from `createProductComponents`.
+*
+* @param store The store that `createProductFormStore` returns.
+* @param options An `onSelect` callback that runs after each resolved or unresolved selection.
+* @returns The option state, the selected variant, cart errors, the matching cart line, the pending state, the register function, and the form props.
+* @publicDocs
 */
 function useProductForm(store, options) {
 	const onSelectRef = useRef(options?.onSelect);
@@ -52,20 +54,20 @@ function useProductForm(store, options) {
 	};
 }
 /**
-* Creates a typed set of product components bound to a specific product type.
+* Creates a product provider and product hooks typed to your product query.
+*
+* The provider creates the product form store, reloads the product into the store when the product changes, and destroys the store on unmount. The `useProduct` hook returns the option state and variant selection. The `useProductForm` hook adds field props, form props, and the pending state.
 *
-* Returns `{ ProductProvider, useProduct, useProductForm }` where:
-* - `ProductProvider` manages store lifecycle (creation, hydration, cleanup)
-* - `useProduct` provides read-only state and variant selection
-* - `useProductForm` provides form-binding utilities (register, formProps, pending)
+* Pass your Storefront API product query type as the type argument to type the selected variant and option values. Render the provider inside a cart provider. The provider throws an error without a cart provider ancestor, and each hook throws an error outside the product provider.
 *
-* Requires a `<CartProvider>` ancestor.
+* @returns The typed `ProductProvider` component and the `useProduct` and `useProductForm` hooks.
 *
 * @example
 * ```ts
 * const { ProductProvider, useProduct, useProductForm } =
 *   createProductComponents<MyProductType>();
 * ```
+* @publicDocs
 */
 function createProductComponents() {
 	const Context = createContext(null);

package/dist/react/product.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"product.mjs","names":[],"sources":["../../src/react/product.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type SubmitEvent,\n} from \"react\";\n\nimport type { CartLine } from \"../core/cart/state\";\nimport { getLogger } from \"../core/logging\";\nimport {\n  createProductFormRegister,\n  createProductFormStore,\n  type ProductFormErrors,\n  type ProductFormOptions,\n  type ProductFormRegister,\n  type ProductFormStore,\n  type ProductInput,\n  type ProductVariantFrom,\n  type ValidProductSelectionResult,\n  type VariantSelectionResult,\n} from \"../core/product\";\nimport { getCartEndpoint, useCartStore } from \"./cart\";\n\nconst log = getLogger(\"product\");\n\n// ---------------------------------------------------------------------------\n// Shared types\n// ---------------------------------------------------------------------------\n\nexport type { ValidProductSelectionResult } from \"../core/product\";\n\n/** Options for {@link useProductForm}. */\nexport interface UseProductFormOptions<TProduct extends ProductInput> {\n  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;\n}\n\n/** Return value of {@link useProductForm}. */\nexport interface UseProductFormResult<TProduct extends ProductInput> {\n  options: ProductFormOptions<TProduct>;\n  selectedVariant: ProductVariantFrom<TProduct> | null;\n  register: ProductFormRegister;\n  formProps: (opts?: {\n    beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n    afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  }) => FormHTMLAttributes<HTMLFormElement>;\n  errors: ProductFormErrors;\n  matchedLineItem: CartLine | null;\n  /** Whether a form submission is currently in flight. */\n  pending: boolean;\n  selectOption: (\n    name: string,\n    value: string,\n  ) => VariantSelectionResult<ProductVariantFrom<TProduct>>;\n}\n\n/** Props for the `ProductProvider` returned by {@link createProductComponents}. */\nexport interface ProductProviderProps<TProduct extends ProductInput> {\n  product: TProduct;\n  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;\n  children?: ReactNode;\n}\n\n/** Return value of the `useProduct` hook from {@link createProductComponents}. */\nexport interface UseProductResult<TProduct extends ProductInput> {\n  options: ProductFormOptions<TProduct>;\n  selectedVariant: ProductVariantFrom<TProduct> | null;\n  selectOption: (\n    name: string,\n    value: string,\n  ) => VariantSelectionResult<ProductVariantFrom<TProduct>>;\n  errors: ProductFormErrors;\n  matchedLineItem: CartLine | null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n// ---------------------------------------------------------------------------\n// Standalone hook\n// ---------------------------------------------------------------------------\n\n/**\n * Subscribes to a {@link ProductFormStore} and returns form-ready state.\n *\n * This is a pure subscription hook — it does **not** manage store lifecycle.\n * Create the store with `createProductFormStore` and manage its lifecycle\n * (hydration, destruction) yourself, or use `createProductComponents` for a\n * provider-based approach.\n */\nexport function useProductForm<TProduct extends ProductInput>(\n  store: ProductFormStore<TProduct>,\n  options?: UseProductFormOptions<TProduct>,\n): UseProductFormResult<TProduct> {\n  const onSelectRef = useRef(options?.onSelect);\n  onSelectRef.current = options?.onSelect;\n\n  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);\n  const [pending, setPending] = useState(false);\n\n  const selectOption = useCallback(\n    (name: string, value: string) => {\n      const result = store.selectOption(name, value);\n      if (result.status !== \"invalid\") {\n        onSelectRef.current?.(result);\n      }\n      return result;\n    },\n    [store],\n  );\n\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- state is the full reactive snapshot; selectOption is stable\n  const register = useMemo(\n    () => createProductFormRegister(state.selectedVariant, selectOption),\n    [state, selectOption],\n  );\n\n  const formProps = useCallback(\n    (opts?: {\n      beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n      afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n    }): FormHTMLAttributes<HTMLFormElement> => ({\n      onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n        opts?.beforeSubmit?.(e);\n        if (e.defaultPrevented) return;\n        e.preventDefault();\n        setPending(true);\n        store\n          .handleFormSubmit(e.nativeEvent)\n          .then(\n            () => opts?.afterSubmit?.(e),\n            (error: unknown) => {\n              // Cart user/network errors are surfaced via the reactive `errors`\n              // state. Thrown exceptions (missing Shopify script, invalid form\n              // target) are programming errors — log them for dev visibility.\n              log.error(\"form submission error\", { error });\n            },\n          )\n          .finally(() => setPending(false));\n      },\n      method: \"post\",\n      action: getCartEndpoint(),\n    }),\n    [store],\n  );\n\n  return {\n    options: state.options,\n    selectedVariant: state.selectedVariant,\n    register,\n    formProps,\n    errors: state.errors,\n    matchedLineItem: state.matchedLineItem,\n    pending,\n    selectOption,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\ninterface ProductContextValue<TProduct extends ProductInput> {\n  store: ProductFormStore<TProduct>;\n  onSelectRef: React.RefObject<\n    ((result: ValidProductSelectionResult<TProduct>) => void) | undefined\n  >;\n}\n\n/**\n * Creates a typed set of product components bound to a specific product type.\n *\n * Returns `{ ProductProvider, useProduct, useProductForm }` where:\n * - `ProductProvider` manages store lifecycle (creation, hydration, cleanup)\n * - `useProduct` provides read-only state and variant selection\n * - `useProductForm` provides form-binding utilities (register, formProps, pending)\n *\n * Requires a `<CartProvider>` ancestor.\n *\n * @example\n * ```ts\n * const { ProductProvider, useProduct, useProductForm } =\n *   createProductComponents<MyProductType>();\n * ```\n */\nexport function createProductComponents<TProduct extends ProductInput>(): {\n  ProductProvider: (props: ProductProviderProps<TProduct>) => ReactNode;\n  useProduct: () => UseProductResult<TProduct>;\n  useProductForm: () => UseProductFormResult<TProduct>;\n} {\n  const Context = createContext<ProductContextValue<TProduct> | null>(null);\n\n  function useProductContext(hookName: string): ProductContextValue<TProduct> {\n    const ctx = useContext(Context);\n    if (!ctx) {\n      throw new Error(\n        `${hookName} must be used inside a <ProductProvider>. ` +\n          \"Wrap your component tree with the ProductProvider from createProductComponents(), \" +\n          \"or use the standalone useProductForm(store) hook instead.\",\n      );\n    }\n    return ctx;\n  }\n\n  function ProductProvider({ product, onSelect, children }: ProductProviderProps<TProduct>) {\n    const cartStore = useCartStore(\"ProductProvider\");\n\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is intentionally created once\n    const store = useMemo(() => createProductFormStore<TProduct>(product, cartStore), []);\n\n    useEffect(() => {\n      store.connect();\n      return () => store.destroy();\n    }, [store]);\n\n    const productKey = `${product.id}:${product.selectedOrFirstAvailableVariant?.id ?? \"\"}`;\n    const mountedRef = useRef(false);\n    useEffect(() => {\n      if (!mountedRef.current) {\n        mountedRef.current = true;\n        return;\n      }\n      store.hydrate(product);\n      // oxlint-disable-next-line react-hooks/exhaustive-deps -- productKey is the semantic dep\n    }, [productKey]);\n\n    const onSelectRef = useRef(onSelect);\n    onSelectRef.current = onSelect;\n\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- onSelectRef is a stable ref object\n    const value = useMemo<ProductContextValue<TProduct>>(() => ({ store, onSelectRef }), [store]);\n\n    return createElement(Context.Provider, { value }, children);\n  }\n\n  function useProductHook(): UseProductResult<TProduct> {\n    const { store, onSelectRef } = useProductContext(\"useProduct\");\n    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);\n\n    const selectOption = useCallback(\n      (name: string, value: string) => {\n        const result = store.selectOption(name, value);\n        if (result.status !== \"invalid\") {\n          onSelectRef.current?.(result);\n        }\n        return result;\n      },\n      [store, onSelectRef],\n    );\n\n    return {\n      options: state.options,\n      selectedVariant: state.selectedVariant,\n      selectOption,\n      errors: state.errors,\n      matchedLineItem: state.matchedLineItem,\n    };\n  }\n\n  function useProductFormHook(): UseProductFormResult<TProduct> {\n    const { store, onSelectRef } = useProductContext(\"useProductForm\");\n    return useProductForm<TProduct>(store, { onSelect: onSelectRef.current });\n  }\n\n  return {\n    ProductProvider,\n    useProduct: useProductHook,\n    useProductForm: useProductFormHook,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"product.mjs","names":[],"sources":["../../src/react/product.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type SubmitEvent,\n} from \"react\";\n\nimport type { CartLine } from \"../core/cart/state\";\nimport { getLogger } from \"../core/logging\";\nimport {\n  createProductFormRegister,\n  createProductFormStore,\n  type ProductFormErrors,\n  type ProductFormOptions,\n  type ProductFormRegister,\n  type ProductFormStore,\n  type ProductInput,\n  type ProductVariantFrom,\n  type ValidProductSelectionResult,\n  type VariantSelectionResult,\n} from \"../core/product\";\nimport { getCartEndpoint, useCartStore } from \"./cart\";\n\nconst log = getLogger(\"product\");\n\n// ---------------------------------------------------------------------------\n// Shared types\n// ---------------------------------------------------------------------------\n\nexport type { ValidProductSelectionResult } from \"../core/product\";\n\n/** Options for the `useProductForm` hook. */\nexport interface UseProductFormOptions<TProduct extends ProductInput> {\n  /** Runs after each resolved or unresolved selection. Invalid selections skip the callback. */\n  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;\n}\n\n/** Product form state and bindings that the product form hooks return. */\nexport interface UseProductFormResult<TProduct extends ProductInput> {\n  /** Each product option and its values, with the selection, existence, and availability of each value. */\n  options: ProductFormOptions<TProduct>;\n  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */\n  selectedVariant: ProductVariantFrom<TProduct> | null;\n  /** Returns the props for a product form field. Spread the props on the matching input or button. */\n  register: ProductFormRegister;\n  /**\n   * Returns props for the product form element. Submitting the form adds the selected variant to the cart, and the form posts to the cart endpoint before JavaScript loads.\n   * Call `preventDefault()` in `beforeSubmit` to cancel the submission. The `afterSubmit` callback runs after the cart store handles the submission. Cart errors appear in the errors field. When the cart store throws an error, the hook logs the error and skips `afterSubmit`.\n   */\n  formProps: (opts?: {\n    beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n    afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n  }) => FormHTMLAttributes<HTMLFormElement>;\n  /** Cart errors and warnings to show near the add-to-cart button. */\n  errors: ProductFormErrors;\n  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */\n  matchedLineItem: CartLine | null;\n  /**\n   * Whether the cart is handling a form submission. Disable the add-to-cart button while the value is `true`.\n   */\n  pending: boolean;\n  /** Selects an option value and returns the result. Resolved and unresolved selections run the `onSelect` callback. */\n  selectOption: (\n    name: string,\n    value: string,\n  ) => VariantSelectionResult<ProductVariantFrom<TProduct>>;\n}\n\n/** Props for the product provider from `createProductComponents`. */\nexport interface ProductProviderProps<TProduct extends ProductInput> {\n  /**\n   * The product from your Storefront API query.\n   * The provider reloads the product into the store when the product ID or the selected or first available variant ID changes. The customer's selection persists through re-renders that keep both IDs.\n   */\n  product: TProduct;\n  /**\n   * Runs after each resolved or unresolved selection. Invalid selections skip the callback. Navigate to the new product URL in this callback, and keep navigation out of option controls.\n   * Make the callback safe to run twice. A click on a hydrated option link runs the callback and also follows the link.\n   */\n  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;\n  /** Content that reads product state through the product hooks. */\n  children?: ReactNode;\n}\n\n/** Product state that the `useProduct` hook from `createProductComponents` returns. */\nexport interface UseProductResult<TProduct extends ProductInput> {\n  /** Each product option and its values, with the selection, existence, and availability of each value. */\n  options: ProductFormOptions<TProduct>;\n  /** Variant that matches the current selection, or `null` when the selection is partial or your query didn't load that variant. */\n  selectedVariant: ProductVariantFrom<TProduct> | null;\n  /** Selects an option value and returns the result. Resolved and unresolved selections run the `onSelect` callback. */\n  selectOption: (\n    name: string,\n    value: string,\n  ) => VariantSelectionResult<ProductVariantFrom<TProduct>>;\n  /** Cart errors and warnings to show near the add-to-cart button. */\n  errors: ProductFormErrors;\n  /** First cart line that holds the selected variant, or `null` when no cart line holds the variant. */\n  matchedLineItem: CartLine | null;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n// ---------------------------------------------------------------------------\n// Standalone hook\n// ---------------------------------------------------------------------------\n\n/**\n * Returns product form state and bindings from a product form store that you manage, and re-renders when the state changes.\n *\n * Create the store with `createProductFormStore`. Call `connect()` on mount, `hydrate()` when the product data changes, and `destroy()` on unmount. To skip the store setup, use the product provider from `createProductComponents`.\n *\n * @param store The store that `createProductFormStore` returns.\n * @param options An `onSelect` callback that runs after each resolved or unresolved selection.\n * @returns The option state, the selected variant, cart errors, the matching cart line, the pending state, the register function, and the form props.\n * @publicDocs\n */\nexport function useProductForm<TProduct extends ProductInput>(\n  store: ProductFormStore<TProduct>,\n  options?: UseProductFormOptions<TProduct>,\n): UseProductFormResult<TProduct> {\n  const onSelectRef = useRef(options?.onSelect);\n  onSelectRef.current = options?.onSelect;\n\n  const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);\n  const [pending, setPending] = useState(false);\n\n  const selectOption = useCallback(\n    (name: string, value: string) => {\n      const result = store.selectOption(name, value);\n      if (result.status !== \"invalid\") {\n        onSelectRef.current?.(result);\n      }\n      return result;\n    },\n    [store],\n  );\n\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- state is the full reactive snapshot; selectOption is stable\n  const register = useMemo(\n    () => createProductFormRegister(state.selectedVariant, selectOption),\n    [state, selectOption],\n  );\n\n  const formProps = useCallback(\n    (opts?: {\n      beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n      afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;\n    }): FormHTMLAttributes<HTMLFormElement> => ({\n      onSubmit: (e: SubmitEvent<HTMLFormElement>) => {\n        opts?.beforeSubmit?.(e);\n        if (e.defaultPrevented) return;\n        e.preventDefault();\n        setPending(true);\n        store\n          .handleFormSubmit(e.nativeEvent)\n          .then(\n            () => opts?.afterSubmit?.(e),\n            (error: unknown) => {\n              // Cart user/network errors are surfaced via the reactive `errors`\n              // state. Thrown exceptions (missing Shopify script, invalid form\n              // target) are programming errors — log them for dev visibility.\n              log.error(\"form submission error\", { error });\n            },\n          )\n          .finally(() => setPending(false));\n      },\n      method: \"post\",\n      action: getCartEndpoint(),\n    }),\n    [store],\n  );\n\n  return {\n    options: state.options,\n    selectedVariant: state.selectedVariant,\n    register,\n    formProps,\n    errors: state.errors,\n    matchedLineItem: state.matchedLineItem,\n    pending,\n    selectOption,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\ninterface ProductContextValue<TProduct extends ProductInput> {\n  store: ProductFormStore<TProduct>;\n  onSelectRef: React.RefObject<\n    ((result: ValidProductSelectionResult<TProduct>) => void) | undefined\n  >;\n}\n\n/**\n * Creates a product provider and product hooks typed to your product query.\n *\n * The provider creates the product form store, reloads the product into the store when the product changes, and destroys the store on unmount. The `useProduct` hook returns the option state and variant selection. The `useProductForm` hook adds field props, form props, and the pending state.\n *\n * Pass your Storefront API product query type as the type argument to type the selected variant and option values. Render the provider inside a cart provider. The provider throws an error without a cart provider ancestor, and each hook throws an error outside the product provider.\n *\n * @returns The typed `ProductProvider` component and the `useProduct` and `useProductForm` hooks.\n *\n * @example\n * ```ts\n * const { ProductProvider, useProduct, useProductForm } =\n *   createProductComponents<MyProductType>();\n * ```\n * @publicDocs\n */\nexport function createProductComponents<TProduct extends ProductInput>(): {\n  ProductProvider: (props: ProductProviderProps<TProduct>) => ReactNode;\n  useProduct: () => UseProductResult<TProduct>;\n  useProductForm: () => UseProductFormResult<TProduct>;\n} {\n  const Context = createContext<ProductContextValue<TProduct> | null>(null);\n\n  function useProductContext(hookName: string): ProductContextValue<TProduct> {\n    const ctx = useContext(Context);\n    if (!ctx) {\n      throw new Error(\n        `${hookName} must be used inside a <ProductProvider>. ` +\n          \"Wrap your component tree with the ProductProvider from createProductComponents(), \" +\n          \"or use the standalone useProductForm(store) hook instead.\",\n      );\n    }\n    return ctx;\n  }\n\n  function ProductProvider({ product, onSelect, children }: ProductProviderProps<TProduct>) {\n    const cartStore = useCartStore(\"ProductProvider\");\n\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is intentionally created once\n    const store = useMemo(() => createProductFormStore<TProduct>(product, cartStore), []);\n\n    useEffect(() => {\n      store.connect();\n      return () => store.destroy();\n    }, [store]);\n\n    const productKey = `${product.id}:${product.selectedOrFirstAvailableVariant?.id ?? \"\"}`;\n    const mountedRef = useRef(false);\n    useEffect(() => {\n      if (!mountedRef.current) {\n        mountedRef.current = true;\n        return;\n      }\n      store.hydrate(product);\n      // oxlint-disable-next-line react-hooks/exhaustive-deps -- productKey is the semantic dep\n    }, [productKey]);\n\n    const onSelectRef = useRef(onSelect);\n    onSelectRef.current = onSelect;\n\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- onSelectRef is a stable ref object\n    const value = useMemo<ProductContextValue<TProduct>>(() => ({ store, onSelectRef }), [store]);\n\n    return createElement(Context.Provider, { value }, children);\n  }\n\n  function useProductHook(): UseProductResult<TProduct> {\n    const { store, onSelectRef } = useProductContext(\"useProduct\");\n    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);\n\n    const selectOption = useCallback(\n      (name: string, value: string) => {\n        const result = store.selectOption(name, value);\n        if (result.status !== \"invalid\") {\n          onSelectRef.current?.(result);\n        }\n        return result;\n      },\n      [store, onSelectRef],\n    );\n\n    return {\n      options: state.options,\n      selectedVariant: state.selectedVariant,\n      selectOption,\n      errors: state.errors,\n      matchedLineItem: state.matchedLineItem,\n    };\n  }\n\n  function useProductFormHook(): UseProductFormResult<TProduct> {\n    const { store, onSelectRef } = useProductContext(\"useProductForm\");\n    return useProductForm<TProduct>(store, { onSelect: onSelectRef.current });\n  }\n\n  return {\n    ProductProvider,\n    useProduct: useProductHook,\n    useProductForm: useProductFormHook,\n  };\n}\n\n/**\n * Returns product form state and bindings from a product form store that you manage, and re-renders when the state changes.\n *\n * Create the store with `createProductFormStore`. Call `connect()` on mount, `hydrate()` when the product data changes, and `destroy()` on unmount. To skip the store setup, use the product provider from `createProductComponents`.\n *\n * @publicDocs\n */\nexport type UseProductFormForDocs =\n  /**\n   * @param store - The store that `createProductFormStore` returns.\n   * @param options - An `onSelect` callback that runs after each resolved or unresolved selection.\n   * @returns The option state, the selected variant, cart errors, the matching cart line, the pending state, the register function, and the form props.\n   */\n  (\n    store: ProductFormStore,\n    options?: UseProductFormOptions<ProductInput>,\n  ) => UseProductFormResult<ProductInput>;\n"],"mappings":";;;;;;;;;AAiCA,MAAM,MAAM,UAAU,UAAU;;;;;;;;;;;AAgGhC,SAAgB,eACd,OACA,SACgC;CAChC,MAAM,cAAc,OAAO,SAAS,SAAS;AAC7C,aAAY,UAAU,SAAS;CAE/B,MAAM,QAAQ,qBAAqB,MAAM,WAAW,MAAM,UAAU,MAAM,SAAS;CACnF,MAAM,CAAC,SAAS,cAAc,SAAS,MAAM;CAE7C,MAAM,eAAe,aAClB,MAAc,UAAkB;EAC/B,MAAM,SAAS,MAAM,aAAa,MAAM,MAAM;AAC9C,MAAI,OAAO,WAAW,UACpB,aAAY,UAAU,OAAO;AAE/B,SAAO;IAET,CAAC,MAAM,CACR;CAGD,MAAM,WAAW,cACT,0BAA0B,MAAM,iBAAiB,aAAa,EACpE,CAAC,OAAO,aAAa,CACtB;CAED,MAAM,YAAY,aACf,UAG2C;EAC1C,WAAW,MAAoC;AAC7C,SAAM,eAAe,EAAE;AACvB,OAAI,EAAE,iBAAkB;AACxB,KAAE,gBAAgB;AAClB,cAAW,KAAK;AAChB,SACG,iBAAiB,EAAE,YAAY,CAC/B,WACO,MAAM,cAAc,EAAE,GAC3B,UAAmB;AAIlB,QAAI,MAAM,yBAAyB,EAAE,OAAO,CAAC;KAEhD,CACA,cAAc,WAAW,MAAM,CAAC;;EAErC,QAAQ;EACR,QAAQ,iBAAiB;EAC1B,GACD,CAAC,MAAM,CACR;AAED,QAAO;EACL,SAAS,MAAM;EACf,iBAAiB,MAAM;EACvB;EACA;EACA,QAAQ,MAAM;EACd,iBAAiB,MAAM;EACvB;EACA;EACD;;;;;;;;;;;;;;;;;;AA8BH,SAAgB,0BAId;CACA,MAAM,UAAU,cAAoD,KAAK;CAEzE,SAAS,kBAAkB,UAAiD;EAC1E,MAAM,MAAM,WAAW,QAAQ;AAC/B,MAAI,CAAC,IACH,OAAM,IAAI,MACR,GAAG,SAAS,uLAGb;AAEH,SAAO;;CAGT,SAAS,gBAAgB,EAAE,SAAS,UAAU,YAA4C;EACxF,MAAM,YAAY,aAAa,kBAAkB;EAGjD,MAAM,QAAQ,cAAc,uBAAiC,SAAS,UAAU,EAAE,EAAE,CAAC;AAErF,kBAAgB;AACd,SAAM,SAAS;AACf,gBAAa,MAAM,SAAS;KAC3B,CAAC,MAAM,CAAC;EAEX,MAAM,aAAa,GAAG,QAAQ,GAAG,GAAG,QAAQ,iCAAiC,MAAM;EACnF,MAAM,aAAa,OAAO,MAAM;AAChC,kBAAgB;AACd,OAAI,CAAC,WAAW,SAAS;AACvB,eAAW,UAAU;AACrB;;AAEF,SAAM,QAAQ,QAAQ;KAErB,CAAC,WAAW,CAAC;EAEhB,MAAM,cAAc,OAAO,SAAS;AACpC,cAAY,UAAU;EAGtB,MAAM,QAAQ,eAA8C;GAAE;GAAO;GAAa,GAAG,CAAC,MAAM,CAAC;AAE7F,SAAO,cAAc,QAAQ,UAAU,EAAE,OAAO,EAAE,SAAS;;CAG7D,SAAS,iBAA6C;EACpD,MAAM,EAAE,OAAO,gBAAgB,kBAAkB,aAAa;EAC9D,MAAM,QAAQ,qBAAqB,MAAM,WAAW,MAAM,UAAU,MAAM,SAAS;EAEnF,MAAM,eAAe,aAClB,MAAc,UAAkB;GAC/B,MAAM,SAAS,MAAM,aAAa,MAAM,MAAM;AAC9C,OAAI,OAAO,WAAW,UACpB,aAAY,UAAU,OAAO;AAE/B,UAAO;KAET,CAAC,OAAO,YAAY,CACrB;AAED,SAAO;GACL,SAAS,MAAM;GACf,iBAAiB,MAAM;GACvB;GACA,QAAQ,MAAM;GACd,iBAAiB,MAAM;GACxB;;CAGH,SAAS,qBAAqD;EAC5D,MAAM,EAAE,OAAO,gBAAgB,kBAAkB,iBAAiB;AAClE,SAAO,eAAyB,OAAO,EAAE,UAAU,YAAY,SAAS,CAAC;;AAG3E,QAAO;EACL;EACA,YAAY;EACZ,gBAAgB;EACjB"}

package/dist/react/shop-pay.d.mts

@@ -2,7 +2,22 @@ import { ShopPayButtonOptions } from "../core/shop-pay/shop-pay.mjs";
 import { ReactElement } from "react";
 
 //#region src/react/shop-pay.d.ts
+/**
+ * Props for the `ShopPayButton` component. The props match the options of `createShopPayButton`.
+ * The component doesn't accept `className` or `style` props.
+ *
+ * @publicDocs
+ */
 type ShopPayButtonProps = ShopPayButtonOptions;
+/**
+ * Renders a Shop Pay button that takes the customer to checkout with Shop Pay. The button renders on the server and shows before scripts load.
+ *
+ * Set the size and shape with the `width` and `borderRadius` props. The component doesn't accept `className` or `style` props.
+ *
+ * @param options - The checkout target, variants, attribution, and display settings for the button.
+ * @returns The Shop Pay button element.
+ * @publicDocs
+ */
 declare function ShopPayButton(options: ShopPayButtonProps): ReactElement;
 //#endregion
 export { ShopPayButton, ShopPayButtonProps };

package/dist/react/shop-pay.mjs

@@ -4,6 +4,15 @@ import { createElement } from "react";
 //#region src/react/shop-pay.tsx
 const canUseDom = typeof document !== "undefined";
 defineShopPayButton();
+/**
+* Renders a Shop Pay button that takes the customer to checkout with Shop Pay. The button renders on the server and shows before scripts load.
+*
+* Set the size and shape with the `width` and `borderRadius` props. The component doesn't accept `className` or `style` props.
+*
+* @param options - The checkout target, variants, attribution, and display settings for the button.
+* @returns The Shop Pay button element.
+* @publicDocs
+*/
 function ShopPayButton(options) {
 	return createElement(SHOP_PAY_BUTTON_TAG_NAME, {
 		...getShopPayButtonElementAttributes(options),

package/dist/react/shop-pay.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shop-pay.mjs","names":[],"sources":["../../src/react/shop-pay.tsx"],"sourcesContent":["import { createElement, type ReactElement } from \"react\";\n\nimport {\n  defineShopPayButton,\n  getShopPayButtonDeclarativeShadowDomHtml,\n  getShopPayButtonElementAttributes,\n  SHOP_PAY_BUTTON_TAG_NAME,\n  type ShopPayButtonOptions,\n} from \"../core/shop-pay/shop-pay\";\n\nexport type ShopPayButtonProps = ShopPayButtonOptions;\n\nconst canUseDom = typeof document !== \"undefined\";\ndefineShopPayButton();\n\nexport function ShopPayButton(options: ShopPayButtonProps): ReactElement {\n  return createElement(SHOP_PAY_BUTTON_TAG_NAME, {\n    ...getShopPayButtonElementAttributes(options),\n    ...(!canUseDom\n      ? {\n          dangerouslySetInnerHTML: {\n            __html: getShopPayButtonDeclarativeShadowDomHtml(options),\n          },\n        }\n      : {}),\n  });\n}\n"],"mappings":";;;;AAYA,MAAM,YAAY,OAAO,aAAa;AACtC,qBAAqB;AAErB,SAAgB,cAAc,SAA2C;AACvE,QAAO,cAAc,0BAA0B;EAC7C,GAAG,kCAAkC,QAAQ;EAC7C,GAAI,CAAC,YACD,EACE,yBAAyB,EACvB,QAAQ,yCAAyC,QAAQ,EAC1D,EACF,GACD,EAAE;EACP,CAAC"}
+{"version":3,"file":"shop-pay.mjs","names":[],"sources":["../../src/react/shop-pay.tsx"],"sourcesContent":["import { createElement, type ReactElement } from \"react\";\n\nimport {\n  defineShopPayButton,\n  getShopPayButtonDeclarativeShadowDomHtml,\n  getShopPayButtonElementAttributes,\n  SHOP_PAY_BUTTON_TAG_NAME,\n  type ShopPayButtonOptions,\n} from \"../core/shop-pay/shop-pay\";\n\n/**\n * Props for the `ShopPayButton` component. The props match the options of `createShopPayButton`.\n * The component doesn't accept `className` or `style` props.\n *\n * @publicDocs\n */\nexport type ShopPayButtonProps = ShopPayButtonOptions;\n\nconst canUseDom = typeof document !== \"undefined\";\ndefineShopPayButton();\n\n/**\n * Renders a Shop Pay button that takes the customer to checkout with Shop Pay. The button renders on the server and shows before scripts load.\n *\n * Set the size and shape with the `width` and `borderRadius` props. The component doesn't accept `className` or `style` props.\n *\n * @param options - The checkout target, variants, attribution, and display settings for the button.\n * @returns The Shop Pay button element.\n * @publicDocs\n */\nexport function ShopPayButton(options: ShopPayButtonProps): ReactElement {\n  return createElement(SHOP_PAY_BUTTON_TAG_NAME, {\n    ...getShopPayButtonElementAttributes(options),\n    ...(!canUseDom\n      ? {\n          dangerouslySetInnerHTML: {\n            __html: getShopPayButtonDeclarativeShadowDomHtml(options),\n          },\n        }\n      : {}),\n  });\n}\n"],"mappings":";;;;AAkBA,MAAM,YAAY,OAAO,aAAa;AACtC,qBAAqB;;;;;;;;;;AAWrB,SAAgB,cAAc,SAA2C;AACvE,QAAO,cAAc,0BAA0B;EAC7C,GAAG,kCAAkC,QAAQ;EAC7C,GAAI,CAAC,YACD,EACE,yBAAyB,EACvB,QAAQ,yCAAyC,QAAQ,EAC1D,EACF,GACD,EAAE;EACP,CAAC"}