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

package/dist/core/cart/attach-quantity-input.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"attach-quantity-input.mjs","names":[],"sources":["../../../src/core/cart/attach-quantity-input.ts"],"sourcesContent":["const FIRST_SUBMIT_BUTTON_SELECTOR = \"button:not([type=button])\";\n\nexport function attachQuantityInput(\n  inputEl: HTMLInputElement,\n  formEl: HTMLFormElement,\n): () => void {\n  const firstSubmitButton = formEl.querySelector(\n    FIRST_SUBMIT_BUTTON_SELECTOR,\n  ) as HTMLButtonElement | null;\n\n  if (\n    !firstSubmitButton ||\n    firstSubmitButton.name !== \"intent\" ||\n    firstSubmitButton.value !== \"set\"\n  ) {\n    throw new Error(\n      `The first button in cart form must have a name of \"intent\" and value of \"set\". Your UI will not behave as expected.`,\n      { cause: formEl },\n    );\n  }\n\n  const handleChange = (e: Event) => {\n    if (formEl.isConnected && e.target === inputEl) {\n      formEl.requestSubmit(firstSubmitButton);\n    }\n  };\n\n  inputEl.addEventListener(\"change\", handleChange);\n\n  return () => {\n    inputEl.removeEventListener(\"change\", handleChange);\n  };\n}\n"],"mappings":";AAAA,MAAM,+BAA+B;AAErC,SAAgB,oBACd,SACA,QACY;CACZ,MAAM,oBAAoB,OAAO,cAC/B,6BACD;AAED,KACE,CAAC,qBACD,kBAAkB,SAAS,YAC3B,kBAAkB,UAAU,MAE5B,OAAM,IAAI,MACR,uHACA,EAAE,OAAO,QAAQ,CAClB;CAGH,MAAM,gBAAgB,MAAa;AACjC,MAAI,OAAO,eAAe,EAAE,WAAW,QACrC,QAAO,cAAc,kBAAkB;;AAI3C,SAAQ,iBAAiB,UAAU,aAAa;AAEhD,cAAa;AACX,UAAQ,oBAAoB,UAAU,aAAa"}
+{"version":3,"file":"attach-quantity-input.mjs","names":[],"sources":["../../../src/core/cart/attach-quantity-input.ts"],"sourcesContent":["const FIRST_SUBMIT_BUTTON_SELECTOR = \"button:not([type=button])\";\n\n/**\n * Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.\n *\n * When the input's value changes, the form is automatically submitted via the\n * first submit button (which must carry `name=\"intent\" value=\"set\"`). Returns\n * a cleanup function that removes the event listener.\n *\n * The form must contain a `\"set\"` button as its first submit element — use\n * `register(\"set\")` from `createCartFormRegister` to produce it.\n *\n * @throws If the form's first submit button is not a `name=\"intent\" value=\"set\"` button.\n *\n * @example\n * ```ts\n * const input = document.querySelector<HTMLInputElement>('input[name=\"quantity\"]');\n * const form = input?.closest('form');\n *\n * if (input && form) {\n *   const detach = attachQuantityInput(input, form);\n *   // Input changes now auto-submit the form\n *\n *   // Clean up when unmounting\n *   detach();\n * }\n * ```\n */\nexport function attachQuantityInput(\n  inputEl: HTMLInputElement,\n  formEl: HTMLFormElement,\n): () => void {\n  const firstSubmitButton = formEl.querySelector(\n    FIRST_SUBMIT_BUTTON_SELECTOR,\n  ) as HTMLButtonElement | null;\n\n  if (\n    !firstSubmitButton ||\n    firstSubmitButton.name !== \"intent\" ||\n    firstSubmitButton.value !== \"set\"\n  ) {\n    throw new Error(\n      `The first button in cart form must have a name of \"intent\" and value of \"set\". Your UI will not behave as expected.`,\n      { cause: formEl },\n    );\n  }\n\n  const handleChange = (e: Event) => {\n    if (formEl.isConnected && e.target === inputEl) {\n      formEl.requestSubmit(firstSubmitButton);\n    }\n  };\n\n  inputEl.addEventListener(\"change\", handleChange);\n\n  return () => {\n    inputEl.removeEventListener(\"change\", handleChange);\n  };\n}\n"],"mappings":";AAAA,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BrC,SAAgB,oBACd,SACA,QACY;CACZ,MAAM,oBAAoB,OAAO,cAC/B,6BACD;AAED,KACE,CAAC,qBACD,kBAAkB,SAAS,YAC3B,kBAAkB,UAAU,MAE5B,OAAM,IAAI,MACR,uHACA,EAAE,OAAO,QAAQ,CAClB;CAGH,MAAM,gBAAgB,MAAa;AACjC,MAAI,OAAO,eAAe,EAAE,WAAW,QACrC,QAAO,cAAc,kBAAkB;;AAI3C,SAAQ,iBAAiB,UAAU,aAAa;AAEhD,cAAa;AACX,UAAQ,oBAAoB,UAAU,aAAa"}

