@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

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

@@ -1,32 +1,57 @@
 import { PredictiveSearchFormRegister as PredictiveSearchFormRegister$1 } from "../core/predictive-search/form.mjs";
 import { PredictiveSearchData } from "../core/predictive-search/search.mjs";
-import { CreatePredictiveSearchStoreOptions, PredictiveSearchState, PredictiveSearchStore } from "../core/predictive-search/store.mjs";
+import { CreatePredictiveSearchStoreOptions, PredictiveSearchActions, PredictiveSearchState, PredictiveSearchStore } from "../core/predictive-search/store.mjs";
 import * as _$react from "react";
 import { ChangeEvent, FormHTMLAttributes, InputHTMLAttributes, ReactNode, SubmitEvent } from "react";
 
 //#region src/react/predictive-search.d.ts
 type PredictiveSearchContextValue = {
   store: PredictiveSearchStore;
+  actions: PredictiveSearchActions;
   searchAction?: string;
 };
+/** Props for the {@link PredictiveSearchProvider} component. */
 type PredictiveSearchProviderProps = CreatePredictiveSearchStoreOptions & {
-  children?: ReactNode;
+  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;
 };
-type PredictiveSearchActions = Pick<PredictiveSearchStore, "search" | "clear">;
+/**
+ * Options for the form props builder returned by {@link usePredictiveSearchForm}.
+ *
+ * Accepts all standard form HTML attributes except `onSubmit`, which is
+ * replaced by a version that provides the extracted search term.
+ */
 type PredictiveSearchFormPropsOptions = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & {
-  preventDefault?: boolean;
+  /** 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. */
   onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;
 };
