@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/dist/development/react/cart.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.mjs","names":[],"sources":["../../../src/react/cart.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type RefCallback,\n  type SubmitEvent,\n} from \"react\";\n\nimport { trackCartAnalytics } from \"../core/analytics/cart-tracker\";\nimport { attachQuantityInput } from \"../core/cart/attach-quantity-input\";\nimport {\n  configureCartEndpoint as configureCoreCartEndpoint,\n  createCartStore,\n  type CreateCartStoreOptions,\n  type CartStore,\n} from \"../core/cart/cart\";\nimport { createCartFormRegister } from \"../core/cart/form\";\nimport type { CartDataFromHandlers } from \"../core/cart/server-handlers\";\nimport { type CartData, type CartState } from \"../core/cart/state\";\n\nconst DEFAULT_CART_ENDPOINT = \"/api/cart\";\n\nlet cartEndpoint = DEFAULT_CART_ENDPOINT;\n\nconst CartContext = createContext<CartStore | null>(null);\n\nexport function configureCartEndpoint(endpoint: string): void {\n  cartEndpoint = endpoint;\n  configureCoreCartEndpoint(endpoint);\n}\n\nexport function getCartEndpoint(): string {\n  return cartEndpoint;\n}\n\ntype TypedCartProviderProps<TData extends CartData> = {\n  initialData?: CartInitialData<TData>;\n  children?: ReactNode;\n};\n\ntype CartInitialData<TData extends CartData = CartData> =\n  CreateCartStoreOptions<TData>[\"initialData\"];\n\n/** Actions for reconciling cart state after updates outside Standard Actions. */\nexport type CartActions = Pick<CartStore, \"refresh\">;\n\ntype TypedCartComponents<TData extends CartData> = {\n  CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;\n  useCart: <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;\n  useSuspenseCart: <S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ) => S;\n  useOptionalCart: <S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ) => S | undefined;\n  useCartActions: typeof useCartActions;\n  useCartForm: typeof useCartForm;\n};\n\nexport function createCartComponents<THandlers>(): TypedCartComponents<\n  CartDataFromHandlers<THandlers>\n> {\n  type TData = CartDataFromHandlers<THandlers>;\n\n  function TypedCartProvider({ initialData, children }: TypedCartProviderProps<TData>) {\n    return (\n      <CartProvider initialData={initialData as CartInitialData | undefined}>\n        {children}\n      </CartProvider>\n    );\n  }\n\n  function useTypedCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    return useCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useTypedOptionalCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S | undefined {\n    return useOptionalCart<CartData, S>((state) => selector(state as CartState<TData>), isEqual);\n  }\n\n  function useSuspenseCart<S>(\n    selector: (state: CartState<TData>) => S,\n    isEqual?: (a: S, b: S) => boolean,\n  ): S {\n    const readyPromise = useCart((state) => state.readyPromise);\n    if (readyPromise) throw readyPromise;\n    return useCart(selector, isEqual);\n  }\n\n  return {\n    CartProvider: TypedCartProvider,\n    useCart: useTypedCart,\n    useSuspenseCart,\n    useOptionalCart: useTypedOptionalCart,\n    useCartActions,\n    useCartForm,\n  } as const;\n}\n\nexport function useCartStore(hookName = \"useCart\"): CartStore {\n  const store = useContext(CartContext);\n  if (!store) throw new Error(`${hookName} must be used inside <CartProvider>.`);\n  return store;\n}\n\nfunction useOptionalCartStore(): CartStore | null {\n  return useContext(CartContext);\n}\n\nexport function CartProvider({\n  initialData,\n  children,\n}: {\n  initialData?: CartInitialData;\n  children?: ReactNode;\n}) {\n  // oxlint-disable-next-line react-hooks/exhaustive-deps -- store is created once with the initial server data\n  const store = useMemo(() => createCartStore({ initialData }), []);\n\n  useEffect(() => {\n    configureCoreCartEndpoint(cartEndpoint);\n    store.connect();\n    return () => {\n      store.destroy();\n    };\n  }, [store]);\n\n  return <CartContext.Provider value={store}>{children}</CartContext.Provider>;\n}\n\nexport function useCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const store = useCartStore();\n  return useCartSelector(store, selector, isEqual) as S;\n}\n\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\nexport function useCartAnalytics(): void {\n  const store = useCartStore();\n\n  useEffect(() => trackCartAnalytics(store), [store]);\n}\n\n/**\n * Like `useCart`, but returns `undefined` when rendered outside a `<CartProvider>`.\n * @internal\n */\nexport function useOptionalCart<TData extends CartData = CartData, S = unknown>(\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S | undefined {\n  const store = useOptionalCartStore();\n  if (!store) return undefined;\n  return useCartSelector(store, selector, isEqual);\n}\n\nfunction useCartSelector<TData extends CartData = CartData, S = unknown>(\n  store: CartStore,\n  selector: (state: CartState<TData>) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S {\n  const cachedRef = useRef<{ state: unknown; selector: typeof selector; value: S } | null>(null);\n\n  const getSnapshot = () => {\n    const state = store.getState() as CartState<TData>;\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    const next = selector(state);\n\n    if (cachedRef.current && isEqual?.(cachedRef.current.value, 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 useCartForm() {\n  const store = useCartStore();\n  const coreRegister = useMemo(() => createCartFormRegister(), []);\n\n  const register = useMemo(() => {\n    type Register = typeof coreRegister;\n    const wrapped = ((...args: Parameters<Register>) => {\n      const result = (coreRegister as Function)(...args);\n      const [field, opts] = args as [string, { interactive?: boolean }?];\n\n      if (field === \"quantity\" && opts?.interactive) {\n        let cleanup: (() => void) | null = null;\n        const ref: RefCallback<HTMLInputElement> = (el) => {\n          cleanup?.();\n          cleanup = null;\n          if (el) {\n            const form = el.closest(\"form\");\n            if (form) cleanup = attachQuantityInput(el, form);\n          }\n        };\n        const { value: _, ...rest } = result;\n        return { ...rest, defaultValue: result.value, ref };\n      }\n\n      return result;\n    }) as Register;\n    return wrapped;\n  }, [coreRegister]);\n\n  const formProps = (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      store.handleFormSubmit(e.nativeEvent).catch(() => {});\n      opts?.afterSubmit?.(e);\n    },\n    method: \"post\",\n    action: cartEndpoint,\n  });\n\n  return { formProps, register };\n}\n"],"mappings":";;;;;;;;;;AA6BA,IAAI,eAAe;AAEnB,MAAM,cAAc,cAAgC,KAAK;AAOzD,SAAgB,kBAA0B;AACxC,QAAO;;AA6BT,SAAgB,uBAEd;CAGA,SAAS,kBAAkB,EAAE,aAAa,YAA2C;AACnF,SACE,oBAAC,cAAD;GAA2B;GACxB;GACY;;CAInB,SAAS,aACP,UACA,SACG;AACH,SAAO,SAAsB,UAAU,SAAS,MAA0B,EAAE,QAAQ;;CAGtF,SAAS,qBACP,UACA,SACe;AACf,SAAO,iBAA8B,UAAU,SAAS,MAA0B,EAAE,QAAQ;;CAG9F,SAAS,gBACP,UACA,SACG;EACH,MAAM,eAAe,SAAS,UAAU,MAAM,aAAa;AAC3D,MAAI,aAAc,OAAM;AACxB,SAAO,QAAQ,UAAU,QAAQ;;AAGnC,QAAO;EACL,cAAc;EACd,SAAS;EACT;EACA,iBAAiB;EACjB;EACA;EACD;;AAGH,SAAgB,aAAa,WAAW,WAAsB;CAC5D,MAAM,QAAQ,WAAW,YAAY;AACrC,KAAI,CAAC,MAAO,OAAM,IAAI,MAAM,GAAG,SAAS,sCAAsC;AAC9E,QAAO;;AAGT,SAAS,uBAAyC;AAChD,QAAO,WAAW,YAAY;;AAGhC,SAAgB,aAAa,EAC3B,aACA,YAIC;CAED,MAAM,QAAQ,cAAc,gBAAgB,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC;AAEjE,iBAAgB;AACd,wBAA0B,aAAa;AACvC,QAAM,SAAS;AACf,eAAa;AACX,SAAM,SAAS;;IAEhB,CAAC,MAAM,CAAC;AAEX,QAAO,oBAAC,YAAY,UAAb;EAAsB,OAAO;EAAQ;EAAgC;;AAG9E,SAAgB,QACd,UACA,SACG;AAEH,QAAO,gBADO,cACc,EAAE,UAAU,QAAQ;;AAGlD,SAAgB,iBAA8B;CAC5C,MAAM,QAAQ,aAAa,iBAAiB;AAE5C,QAAO,eAAe,EAAE,SAAS,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC;;AAG7D,SAAgB,mBAAyB;CACvC,MAAM,QAAQ,cAAc;AAE5B,iBAAgB,mBAAmB,MAAM,EAAE,CAAC,MAAM,CAAC;;;;;;AAOrD,SAAgB,gBACd,UACA,SACe;CACf,MAAM,QAAQ,sBAAsB;AACpC,KAAI,CAAC,MAAO,QAAO;AACnB,QAAO,gBAAgB,OAAO,UAAU,QAAQ;;AAGlD,SAAS,gBACP,OACA,UACA,SACG;CACH,MAAM,YAAY,OAAuE,KAAK;CAE9F,MAAM,oBAAoB;EACxB,MAAM,QAAQ,MAAM,UAAU;AAE9B,MACE,UAAU,WACV,UAAU,QAAQ,UAAU,SAC5B,UAAU,QAAQ,aAAa,SAE/B,QAAO,UAAU,QAAQ;EAG3B,MAAM,OAAO,SAAS,MAAM;AAE5B,MAAI,UAAU,WAAW,UAAU,UAAU,QAAQ,OAAO,KAAK,EAAE;AACjE,aAAU,UAAU;IAAE;IAAO;IAAU,OAAO,UAAU,QAAQ;IAAO;AACvE,UAAO,UAAU,QAAQ;;AAG3B,YAAU,UAAU;GAAE;GAAO;GAAU,OAAO;GAAM;AACpD,SAAO;;AAGT,QAAO,qBAAqB,MAAM,WAAW,aAAa,YAAY;;AAGxE,SAAgB,cAAc;CAC5B,MAAM,QAAQ,cAAc;CAC5B,MAAM,eAAe,cAAc,wBAAwB,EAAE,EAAE,CAAC;CAEhE,MAAM,WAAW,cAAc;EAE7B,MAAM,YAAY,GAAG,SAA+B;GAClD,MAAM,SAAU,aAA0B,GAAG,KAAK;GAClD,MAAM,CAAC,OAAO,QAAQ;AAEtB,OAAI,UAAU,cAAc,MAAM,aAAa;IAC7C,IAAI,UAA+B;IACnC,MAAM,OAAsC,OAAO;AACjD,gBAAW;AACX,eAAU;AACV,SAAI,IAAI;MACN,MAAM,OAAO,GAAG,QAAQ,OAAO;AAC/B,UAAI,KAAM,WAAU,oBAAoB,IAAI,KAAK;;;IAGrD,MAAM,EAAE,OAAO,GAAG,GAAG,SAAS;AAC9B,WAAO;KAAE,GAAG;KAAM,cAAc,OAAO;KAAO;KAAK;;AAGrD,UAAO;;AAET,SAAO;IACN,CAAC,aAAa,CAAC;CAElB,MAAM,aAAa,UAGyB;EAC1C,WAAW,MAAoC;AAC7C,SAAM,eAAe,EAAE;AACvB,OAAI,EAAE,iBAAkB;AACxB,KAAE,gBAAgB;AAClB,SAAM,iBAAiB,EAAE,YAAY,CAAC,YAAY,GAAG;AACrD,SAAM,cAAc,EAAE;;EAExB,QAAQ;EACR,QAAQ;EACT;AAED,QAAO;EAAE;EAAW;EAAU"}

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