package/dist/core/cart/cart.d.mts

@@ -1,37 +1,137 @@
 import { CartData, CartState } from "./state.mjs";
 
 //#region src/core/cart/cart.d.ts
+/** Timeout (in milliseconds) for cart loads and mutations. */
 declare const STANDARD_ACTION_TIMEOUT_IN_MS = 30000;
+/**
+ * Error thrown when the cart endpoint responds with a non-2xx status.
+ *
+ * Carries the HTTP {@link CartNetworkError.status | status} code so callers
+ * can distinguish transient failures from permanent ones.
+ */
 declare class CartNetworkError extends Error {
   readonly status: number;
   constructor(status: number);
 }
+/**
+ * A reactive, framework-agnostic cart state machine.
+ *
+ * The store manages optimistic mutations and server reconciliation — the client's
+ * *intent*. Cart-level costs and totals are always server-authoritative, but
+ * line-level data (quantity, estimated cost) and discount applicability are
+ * projected optimistically until the server response arrives.
+ *
+ * Mutations are dispatched via {@link CartStore.handleFormSubmit} (from HTML
+ * forms) or through Shopify Standard Action `shopify:cart:*` events.
+ *
+ * @example
+ * ```ts
+ * const store = createCartStore({
+ *   initialData: { cart: loaderData.cart },
+ * });
+ *
+ * store.connect();
+ *
+ * const unsubscribe = store.subscribe((state) => {
+ *   renderCart(state.data);
+ * });
+ *
+ * store.destroy();
+ * ```
+ */
 type CartStore = {
-  connect(): void;
-  destroy(): void;
-  hydrate(data: CartData): void;
+  /**
+   * Activates the store — starts listening for Shopify standard action events
+   * and triggers the initial cart load if no `initialData` was provided.
+   * Idempotent; no-op without `document` (SSR-safe).
+   */
+  connect(): void; /** Tears down the store — cancels in-flight requests, removes event listeners, releases resources. */
+  destroy(): void; /** Replaces the settled cart data with a fresh server response. */
+  hydrate(data: CartData): void; /** Returns the current {@link CartState}, with optimistic projections applied on top of settled data. */
   getState(): CartState;
-  subscribe(listener: (state: CartState) => void): () => void;
+  /**
+   * Registers a listener invoked on every state change. Returns an unsubscribe function.
+   * Compatible with React's `useSyncExternalStore`.
+   *
+   * @param listener - Callback receiving the new {@link CartState} snapshot
+   */
+  subscribe(listener: (state: CartState) => void): () => void; /** Triggers a full cart load from the server endpoint. */
   fetch(): Promise<void>;
   /**
    * Reconciles the cart after an out-of-band mutation: revalidates the current
    * cart, or loads one when none is present yet (e.g. just created server-side).
    */
-  refresh(): void;
+  refresh(): void; /** Resets the store — aborts in-flight requests, clears data and errors, and re-fetches when connected. */
   reset(): void;
+  /**
+   * Intercepts a native `SubmitEvent` from a cart form, parses the intent and
+   * field values, and dispatches the matching transaction.
+   *
+   * The submitter's `value` attribute determines the action — `"add"`,
+   * `"increase"`, `"decrease"`, `"remove"`, `"set"`, `"discount-apply"`,
+   * `"discount-remove"`, `"note-update"`, or `"attributes-update"`. An empty
+   * value with a `merchandiseId` field is treated as `"add"`.
+   *
+   * The returned promise rejects with a `TypeError` if `event.target` is not
+   * a form or `event.submitter` is missing, and with an `Error` if the
+   * submitter's value is not a recognized intent.
+   */
   handleFormSubmit(event: SubmitEvent, eventDetail?: Record<string, unknown>): Promise<void>;
 };
+/** Actions for reconciling cart state after updates outside Standard Actions. */
+type CartActions = Pick<CartStore, "refresh">;
 type CartInitialData<TData extends CartData = CartData> = {
   cart: TData | null;
   errors?: Array<{
     message: string;
   }>;
 };