+/**
+ * Options for the query input props builder returned by
+ * {@link usePredictiveSearchForm}'s `register` method.
+ *
+ * Accepts all standard input HTML attributes except those controlled by the
+ * form registration.
+ */
 type PredictiveSearchQueryInputPropsOptions = Omit<InputHTMLAttributes<HTMLInputElement>, "autoCapitalize" | "autoComplete" | "name" | "onChange" | "spellCheck" | "type"> & {
-  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;
+  /** 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 PredictiveSearchFormField = Parameters<PredictiveSearchFormRegister$1>[0];
+/** Generates input element attributes for a named form field. */
 type PredictiveSearchFormRegister = (field: PredictiveSearchFormField, options?: PredictiveSearchQueryInputPropsOptions) => InputHTMLAttributes<HTMLInputElement>;
+/** Return type of {@link usePredictiveSearchForm}, providing methods to build a progressively-enhanced search form. */
 type PredictiveSearchFormResult = {
-  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;
+  /** 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. */
   register: PredictiveSearchFormRegister;
 };
+/**
+ * Creates and manages a predictive search store, providing it to descendant
+ * hooks via React context.
+ *
+ * Recreates the store when configuration props change. Connects the store
+ * on mount and destroys it on unmount.
+ *
+ * @throws {Error} When no `fetch` implementation is available (neither passed as a prop nor available on `globalThis`).
+ */
 declare function PredictiveSearchProvider({
   children,
   predictiveSearchEndpoint,
@@ -40,10 +65,46 @@ declare function PredictiveSearchProvider({
   searchableFields,
   unavailableProducts
 }: PredictiveSearchProviderProps): _$react.FunctionComponentElement<_$react.ProviderProps<PredictiveSearchContextValue | null>>;
+/**
+ * Subscribes to the predictive search store's state.
+ *
+ * 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`).
+ *
+ * Must be used inside a {@link PredictiveSearchProvider}.
+ *
+ * @throws {Error} When called outside a PredictiveSearchProvider.
+ */
 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.
+ *
+ * Must be used inside a {@link PredictiveSearchProvider}.
+ *
+ * @throws {Error} When called outside a PredictiveSearchProvider.
+ */
 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.
+ *
+ * Must be used inside a {@link PredictiveSearchProvider}.
+ *
+ * @throws {Error} When called outside a PredictiveSearchProvider.
+ */
 declare function usePredictiveSearchForm(): PredictiveSearchFormResult;
 //#endregion
-export { PredictiveSearchActions, PredictiveSearchFormPropsOptions, PredictiveSearchFormRegister, PredictiveSearchFormResult, PredictiveSearchProvider, PredictiveSearchProviderProps, PredictiveSearchQueryInputPropsOptions, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm };
+export { PredictiveSearchFormPropsOptions, PredictiveSearchFormRegister, PredictiveSearchFormResult, PredictiveSearchProvider, PredictiveSearchProviderProps, PredictiveSearchQueryInputPropsOptions, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm };
 //# sourceMappingURL=predictive-search.d.mts.map

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

@@ -2,11 +2,20 @@
 
 import { createPredictiveSearchFormRegister, getPredictiveSearchFormAttributes, readPredictiveSearchFormTerm } from "../core/predictive-search/form.mjs";
 import { createPredictiveSearchStore } from "../core/predictive-search/store.mjs";
-import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useInsertionEffect, useMemo, useRef, useSyncExternalStore } from "react";
 
 //#region src/react/predictive-search.tsx
 const CONFIG_ARRAY_SEPARATOR = "\0";
 const PredictiveSearchContext = createContext(null);
+/**
+* Creates and manages a predictive search store, providing it to descendant
+* hooks via React context.
+*
+* Recreates the store when configuration props change. Connects the store
+* on mount and destroys it on unmount.
+*
+* @throws {Error} When no `fetch` implementation is available (neither passed as a prop nor available on `globalThis`).
+*/
 function PredictiveSearchProvider({ children, predictiveSearchEndpoint, searchAction, debounceInMs, minTermLength, fetch, limit, limitScope, types, searchableFields, unavailableProducts }) {
 	const store = useMemo(() => createPredictiveSearchStore({
 		predictiveSearchEndpoint,
@@ -29,14 +38,27 @@ function PredictiveSearchProvider({ children, predictiveSearchEndpoint, searchAc
 		getArrayKey(searchableFields),
 		unavailableProducts
 	]);
+	const storeRef = useRef(store);
+	useInsertionEffect(() => {
+		storeRef.current = store;
+	}, [store]);
+	const actions = useMemo(() => ({
+		search: (term) => storeRef.current.search(term),
+		clear: () => storeRef.current.clear()
+	}), []);
 	useEffect(() => {
 		store.connect();
 		return () => store.destroy();
 	}, [store]);
 	const contextValue = useMemo(() => ({
 		store,
+		actions,
 		searchAction
-	}), [store, searchAction]);
+	}), [
+		store,
+		actions,
+		searchAction
+	]);
 	return createElement(PredictiveSearchContext.Provider, { value: contextValue }, children);
 }
 function getArrayKey(values) {
@@ -84,15 +106,35 @@ 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.
+*
+* Must be used inside a {@link PredictiveSearchProvider}.
+*
+* @throws {Error} When called outside a PredictiveSearchProvider.
+*/
 function usePredictiveSearchActions() {
-	const store = useRequiredStore("usePredictiveSearchActions");
-	return useMemo(() => ({
-		search: store.search,
-		clear: store.clear
-	}), [store]);
+	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.
+*
+* Must be used inside a {@link PredictiveSearchProvider}.
+*
+* @throws {Error} When called outside a PredictiveSearchProvider.
+*/
 function usePredictiveSearchForm() {
-	const { searchAction, store } = useRequiredContext("usePredictiveSearchForm");
+	const { searchAction, actions } = useRequiredContext("usePredictiveSearchForm");
 	const coreRegister = useMemo(() => createPredictiveSearchFormRegister(), []);
 	const register = useCallback((field, props = {}) => {
 		const { onChange, ...attributes } = props;
@@ -104,10 +146,10 @@ function usePredictiveSearchForm() {
 				const term = event.currentTarget.value;
 				onChange?.(event, term);
 				if (event.defaultPrevented) return;
-				store.search(term);
+				actions.search(term);
 			}
 		};
-	}, [coreRegister, store]);
+	}, [coreRegister, actions]);
 	return {
 		formProps: useCallback((props = {}) => {
 			const { onSubmit, preventDefault, ...attributes } = props;
@@ -120,10 +162,10 @@ function usePredictiveSearchForm() {
 					if (event.defaultPrevented) return;
 					if (!preventDefault) return;
 					event.preventDefault();
-					store.search(term);
+					actions.search(term);
 				}
 			};
-		}, [searchAction, store]),
+		}, [searchAction, actions]),
 		register
 	};
 }

