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

package/dist/development/graphql/graphql.mjs

@@ -1,4 +1,34 @@
 //#region src/graphql/graphql.ts
+/**
+* Tags a Storefront API query string for type-safe inference.
+*
+* At runtime, returns the source string (concatenated with any fragments).
+* At the type level, the return type carries phantom `Result` and `Variables`
+* types inferred from the Storefront API schema via gql.tada.
+*
+* Pass an array of previously declared `gql()` fragments as the second
+* argument to compose documents while preserving full type inference.
+*
+* @example
+* ```ts
+* import { gql } from "@shopify/hydrogen";
+*
+* const PRODUCT_QUERY = gql(`
+*   query Product($handle: String!) {
+*     product(handle: $handle) { title }
+*   }
+* `);
+*
+* const result = await storefront.graphql(PRODUCT_QUERY, {
+*   variables: { handle: "snowboard" },
+* });
+*
+* if (!result.errors) {
+*   // result.data.product is typed as `{ title: string } | null`
+*   console.log(result.data.product?.title);
+* }
+* ```
+*/
 const gql = ((source, fragments) => {
 	let query = source;
 	if (fragments) {

package/dist/development/graphql/graphql.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graphql.mjs","names":[],"sources":["../../../src/graphql/graphql.ts"],"sourcesContent":["import type { DocumentDecoration, initGraphQLTada as InitGraphQLTada } from \"gql.tada\";\n\nimport type { introspection } from \"./generated/graphql-env\";\nimport type { StorefrontScalars } from \"./scalars\";\nimport type { InferResult, InferVariables } from \"./type-resolver\";\n\ntype StorefrontTadaGql = InitGraphQLTada<{\n  introspection: introspection;\n  scalars: StorefrontScalars;\n}>;\n\ntype StorefrontQueryMetadata<Source extends string = string> = {\n  readonly __hydrogenQueryBrand: true;\n  readonly __hydrogenQuerySource?: Source;\n};\n\n/**\n * A branded string that carries phantom Result and Variables types.\n *\n * Honest about being a `string` at runtime (unlike `TadaDocumentNode`\n * which claims to be an AST). Implements `DocumentDecoration` so\n * `ResultOf<>` and `VariablesOf<>` work on it.\n */\nexport type StorefrontQueryString<\n  Result = any,\n  Variables = any,\n  Source extends string = string,\n> = string &\n  DocumentDecoration<Result, Variables> & {\n    readonly __hydrogenQueryBrand: true;\n    readonly __hydrogenQuerySource?: Source;\n  };\n\nexport type AnyStorefrontQueryString = string & StorefrontQueryMetadata;\n\nexport type SourceOf<Doc> = Doc extends {\n  readonly __hydrogenQuerySource?: infer Source extends string;\n}\n  ? Source\n  : never;\n\nexport type FragmentSources<Fragments extends readonly AnyStorefrontQueryString[]> =\n  Fragments extends readonly []\n    ? \"\"\n    : Fragments extends readonly [infer Only extends AnyStorefrontQueryString]\n      ? SourceOf<Only>\n      : Fragments extends readonly [\n            infer First extends AnyStorefrontQueryString,\n            ...infer Rest extends readonly AnyStorefrontQueryString[],\n          ]\n        ? `${SourceOf<First>}\\n${FragmentSources<Rest>}`\n        : string;\n\nexport type ComposedSource<\n  Source extends string,\n  Fragments extends readonly AnyStorefrontQueryString[],\n> = FragmentSources<Fragments> extends \"\" ? Source : `${Source}\\n${FragmentSources<Fragments>}`;\n\ntype StorefrontGql = {\n  // Composes an already-declared document with additional fragments. Declared\n  // before the raw-source overloads so branded documents recover their literal\n  // source through SourceOf instead of binding Source to the branded type,\n  // which would degrade ComposedSource and kill inference.\n  <\n    const Document extends AnyStorefrontQueryString,\n    const Fragments extends readonly AnyStorefrontQueryString[],\n    const DocumentSource extends string = ComposedSource<SourceOf<Document>, Fragments>,\n  >(\n    document: Document,\n    fragments: Fragments,\n  ): StorefrontQueryString<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n  <const Source extends string>(\n    source: Source,\n  ): StorefrontQueryString<InferResult<Source>, InferVariables<Source>, Source>;\n  <\n    const Source extends string,\n    const Fragments extends readonly AnyStorefrontQueryString[],\n    const DocumentSource extends string = ComposedSource<Source, Fragments>,\n  >(\n    source: Source,\n    fragments: Fragments,\n  ): StorefrontQueryString<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n} & StorefrontTadaGql;\n\n// oxlint-disable-next-line typescript-eslint/consistent-type-assertions -- gql.tada adds phantom helper properties to the function type that are not used at runtime.\nexport const gql = ((source: string, fragments?: Array<string>) => {\n  let query = source;\n\n  if (fragments) {\n    const seen = new Set<string>();\n    for (const fragment of fragments) {\n      if (!seen.has(fragment)) {\n        seen.add(fragment);\n        query += \"\\n\" + fragment;\n      }\n    }\n  }\n\n  return query;\n}) as unknown as StorefrontGql;\n"],"mappings":";AA6FA,MAAa,QAAQ,QAAgB,cAA8B;CACjE,IAAI,QAAQ;AAEZ,KAAI,WAAW;EACb,MAAM,uBAAO,IAAI,KAAa;AAC9B,OAAK,MAAM,YAAY,UACrB,KAAI,CAAC,KAAK,IAAI,SAAS,EAAE;AACvB,QAAK,IAAI,SAAS;AAClB,YAAS,OAAO;;;AAKtB,QAAO"}
+{"version":3,"file":"graphql.mjs","names":[],"sources":["../../../src/graphql/graphql.ts"],"sourcesContent":["import type { DocumentDecoration, initGraphQLTada as InitGraphQLTada } from \"gql.tada\";\n\nimport type { introspection } from \"./generated/graphql-env\";\nimport type { StorefrontScalars } from \"./scalars\";\nimport type { InferResult, InferVariables } from \"./type-resolver\";\n\ntype StorefrontTadaGql = InitGraphQLTada<{\n  introspection: introspection;\n  scalars: StorefrontScalars;\n}>;\n\ntype StorefrontQueryMetadata<Source extends string = string> = {\n  readonly __hydrogenQueryBrand: true;\n  readonly __hydrogenQuerySource?: Source;\n};\n\n/**\n * A branded string that carries phantom Result and Variables types.\n *\n * Honest about being a `string` at runtime (unlike `TadaDocumentNode`\n * which claims to be an AST). Implements `DocumentDecoration` so\n * `ResultOf<>` and `VariablesOf<>` work on it.\n */\nexport type StorefrontQueryString<\n  Result = any,\n  Variables = any,\n  Source extends string = string,\n> = string &\n  DocumentDecoration<Result, Variables> & {\n    readonly __hydrogenQueryBrand: true;\n    readonly __hydrogenQuerySource?: Source;\n  };\n\n/** Any `gql()`-branded string, regardless of inferred Result/Variables. Used in constraints that accept any Storefront document. */\nexport type AnyStorefrontQueryString = string & StorefrontQueryMetadata;\n\n/** Extracts the literal source text from a `gql()`-branded document type. Resolves to `never` for unbranded strings. */\nexport type SourceOf<Doc> = Doc extends {\n  readonly __hydrogenQuerySource?: infer Source extends string;\n}\n  ? Source\n  : never;\n\nexport type FragmentSources<Fragments extends readonly AnyStorefrontQueryString[]> =\n  Fragments extends readonly []\n    ? \"\"\n    : Fragments extends readonly [infer Only extends AnyStorefrontQueryString]\n      ? SourceOf<Only>\n      : Fragments extends readonly [\n            infer First extends AnyStorefrontQueryString,\n            ...infer Rest extends readonly AnyStorefrontQueryString[],\n          ]\n        ? `${SourceOf<First>}\\n${FragmentSources<Rest>}`\n        : string;\n\n/** Concatenates a query source with its fragment sources into a single literal type, enabling end-to-end type inference for composed documents. */\nexport type ComposedSource<\n  Source extends string,\n  Fragments extends readonly AnyStorefrontQueryString[],\n> = FragmentSources<Fragments> extends \"\" ? Source : `${Source}\\n${FragmentSources<Fragments>}`;\n\ntype StorefrontGql = {\n  // Composes an already-declared document with additional fragments. Declared\n  // before the raw-source overloads so branded documents recover their literal\n  // source through SourceOf instead of binding Source to the branded type,\n  // which would degrade ComposedSource and kill inference.\n  <\n    const Document extends AnyStorefrontQueryString,\n    const Fragments extends readonly AnyStorefrontQueryString[],\n    const DocumentSource extends string = ComposedSource<SourceOf<Document>, Fragments>,\n  >(\n    document: Document,\n    fragments: Fragments,\n  ): StorefrontQueryString<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n  <const Source extends string>(\n    source: Source,\n  ): StorefrontQueryString<InferResult<Source>, InferVariables<Source>, Source>;\n  <\n    const Source extends string,\n    const Fragments extends readonly AnyStorefrontQueryString[],\n    const DocumentSource extends string = ComposedSource<Source, Fragments>,\n  >(\n    source: Source,\n    fragments: Fragments,\n  ): StorefrontQueryString<\n    InferResult<DocumentSource>,\n    InferVariables<DocumentSource>,\n    DocumentSource\n  >;\n} & StorefrontTadaGql;\n\n/**\n * Tags a Storefront API query string for type-safe inference.\n *\n * At runtime, returns the source string (concatenated with any fragments).\n * At the type level, the return type carries phantom `Result` and `Variables`\n * types inferred from the Storefront API schema via gql.tada.\n *\n * Pass an array of previously declared `gql()` fragments as the second\n * argument to compose documents while preserving full type inference.\n *\n * @example\n * ```ts\n * import { gql } from \"@shopify/hydrogen\";\n *\n * const PRODUCT_QUERY = gql(`\n *   query Product($handle: String!) {\n *     product(handle: $handle) { title }\n *   }\n * `);\n *\n * const result = await storefront.graphql(PRODUCT_QUERY, {\n *   variables: { handle: \"snowboard\" },\n * });\n *\n * if (!result.errors) {\n *   // result.data.product is typed as `{ title: string } | null`\n *   console.log(result.data.product?.title);\n * }\n * ```\n */\n// oxlint-disable-next-line typescript-eslint/consistent-type-assertions -- gql.tada adds phantom helper properties to the function type that are not used at runtime.\nexport const gql = ((source: string, fragments?: Array<string>) => {\n  let query = source;\n\n  if (fragments) {\n    const seen = new Set<string>();\n    for (const fragment of fragments) {\n      if (!seen.has(fragment)) {\n        seen.add(fragment);\n        query += \"\\n\" + fragment;\n      }\n    }\n  }\n\n  return query;\n}) as unknown as StorefrontGql;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8HA,MAAa,QAAQ,QAAgB,cAA8B;CACjE,IAAI,QAAQ;AAEZ,KAAI,WAAW;EACb,MAAM,uBAAO,IAAI,KAAa;AAC9B,OAAK,MAAM,YAAY,UACrB,KAAI,CAAC,KAAK,IAAI,SAAS,EAAE;AACvB,QAAK,IAAI,SAAS;AAClB,YAAS,OAAO;;;AAKtB,QAAO"}

package/dist/development/graphql/type-resolver.d.mts

@@ -221,7 +221,21 @@ type OperationKindType<Doc> = Doc extends {
 } ? Operation : "unknown" : "unknown";
 type InferResultForSchema<T extends string, Schema extends SchemaLike> = parseDocument<T> extends infer Doc ? Doc extends never ? never : DocumentType<Doc, Schema> : never;
 type InferVariablesForSchema<T extends string, Schema extends SchemaLike> = parseDocument<T> extends infer Doc ? Doc extends never ? never : VariablesType<Doc, Schema> : never;
+/**
+ * Infers the result type of a Storefront API query string against the bundled schema.
+ *
+ * Useful when you need the result shape outside of `storefront.graphql()` — e.g. for
+ * a component prop type. Takes a raw query source literal: for `gql()` documents use
+ * `StorefrontApi.ResultOf`, since `InferResult<typeof doc>` resolves to `never`.
+ */
 type InferResult<T extends string> = InferResultForSchema<T, StorefrontSchema>;
+/**
+ * Infers the variables type of a Storefront API query string against the bundled schema.
+ *
+ * Useful when you need the variables shape outside of `storefront.graphql()` — e.g. for
+ * a loader param type. Takes a raw query source literal: for `gql()` documents use
+ * `StorefrontApi.VariablesOf`, since `InferVariables<typeof doc>` resolves to `never`.
+ */
 type InferVariables<T extends string> = InferVariablesForSchema<T, StorefrontSchema>;
 type InferOperationKind<T extends string> = parseDocument<T> extends infer Doc ? [Doc] extends [never] ? "unknown" : OperationKindType<Doc> : "unknown";
 //#endregion

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

@@ -1,18 +1,14 @@
 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 { FormHTMLAttributes, ReactNode, SubmitEvent } from "react";
-import * as _$react_jsx_runtime0 from "react/jsx-runtime";
-
 //#region src/react/cart.d.ts
 type TypedCartProviderProps<TData extends CartData> = {
   initialData?: CartInitialData<TData>;
   children?: ReactNode;
 };
 type CartInitialData<TData extends CartData = CartData> = CreateCartStoreOptions<TData>["initialData"];
-/** Actions for reconciling cart state after updates outside Standard Actions. */
-type CartActions = Pick<CartStore, "refresh">;
 type TypedCartComponents<TData extends CartData> = {
   CartProvider: (props: TypedCartProviderProps<TData>) => ReactNode;
   useCart: <S>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean) => S;
@@ -21,17 +17,92 @@ type TypedCartComponents<TData extends CartData> = {
   useCartActions: typeof useCartActions;
   useCartForm: typeof useCartForm;
 };
+/**
+ * Factory that returns typed cart components and hooks matched to your server handler's
+ * cart query shape.
+ *
+ * The generic `THandlers` parameter is inferred from your `createCartServerHandlers`
+ * call, so every hook's {@link CartState} carries your custom cart fields end-to-end.
+ *
+ * @example
+ * ```tsx
+ * import type { cartServerHandlers } from "./server/cart.server";
+ *
+ * const {
+ *   CartProvider,
+ *   useCart,
+ *   useSuspenseCart,
+ *   useOptionalCart,
+ *   useCartActions,
+ *   useCartForm,
+ * } = createCartComponents<typeof cartServerHandlers>();
+ * ```
+ */
 declare function createCartComponents<THandlers>(): TypedCartComponents<CartDataFromHandlers<THandlers>>;
-declare function CartProvider({
-  initialData,
-  children
-}: {
-  initialData?: CartInitialData;
-  children?: ReactNode;
-}): _$react_jsx_runtime0.JSX.Element;
-declare function useCart<TData extends CartData = CartData, S = unknown>(selector: (state: CartState<TData>) => S, isEqual?: (a: S, b: S) => boolean): S;
+/**
+ * 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 (e.g. a server action that creates the
+ * cart before the client knows about it).
+ *
+ * @example
+ * ```tsx
+ * const { refresh } = useCartActions();
+ *
+ * async function handleServerAction() {
+ *   await createCartOnServer();
+ *   refresh(); // re-fetch the cart
+ * }
+ * ```
+ */
 declare function useCartActions(): CartActions;
+/**
+ * Subscribes the {@link CartStore} to the analytics event dispatcher.
+ *
+ * Call once near the root of your app — it subscribes on mount and
+ * cleans up on unmount. Publishes `CART_UPDATED`, `PRODUCT_ADD_TO_CART`,
+ * and `PRODUCT_REMOVED_FROM_CART` analytics events automatically.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useCartAnalytics();
+ *   return <Layout />;
+ * }
+ * ```
+ */
 declare function useCartAnalytics(): void;
+/**
+ * Returns form props and a field register function for building cart forms.
+ *
+ * `formProps()` returns `<form>` attributes that intercept submission, call
+ * {@link CartStore.handleFormSubmit}, and prevent the default browser navigation.
+ * `register()` returns the correct HTML attributes for each field type — see
+ * `CartFormRegister` for the full field/action list.
+ *
+ * When `register("quantity", { interactive: true })` is called, the returned
+ * attributes include a `ref` callback that attaches {@link attachQuantityInput}
+ * for auto-submit-on-change behavior.
+ *
+ * @example
+ * ```tsx
+ * function LineItem({ line }) {
+ *   const { formProps, register } = useCartForm();
+ *
+ *   return (
+ *     <form {...formProps()}>
+ *       <input {...register("lineId", { value: line.id })} />
+ *       <input {...register("quantity", { value: line.quantity, interactive: true })} />
+ *       <button {...register("set")} />
+ *       <button {...register("increase")}>+</button>
+ *       <button {...register("decrease")}>−</button>
+ *       <button {...register("remove")}>Remove</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
 declare function useCartForm(): {
   formProps: (opts?: {
     beforeSubmit?: (e: SubmitEvent<HTMLFormElement>) => void;
@@ -40,5 +111,5 @@ declare function useCartForm(): {
   register: CartFormRegister;
 };
 //#endregion
-export { CartActions, CartProvider, createCartComponents, useCart, useCartActions, useCartAnalytics, useCartForm };
+export { createCartComponents, useCartAnalytics };
 //# sourceMappingURL=cart.d.mts.map

package/dist/development/react/cart.mjs

@@ -13,6 +13,27 @@ const CartContext = createContext(null);
 function getCartEndpoint() {
 	return cartEndpoint;
 }
+/**
+* Factory that returns typed cart components and hooks matched to your server handler's
+* cart query shape.
+*
+* The generic `THandlers` parameter is inferred from your `createCartServerHandlers`
+* call, so every hook's {@link CartState} carries your custom cart fields end-to-end.
+*
+* @example
+* ```tsx
+* import type { cartServerHandlers } from "./server/cart.server";
+*
+* const {
+*   CartProvider,
+*   useCart,
+*   useSuspenseCart,
+*   useOptionalCart,
+*   useCartActions,
+*   useCartForm,
+* } = createCartComponents<typeof cartServerHandlers>();
+* ```
+*/
 function createCartComponents() {
 	function TypedCartProvider({ initialData, children }) {
 		return /* @__PURE__ */ jsx(CartProvider, {
@@ -48,6 +69,21 @@ function useCartStore(hookName = "useCart") {
 function useOptionalCartStore() {
 	return useContext(CartContext);
 }
+/**
+* React context provider that creates and manages a {@link CartStore} instance.
+*
+* Calls {@link CartStore.connect} on mount and {@link CartStore.destroy} on unmount.
+* All cart hooks (`useCart`, `useCartForm`, `useCartActions`) must be rendered
+* inside this provider.
+*
+* @example
+* ```tsx
+* // In your root layout
+* <CartProvider initialData={{ cart: loaderData.cart }}>
+*   <App />
+* </CartProvider>
+* ```
+*/
 function CartProvider({ initialData, children }) {
 	const store = useMemo(() => createCartStore({ initialData }), []);
 	useEffect(() => {
@@ -62,15 +98,69 @@ function CartProvider({ initialData, children }) {
 		children
 	});
 }
+/**
+* Subscribes to a slice of {@link CartState} via `useSyncExternalStore`.
+*
+* The component re-renders only when the selected value changes (by reference,
+* or by a custom `isEqual`). Always pass a selector — subscribing to the full
+* state object defeats memoization.
+*
+* @example
+* ```tsx
+* // Select cart lines
+* const lines = useCart((state) => state.data.lines.nodes);
+*
+* // Select pending state for a specific line
+* const isPending = useCart((state) => state.pending.lines.has(lineId));
+*
+* // Custom equality to avoid re-renders on unchanged totals
+* const total = useCart(
+*   (state) => state.data.cost.totalAmount,
+*   (a, b) => a.amount === b.amount,
+* );
+* ```
+*/
 function useCart(selector, isEqual) {
 	return useCartSelector(useCartStore(), selector, 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 (e.g. a server action that creates the
+* cart before the client knows about it).
+*
+* @example
+* ```tsx
+* const { refresh } = useCartActions();
+*
+* async function handleServerAction() {
+*   await createCartOnServer();
+*   refresh(); // re-fetch the cart
+* }
+* ```
+*/
 function useCartActions() {
 	const store = useCartStore("useCartActions");
 	return useMemo(() => ({ refresh: store.refresh }), [store]);
 }
+/**
+* Subscribes the {@link CartStore} to the analytics event dispatcher.
+*
+* Call once near the root of your app — it subscribes on mount and
+* cleans up on unmount. Publishes `CART_UPDATED`, `PRODUCT_ADD_TO_CART`,
+* and `PRODUCT_REMOVED_FROM_CART` analytics events automatically.
+*
+* @example
+* ```tsx
+* function App() {
+*   useCartAnalytics();
+*   return <Layout />;
+* }
+* ```
+*/
 function useCartAnalytics() {
-	const store = useCartStore();
+	const store = useCartStore("useCartAnalytics");
 	useEffect(() => trackCartAnalytics(store), [store]);
 }
 /**
@@ -105,8 +195,38 @@ function useCartSelector(store, selector, isEqual) {
 	};
 	return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
 }
+/**
+* Returns form props and a field register function for building cart forms.
+*
+* `formProps()` returns `<form>` attributes that intercept submission, call
+* {@link CartStore.handleFormSubmit}, and prevent the default browser navigation.
+* `register()` returns the correct HTML attributes for each field type — see
+* `CartFormRegister` for the full field/action list.
+*
+* When `register("quantity", { interactive: true })` is called, the returned
+* attributes include a `ref` callback that attaches {@link attachQuantityInput}
+* for auto-submit-on-change behavior.
+*
+* @example
+* ```tsx
+* function LineItem({ line }) {
+*   const { formProps, register } = useCartForm();
+*
+*   return (
+*     <form {...formProps()}>
+*       <input {...register("lineId", { value: line.id })} />
+*       <input {...register("quantity", { value: line.quantity, interactive: true })} />
+*       <button {...register("set")} />
+*       <button {...register("increase")}>+</button>
+*       <button {...register("decrease")}>−</button>
+*       <button {...register("remove")}>Remove</button>
+*     </form>
+*   );
+* }
+* ```
+*/
 function useCartForm() {
-	const store = useCartStore();
+	const store = useCartStore("useCartForm");
 	const coreRegister = useMemo(() => createCartFormRegister(), []);
 	const register = useMemo(() => {
 		const wrapped = ((...args) => {
@@ -151,5 +271,5 @@ function useCartForm() {
 }
 
 //#endregion
-export { CartProvider, createCartComponents, getCartEndpoint, useCart, useCartActions, useCartAnalytics, useCartForm, useCartStore };
+export { createCartComponents, getCartEndpoint, useCartAnalytics, useCartStore };
 //# sourceMappingURL=cart.mjs.map

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

@@ -1 +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":"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"}
+{"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 CartActions,\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\nexport type { CartActions };\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\n/**\n * Factory that returns typed cart components and hooks matched to your server handler's\n * cart query shape.\n *\n * The generic `THandlers` parameter is inferred from your `createCartServerHandlers`\n * call, so every hook's {@link CartState} carries your custom cart fields end-to-end.\n *\n * @example\n * ```tsx\n * import type { cartServerHandlers } from \"./server/cart.server\";\n *\n * const {\n *   CartProvider,\n *   useCart,\n *   useSuspenseCart,\n *   useOptionalCart,\n *   useCartActions,\n *   useCartForm,\n * } = createCartComponents<typeof cartServerHandlers>();\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\n/**\n * React context provider that creates and manages a {@link CartStore} instance.\n *\n * Calls {@link CartStore.connect} on mount and {@link CartStore.destroy} on unmount.\n * All cart hooks (`useCart`, `useCartForm`, `useCartActions`) must be rendered\n * inside this provider.\n *\n * @example\n * ```tsx\n * // In your root layout\n * <CartProvider initialData={{ cart: loaderData.cart }}>\n *   <App />\n * </CartProvider>\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\n/**\n * Subscribes to a slice of {@link CartState} via `useSyncExternalStore`.\n *\n * The component re-renders only when the selected value changes (by reference,\n * or by a custom `isEqual`). Always pass a selector — subscribing to the full\n * state object defeats memoization.\n *\n * @example\n * ```tsx\n * // Select cart lines\n * const lines = useCart((state) => state.data.lines.nodes);\n *\n * // Select pending state for a specific line\n * const isPending = useCart((state) => state.pending.lines.has(lineId));\n *\n * // Custom equality to avoid re-renders on unchanged totals\n * const total = useCart(\n *   (state) => state.data.cost.totalAmount,\n *   (a, b) => a.amount === b.amount,\n * );\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\n/**\n * Returns cart actions for reconciling state after out-of-band mutations.\n *\n * Currently exposes {@link CartStore.refresh} — call it after server-side cart\n * mutations that bypass the form system (e.g. a server action that creates the\n * cart before the client knows about it).\n *\n * @example\n * ```tsx\n * const { refresh } = useCartActions();\n *\n * async function handleServerAction() {\n *   await createCartOnServer();\n *   refresh(); // re-fetch the cart\n * }\n * ```\n */\nexport function useCartActions(): CartActions {\n  const store = useCartStore(\"useCartActions\");\n\n  return useMemo(() => ({ refresh: store.refresh }), [store]);\n}\n\n/**\n * Subscribes the {@link CartStore} to the analytics event dispatcher.\n *\n * Call once near the root of your app — it subscribes on mount and\n * cleans up on unmount. Publishes `CART_UPDATED`, `PRODUCT_ADD_TO_CART`,\n * and `PRODUCT_REMOVED_FROM_CART` analytics events automatically.\n *\n * @example\n * ```tsx\n * function App() {\n *   useCartAnalytics();\n *   return <Layout />;\n * }\n * ```\n */\nexport function useCartAnalytics(): void {\n  const store = useCartStore(\"useCartAnalytics\");\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\n/**\n * Returns form props and a field register function for building cart forms.\n *\n * `formProps()` returns `<form>` attributes that intercept submission, call\n * {@link CartStore.handleFormSubmit}, and prevent the default browser navigation.\n * `register()` returns the correct HTML attributes for each field type — see\n * `CartFormRegister` for the full field/action list.\n *\n * When `register(\"quantity\", { interactive: true })` is called, the returned\n * attributes include a `ref` callback that attaches {@link attachQuantityInput}\n * for auto-submit-on-change behavior.\n *\n * @example\n * ```tsx\n * function LineItem({ line }) {\n *   const { formProps, register } = useCartForm();\n *\n *   return (\n *     <form {...formProps()}>\n *       <input {...register(\"lineId\", { value: line.id })} />\n *       <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *       <button {...register(\"set\")} />\n *       <button {...register(\"increase\")}>+</button>\n *       <button {...register(\"decrease\")}>−</button>\n *       <button {...register(\"remove\")}>Remove</button>\n *     </form>\n *   );\n * }\n * ```\n */\nexport function useCartForm() {\n  const store = useCartStore(\"useCartForm\");\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":"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"}

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

@@ -1,5 +1,5 @@
 import { CollectionState } from "../core/collection/state.mjs";
-import { CollectionData, CollectionStore } from "../core/collection/collection.mjs";
+import { CollectionActions, CollectionData, CollectionStore } from "../core/collection/collection.mjs";
 import * as _$react from "react";
 import { FormHTMLAttributes, ReactNode, SubmitEvent } from "react";
 
@@ -58,8 +58,6 @@ declare function useCollection(): CollectionState;
  * ```
  */
 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
@@ -87,5 +85,5 @@ declare function useCollectionForm(): {
   }) => FormHTMLAttributes<HTMLFormElement>;
 };
 //#endregion
-export { CollectionActions, CollectionProvider, CollectionProviderProps, useCollection, useCollectionActions, useCollectionForm };
+export { CollectionProvider, CollectionProviderProps, useCollection, useCollectionActions, useCollectionForm };
 //# sourceMappingURL=collection.d.mts.map

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

@@ -1 +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"}
+{"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 CollectionActions,\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/**\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 { CollectionActions, CollectionData };\n"],"mappings":";;;;;;;AA0BA,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;;;;;;;AAQxE,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

@@ -1,13 +1,15 @@
 import { ShopifyStandardActions } from "../vendor/standard-actions.mjs";
+import { CartActions } from "../core/cart/cart.mjs";
 import { ShopifyGlobal } from "../globals.mjs";
 import { QuantityInputAttributes, SetButtonAttributes } from "../core/cart/form.mjs";
-import { CollectionData } from "../core/collection/collection.mjs";
+import { CollectionActions, 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 { ProductAddToCartProps, ProductAttributeDefaultValueProps, ProductAttributeValueProps, ProductFormRegister, ProductMerchandiseIdProps, ProductOptionValueProps, ProductQuantityDefaultProps, ProductQuantityProps } from "../core/product/form.mjs";
+import { PredictiveSearchActions } from "../core/predictive-search/store.mjs";
+import { createCartComponents, useCartAnalytics } from "./cart.mjs";
+import { CollectionProvider, CollectionProviderProps, useCollection, useCollectionActions, useCollectionForm } from "./collection.mjs";
+import { 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 };
+export { type CartActions, type CollectionActions, type CollectionData, CollectionProvider, type CollectionProviderProps, type PredictiveSearchActions, type PredictiveSearchFormPropsOptions, type PredictiveSearchFormRegister, type PredictiveSearchFormResult, PredictiveSearchProvider, type PredictiveSearchProviderProps, type PredictiveSearchQueryInputPropsOptions, type ProductAddToCartProps, type ProductAttributeDefaultValueProps, type ProductAttributeValueProps, 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, useCartAnalytics, useCollection, useCollectionActions, useCollectionForm, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm, useProductForm };

package/dist/development/react/index.mjs

@@ -1,10 +1,10 @@
 "use client";
 
-import { CartProvider, createCartComponents, useCart, useCartActions, useCartAnalytics, useCartForm } from "./cart.mjs";
+import { createCartComponents, useCartAnalytics } 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 };
+export { CollectionProvider, PredictiveSearchProvider, ShopPayButton, ShopifyScripts, createCartComponents, createProductComponents, useCartAnalytics, useCollection, useCollectionActions, useCollectionForm, usePredictiveSearch, usePredictiveSearchActions, usePredictiveSearchForm, useProductForm };