@@ -0,0 +1,91 @@
+import { CollectionState } from "../core/collection/state.mjs";
+import { CollectionData, CollectionStore } from "../core/collection/collection.mjs";
+import * as _$react from "react";
+import { FormHTMLAttributes, ReactNode, SubmitEvent } from "react";
+
+//#region src/react/collection.d.ts
+/** Props for the {@link CollectionProvider} component. */
+interface CollectionProviderProps {
+  /** Collection metadata from the framework data fetch (`handle`, `dataSearch`). */
+  data: CollectionData;
+  /**
+   * Live URL search string from the framework router (with or without leading `?`).
+   * Seeds the store on mount and keeps browse state in sync with back/forward.
+   */
+  urlSearch?: string;
+  /**
+   * Called after user-initiated filter/sort changes with a ready-to-use
+   * search string. The consumer's only job is to navigate:
+   *
+   * ```tsx
+   * onChange={(search) =>
+   *   navigate({ search }, { replace: searchParams.size > 0, preventScrollReset: true })
+   * }
+   * ```
+   */
+  onChange?: (searchString: string) => void;
+  children?: ReactNode;
+}
+/**
+ * Manages the lifecycle of a {@link CollectionStore}: creates on mount and
+ * syncs with URL changes. Recreates the store when `data.handle` changes
+ * (navigating to a different collection).
+ */
+declare function CollectionProvider({
+  data,
+  urlSearch,
+  onChange,
+  children
+}: CollectionProviderProps): _$react.FunctionComponentElement<_$react.ProviderProps<CollectionStore | null>>;
+/**
+ * Subscribes to the collection store and returns the full state snapshot.
+ *
+ * @example
+ * ```tsx
+ * const { status, filters } = useCollection();
+ * ```
+ */
+declare function useCollection(): CollectionState;
+/**
+ * Subscribes to the collection store and returns a derived value via `selector`.
+ * Optionally accepts an `isEqual` comparator to skip re-renders when the
+ * derived value is structurally unchanged.
+ *
+ * @example
+ * ```tsx
+ * const status = useCollection(s => s.status);
+ * const filters = useCollection(s => s.filters, shallowEqual);
+ * ```
+ */
+declare function useCollection<S>(selector: (state: CollectionState) => S, isEqual?: (a: S, b: S) => boolean): S;
+/** Mutation methods that update store state and trigger the `onChange` callback. */
+type CollectionActions = Pick<CollectionStore, "setFilters" | "toggleFilter" | "toggleFilterInput" | "setSortKey" | "setSortByValue" | "reset" | "handleFormSubmit">;
+/**
+ * Returns methods that change filters and sort. The store's `onBrowseChange`
+ * callback (set by {@link CollectionProvider}) handles calling `onChange` with
+ * a serialized search string.
+ */
+declare function useCollectionActions(): CollectionActions;
+/**
+ * Returns form props for progressive-enhancement of collection filter forms.
+ *
+ * @example
+ * ```tsx
+ * const { formProps } = useCollectionForm();
+ * return (
+ *   <form {...formProps()} action="/collections/shoes">
+ *     <input type="checkbox" name="filter.p.tag" value="sale" />
+ *     <button type="submit">Apply</button>
+ *   </form>
+ * );
+ * ```
+ */
+declare function useCollectionForm(): {
+  formProps: (opts?: {
+    beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
+    afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
+  }) => FormHTMLAttributes<HTMLFormElement>;
+};
+//#endregion
+export { CollectionActions, CollectionProvider, CollectionProviderProps, useCollection, useCollectionActions, useCollectionForm };
+//# sourceMappingURL=collection.d.mts.map