package/dist/development/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  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 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  searchAction?: string;\n};\n\nconst PredictiveSearchContext = createContext<PredictiveSearchContextValue | null>(null);\n\nexport type PredictiveSearchProviderProps = CreatePredictiveSearchStoreOptions & {\n  children?: ReactNode;\n  searchAction?: string;\n};\n\nexport type PredictiveSearchActions = Pick<PredictiveSearchStore, \"search\" | \"clear\">;\n\nexport type PredictiveSearchFormPropsOptions = Omit<\n  FormHTMLAttributes<HTMLFormElement>,\n  \"onSubmit\"\n> & {\n  preventDefault?: boolean;\n  onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;\n};\n\nexport type PredictiveSearchQueryInputPropsOptions = Omit<\n  InputHTMLAttributes<HTMLInputElement>,\n  \"autoCapitalize\" | \"autoComplete\" | \"name\" | \"onChange\" | \"spellCheck\" | \"type\"\n> & {\n  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;\n};\n\ntype PredictiveSearchFormField = Parameters<CorePredictiveSearchFormRegister>[0];\n\nexport type PredictiveSearchFormRegister = (\n  field: PredictiveSearchFormField,\n  options?: PredictiveSearchQueryInputPropsOptions,\n) => InputHTMLAttributes<HTMLInputElement>;\n\nexport type PredictiveSearchFormResult = {\n  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;\n  register: PredictiveSearchFormRegister;\n};\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  useEffect(() => {\n    store.connect();\n    return () => store.destroy();\n  }, [store]);\n\n  const contextValue = useMemo(() => ({ store, searchAction }), [store, searchAction]);\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\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\nexport function usePredictiveSearchActions(): PredictiveSearchActions {\n  const store = useRequiredStore(\"usePredictiveSearchActions\");\n\n  return useMemo(\n    () => ({\n      search: store.search,\n      clear: store.clear,\n    }),\n    [store],\n  );\n}\n\nexport function usePredictiveSearchForm(): PredictiveSearchFormResult {\n  const { searchAction, store } = 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 store.search(term);\n        },\n      };\n    },\n    [coreRegister, store],\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 store.search(term);\n        },\n      };\n    },\n    [searchAction, store],\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/** 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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"}

package/dist/development/react/product.d.mts

@@ -20,6 +20,7 @@ interface UseProductFormResult<TProduct extends ProductInput> {
   }) => FormHTMLAttributes<HTMLFormElement>;
   errors: ProductFormErrors;
   matchedLineItem: CartLine | null;
+  /** Whether a form submission is currently in flight. */
   pending: boolean;
   selectOption: (name: string, value: string) => VariantSelectionResult<ProductVariantFrom<TProduct>>;
 }

package/dist/development/react/product.mjs