+/** Options for {@link createCartStore}. */
 type CreateCartStoreOptions<TData extends CartData = CartData> = {
+  /**
+   * Server-loaded cart data to hydrate the store with on creation.
+   *
+   * Accepts a synchronous value or a `PromiseLike` for streamed/deferred data.
+   * When omitted, the store starts empty and loads the cart on {@link CartStore.connect}.
+   */
   initialData?: CartInitialData<TData> | PromiseLike<CartInitialData<TData>>;
 };
+/**
+ * Creates a new {@link CartStore} for the given initial data.
+ *
+ * The store is inert until {@link CartStore.connect} is called — no network
+ * requests are made and no event listeners are attached at creation time.
+ * Framework adapters call `connect()` on mount and `destroy()` on unmount.
+ *
+ * @example
+ * ```ts
+ * // With synchronous loader data
+ * const store = createCartStore({
+ *   initialData: { cart: loaderData.cart },
+ * });
+ *
+ * // With deferred/streamed data
+ * const store = createCartStore({
+ *   initialData: cartPromise,
+ * });
+ *
+ * // Empty — loads the cart on connect()
+ * const store = createCartStore();
+ * ```
+ */
 declare function createCartStore<TData extends CartData = CartData>(options?: CreateCartStoreOptions<TData>): CartStore;
+/**
+ * Routes cart loads and mutations to a custom endpoint instead of the
+ * Standard Actions default handler.
+ *
+ * Logs a warning if called again with a different endpoint.
+ *
+ * @example
+ * ```ts
+ * configureCartEndpoint("/storefront/cart");
+ * ```
+ */
 declare function configureCartEndpoint(endpoint: string): void;
 //#endregion
-export { CartNetworkError, CartStore, CreateCartStoreOptions, STANDARD_ACTION_TIMEOUT_IN_MS, configureCartEndpoint, createCartStore };
+export { CartActions, CartNetworkError, CartStore, CreateCartStoreOptions, STANDARD_ACTION_TIMEOUT_IN_MS, configureCartEndpoint, createCartStore };
 //# sourceMappingURL=cart.d.mts.map

package/dist/core/cart/cart.mjs

@@ -23,7 +23,14 @@ const EMPTY_QUANTITY = 0;
 const FNV1A_OFFSET_BASIS = 2166136261;
 const FNV1A_PRIME = 16777619;
 const CART_REVALIDATION_ERROR_MESSAGE = "Something went wrong refreshing your cart. Please try again.";
+/** Timeout (in milliseconds) for cart loads and mutations. */
 const STANDARD_ACTION_TIMEOUT_IN_MS = 3e4;
+/**
+* Error thrown when the cart endpoint responds with a non-2xx status.
+*
+* Carries the HTTP {@link CartNetworkError.status | status} code so callers
+* can distinguish transient failures from permanent ones.
+*/
 var CartNetworkError = class extends Error {
 	status;
 	constructor(status) {
@@ -1369,6 +1376,29 @@ function loadCartInStore(store, cartPromise) {
 	store.observable.setReadyState(state);
 	return promise;
 }
+/**
+* Creates a new {@link CartStore} for the given initial data.
+*
+* The store is inert until {@link CartStore.connect} is called — no network
+* requests are made and no event listeners are attached at creation time.
+* Framework adapters call `connect()` on mount and `destroy()` on unmount.
+*
+* @example
+* ```ts
+* // With synchronous loader data
+* const store = createCartStore({
+*   initialData: { cart: loaderData.cart },
+* });
+*
+* // With deferred/streamed data
+* const store = createCartStore({
+*   initialData: cartPromise,
+* });
+*
+* // Empty — loads the cart on connect()
+* const store = createCartStore();
+* ```
+*/
 function createCartStore(options = {}) {
 	const initialData = options.initialData;
 	const asyncInitialData = isPromiseLike(initialData);
@@ -1521,6 +1551,17 @@ async function handleFormSubmitInStore(store, handlers, event, eventDetail) {
 	})) });
 	throw new Error(`Unknown cart form intent: "${intent}"`);
 }
+/**
+* Routes cart loads and mutations to a custom endpoint instead of the
+* Standard Actions default handler.
+*
+* Logs a warning if called again with a different endpoint.
+*
+* @example
+* ```ts
+* configureCartEndpoint("/storefront/cart");
+* ```
+*/
 function configureCartEndpoint(endpoint) {
 	if (configuredCartEndpoint === endpoint) return;
 	if (configuredCartEndpoint !== null) log.warn(`configureCartEndpoint called with "${endpoint}" but already configured with "${configuredCartEndpoint}".`);