package/dist/development/react/collection.mjs

@@ -0,0 +1,129 @@
+"use client";
+
+import { createCollectionStore } from "../core/collection/collection.mjs";
+import { createCollectionReconciler } from "../core/collection/reconciler.mjs";
+import { createContext, createElement, useCallback, useContext, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from "react";
+
+//#region src/react/collection.tsx
+const CollectionContext = createContext(null);
+/**
+* Manages the lifecycle of a {@link CollectionStore}: creates on mount and
+* syncs with URL changes. Recreates the store when `data.handle` changes
+* (navigating to a different collection).
+*/
+function CollectionProvider({ data, urlSearch = "", onChange, children }) {
+	const onChangeRef = useRef(onChange);
+	onChangeRef.current = onChange;
+	const urlSearchRef = useRef(urlSearch);
+	urlSearchRef.current = urlSearch;
+	const dataRef = useRef(data);
+	dataRef.current = data;
+	const { handle: collectionHandle, dataSearch } = data;
+	const store = useMemo(() => createCollectionStore({
+		data,
+		urlSearch
+	}), [data.handle]);
+	const reconcilerRef = useRef(null);
+	useLayoutEffect(() => {
+		reconcilerRef.current = createCollectionReconciler({
+			getStore: () => store,
+			readUrlSearch: () => urlSearchRef.current,
+			emitChange: (s) => onChangeRef.current?.(s)
+		}, urlSearchRef.current);
+		store.setOnBrowseChange(() => reconcilerRef.current?.handleBrowseChange());
+		return () => {
+			store.setOnBrowseChange(null);
+		};
+	}, [store]);
+	useLayoutEffect(() => {
+		reconcilerRef.current?.reconcile(urlSearch, dataRef.current.dataSearch);
+	}, [
+		urlSearch,
+		store,
+		collectionHandle,
+		dataSearch
+	]);
+	return createElement(CollectionContext.Provider, { value: store }, children);
+}
+function useRequiredStore(hookName) {
+	const store = useContext(CollectionContext);
+	if (!store) throw new Error(`${hookName} must be used inside a <CollectionProvider>.`);
+	return store;
+}
+function useCollection(selector, isEqual) {
+	const store = useRequiredStore("useCollection");
+	const cachedRef = useRef(null);
+	const getSnapshot = () => {
+		const state = store.getState();
+		if (cachedRef.current && cachedRef.current.state === state && cachedRef.current.selector === selector) return cachedRef.current.value;
+		if (!selector) {
+			cachedRef.current = {
+				state,
+				selector,
+				value: state
+			};
+			return state;
+		}
+		const next = selector(state);
+		if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {
+			cachedRef.current = {
+				state,
+				selector,
+				value: cachedRef.current.value
+			};
+			return cachedRef.current.value;
+		}
+		cachedRef.current = {
+			state,
+			selector,
+			value: next
+		};
+		return next;
+	};
+	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+/**
+* Returns methods that change filters and sort. The store's `onBrowseChange`
+* callback (set by {@link CollectionProvider}) handles calling `onChange` with
+* a serialized search string.
+*/
+function useCollectionActions() {
+	const store = useRequiredStore("useCollectionActions");
+	return useMemo(() => ({
+		setFilters: store.setFilters,
+		toggleFilter: store.toggleFilter,
+		toggleFilterInput: store.toggleFilterInput,
+		setSortKey: store.setSortKey,
+		setSortByValue: store.setSortByValue,
+		reset: store.reset,
+		handleFormSubmit: store.handleFormSubmit
+	}), [store]);
+}
+/**
+* Returns form props for progressive-enhancement of collection filter forms.
+*
+* @example
+* ```tsx
+* const { formProps } = useCollectionForm();
+* return (
+*   <form {...formProps()} action="/collections/shoes">
+*     <input type="checkbox" name="filter.p.tag" value="sale" />
+*     <button type="submit">Apply</button>
+*   </form>
+* );
+* ```
+*/
+function useCollectionForm() {
+	const actions = useCollectionActions();
+	return { formProps: useCallback((opts) => ({ onSubmit: (e) => {
+		opts?.beforeSubmit?.(e);
+		if (e.defaultPrevented) return;
+		e.preventDefault();
+		actions.handleFormSubmit(e.nativeEvent);
+		opts?.afterSubmit?.(e);
+	} }), [actions]) };
+}
+
+//#endregion
+export { CollectionProvider, useCollection, useCollectionActions, useCollectionForm };
+//# sourceMappingURL=collection.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collection.mjs","names":[],"sources":["../../../src/react/collection.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  createElement,\n  useCallback,\n  useContext,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n  type FormHTMLAttributes,\n  type ReactNode,\n  type SubmitEvent,\n} from \"react\";\n\nimport {\n  createCollectionStore,\n  createCollectionReconciler,\n  type CollectionData,\n  type CollectionReconciler,\n  type CollectionStore,\n} from \"../core/collection\";\nimport type { CollectionState } from \"../core/collection\";\n\nconst CollectionContext = createContext<CollectionStore | null>(null);\n\n/** Props for the {@link CollectionProvider} component. */\nexport interface CollectionProviderProps {\n  /** Collection metadata from the framework data fetch (`handle`, `dataSearch`). */\n  data: CollectionData;\n  /**\n   * Live URL search string from the framework router (with or without leading `?`).\n   * Seeds the store on mount and keeps browse state in sync with back/forward.\n   */\n  urlSearch?: string;\n  /**\n   * Called after user-initiated filter/sort changes with a ready-to-use\n   * search string. The consumer's only job is to navigate:\n   *\n   * ```tsx\n   * onChange={(search) =>\n   *   navigate({ search }, { replace: searchParams.size > 0, preventScrollReset: true })\n   * }\n   * ```\n   */\n  onChange?: (searchString: string) => void;\n  children?: ReactNode;\n}\n\n/**\n * Manages the lifecycle of a {@link CollectionStore}: creates on mount and\n * syncs with URL changes. Recreates the store when `data.handle` changes\n * (navigating to a different collection).\n */\nexport function CollectionProvider({\n  data,\n  urlSearch = \"\",\n  onChange,\n  children,\n}: CollectionProviderProps) {\n  const onChangeRef = useRef(onChange);\n  onChangeRef.current = onChange;\n\n  const urlSearchRef = useRef(urlSearch);\n  urlSearchRef.current = urlSearch;\n\n  const dataRef = useRef(data);\n  dataRef.current = data;\n\n  const { handle: collectionHandle, dataSearch } = data;\n\n  const store = useMemo(\n    () => createCollectionStore({ data, urlSearch }),\n    // oxlint-disable-next-line react-hooks/exhaustive-deps -- store recreated only when collection handle changes\n    [data.handle],\n  );\n\n  const reconcilerRef = useRef<CollectionReconciler | null>(null);\n\n  useLayoutEffect(() => {\n    reconcilerRef.current = createCollectionReconciler(\n      {\n        getStore: () => store,\n        readUrlSearch: () => urlSearchRef.current,\n        emitChange: (s) => onChangeRef.current?.(s),\n      },\n      urlSearchRef.current,\n    );\n    store.setOnBrowseChange(() => reconcilerRef.current?.handleBrowseChange());\n    return () => {\n      store.setOnBrowseChange(null);\n    };\n  }, [store]);\n\n  useLayoutEffect(() => {\n    reconcilerRef.current?.reconcile(urlSearch, dataRef.current.dataSearch);\n  }, [urlSearch, store, collectionHandle, dataSearch]);\n\n  return createElement(CollectionContext.Provider, { value: store }, children);\n}\n\nfunction useRequiredStore(hookName: string): CollectionStore {\n  const store = useContext(CollectionContext);\n  if (!store) {\n    throw new Error(`${hookName} must be used inside a <CollectionProvider>.`);\n  }\n  return store;\n}\n\n/**\n * Subscribes to the collection store and returns the full state snapshot.\n *\n * @example\n * ```tsx\n * const { status, filters } = useCollection();\n * ```\n */\nexport function useCollection(): CollectionState;\n/**\n * Subscribes to the collection store and returns a derived value via `selector`.\n * Optionally accepts an `isEqual` comparator to skip re-renders when the\n * derived value is structurally unchanged.\n *\n * @example\n * ```tsx\n * const status = useCollection(s => s.status);\n * const filters = useCollection(s => s.filters, shallowEqual);\n * ```\n */\nexport function useCollection<S>(\n  selector: (state: CollectionState) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): S;\nexport function useCollection<S>(\n  selector?: (state: CollectionState) => S,\n  isEqual?: (a: S, b: S) => boolean,\n): CollectionState | S {\n  const store = useRequiredStore(\"useCollection\");\n  const cachedRef = useRef<{\n    state: unknown;\n    selector: typeof selector;\n    value: CollectionState | 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\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/** Mutation methods that update store state and trigger the `onChange` callback. */\nexport type CollectionActions = Pick<\n  CollectionStore,\n  | \"setFilters\"\n  | \"toggleFilter\"\n  | \"toggleFilterInput\"\n  | \"setSortKey\"\n  | \"setSortByValue\"\n  | \"reset\"\n  | \"handleFormSubmit\"\n>;\n\n/**\n * Returns methods that change filters and sort. The store's `onBrowseChange`\n * callback (set by {@link CollectionProvider}) handles calling `onChange` with\n * a serialized search string.\n */\nexport function useCollectionActions(): CollectionActions {\n  const store = useRequiredStore(\"useCollectionActions\");\n\n  return useMemo(\n    () => ({\n      setFilters: store.setFilters,\n      toggleFilter: store.toggleFilter,\n      toggleFilterInput: store.toggleFilterInput,\n      setSortKey: store.setSortKey,\n      setSortByValue: store.setSortByValue,\n      reset: store.reset,\n      handleFormSubmit: store.handleFormSubmit,\n    }),\n    [store],\n  );\n}\n\n/**\n * Returns form props for progressive-enhancement of collection filter forms.\n *\n * @example\n * ```tsx\n * const { formProps } = useCollectionForm();\n * return (\n *   <form {...formProps()} action=\"/collections/shoes\">\n *     <input type=\"checkbox\" name=\"filter.p.tag\" value=\"sale\" />\n *     <button type=\"submit\">Apply</button>\n *   </form>\n * );\n * ```\n */\nexport function useCollectionForm() {\n  const actions = useCollectionActions();\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        actions.handleFormSubmit(e.nativeEvent);\n        opts?.afterSubmit?.(e);\n      },\n    }),\n    [actions],\n  );\n\n  return { formProps };\n}\n\nexport type { CollectionData };\n"],"mappings":";;;;;;;AAyBA,MAAM,oBAAoB,cAAsC,KAAK;;;;;;AA8BrE,SAAgB,mBAAmB,EACjC,MACA,YAAY,IACZ,UACA,YAC0B;CAC1B,MAAM,cAAc,OAAO,SAAS;AACpC,aAAY,UAAU;CAEtB,MAAM,eAAe,OAAO,UAAU;AACtC,cAAa,UAAU;CAEvB,MAAM,UAAU,OAAO,KAAK;AAC5B,SAAQ,UAAU;CAElB,MAAM,EAAE,QAAQ,kBAAkB,eAAe;CAEjD,MAAM,QAAQ,cACN,sBAAsB;EAAE;EAAM;EAAW,CAAC,EAEhD,CAAC,KAAK,OAAO,CACd;CAED,MAAM,gBAAgB,OAAoC,KAAK;AAE/D,uBAAsB;AACpB,gBAAc,UAAU,2BACtB;GACE,gBAAgB;GAChB,qBAAqB,aAAa;GAClC,aAAa,MAAM,YAAY,UAAU,EAAE;GAC5C,EACD,aAAa,QACd;AACD,QAAM,wBAAwB,cAAc,SAAS,oBAAoB,CAAC;AAC1E,eAAa;AACX,SAAM,kBAAkB,KAAK;;IAE9B,CAAC,MAAM,CAAC;AAEX,uBAAsB;AACpB,gBAAc,SAAS,UAAU,WAAW,QAAQ,QAAQ,WAAW;IACtE;EAAC;EAAW;EAAO;EAAkB;EAAW,CAAC;AAEpD,QAAO,cAAc,kBAAkB,UAAU,EAAE,OAAO,OAAO,EAAE,SAAS;;AAG9E,SAAS,iBAAiB,UAAmC;CAC3D,MAAM,QAAQ,WAAW,kBAAkB;AAC3C,KAAI,CAAC,MACH,OAAM,IAAI,MAAM,GAAG,SAAS,8CAA8C;AAE5E,QAAO;;AA2BT,SAAgB,cACd,UACA,SACqB;CACrB,MAAM,QAAQ,iBAAiB,gBAAgB;CAC/C,MAAM,YAAY,OAIR,KAAK;CAEf,MAAM,oBAAoB;EACxB,MAAM,QAAQ,MAAM,UAAU;AAE9B,MACE,UAAU,WACV,UAAU,QAAQ,UAAU,SAC5B,UAAU,QAAQ,aAAa,SAE/B,QAAO,UAAU,QAAQ;AAG3B,MAAI,CAAC,UAAU;AACb,aAAU,UAAU;IAAE;IAAO;IAAU,OAAO;IAAO;AACrD,UAAO;;EAGT,MAAM,OAAO,SAAS,MAAM;AAE5B,MAAI,UAAU,WAAW,UAAU,UAAU,QAAQ,OAAY,KAAK,EAAE;AACtE,aAAU,UAAU;IAAE;IAAO;IAAU,OAAO,UAAU,QAAQ;IAAO;AACvE,UAAO,UAAU,QAAQ;;AAG3B,YAAU,UAAU;GAAE;GAAO;GAAU,OAAO;GAAM;AACpD,SAAO;;AAGT,QAAO,qBAAqB,MAAM,WAAW,aAAa,YAAY;;;;;;;AAoBxE,SAAgB,uBAA0C;CACxD,MAAM,QAAQ,iBAAiB,uBAAuB;AAEtD,QAAO,eACE;EACL,YAAY,MAAM;EAClB,cAAc,MAAM;EACpB,mBAAmB,MAAM;EACzB,YAAY,MAAM;EAClB,gBAAgB,MAAM;EACtB,OAAO,MAAM;EACb,kBAAkB,MAAM;EACzB,GACD,CAAC,MAAM,CACR;;;;;;;;;;;;;;;;AAiBH,SAAgB,oBAAoB;CAClC,MAAM,UAAU,sBAAsB;AAkBtC,QAAO,EAAE,WAhBS,aACf,UAG2C,EAC1C,WAAW,MAAoC;AAC7C,QAAM,eAAe,EAAE;AACvB,MAAI,EAAE,iBAAkB;AACxB,IAAE,gBAAgB;AAClB,UAAQ,iBAAiB,EAAE,YAAY;AACvC,QAAM,cAAc,EAAE;IAEzB,GACD,CAAC,QAAQ,CAGO,EAAE"}

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

@@ -0,0 +1,13 @@
+import { ShopifyStandardActions } from "../vendor/standard-actions.mjs";
+import { ShopifyGlobal } from "../globals.mjs";
+import { QuantityInputAttributes, SetButtonAttributes } from "../core/cart/form.mjs";
+import { CollectionData } from "../core/collection/collection.mjs";
+import { ValidProductSelectionResult } from "../core/product/product-form.mjs";
+import { ProductAddToCartProps, ProductFormRegister, ProductMerchandiseIdProps, ProductOptionValueProps, ProductQuantityDefaultProps, ProductQuantityProps } from "../core/product/form.mjs";
+import { CartActions, CartProvider, createCartComponents, useCart, useCartActions, useCartAnalytics, useCartForm } from "./cart.mjs";
+import { CollectionActions, CollectionProvider, CollectionProviderProps, useCollection, useCollectionActions, useCollectionForm } from "./collection.mjs";
+import { PredictiveSearchActions, PredictiveSearchFormPropsOptions, PredictiveSearchFormRegister, PredictiveSearchFormResult, PredictiveSearchProvider, PredictiveSearchProviderProps, PredictiveSearchQueryInputPropsOptions, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm } from "./predictive-search.mjs";
+import { ProductProviderProps, UseProductFormOptions, UseProductFormResult, UseProductResult, createProductComponents, useProductForm } from "./product.mjs";
+import { ShopPayButton, ShopPayButtonProps } from "./shop-pay.mjs";
+import { ShopifyScripts, ShopifyScriptsProps } from "./shopify-scripts.mjs";
+export { type CartActions, CartProvider, type CollectionActions, type CollectionData, CollectionProvider, type CollectionProviderProps, type PredictiveSearchActions, type PredictiveSearchFormPropsOptions, type PredictiveSearchFormRegister, type PredictiveSearchFormResult, PredictiveSearchProvider, type PredictiveSearchProviderProps, type PredictiveSearchQueryInputPropsOptions, type ProductAddToCartProps, type ProductFormRegister, type ProductMerchandiseIdProps, type ProductOptionValueProps, type ProductProviderProps, type ProductQuantityDefaultProps, type ProductQuantityProps, type QuantityInputAttributes, type SetButtonAttributes, ShopPayButton, type ShopPayButtonProps, type ShopifyGlobal, ShopifyScripts, type ShopifyScriptsProps, type ShopifyStandardActions, type UseProductFormOptions, type UseProductFormResult, type UseProductResult, type ValidProductSelectionResult, createCartComponents, createProductComponents, useCart, useCartActions, useCartAnalytics, useCartForm, useCollection, useCollectionActions, useCollectionForm, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm, useProductForm };

package/dist/development/react/index.mjs

@@ -0,0 +1,10 @@
+"use client";
+
+import { CartProvider, createCartComponents, useCart, useCartActions, useCartAnalytics, useCartForm } from "./cart.mjs";
+import { CollectionProvider, useCollection, useCollectionActions, useCollectionForm } from "./collection.mjs";
+import { PredictiveSearchProvider, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm } from "./predictive-search.mjs";
+import { createProductComponents, useProductForm } from "./product.mjs";
+import { ShopPayButton } from "./shop-pay.mjs";
+import { ShopifyScripts } from "./shopify-scripts.mjs";
+
+export { CartProvider, CollectionProvider, PredictiveSearchProvider, ShopPayButton, ShopifyScripts, createCartComponents, createProductComponents, useCart, useCartActions, useCartAnalytics, useCartForm, useCollection, useCollectionActions, useCollectionForm, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm, useProductForm };

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

@@ -0,0 +1,49 @@
+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 * as _$react from "react";
+import { ChangeEvent, FormHTMLAttributes, InputHTMLAttributes, ReactNode, SubmitEvent } from "react";
+
+//#region src/react/predictive-search.d.ts
+type PredictiveSearchContextValue = {
+  store: PredictiveSearchStore;
+  searchAction?: string;
+};
+type PredictiveSearchProviderProps = CreatePredictiveSearchStoreOptions & {
+  children?: ReactNode;
+  searchAction?: string;
+};
+type PredictiveSearchActions = Pick<PredictiveSearchStore, "search" | "clear">;
+type PredictiveSearchFormPropsOptions = Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & {
+  preventDefault?: boolean;
+  onSubmit?: (event: SubmitEvent<HTMLFormElement>, term: string) => void;
+};
+type PredictiveSearchQueryInputPropsOptions = Omit<InputHTMLAttributes<HTMLInputElement>, "autoCapitalize" | "autoComplete" | "name" | "onChange" | "spellCheck" | "type"> & {
+  onChange?: (event: ChangeEvent<HTMLInputElement>, term: string) => void;
+};
+type PredictiveSearchFormField = Parameters<PredictiveSearchFormRegister$1>[0];
+type PredictiveSearchFormRegister = (field: PredictiveSearchFormField, options?: PredictiveSearchQueryInputPropsOptions) => InputHTMLAttributes<HTMLInputElement>;
+type PredictiveSearchFormResult = {
+  formProps(options?: PredictiveSearchFormPropsOptions): FormHTMLAttributes<HTMLFormElement>;
+  register: PredictiveSearchFormRegister;
+};
+declare function PredictiveSearchProvider({
+  children,
+  predictiveSearchEndpoint,
+  searchAction,
+  debounceInMs,
+  minTermLength,
+  fetch,
+  limit,
+  limitScope,
+  types,
+  searchableFields,
+  unavailableProducts
+}: PredictiveSearchProviderProps): _$react.FunctionComponentElement<_$react.ProviderProps<PredictiveSearchContextValue | null>>;
+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;
+declare function usePredictiveSearchActions(): PredictiveSearchActions;
+declare function usePredictiveSearchForm(): PredictiveSearchFormResult;
+//#endregion
+export { PredictiveSearchActions, PredictiveSearchFormPropsOptions, PredictiveSearchFormRegister, PredictiveSearchFormResult, PredictiveSearchProvider, PredictiveSearchProviderProps, PredictiveSearchQueryInputPropsOptions, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm };
+//# sourceMappingURL=predictive-search.d.mts.map

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

@@ -0,0 +1,133 @@
+"use client";
+
+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";
+
+//#region src/react/predictive-search.tsx
+const CONFIG_ARRAY_SEPARATOR = "\0";
+const PredictiveSearchContext = createContext(null);
+function PredictiveSearchProvider({ children, predictiveSearchEndpoint, searchAction, debounceInMs, minTermLength, fetch, limit, limitScope, types, searchableFields, unavailableProducts }) {
+	const store = useMemo(() => createPredictiveSearchStore({
+		predictiveSearchEndpoint,
+		debounceInMs,
+		minTermLength,
+		fetch,
+		limit,
+		limitScope,
+		types,
+		searchableFields,
+		unavailableProducts
+	}), [
+		predictiveSearchEndpoint,
+		debounceInMs,
+		minTermLength,
+		fetch,
+		limit,
+		limitScope,
+		getArrayKey(types),
+		getArrayKey(searchableFields),
+		unavailableProducts
+	]);
+	useEffect(() => {
+		store.connect();
+		return () => store.destroy();
+	}, [store]);
+	const contextValue = useMemo(() => ({
+		store,
+		searchAction
+	}), [store, searchAction]);
+	return createElement(PredictiveSearchContext.Provider, { value: contextValue }, children);
+}
+function getArrayKey(values) {
+	return values?.join(CONFIG_ARRAY_SEPARATOR) ?? "";
+}
+function useRequiredStore(hookName) {
+	const context = useContext(PredictiveSearchContext);
+	if (!context) throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);
+	return context.store;
+}
+function useRequiredContext(hookName) {
+	const context = useContext(PredictiveSearchContext);
+	if (!context) throw new Error(`${hookName} must be used inside a <PredictiveSearchProvider>.`);
+	return context;
+}
+function usePredictiveSearch(selector, isEqual) {
+	const store = useRequiredStore("usePredictiveSearch");
+	const cachedRef = useRef(null);
+	const getSnapshot = () => {
+		const state = store.getState();
+		if (cachedRef.current && cachedRef.current.state === state && cachedRef.current.selector === selector) return cachedRef.current.value;
+		if (!selector) {
+			cachedRef.current = {
+				state,
+				selector,
+				value: state
+			};
+			return state;
+		}
+		const next = selector(state);
+		if (cachedRef.current && isEqual?.(cachedRef.current.value, next)) {
+			cachedRef.current = {
+				state,
+				selector,
+				value: cachedRef.current.value
+			};
+			return cachedRef.current.value;
+		}
+		cachedRef.current = {
+			state,
+			selector,
+			value: next
+		};
+		return next;
+	};
+	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
+}
+function usePredictiveSearchActions() {
+	const store = useRequiredStore("usePredictiveSearchActions");
+	return useMemo(() => ({
+		search: store.search,
+		clear: store.clear
+	}), [store]);
+}
+function usePredictiveSearchForm() {
+	const { searchAction, store } = useRequiredContext("usePredictiveSearchForm");
+	const coreRegister = useMemo(() => createPredictiveSearchFormRegister(), []);
+	const register = useCallback((field, props = {}) => {
+		const { onChange, ...attributes } = props;
+		const coreAttributes = coreRegister(field);
+		return {
+			...attributes,
+			...coreAttributes,
+			onChange: (event) => {
+				const term = event.currentTarget.value;
+				onChange?.(event, term);
+				if (event.defaultPrevented) return;
+				store.search(term);
+			}
+		};
+	}, [coreRegister, store]);
+	return {
+		formProps: useCallback((props = {}) => {
+			const { onSubmit, preventDefault, ...attributes } = props;
+			return {
+				...getPredictiveSearchFormAttributes(searchAction),
+				...attributes,
+				onSubmit: (event) => {
+					const term = readPredictiveSearchFormTerm(new FormData(event.currentTarget));
+					onSubmit?.(event, term);
+					if (event.defaultPrevented) return;
+					if (!preventDefault) return;
+					event.preventDefault();
+					store.search(term);
+				}
+			};
+		}, [searchAction, store]),
+		register
+	};
+}
+
+//#endregion
+export { PredictiveSearchProvider, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm };
+//# sourceMappingURL=predictive-search.mjs.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,72 @@
+import { CartLine } from "../core/cart/state.mjs";
+import { ProductInput, ProductVariantFrom } from "../core/product/state.mjs";
+import { ProductFormErrors, ProductFormOptions, ProductFormStore, ValidProductSelectionResult, VariantSelectionResult } from "../core/product/product-form.mjs";
+import { ProductFormRegister } from "../core/product/form.mjs";
+import { FormHTMLAttributes, ReactNode, SubmitEvent } from "react";
+
+//#region src/react/product.d.ts
+/** Options for {@link useProductForm}. */
+interface UseProductFormOptions<TProduct extends ProductInput> {
+  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;
+}
+/** Return value of {@link useProductForm}. */
+interface UseProductFormResult<TProduct extends ProductInput> {
+  options: ProductFormOptions<TProduct>;
+  selectedVariant: ProductVariantFrom<TProduct> | null;
+  register: ProductFormRegister;
+  formProps: (opts?: {
+    beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
+    afterSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
+  }) => FormHTMLAttributes<HTMLFormElement>;
+  errors: ProductFormErrors;
+  matchedLineItem: CartLine | null;
+  pending: boolean;
+  selectOption: (name: string, value: string) => VariantSelectionResult<ProductVariantFrom<TProduct>>;
+}
+/** Props for the `ProductProvider` returned by {@link createProductComponents}. */
+interface ProductProviderProps<TProduct extends ProductInput> {
+  product: TProduct;
+  onSelect?: (result: ValidProductSelectionResult<TProduct>) => void;
+  children?: ReactNode;
+}
+/** Return value of the `useProduct` hook from {@link createProductComponents}. */
+interface UseProductResult<TProduct extends ProductInput> {
+  options: ProductFormOptions<TProduct>;
+  selectedVariant: ProductVariantFrom<TProduct> | null;
+  selectOption: (name: string, value: string) => VariantSelectionResult<ProductVariantFrom<TProduct>>;
+  errors: ProductFormErrors;
+  matchedLineItem: CartLine | null;
+}
+/**
+ * Subscribes to a {@link ProductFormStore} and returns form-ready state.
+ *
+ * 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.
+ */
+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.
+ *
+ * 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)
+ *
+ * Requires a `<CartProvider>` ancestor.
+ *
+ * @example
+ * ```ts
+ * const { ProductProvider, useProduct, useProductForm } =
+ *   createProductComponents<MyProductType>();
+ * ```
+ */
+declare function createProductComponents<TProduct extends ProductInput>(): {
+  ProductProvider: (props: ProductProviderProps<TProduct>) => ReactNode;
+  useProduct: () => UseProductResult<TProduct>;
+  useProductForm: () => UseProductFormResult<TProduct>;
+};
+//#endregion
+export { ProductProviderProps, UseProductFormOptions, UseProductFormResult, UseProductResult, createProductComponents, useProductForm };
+//# sourceMappingURL=product.d.mts.map