@@ -75,9 +75,12 @@ function createProductComponents() {
 		return ctx;
 	}
 	function ProductProvider({ product, onSelect, children }) {
-		const cartStore = useCartStore();
+		const cartStore = useCartStore("ProductProvider");
 		const store = useMemo(() => createProductFormStore(product, cartStore), []);
-		useEffect(() => () => store.destroy(), [store]);
+		useEffect(() => {
+			store.connect();
+			return () => store.destroy();
+		}, [store]);
 		const productKey = `${product.id}:${product.selectedOrFirstAvailableVariant?.id ?? ""}`;
 		const mountedRef = useRef(false);
 		useEffect(() => {

package/dist/development/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  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();\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(() => () => store.destroy(), [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":";;;;;;;;;AAiCA,MAAM,MAAM,UAAU,UAAU;;;;;;;;;AAkEhC,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,cAAc;EAGhC,MAAM,QAAQ,cAAc,uBAAiC,SAAS,UAAU,EAAE,EAAE,CAAC;AAErF,wBAAsB,MAAM,SAAS,EAAE,CAAC,MAAM,CAAC;EAE/C,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"}
+{"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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"}

package/dist/development/react/shopify-scripts.mjs

@@ -9,6 +9,7 @@ function ShopifyScripts(options) {
 	const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;
 	useEffect(() => {
 		initializeShopifyScripts({
+			consent,
 			navigate,
 			routes,
 			webMcp

package/dist/development/react/shopify-scripts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shopify-scripts.mjs","names":[],"sources":["../../../src/react/shopify-scripts.tsx"],"sourcesContent":["\"use client\";\n\nimport { createElement, Fragment, useEffect } from \"react\";\nimport type * as React from \"react\";\n\nimport {\n  getShopifyScriptTags,\n  initializeShopifyScripts,\n  type ShopifyRoutesOptions,\n  type ShopifyScriptTagsOptions,\n} from \"../core/shopify-scripts\";\n\nexport type ShopifyScriptsProps = ShopifyScriptTagsOptions & {\n  navigate?: ShopifyRoutesOptions[\"navigate\"];\n  routes?: ShopifyRoutesOptions[\"routes\"];\n  webMcp?: boolean;\n};\n\ndeclare module \"react\" {\n  namespace JSX {\n    interface IntrinsicElements {\n      \"shopify-chat\": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;\n    }\n  }\n}\n\nexport function ShopifyScripts(options: ShopifyScriptsProps) {\n  const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;\n\n  useEffect(() => {\n    void initializeShopifyScripts({ navigate, routes, webMcp });\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- ShopifyScripts browser startup is initialized once from initial props.\n  }, []);\n\n  return createElement(\n    Fragment,\n    null,\n    getShopifyScriptTags({ ...scriptOptions, consent }).tags.map(\n      ({ tagName, attributes, innerHTML }, index) =>\n        createElement(tagName, {\n          key: index,\n          ...getReactAttributes(attributes),\n          ...(innerHTML ? { dangerouslySetInnerHTML: { __html: innerHTML } } : {}),\n        }),\n    ),\n  );\n}\n\nfunction getReactAttributes(attributes: Record<string, string | boolean> = {}) {\n  const reactAttributes = Object.fromEntries(\n    Object.entries(attributes).map(([name, value]) => [\n      name === \"crossorigin\" ? \"crossOrigin\" : name,\n      value,\n    ]),\n  );\n\n  if (attributes.nonce !== undefined) {\n    // Browsers intentionally hide nonce content attributes from getAttribute(),\n    // which can make React report a false hydration mismatch for SSR scripts.\n    reactAttributes.suppressHydrationWarning = true;\n  }\n\n  if (attributes.async === true && typeof attributes.src === \"string\") {\n    // React hoists async scripts without handlers, which can let them execute before\n    // the inline Shopify bootstrap scripts that configure their globals.\n    return { ...reactAttributes, onLoad: disableReactScriptHoisting };\n  }\n\n  return reactAttributes;\n}\n\nconst disableReactScriptHoisting = () => {};\n"],"mappings":";;;;;;;AA0BA,SAAgB,eAAe,SAA8B;CAC3D,MAAM,EAAE,SAAS,UAAU,QAAQ,SAAS,MAAM,GAAG,kBAAkB;AAEvE,iBAAgB;AACd,EAAK,yBAAyB;GAAE;GAAU;GAAQ;GAAQ,CAAC;IAE1D,EAAE,CAAC;AAEN,QAAO,cACL,UACA,MACA,qBAAqB;EAAE,GAAG;EAAe;EAAS,CAAC,CAAC,KAAK,KACtD,EAAE,SAAS,YAAY,aAAa,UACnC,cAAc,SAAS;EACrB,KAAK;EACL,GAAG,mBAAmB,WAAW;EACjC,GAAI,YAAY,EAAE,yBAAyB,EAAE,QAAQ,WAAW,EAAE,GAAG,EAAE;EACxE,CAAC,CACL,CACF;;AAGH,SAAS,mBAAmB,aAA+C,EAAE,EAAE;CAC7E,MAAM,kBAAkB,OAAO,YAC7B,OAAO,QAAQ,WAAW,CAAC,KAAK,CAAC,MAAM,WAAW,CAChD,SAAS,gBAAgB,gBAAgB,MACzC,MACD,CAAC,CACH;AAED,KAAI,WAAW,UAAU,OAGvB,iBAAgB,2BAA2B;AAG7C,KAAI,WAAW,UAAU,QAAQ,OAAO,WAAW,QAAQ,SAGzD,QAAO;EAAE,GAAG;EAAiB,QAAQ;EAA4B;AAGnE,QAAO;;AAGT,MAAM,mCAAmC"}
+{"version":3,"file":"shopify-scripts.mjs","names":[],"sources":["../../../src/react/shopify-scripts.tsx"],"sourcesContent":["\"use client\";\n\nimport { createElement, Fragment, useEffect } from \"react\";\nimport type * as React from \"react\";\n\nimport {\n  getShopifyScriptTags,\n  initializeShopifyScripts,\n  type ShopifyRoutesOptions,\n  type ShopifyScriptTagsOptions,\n} from \"../core/shopify-scripts\";\n\nexport type ShopifyScriptsProps = ShopifyScriptTagsOptions & {\n  navigate?: ShopifyRoutesOptions[\"navigate\"];\n  routes?: ShopifyRoutesOptions[\"routes\"];\n  webMcp?: boolean;\n};\n\ndeclare module \"react\" {\n  namespace JSX {\n    interface IntrinsicElements {\n      \"shopify-chat\": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;\n    }\n  }\n}\n\nexport function ShopifyScripts(options: ShopifyScriptsProps) {\n  const { consent, navigate, routes, webMcp = true, ...scriptOptions } = options;\n\n  useEffect(() => {\n    void initializeShopifyScripts({ consent, navigate, routes, webMcp });\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- ShopifyScripts browser startup is initialized once from initial props.\n  }, []);\n\n  return createElement(\n    Fragment,\n    null,\n    getShopifyScriptTags({ ...scriptOptions, consent }).tags.map(\n      ({ tagName, attributes, innerHTML }, index) =>\n        createElement(tagName, {\n          key: index,\n          ...getReactAttributes(attributes),\n          ...(innerHTML ? { dangerouslySetInnerHTML: { __html: innerHTML } } : {}),\n        }),\n    ),\n  );\n}\n\nfunction getReactAttributes(attributes: Record<string, string | boolean> = {}) {\n  const reactAttributes = Object.fromEntries(\n    Object.entries(attributes).map(([name, value]) => [\n      name === \"crossorigin\" ? \"crossOrigin\" : name,\n      value,\n    ]),\n  );\n\n  if (attributes.nonce !== undefined) {\n    // Browsers intentionally hide nonce content attributes from getAttribute(),\n    // which can make React report a false hydration mismatch for SSR scripts.\n    reactAttributes.suppressHydrationWarning = true;\n  }\n\n  if (attributes.async === true && typeof attributes.src === \"string\") {\n    // React hoists async scripts without handlers, which can let them execute before\n    // the inline Shopify bootstrap scripts that configure their globals.\n    return { ...reactAttributes, onLoad: disableReactScriptHoisting };\n  }\n\n  return reactAttributes;\n}\n\nconst disableReactScriptHoisting = () => {};\n"],"mappings":";;;;;;;AA0BA,SAAgB,eAAe,SAA8B;CAC3D,MAAM,EAAE,SAAS,UAAU,QAAQ,SAAS,MAAM,GAAG,kBAAkB;AAEvE,iBAAgB;AACd,EAAK,yBAAyB;GAAE;GAAS;GAAU;GAAQ;GAAQ,CAAC;IAEnE,EAAE,CAAC;AAEN,QAAO,cACL,UACA,MACA,qBAAqB;EAAE,GAAG;EAAe;EAAS,CAAC,CAAC,KAAK,KACtD,EAAE,SAAS,YAAY,aAAa,UACnC,cAAc,SAAS;EACrB,KAAK;EACL,GAAG,mBAAmB,WAAW;EACjC,GAAI,YAAY,EAAE,yBAAyB,EAAE,QAAQ,WAAW,EAAE,GAAG,EAAE;EACxE,CAAC,CACL,CACF;;AAGH,SAAS,mBAAmB,aAA+C,EAAE,EAAE;CAC7E,MAAM,kBAAkB,OAAO,YAC7B,OAAO,QAAQ,WAAW,CAAC,KAAK,CAAC,MAAM,WAAW,CAChD,SAAS,gBAAgB,gBAAgB,MACzC,MACD,CAAC,CACH;AAED,KAAI,WAAW,UAAU,OAGvB,iBAAgB,2BAA2B;AAG7C,KAAI,WAAW,UAAU,QAAQ,OAAO,WAAW,QAAQ,SAGzD,QAAO;EAAE,GAAG;EAAiB,QAAQ;EAA4B;AAGnE,QAAO;;AAGT,MAAM,mCAAmC"}

package/dist/development/vue/cart.d.mts

@@ -1,5 +1,5 @@
 import { CartData, CartState } from "../core/cart/state.mjs";
-import { CartStore, CreateCartStoreOptions } from "../core/cart/cart.mjs";
+import { CartActions, CreateCartStoreOptions } from "../core/cart/cart.mjs";
 import { CartFormRegister } from "../core/cart/form.mjs";
 import { CartDataFromHandlers } from "../core/cart/server-handlers.mjs";
 import { ComputedRef, PropType, ShallowRef } from "vue";
@@ -18,8 +18,6 @@ type TypedCartProvider<TData extends CartData> = {
     };
   };
 };
-/** Actions for reconciling cart state after updates outside Standard Actions. */
-type CartActions = Pick<CartStore, "refresh">;
 type TypedCartComponents<TData extends CartData> = {
   CartProvider: TypedCartProvider<TData>;
   useCart: TypedUseCart<TData>;
@@ -27,12 +25,73 @@ type TypedCartComponents<TData extends CartData> = {
   useCartActions: typeof useCartActions;
   useCartForm: typeof useCartForm;
 };
+/**
+ * Returns cart actions for reconciling state after out-of-band mutations.
+ *
+ * Currently exposes {@link CartStore.refresh} — call it after server-side cart
+ * mutations that bypass the form system.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { refresh } = useCartActions();
+ *
+ * async function handleServerAction() {
+ *   await createCartOnServer();
+ *   refresh();
+ * }
+ * </script>
+ * ```
+ */
 declare function useCartActions(): CartActions;
+/**
+ * Subscribes the {@link CartStore} to the analytics event dispatcher.
+ *
+ * Call once near the root of your app. Starts tracking on mount via `onMounted`
+ * and cleans up via `onScopeDispose`.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * useCartAnalytics();
+ * </script>
+ * ```
+ */
 declare function useCartAnalytics(): void;
+/**
+ * Returns form props, a field register function, and reactive pending state
+ * for building cart forms in Vue.
+ *
+ * Unlike the React hook, the Vue variant includes `isPending` — a reactive
+ * object with `initial` (`ComputedRef<boolean>`) for the initial cart load
+ * and `lines(lineId?)` for checking per-line or any-line pending state.
+ *
+ * Note: `interactive: true` returns numeric input attributes but does **not**
+ * auto-submit on change — that behavior requires `attachQuantityInput`, which
+ * is only wired by the React adapter.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { formProps, register, isPending } = useCartForm();
+ * </script>
+ *
+ * <template>
+ *   <form v-bind="formProps()">
+ *     <input v-bind="register('lineId', { value: line.id })" />
+ *     <input v-bind="register('quantity', { value: line.quantity })" />
+ *     <button v-bind="register('set')" />
+ *     <button v-bind="register('increase')">+</button>
+ *     <button v-bind="register('decrease')">−</button>
+ *     <span v-if="isPending.lines(line.id)">Updating…</span>
+ *   </form>
+ * </template>
+ * ```
+ */
 declare function useCartForm(): {
   formProps: (opts?: {
-    beforeSubmit?: (e: Event) => void;
-    afterSubmit?: (e: Event) => void;
+    beforeSubmit?: (e: SubmitEvent) => void;
+    afterSubmit?: (e: SubmitEvent) => void;
   }) => Record<string, unknown>;
   register: CartFormRegister;
   isPending: {
@@ -40,7 +99,27 @@ declare function useCartForm(): {
     lines: (lineId?: string) => boolean;
   };
 };
+/**
+ * Factory that returns typed cart components and composables matched to your
+ * server handler's cart query shape.
+ *
+ * The generic `THandlers` parameter is inferred from your `createCartServerHandlers`
+ * call, so every composable's {@link CartState} carries your custom cart fields.
+ *
+ * @example
+ * ```ts
+ * import type { cartServerHandlers } from "./server/cart.server";
+ *
+ * const {
+ *   CartProvider,
+ *   useCart,
+ *   useOptionalCart,
+ *   useCartActions,
+ *   useCartForm,
+ * } = createCartComponents<typeof cartServerHandlers>();
+ * ```
+ */
 declare function createCartComponents<THandlers>(): TypedCartComponents<CartDataFromHandlers<THandlers>>;
 //#endregion
-export { CartActions, createCartComponents, useCartActions, useCartAnalytics };
+export { createCartComponents, useCartActions, useCartAnalytics };
 //# sourceMappingURL=cart.d.mts.map

package/dist/development/vue/cart.mjs

@@ -25,6 +25,20 @@ function useCartStore(composableName = "useCartStore") {
 function useOptionalCartStore() {
 	return inject(CartStoreKey, null);
 }
+/**
+* Vue component that creates and manages a {@link CartStore} instance.
+*
+* Calls {@link CartStore.connect} on mount and {@link CartStore.destroy} on unmount.
+* All cart composables (`useCart`, `useCartForm`, `useCartActions`) must be
+* descendants of this component.
+*
+* @example
+* ```vue
+* <CartProvider :initialData="{ cart: loaderData.cart }">
+*   <App />
+* </CartProvider>
+* ```
+*/
 const CartProvider = defineComponent({
 	name: "CartProvider",
 	props: { initialData: {
@@ -47,9 +61,40 @@ const CartProvider = defineComponent({
 function useCart(selector, isEqual) {
 	return useCartSelector(useCartStore("useCart"), selector ?? ((state) => state), isEqual);
 }
+/**
+* Returns cart actions for reconciling state after out-of-band mutations.
+*
+* Currently exposes {@link CartStore.refresh} — call it after server-side cart
+* mutations that bypass the form system.
+*
+* @example
+* ```vue
+* <script setup>
+* const { refresh } = useCartActions();
+*
+* async function handleServerAction() {
+*   await createCartOnServer();
+*   refresh();
+* }
+* <\/script>
+* ```
+*/
 function useCartActions() {
 	return { refresh: useCartStore("useCartActions").refresh };
 }
+/**
+* Subscribes the {@link CartStore} to the analytics event dispatcher.
+*
+* Call once near the root of your app. Starts tracking on mount via `onMounted`
+* and cleans up via `onScopeDispose`.
+*
+* @example
+* ```vue
+* <script setup>
+* useCartAnalytics();
+* <\/script>
+* ```
+*/
 function useCartAnalytics() {
 	const store = useCartStore("useCartAnalytics");
 	let stopTracking;
@@ -76,6 +121,36 @@ function useCartSelector(store, selector, isEqual) {
 	}));
 	return selected;
 }
+/**
+* Returns form props, a field register function, and reactive pending state
+* for building cart forms in Vue.
+*
+* Unlike the React hook, the Vue variant includes `isPending` — a reactive
+* object with `initial` (`ComputedRef<boolean>`) for the initial cart load
+* and `lines(lineId?)` for checking per-line or any-line pending state.
+*
+* Note: `interactive: true` returns numeric input attributes but does **not**
+* auto-submit on change — that behavior requires `attachQuantityInput`, which
+* is only wired by the React adapter.
+*
+* @example
+* ```vue
+* <script setup>
+* const { formProps, register, isPending } = useCartForm();
+* <\/script>
+*
+* <template>
+*   <form v-bind="formProps()">
+*     <input v-bind="register('lineId', { value: line.id })" />
+*     <input v-bind="register('quantity', { value: line.quantity })" />
+*     <button v-bind="register('set')" />
+*     <button v-bind="register('increase')">+</button>
+*     <button v-bind="register('decrease')">−</button>
+*     <span v-if="isPending.lines(line.id)">Updating…</span>
+*   </form>
+* </template>
+* ```
+*/
 function useCartForm() {
 	const store = useCartStore("useCartForm");
 	const loading = useCart((s) => s.loading);
@@ -101,6 +176,26 @@ function useCartForm() {
 		}
 	};
 }
+/**
+* Factory that returns typed cart components and composables matched to your
+* server handler's cart query shape.
+*
+* The generic `THandlers` parameter is inferred from your `createCartServerHandlers`
+* call, so every composable's {@link CartState} carries your custom cart fields.
+*
+* @example
+* ```ts
+* import type { cartServerHandlers } from "./server/cart.server";
+*
+* const {
+*   CartProvider,
+*   useCart,
+*   useOptionalCart,
+*   useCartActions,
+*   useCartForm,
+* } = createCartComponents<typeof cartServerHandlers>();
+* ```
+*/
 function createCartComponents() {
 	const TypedCartProvider = createTypedCartProvider();
 	const useTypedCart = ((selector, isEqual) => {