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

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

@@ -1,6 +1,6 @@
 import { getLogger } from "../logging/logging.mjs";
 import { createObservable } from "../observable.mjs";
-import { SHOPIFY_STOREFRONT_STANDARD_ACTIONS_SCRIPT, VISITOR_CONSENT_COLLECTED_EVENT } from "../shopify-scripts/constants.mjs";
+import { CONSENT_TRACKING_API_LOADED_EVENT, SHOPIFY_STOREFRONT_STANDARD_ACTIONS_SCRIPT, VISITOR_CONSENT_COLLECTED_EVENT } from "../shopify-scripts/constants.mjs";
 import { getCartAttributeFormEntries } from "./form.mjs";
 import { DEFAULT_MINIMUM_QUANTITY, sanitizeQuantity } from "./quantity.mjs";
 import { createCartState, createEmptyCartState, createEmptyErrorGroup } from "./state.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) {
@@ -949,6 +956,7 @@ function enqueueTransaction(store, type, payload, promise, reservedTransaction,
 	const expectedEventIndex = store.expectedEvents.findIndex((expected) => expected.token === eventToken);
 	if (expectedEventIndex !== -1) {
 		store.expectedEvents.splice(expectedEventIndex, 1);
+		promise.then(NOOP, NOOP);
 		return;
 	}
 	if (store.observedPromises.has(promise)) return;
@@ -1229,17 +1237,20 @@ function destroyCartStore(store, handlers) {
 	store.cartSyncAttached = false;
 	publishVisibleState(store);
 }
-function handleVisitorConsentCollected() {
+function handleConsentStateChanged() {
 	revalidateConnectedCartCheckoutUrls();
 }
 function attachCartConsentListener() {
 	if (cartConsentListenerAttached) return;
-	document.addEventListener(VISITOR_CONSENT_COLLECTED_EVENT, handleVisitorConsentCollected);
+	document.addEventListener(CONSENT_TRACKING_API_LOADED_EVENT, handleConsentStateChanged);
+	document.addEventListener(VISITOR_CONSENT_COLLECTED_EVENT, handleConsentStateChanged);
 	cartConsentListenerAttached = true;
+	if (window.Shopify?.customerPrivacy?.consentStatus === "loaded") revalidateConnectedCartCheckoutUrls();
 }
 function detachCartConsentListenerIfIdle() {
 	if (!cartConsentListenerAttached || connectedCartStores.size > 0) return;
-	document.removeEventListener(VISITOR_CONSENT_COLLECTED_EVENT, handleVisitorConsentCollected);
+	document.removeEventListener(CONSENT_TRACKING_API_LOADED_EVENT, handleConsentStateChanged);
+	document.removeEventListener(VISITOR_CONSENT_COLLECTED_EVENT, handleConsentStateChanged);
 	cartConsentListenerAttached = false;
 }
 function createCartObservable(initialState, onReadyPromiseRemoved) {
@@ -1365,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);
@@ -1476,11 +1510,17 @@ function getAddPayload(formData, eventDetail) {
 	const rawQuantity = Number.parseInt(formData.get("quantity"), 10);
 	const quantity = Number.isNaN(rawQuantity) ? DEFAULT_ADD_QUANTITY : Math.max(DEFAULT_ADD_QUANTITY, rawQuantity);
 	const sellingPlanId = formData.get("sellingPlanId") || void 0;
+	const rawAttributes = getCartAttributeFormEntries(formData);
+	const attributes = rawAttributes.length > 0 ? rawAttributes.filter(({ key }) => key !== "").map(({ key, value }) => ({
+		key,
+		value: String(value)
+	})) : void 0;
 	return {
 		lines: [{
 			merchandiseId,
 			quantity,
-			...sellingPlanId ? { sellingPlanId } : {}
+			...sellingPlanId ? { sellingPlanId } : {},
+			...attributes ? { attributes } : {}
 		}],
 		products: extractProductDetails(eventDetail),
 		...eventDetail ? { eventDetail } : {}
@@ -1505,12 +1545,23 @@ async function handleFormSubmitInStore(store, handlers, event, eventDetail) {
 	if (LINE_INTENTS.has(intent)) return submitLineIntent(store, intent, formData);
 	if (DISCOUNT_INTENTS.has(intent)) return submitDiscountIntent(store, intent, formData);
 	if (intent === "note-update") return dispatchTransaction(store, "set_note", { note: formData.get("note") ?? "" });
-	if (intent === "attributes-update") return dispatchTransaction(store, "set_attributes", { attributes: getCartAttributeFormEntries(formData).map(({ key, value }) => ({
+	if (intent === "attributes-update") return dispatchTransaction(store, "set_attributes", { attributes: getCartAttributeFormEntries(formData).filter(({ key }) => key !== "").map(({ key, value }) => ({
 		key,
 		value: String(value)
 	})) });
 	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}".`);