@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

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

@@ -1,22 +1,23 @@
 import { CartErrorCode, CartWarningCode } from "../../graphql/generated/storefront-api-types.mjs";
 
 //#region src/core/cart/state.d.ts
-/** Storefront API monetary value — an amount string and ISO 4217 currency code. */
+/** A monetary value from the Storefront API. */
 interface Money {
-  /** Decimal amount as a string (e.g. `"29.99"`). */
+  /** The decimal amount as a string, such as `29.99`. */
   amount: string;
-  /** ISO 4217 currency code (e.g. `"USD"`, `"EUR"`). */
+  /** The ISO 4217 currency code, such as `USD`. */
   currencyCode: string;
 }
-/** Cart-level cost breakdown returned by the Storefront API. */
+/** The cart's costs from the Storefront API. */
 interface CartCost {
   /** The amount, before taxes and cart-level discounts, for the customer to pay. */
   subtotalAmount: Money;
-  /** Final amount the buyer pays at checkout. */
+  /** Final amount the customer pays at checkout. */
   totalAmount: Money;
   /** Estimated amount due at checkout, excluding deferred payments. Equals the subtotal when no deferred payments exist. */
   checkoutChargeAmount: Money;
 }
+/** A cart line's costs from the Storefront API. */
 interface CartLineCost {
   /** Line total after all applicable discounts. */
   totalAmount: Money;
@@ -27,22 +28,24 @@ interface CartLineCost {
   /** Original compare-at unit price, or `null` when no comparison exists. */
   compareAtAmountPerQuantity: Money | null;
 }
-/** Product variant information attached to a {@link CartLine}. */
+/** The product variant on a cart line. */
 interface CartLineMerchandise {
   /** Storefront API GID of the product variant. */
   id: string;
-  /** Variant title (e.g. `"Small / Black"`). */
+  /** The variant title, such as `"Small / Black"`. */
   title?: string;
-  /** Selected variant option name/value pairs (e.g. `{ name: "Size", value: "S" }`). */
+  /** The variant's selected options as name and value pairs. */
   selectedOptions?: Array<{
     name: string;
     value: string;
   }>;
+  /** The product that the variant belongs to. */
   product: {
     title: string;
     handle?: string;
     [key: string]: unknown;
   };
+  /** The variant image that the cart query selects. */
   image?: {
     id?: string | null;
     url: string;
@@ -51,25 +54,28 @@ interface CartLineMerchandise {
     height?: number | null;
     [key: string]: unknown;
   } | null;
+  /** Units available for sale. When your cart fragment selects the field, the store caps the quantity of a `set` submission at this number. */
   quantityAvailable?: number | null;
+  /** Extra variant fields from your custom cart fragment, unchanged. */
   [key: string]: unknown;
 }
 /**
  * A single line item in the cart.
  *
- * Each line represents a product variant at a given quantity. Lines may carry
- * custom {@link Attribute | attributes}, a selling plan allocation (subscriptions),
- * or nested {@link CartLine.lineComponents | line components} (bundles).
+ * Each line holds a product variant at a quantity. A line can carry custom
+ * attributes, a selling plan allocation for a subscription, or line components
+ * for a bundle.
  */
 interface CartLine {
-  /** Storefront API GID of this cart line — used as the key in {@link CartPending.lines}. */
+  /** The cart line's Storefront API GID. Look up the line's pending state and errors with this ID. */
   id: string;
   /** Number of units of this merchandise in the cart. */
   quantity: number;
+  /** Custom key-value attributes attached to the line. */
   attributes?: Attribute[];
   /** Per-line cost breakdown from the Storefront API. */
   cost: CartLineCost;
-  /** The product variant this line represents. */
+  /** The product variant on the line. */
   merchandise?: CartLineMerchandise;
   /** Subscription selling plan allocation, or `null` for one-time purchases. */
   sellingPlanAllocation?: {
@@ -77,6 +83,7 @@ interface CartLine {
       id: string;
     };
   } | null;
+  /** The parent line's ID when this line is a bundle component. */
   parentRelationship?: {
     parent: {
       id: string;
@@ -85,52 +92,65 @@ interface CartLine {
   /** Nested child lines when this line is a bundle parent. */
   lineComponents?: CartLine[];
 }
+/** The cart's line items in the Storefront API connection shape. */
 interface CartLineConnection {
+  /** The cart lines that the cart query returns. */
   nodes: CartLine[];
+  /** Extra connection fields from your custom cart fragment, unchanged. */
   [key: string]: unknown;
 }
 /** A discount code applied to the cart. */
 interface DiscountCode {
+  /** The discount code text. Look up the code's pending state and errors with this value. */
   code: string;
-  /** Whether the code is applicable to the cart's current contents. Set optimistically to `false` for newly added codes until the server confirms. */
+  /** Whether the code applies to the cart's current contents. A new code reads `false` until the server responds. */
   applicable: boolean;
 }
 /** A validation error returned by a Storefront API cart mutation. */
 interface CartUserError {
   /** Machine-readable error code, or `null` for unclassified errors. */
   code: CartErrorCode | null;
+  /** Human-readable error text from the Storefront API. */
   message: string;
-  /** JSONPath to the input field that caused the error (e.g. `["lines", "0", "quantity"]`). */
+  /** The path to the input field that caused the error, such as `["lines", "0", "quantity"]`. */
   field?: string[];
 }
 /** A non-blocking warning returned by a Storefront API cart mutation. */
 interface CartWarning {
+  /** The warning code from the Storefront API. */
   code: CartWarningCode;
+  /** Human-readable warning text from the Storefront API. */
   message: string;
 }
-/** Errors and warnings from a single cart mutation response. */
+/** Errors and warnings from one cart change. */
 interface CartErrorGroup {
+  /** Validation errors that the mutation returned. */
   userErrors: CartUserError[];
+  /** Non-blocking warnings that the mutation returned. */
   warnings: CartWarning[];
 }
-/** A network-level error encountered during a cart operation (e.g. non-2xx response, timeout). Aborted requests are not recorded. */
+/**
+ * A failed cart request, such as a non-2xx response or a timeout. Canceled requests add no entry.
+ */
 interface CartNetworkEntry {
+  /** The error message, or a generic message when the failure has no message of its own. */
   message: string;
-  /** HTTP status code when available. */
+  /** The HTTP status code, when the endpoint returned a non-2xx response. */
   status?: number;
 }
-/** A key-value pair attached to the cart or to an individual {@link CartLine}. */
+/** A key-value pair attached to the cart or to an individual cart line. */
 interface Attribute {
+  /** The attribute name. Look up the attribute's errors with this name. */
   key: string;
+  /** The attribute value. */
   value: string | null;
 }
 /**
- * Tracks which parts of the cart have in-flight mutations.
+ * Shows which parts of the cart have changes in flight.
  *
- * `lines` and `discountCodes` are `Set<string>` keyed by line ID / discount code,
- * enabling per-item pending indicators rather than a single global spinner.
- * `cost` is a boolean because *any* line or discount change affects the total —
- * use it to show pending UI on price displays without computing optimistic amounts.
+ * Check a line ID or a discount code to show a pending indicator on that item.
+ * Check `cost` to show pending UI on prices, which update only when the server
+ * responds.
  *
  * @example
  * ```ts
@@ -148,64 +168,73 @@ interface Attribute {
  * ```
  */
 interface CartPending {
-  /** Line IDs with in-flight add, quantity, or remove mutations. New lines use their `optimistic:` ID until the server confirms. */
+  /** Line IDs with an add, quantity change, or removal in flight. A new line has an ID that starts with `optimistic:` until the server confirms the line. */
   lines: Set<string>;
+  /** `true` while a note update is in flight. */
   note: boolean;
+  /** `true` while an attribute update is in flight. */
   attributes: boolean;
-  /** Discount codes with in-flight apply/remove mutations. */
+  /** Discount codes with an apply or remove in flight. */
   discountCodes: Set<string>;
-  /** `true` when any mutation may affect cart pricing — show pending UI on cost displays. */
+  /** `true` while a change that can affect cart prices is in flight. */
   cost?: boolean;
 }
 /**
- * Per-resource error tracking for the cart.
+ * The cart's errors, grouped by the part of the cart that they affect: lines, the note,
+ * attributes, discount codes, or the cart as a whole. Each group has a timestamp in
+ * milliseconds since the epoch. Use the timestamps to flag stale errors or dismiss
+ * errors after a timeout.
  *
- * Errors are bucketed by the resource they affect — `lines`, `note`, `attributes`,
- * `discountCodes`, or `cart` (for cross-cutting errors). Each bucket carries a
- * `*UpdatedAt` timestamp (ms since epoch) so the UI can show stale-error indicators
- * or auto-dismiss after a timeout.
- *
- * `network` collects transport-level failures (timeouts, 5xx) separately from
- * Storefront API user errors.
+ * Failed requests go in a network list, apart from Storefront API user errors.
  */
 interface CartErrorState {
-  /** Cross-cutting cart errors not attributable to a specific resource. */
+  /** Errors that don't belong to a line, the note, an attribute, or a discount code. */
   cart: CartErrorGroup;
-  /** Errors keyed by {@link CartLine.id}. */
+  /** Errors keyed by cart line ID. */
   lines: Map<string, CartErrorGroup>;
+  /** Errors for the cart note. */
   note: CartErrorGroup;
-  /** Errors keyed by {@link Attribute.key}. */
+  /** Errors keyed by attribute name. */
   attributes: Map<string, CartErrorGroup>;
-  /** Errors keyed by discount code string. */
+  /** Errors keyed by discount code. */
   discountCodes: Map<string, CartErrorGroup>;
+  /**
+   * Failed cart requests. A failed cart change adds an entry, with an HTTP status when the endpoint returned a non-2xx response. A failed refresh adds an entry with a generic message and no status. A failed first load or a failed load after a reset adds no entry.
+   */
   network: CartNetworkEntry[];
+  /** Time in milliseconds since the epoch when the store last recorded any error, or `0` before the first. */
   lastUpdatedAt: number;
+  /** Time in milliseconds since the epoch of the last line, discount code, or attribute error, or `0` before any. */
   cartUpdatedAt: number;
+  /** Time in milliseconds since the epoch when the store last recorded line errors, or `0` before any. */
   linesUpdatedAt: number;
+  /** Time in milliseconds since the epoch when the store last recorded note errors, or `0` before any. */
   noteUpdatedAt: number;
+  /** Time in milliseconds since the epoch when the store last recorded attribute errors, or `0` before any. */
   attributesUpdatedAt: number;
+  /** Time in milliseconds since the epoch when the store last recorded discount code errors, or `0` before any. */
   discountCodesUpdatedAt: number;
+  /** Time in milliseconds since the epoch when the store last recorded a network error, or `0` before any. */
   networkUpdatedAt: number;
 }
 /**
- * Cart data returned by the Storefront API.
+ * The customer's cart, in the shape that the Storefront API returns.
  *
- * This is the server's authoritative snapshot — prices, discount applicability,
- * and totals come exclusively from here, never from client-side computation.
- * The index signature allows custom cart query fields to pass through.
+ * Cart costs come only from the server. Extra fields from your custom cart
+ * fragment appear unchanged.
  */
 interface CartData {
-  /** Storefront API Cart GID, or `null` when no cart exists yet. */
+  /** The cart's Storefront API GID, or `null` when no cart exists yet. */
   id: string | null;
-  /** `Cart.updatedAt` (ISO 8601). Absent until the first server response. */
+  /** The cart's last update time in ISO 8601 format. Absent until the first server response. */
   updatedAt?: string;
-  /** Shopify checkout URL. Changes when buyer identity or consent state changes. */
+  /** The Shopify checkout URL. The URL can change when the customer logs in or out, or changes tracking consent. */
   checkoutUrl?: string | null;
   /** Sum of all line quantities. */
   totalQuantity: number;
-  /** Cart-level cost breakdown (subtotal, total, checkout charge). */
+  /** The cart's subtotal, total, and checkout charge. */
   cost: CartCost;
-  /** Buyer-supplied cart note, or `null`/empty when unset. */
+  /** Customer-supplied cart note, or `null` or empty when unset. */
   note?: string | null;
   /** Cart-level custom attributes. */
   attributes: Attribute[];
@@ -213,15 +242,14 @@ interface CartData {
   lines: CartLineConnection;
   /** Discount codes applied to the cart, with their applicability. */
   discountCodes: DiscountCode[];
+  /** Extra cart fields from your custom cart fragment, unchanged. */
   [key: string]: unknown;
 }
 /**
- * Full observable state of the cart store.
+ * The cart, plus what's loading, pending, and failed.
  *
- * Framework adapters subscribe to this via `CartStore.subscribe` (or the
- * framework-specific hooks like `useCart`). The generic `TData` parameter
- * flows from your server handler configuration, so `data` is typed to match
- * your custom cart query.
+ * The cart hooks return values from this state. The data type matches the cart
+ * fragment in your cart server handlers.
  *
  * @example
  * ```ts
@@ -241,29 +269,47 @@ interface CartData {
  * ```
  */
 interface CartState<TData extends CartData = CartData> {
-  /** The latest server-confirmed cart data, with optimistic projections applied on top. */
+  /** The cart, including changes that the server hasn't confirmed yet. */
   data: TData;
-  /** `true` during a full-cart fetch — initial load, after `reset()`, or before connect with no `initialData`. */
+  /** `true` while the store loads the full cart: the first load, a load after `reset()`, or before `connect()` when the store has no initial data. */
   loading: boolean;
-  /** Non-rejecting signal that resolves when the current full-cart load settles or is invalidated. */
+  /** Present while a full cart load runs. The promise resolves, and never rejects, when the load finishes or the store drops the load. */
   readonly readyPromise?: PromiseLike<void>;
-  /** Per-resource in-flight mutation tracking. */
+  /** The parts of the cart with changes in flight. */
   pending: CartPending;
-  /** `true` when a background revalidation is in flight (triggered by overlapping mutations or `refresh()`). */
+  /** `true` while the store reloads the cart in the background after overlapping cart changes or a `refresh()` call. */
   revalidating?: boolean;
-  /** Per-resource error and warning state. */
+  /** Errors and warnings, grouped by the part of the cart that they affect. */
   errors: CartErrorState;
 }
-/** Creates an empty {@link CartErrorGroup} — no user errors, no warnings. */
+/**
+ * Creates an empty error group with no user errors and no warnings.
+ *
+ * @returns A new error group with empty user error and warning arrays.
+ * @publicDocs
+ */
 declare function createEmptyErrorGroup(): CartErrorGroup;
-/** Creates an empty {@link CartErrorState} — all timestamps at `0`, all buckets empty. */
+/**
+ * Creates a cart error state with no errors and every timestamp at `0`.
+ *
+ * Each call returns new groups, maps, and arrays.
+ *
+ * @returns A new, empty error state.
+ * @publicDocs
+ */
 declare function createEmptyCartErrors(): CartErrorState;
 /**
- * Frozen {@link CartData} representing an empty cart — `id: null`, zero quantities,
- * zero-amount costs. Used as the initial/fallback value before the first server response.
+ * Frozen cart data for an empty cart, with a `null` ID, zero quantities, and
+ * zero-amount costs. A cart store without initial data starts from this cart.
+ *
+ * @publicDocs
  */
 declare const EMPTY_CART_DATA: CartData;
-/** Shared empty {@link CartState} — backed by {@link EMPTY_CART_DATA}, defaults to `loading: true`. */
+/**
+ * Shared empty cart state backed by the empty cart data, with loading set to `true`.
+ *
+ * @publicDocs
+ */
 declare const EMPTY_CART_STATE: CartState;
 //#endregion
 export { Attribute, CartCost, CartData, CartErrorGroup, CartErrorState, CartLine, CartLineConnection, CartLineCost, CartLineMerchandise, CartNetworkEntry, CartPending, CartState, CartUserError, CartWarning, DiscountCode, EMPTY_CART_DATA, EMPTY_CART_STATE, createEmptyCartErrors, createEmptyErrorGroup };

package/dist/core/cart/state.mjs

@@ -8,14 +8,26 @@ function createEmptyPending() {
 		cost: false
 	};
 }
-/** Creates an empty {@link CartErrorGroup} — no user errors, no warnings. */
+/**
+* Creates an empty error group with no user errors and no warnings.
+*
+* @returns A new error group with empty user error and warning arrays.
+* @publicDocs
+*/
 function createEmptyErrorGroup() {
 	return {
 		userErrors: [],
 		warnings: []
 	};
 }
-/** Creates an empty {@link CartErrorState} — all timestamps at `0`, all buckets empty. */
+/**
+* Creates a cart error state with no errors and every timestamp at `0`.
+*
+* Each call returns new groups, maps, and arrays.
+*
+* @returns A new, empty error state.
+* @publicDocs
+*/
 function createEmptyCartErrors() {
 	return {
 		cart: createEmptyErrorGroup(),
@@ -34,8 +46,10 @@ function createEmptyCartErrors() {
 	};
 }
 /**
-* Frozen {@link CartData} representing an empty cart — `id: null`, zero quantities,
-* zero-amount costs. Used as the initial/fallback value before the first server response.
+* Frozen cart data for an empty cart, with a `null` ID, zero quantities, and
+* zero-amount costs. A cart store without initial data starts from this cart.
+*
+* @publicDocs
 */
 const EMPTY_CART_DATA = Object.freeze({
 	id: null,
@@ -68,7 +82,7 @@ function createCartState(data, { loading = false } = {}) {
 		errors: createEmptyCartErrors()
 	};
 }
-/** Creates an empty {@link CartState} backed by {@link EMPTY_CART_DATA}. Defaults to `loading: true`. */
+/** Creates an empty cart state backed by the empty cart data. Loading defaults to `true`. */
 function createEmptyCartState({ loading = true } = {}) {
 	return createCartState({
 		...EMPTY_CART_DATA,
@@ -76,7 +90,11 @@ function createEmptyCartState({ loading = true } = {}) {
 		discountCodes: []
 	}, { loading });
 }
-/** Shared empty {@link CartState} — backed by {@link EMPTY_CART_DATA}, defaults to `loading: true`. */
+/**
+* Shared empty cart state backed by the empty cart data, with loading set to `true`.
+*
+* @publicDocs
+*/
 const EMPTY_CART_STATE = createEmptyCartState();
 
 //#endregion

package/dist/core/cart/state.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"state.mjs","names":[],"sources":["../../../src/core/cart/state.ts"],"sourcesContent":["import type { CartErrorCode, CartWarningCode } from \"../../graphql/generated/storefront-api-types\";\n\n/** Storefront API monetary value — an amount string and ISO 4217 currency code. */\nexport interface Money {\n  /** Decimal amount as a string (e.g. `\"29.99\"`). */\n  amount: string;\n  /** ISO 4217 currency code (e.g. `\"USD\"`, `\"EUR\"`). */\n  currencyCode: string;\n}\n\n/** Cart-level cost breakdown returned by the Storefront API. */\nexport interface CartCost {\n  /** The amount, before taxes and cart-level discounts, for the customer to pay. */\n  subtotalAmount: Money;\n  /** Final amount the buyer pays at checkout. */\n  totalAmount: Money;\n  /** Estimated amount due at checkout, excluding deferred payments. Equals the subtotal when no deferred payments exist. */\n  checkoutChargeAmount: Money;\n}\n\nexport interface CartLineCost {\n  /** Line total after all applicable discounts. */\n  totalAmount: Money;\n  /** Line subtotal before line-level discounts. */\n  subtotalAmount: Money;\n  /** Unit price for a single quantity of this line. */\n  amountPerQuantity: Money;\n  /** Original compare-at unit price, or `null` when no comparison exists. */\n  compareAtAmountPerQuantity: Money | null;\n}\n\n/** Product variant information attached to a {@link CartLine}. */\nexport interface CartLineMerchandise {\n  /** Storefront API GID of the product variant. */\n  id: string;\n  /** Variant title (e.g. `\"Small / Black\"`). */\n  title?: string;\n  /** Selected variant option name/value pairs (e.g. `{ name: \"Size\", value: \"S\" }`). */\n  selectedOptions?: Array<{ name: string; value: string }>;\n  product: {\n    title: string;\n    handle?: string;\n    [key: string]: unknown;\n  };\n  image?: {\n    id?: string | null;\n    url: string;\n    altText?: string | null;\n    width?: number | null;\n    height?: number | null;\n    [key: string]: unknown;\n  } | null;\n  quantityAvailable?: number | null;\n  [key: string]: unknown;\n}\n\n/**\n * A single line item in the cart.\n *\n * Each line represents a product variant at a given quantity. Lines may carry\n * custom {@link Attribute | attributes}, a selling plan allocation (subscriptions),\n * or nested {@link CartLine.lineComponents | line components} (bundles).\n */\nexport interface CartLine {\n  /** Storefront API GID of this cart line — used as the key in {@link CartPending.lines}. */\n  id: string;\n  /** Number of units of this merchandise in the cart. */\n  quantity: number;\n  attributes?: Attribute[];\n  /** Per-line cost breakdown from the Storefront API. */\n  cost: CartLineCost;\n  /** The product variant this line represents. */\n  merchandise?: CartLineMerchandise;\n  /** Subscription selling plan allocation, or `null` for one-time purchases. */\n  sellingPlanAllocation?: { sellingPlan: { id: string } } | null;\n  parentRelationship?: { parent: { id: string } } | null;\n  /** Nested child lines when this line is a bundle parent. */\n  lineComponents?: CartLine[];\n}\n\nexport interface CartLineConnection {\n  nodes: CartLine[];\n  [key: string]: unknown;\n}\n\n/** A discount code applied to the cart. */\nexport interface DiscountCode {\n  code: string;\n  /** Whether the code is applicable to the cart's current contents. Set optimistically to `false` for newly added codes until the server confirms. */\n  applicable: boolean;\n}\n\n/** A validation error returned by a Storefront API cart mutation. */\nexport interface CartUserError {\n  /** Machine-readable error code, or `null` for unclassified errors. */\n  code: CartErrorCode | null;\n  message: string;\n  /** JSONPath to the input field that caused the error (e.g. `[\"lines\", \"0\", \"quantity\"]`). */\n  field?: string[];\n}\n\n/** A non-blocking warning returned by a Storefront API cart mutation. */\nexport interface CartWarning {\n  code: CartWarningCode;\n  message: string;\n}\n\n/** Errors and warnings from a single cart mutation response. */\nexport interface CartErrorGroup {\n  userErrors: CartUserError[];\n  warnings: CartWarning[];\n}\n\n/** A network-level error encountered during a cart operation (e.g. non-2xx response, timeout). Aborted requests are not recorded. */\nexport interface CartNetworkEntry {\n  message: string;\n  /** HTTP status code when available. */\n  status?: number;\n}\n\n/** A key-value pair attached to the cart or to an individual {@link CartLine}. */\nexport interface Attribute {\n  key: string;\n  value: string | null;\n}\n\n/**\n * Tracks which parts of the cart have in-flight mutations.\n *\n * `lines` and `discountCodes` are `Set<string>` keyed by line ID / discount code,\n * enabling per-item pending indicators rather than a single global spinner.\n * `cost` is a boolean because *any* line or discount change affects the total —\n * use it to show pending UI on price displays without computing optimistic amounts.\n *\n * @example\n * ```ts\n * const { pending } = store.getState();\n *\n * // Per-line-item pending indicator\n * if (pending.lines.has(lineId)) {\n *   showSpinner(lineId);\n * }\n *\n * // Cart total is stale — show pending UI, don't compute a price\n * if (pending.cost) {\n *   dimTotalDisplay();\n * }\n * ```\n */\nexport interface CartPending {\n  /** Line IDs with in-flight add, quantity, or remove mutations. New lines use their `optimistic:` ID until the server confirms. */\n  lines: Set<string>;\n  note: boolean;\n  attributes: boolean;\n  /** Discount codes with in-flight apply/remove mutations. */\n  discountCodes: Set<string>;\n  /** `true` when any mutation may affect cart pricing — show pending UI on cost displays. */\n  cost?: boolean;\n}\n\n/**\n * Per-resource error tracking for the cart.\n *\n * Errors are bucketed by the resource they affect — `lines`, `note`, `attributes`,\n * `discountCodes`, or `cart` (for cross-cutting errors). Each bucket carries a\n * `*UpdatedAt` timestamp (ms since epoch) so the UI can show stale-error indicators\n * or auto-dismiss after a timeout.\n *\n * `network` collects transport-level failures (timeouts, 5xx) separately from\n * Storefront API user errors.\n */\nexport interface CartErrorState {\n  /** Cross-cutting cart errors not attributable to a specific resource. */\n  cart: CartErrorGroup;\n  /** Errors keyed by {@link CartLine.id}. */\n  lines: Map<string, CartErrorGroup>;\n  note: CartErrorGroup;\n  /** Errors keyed by {@link Attribute.key}. */\n  attributes: Map<string, CartErrorGroup>;\n  /** Errors keyed by discount code string. */\n  discountCodes: Map<string, CartErrorGroup>;\n  network: CartNetworkEntry[];\n  lastUpdatedAt: number;\n  cartUpdatedAt: number;\n  linesUpdatedAt: number;\n  noteUpdatedAt: number;\n  attributesUpdatedAt: number;\n  discountCodesUpdatedAt: number;\n  networkUpdatedAt: number;\n}\n\n/**\n * Cart data returned by the Storefront API.\n *\n * This is the server's authoritative snapshot — prices, discount applicability,\n * and totals come exclusively from here, never from client-side computation.\n * The index signature allows custom cart query fields to pass through.\n */\nexport interface CartData {\n  /** Storefront API Cart GID, or `null` when no cart exists yet. */\n  id: string | null;\n  /** `Cart.updatedAt` (ISO 8601). Absent until the first server response. */\n  updatedAt?: string;\n  /** Shopify checkout URL. Changes when buyer identity or consent state changes. */\n  checkoutUrl?: string | null;\n  /** Sum of all line quantities. */\n  totalQuantity: number;\n  /** Cart-level cost breakdown (subtotal, total, checkout charge). */\n  cost: CartCost;\n  /** Buyer-supplied cart note, or `null`/empty when unset. */\n  note?: string | null;\n  /** Cart-level custom attributes. */\n  attributes: Attribute[];\n  /** The cart's line items. */\n  lines: CartLineConnection;\n  /** Discount codes applied to the cart, with their applicability. */\n  discountCodes: DiscountCode[];\n  [key: string]: unknown;\n}\n\n/**\n * Full observable state of the cart store.\n *\n * Framework adapters subscribe to this via `CartStore.subscribe` (or the\n * framework-specific hooks like `useCart`). The generic `TData` parameter\n * flows from your server handler configuration, so `data` is typed to match\n * your custom cart query.\n *\n * @example\n * ```ts\n * const state = store.getState();\n *\n * if (state.loading) {\n *   // Initial cart load in progress — show skeleton\n * }\n *\n * if (state.pending.lines.size > 0) {\n *   // One or more lines are mid-mutation — show per-line spinners\n * }\n *\n * if (state.errors.network.length > 0) {\n *   // Network errors occurred — show retry prompt\n * }\n * ```\n */\nexport interface CartState<TData extends CartData = CartData> {\n  /** The latest server-confirmed cart data, with optimistic projections applied on top. */\n  data: TData;\n  /** `true` during a full-cart fetch — initial load, after `reset()`, or before connect with no `initialData`. */\n  loading: boolean;\n  /** Non-rejecting signal that resolves when the current full-cart load settles or is invalidated. */\n  readonly readyPromise?: PromiseLike<void>;\n  /** Per-resource in-flight mutation tracking. */\n  pending: CartPending;\n  /** `true` when a background revalidation is in flight (triggered by overlapping mutations or `refresh()`). */\n  revalidating?: boolean;\n  /** Per-resource error and warning state. */\n  errors: CartErrorState;\n}\n\nexport function createEmptyPending(): CartPending {\n  return {\n    lines: new Set(),\n    note: false,\n    attributes: false,\n    discountCodes: new Set(),\n    cost: false,\n  };\n}\n\n/** Creates an empty {@link CartErrorGroup} — no user errors, no warnings. */\nexport function createEmptyErrorGroup(): CartErrorGroup {\n  return { userErrors: [], warnings: [] };\n}\n\n/** Creates an empty {@link CartErrorState} — all timestamps at `0`, all buckets empty. */\nexport function createEmptyCartErrors(): CartErrorState {\n  return {\n    cart: createEmptyErrorGroup(),\n    lines: new Map(),\n    note: createEmptyErrorGroup(),\n    attributes: new Map(),\n    discountCodes: new Map(),\n    network: [],\n    lastUpdatedAt: 0,\n    cartUpdatedAt: 0,\n    linesUpdatedAt: 0,\n    noteUpdatedAt: 0,\n    attributesUpdatedAt: 0,\n    discountCodesUpdatedAt: 0,\n    networkUpdatedAt: 0,\n  };\n}\n\n/**\n * Frozen {@link CartData} representing an empty cart — `id: null`, zero quantities,\n * zero-amount costs. Used as the initial/fallback value before the first server response.\n */\nexport const EMPTY_CART_DATA: CartData = Object.freeze({\n  id: null,\n  checkoutUrl: null,\n  totalQuantity: 0,\n  cost: Object.freeze({\n    subtotalAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n    totalAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n    checkoutChargeAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n  }),\n  note: \"\",\n  attributes: [] as Attribute[],\n  lines: Object.freeze({ nodes: [] as CartLine[] }),\n  discountCodes: [] as DiscountCode[],\n});\n\nexport function createCartState<TData extends CartData>(\n  data: TData,\n  { loading = false }: { loading?: boolean } = {},\n): CartState<TData> {\n  return {\n    data,\n    loading,\n    pending: createEmptyPending(),\n    errors: createEmptyCartErrors(),\n  };\n}\n\n/** Creates an empty {@link CartState} backed by {@link EMPTY_CART_DATA}. Defaults to `loading: true`. */\nexport function createEmptyCartState({ loading = true }: { loading?: boolean } = {}): CartState {\n  return createCartState(\n    {\n      ...EMPTY_CART_DATA,\n      lines: { nodes: [] },\n      discountCodes: [],\n    },\n    { loading },\n  );\n}\n\n/** Shared empty {@link CartState} — backed by {@link EMPTY_CART_DATA}, defaults to `loading: true`. */\nexport const EMPTY_CART_STATE: CartState = createEmptyCartState();\n"],"mappings":";AAoQA,SAAgB,qBAAkC;AAChD,QAAO;EACL,uBAAO,IAAI,KAAK;EAChB,MAAM;EACN,YAAY;EACZ,+BAAe,IAAI,KAAK;EACxB,MAAM;EACP;;;AAIH,SAAgB,wBAAwC;AACtD,QAAO;EAAE,YAAY,EAAE;EAAE,UAAU,EAAE;EAAE;;;AAIzC,SAAgB,wBAAwC;AACtD,QAAO;EACL,MAAM,uBAAuB;EAC7B,uBAAO,IAAI,KAAK;EAChB,MAAM,uBAAuB;EAC7B,4BAAY,IAAI,KAAK;EACrB,+BAAe,IAAI,KAAK;EACxB,SAAS,EAAE;EACX,eAAe;EACf,eAAe;EACf,gBAAgB;EAChB,eAAe;EACf,qBAAqB;EACrB,wBAAwB;EACxB,kBAAkB;EACnB;;;;;;AAOH,MAAa,kBAA4B,OAAO,OAAO;CACrD,IAAI;CACJ,aAAa;CACb,eAAe;CACf,MAAM,OAAO,OAAO;EAClB,gBAAgB,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EAChE,aAAa,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EAC7D,sBAAsB,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EACvE,CAAC;CACF,MAAM;CACN,YAAY,EAAE;CACd,OAAO,OAAO,OAAO,EAAE,OAAO,EAAE,EAAgB,CAAC;CACjD,eAAe,EAAE;CAClB,CAAC;AAEF,SAAgB,gBACd,MACA,EAAE,UAAU,UAAiC,EAAE,EAC7B;AAClB,QAAO;EACL;EACA;EACA,SAAS,oBAAoB;EAC7B,QAAQ,uBAAuB;EAChC;;;AAIH,SAAgB,qBAAqB,EAAE,UAAU,SAAgC,EAAE,EAAa;AAC9F,QAAO,gBACL;EACE,GAAG;EACH,OAAO,EAAE,OAAO,EAAE,EAAE;EACpB,eAAe,EAAE;EAClB,EACD,EAAE,SAAS,CACZ;;;AAIH,MAAa,mBAA8B,sBAAsB"}
+{"version":3,"file":"state.mjs","names":[],"sources":["../../../src/core/cart/state.ts"],"sourcesContent":["import type { CartErrorCode, CartWarningCode } from \"../../graphql/generated/storefront-api-types\";\n\n/** A monetary value from the Storefront API. */\nexport interface Money {\n  /** The decimal amount as a string, such as `29.99`. */\n  amount: string;\n  /** The ISO 4217 currency code, such as `USD`. */\n  currencyCode: string;\n}\n\n/** The cart's costs from the Storefront API. */\nexport interface CartCost {\n  /** The amount, before taxes and cart-level discounts, for the customer to pay. */\n  subtotalAmount: Money;\n  /** Final amount the customer pays at checkout. */\n  totalAmount: Money;\n  /** Estimated amount due at checkout, excluding deferred payments. Equals the subtotal when no deferred payments exist. */\n  checkoutChargeAmount: Money;\n}\n\n/** A cart line's costs from the Storefront API. */\nexport interface CartLineCost {\n  /** Line total after all applicable discounts. */\n  totalAmount: Money;\n  /** Line subtotal before line-level discounts. */\n  subtotalAmount: Money;\n  /** Unit price for a single quantity of this line. */\n  amountPerQuantity: Money;\n  /** Original compare-at unit price, or `null` when no comparison exists. */\n  compareAtAmountPerQuantity: Money | null;\n}\n\n/** The product variant on a cart line. */\nexport interface CartLineMerchandise {\n  /** Storefront API GID of the product variant. */\n  id: string;\n  /** The variant title, such as `\"Small / Black\"`. */\n  title?: string;\n  /** The variant's selected options as name and value pairs. */\n  selectedOptions?: Array<{ name: string; value: string }>;\n  /** The product that the variant belongs to. */\n  product: {\n    title: string;\n    handle?: string;\n    [key: string]: unknown;\n  };\n  /** The variant image that the cart query selects. */\n  image?: {\n    id?: string | null;\n    url: string;\n    altText?: string | null;\n    width?: number | null;\n    height?: number | null;\n    [key: string]: unknown;\n  } | null;\n  /** Units available for sale. When your cart fragment selects the field, the store caps the quantity of a `set` submission at this number. */\n  quantityAvailable?: number | null;\n  /** Extra variant fields from your custom cart fragment, unchanged. */\n  [key: string]: unknown;\n}\n\n/**\n * A single line item in the cart.\n *\n * Each line holds a product variant at a quantity. A line can carry custom\n * attributes, a selling plan allocation for a subscription, or line components\n * for a bundle.\n */\nexport interface CartLine {\n  /** The cart line's Storefront API GID. Look up the line's pending state and errors with this ID. */\n  id: string;\n  /** Number of units of this merchandise in the cart. */\n  quantity: number;\n  /** Custom key-value attributes attached to the line. */\n  attributes?: Attribute[];\n  /** Per-line cost breakdown from the Storefront API. */\n  cost: CartLineCost;\n  /** The product variant on the line. */\n  merchandise?: CartLineMerchandise;\n  /** Subscription selling plan allocation, or `null` for one-time purchases. */\n  sellingPlanAllocation?: { sellingPlan: { id: string } } | null;\n  /** The parent line's ID when this line is a bundle component. */\n  parentRelationship?: { parent: { id: string } } | null;\n  /** Nested child lines when this line is a bundle parent. */\n  lineComponents?: CartLine[];\n}\n\n/** The cart's line items in the Storefront API connection shape. */\nexport interface CartLineConnection {\n  /** The cart lines that the cart query returns. */\n  nodes: CartLine[];\n  /** Extra connection fields from your custom cart fragment, unchanged. */\n  [key: string]: unknown;\n}\n\n/** A discount code applied to the cart. */\nexport interface DiscountCode {\n  /** The discount code text. Look up the code's pending state and errors with this value. */\n  code: string;\n  /** Whether the code applies to the cart's current contents. A new code reads `false` until the server responds. */\n  applicable: boolean;\n}\n\n/** A validation error returned by a Storefront API cart mutation. */\nexport interface CartUserError {\n  /** Machine-readable error code, or `null` for unclassified errors. */\n  code: CartErrorCode | null;\n  /** Human-readable error text from the Storefront API. */\n  message: string;\n  /** The path to the input field that caused the error, such as `[\"lines\", \"0\", \"quantity\"]`. */\n  field?: string[];\n}\n\n/** A non-blocking warning returned by a Storefront API cart mutation. */\nexport interface CartWarning {\n  /** The warning code from the Storefront API. */\n  code: CartWarningCode;\n  /** Human-readable warning text from the Storefront API. */\n  message: string;\n}\n\n/** Errors and warnings from one cart change. */\nexport interface CartErrorGroup {\n  /** Validation errors that the mutation returned. */\n  userErrors: CartUserError[];\n  /** Non-blocking warnings that the mutation returned. */\n  warnings: CartWarning[];\n}\n\n/**\n * A failed cart request, such as a non-2xx response or a timeout. Canceled requests add no entry.\n */\nexport interface CartNetworkEntry {\n  /** The error message, or a generic message when the failure has no message of its own. */\n  message: string;\n  /** The HTTP status code, when the endpoint returned a non-2xx response. */\n  status?: number;\n}\n\n/** A key-value pair attached to the cart or to an individual cart line. */\nexport interface Attribute {\n  /** The attribute name. Look up the attribute's errors with this name. */\n  key: string;\n  /** The attribute value. */\n  value: string | null;\n}\n\n/**\n * Shows which parts of the cart have changes in flight.\n *\n * Check a line ID or a discount code to show a pending indicator on that item.\n * Check `cost` to show pending UI on prices, which update only when the server\n * responds.\n *\n * @example\n * ```ts\n * const { pending } = store.getState();\n *\n * // Per-line-item pending indicator\n * if (pending.lines.has(lineId)) {\n *   showSpinner(lineId);\n * }\n *\n * // Cart total is stale — show pending UI, don't compute a price\n * if (pending.cost) {\n *   dimTotalDisplay();\n * }\n * ```\n */\nexport interface CartPending {\n  /** Line IDs with an add, quantity change, or removal in flight. A new line has an ID that starts with `optimistic:` until the server confirms the line. */\n  lines: Set<string>;\n  /** `true` while a note update is in flight. */\n  note: boolean;\n  /** `true` while an attribute update is in flight. */\n  attributes: boolean;\n  /** Discount codes with an apply or remove in flight. */\n  discountCodes: Set<string>;\n  /** `true` while a change that can affect cart prices is in flight. */\n  cost?: boolean;\n}\n\n/**\n * The cart's errors, grouped by the part of the cart that they affect: lines, the note,\n * attributes, discount codes, or the cart as a whole. Each group has a timestamp in\n * milliseconds since the epoch. Use the timestamps to flag stale errors or dismiss\n * errors after a timeout.\n *\n * Failed requests go in a network list, apart from Storefront API user errors.\n */\nexport interface CartErrorState {\n  /** Errors that don't belong to a line, the note, an attribute, or a discount code. */\n  cart: CartErrorGroup;\n  /** Errors keyed by cart line ID. */\n  lines: Map<string, CartErrorGroup>;\n  /** Errors for the cart note. */\n  note: CartErrorGroup;\n  /** Errors keyed by attribute name. */\n  attributes: Map<string, CartErrorGroup>;\n  /** Errors keyed by discount code. */\n  discountCodes: Map<string, CartErrorGroup>;\n  /**\n   * Failed cart requests. A failed cart change adds an entry, with an HTTP status when the endpoint returned a non-2xx response. A failed refresh adds an entry with a generic message and no status. A failed first load or a failed load after a reset adds no entry.\n   */\n  network: CartNetworkEntry[];\n  /** Time in milliseconds since the epoch when the store last recorded any error, or `0` before the first. */\n  lastUpdatedAt: number;\n  /** Time in milliseconds since the epoch of the last line, discount code, or attribute error, or `0` before any. */\n  cartUpdatedAt: number;\n  /** Time in milliseconds since the epoch when the store last recorded line errors, or `0` before any. */\n  linesUpdatedAt: number;\n  /** Time in milliseconds since the epoch when the store last recorded note errors, or `0` before any. */\n  noteUpdatedAt: number;\n  /** Time in milliseconds since the epoch when the store last recorded attribute errors, or `0` before any. */\n  attributesUpdatedAt: number;\n  /** Time in milliseconds since the epoch when the store last recorded discount code errors, or `0` before any. */\n  discountCodesUpdatedAt: number;\n  /** Time in milliseconds since the epoch when the store last recorded a network error, or `0` before any. */\n  networkUpdatedAt: number;\n}\n\n/**\n * The customer's cart, in the shape that the Storefront API returns.\n *\n * Cart costs come only from the server. Extra fields from your custom cart\n * fragment appear unchanged.\n */\nexport interface CartData {\n  /** The cart's Storefront API GID, or `null` when no cart exists yet. */\n  id: string | null;\n  /** The cart's last update time in ISO 8601 format. Absent until the first server response. */\n  updatedAt?: string;\n  /** The Shopify checkout URL. The URL can change when the customer logs in or out, or changes tracking consent. */\n  checkoutUrl?: string | null;\n  /** Sum of all line quantities. */\n  totalQuantity: number;\n  /** The cart's subtotal, total, and checkout charge. */\n  cost: CartCost;\n  /** Customer-supplied cart note, or `null` or empty when unset. */\n  note?: string | null;\n  /** Cart-level custom attributes. */\n  attributes: Attribute[];\n  /** The cart's line items. */\n  lines: CartLineConnection;\n  /** Discount codes applied to the cart, with their applicability. */\n  discountCodes: DiscountCode[];\n  /** Extra cart fields from your custom cart fragment, unchanged. */\n  [key: string]: unknown;\n}\n\n/**\n * The cart, plus what's loading, pending, and failed.\n *\n * The cart hooks return values from this state. The data type matches the cart\n * fragment in your cart server handlers.\n *\n * @example\n * ```ts\n * const state = store.getState();\n *\n * if (state.loading) {\n *   // Initial cart load in progress — show skeleton\n * }\n *\n * if (state.pending.lines.size > 0) {\n *   // One or more lines are mid-mutation — show per-line spinners\n * }\n *\n * if (state.errors.network.length > 0) {\n *   // Network errors occurred — show retry prompt\n * }\n * ```\n */\nexport interface CartState<TData extends CartData = CartData> {\n  /** The cart, including changes that the server hasn't confirmed yet. */\n  data: TData;\n  /** `true` while the store loads the full cart: the first load, a load after `reset()`, or before `connect()` when the store has no initial data. */\n  loading: boolean;\n  /** Present while a full cart load runs. The promise resolves, and never rejects, when the load finishes or the store drops the load. */\n  readonly readyPromise?: PromiseLike<void>;\n  /** The parts of the cart with changes in flight. */\n  pending: CartPending;\n  /** `true` while the store reloads the cart in the background after overlapping cart changes or a `refresh()` call. */\n  revalidating?: boolean;\n  /** Errors and warnings, grouped by the part of the cart that they affect. */\n  errors: CartErrorState;\n}\n\nexport function createEmptyPending(): CartPending {\n  return {\n    lines: new Set(),\n    note: false,\n    attributes: false,\n    discountCodes: new Set(),\n    cost: false,\n  };\n}\n\n/**\n * Creates an empty error group with no user errors and no warnings.\n *\n * @returns A new error group with empty user error and warning arrays.\n * @publicDocs\n */\nexport function createEmptyErrorGroup(): CartErrorGroup {\n  return { userErrors: [], warnings: [] };\n}\n\n/**\n * Creates a cart error state with no errors and every timestamp at `0`.\n *\n * Each call returns new groups, maps, and arrays.\n *\n * @returns A new, empty error state.\n * @publicDocs\n */\nexport function createEmptyCartErrors(): CartErrorState {\n  return {\n    cart: createEmptyErrorGroup(),\n    lines: new Map(),\n    note: createEmptyErrorGroup(),\n    attributes: new Map(),\n    discountCodes: new Map(),\n    network: [],\n    lastUpdatedAt: 0,\n    cartUpdatedAt: 0,\n    linesUpdatedAt: 0,\n    noteUpdatedAt: 0,\n    attributesUpdatedAt: 0,\n    discountCodesUpdatedAt: 0,\n    networkUpdatedAt: 0,\n  };\n}\n\n/**\n * Frozen cart data for an empty cart, with a `null` ID, zero quantities, and\n * zero-amount costs. A cart store without initial data starts from this cart.\n *\n * @publicDocs\n */\nexport const EMPTY_CART_DATA: CartData = Object.freeze({\n  id: null,\n  checkoutUrl: null,\n  totalQuantity: 0,\n  cost: Object.freeze({\n    subtotalAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n    totalAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n    checkoutChargeAmount: Object.freeze({ amount: \"0\", currencyCode: \"\" }),\n  }),\n  note: \"\",\n  attributes: [] as Attribute[],\n  lines: Object.freeze({ nodes: [] as CartLine[] }),\n  discountCodes: [] as DiscountCode[],\n});\n\nexport function createCartState<TData extends CartData>(\n  data: TData,\n  { loading = false }: { loading?: boolean } = {},\n): CartState<TData> {\n  return {\n    data,\n    loading,\n    pending: createEmptyPending(),\n    errors: createEmptyCartErrors(),\n  };\n}\n\n/** Creates an empty cart state backed by the empty cart data. Loading defaults to `true`. */\nexport function createEmptyCartState({ loading = true }: { loading?: boolean } = {}): CartState {\n  return createCartState(\n    {\n      ...EMPTY_CART_DATA,\n      lines: { nodes: [] },\n      discountCodes: [],\n    },\n    { loading },\n  );\n}\n\n/**\n * Shared empty cart state backed by the empty cart data, with loading set to `true`.\n *\n * @publicDocs\n */\nexport const EMPTY_CART_STATE: CartState = createEmptyCartState();\n"],"mappings":";AAgSA,SAAgB,qBAAkC;AAChD,QAAO;EACL,uBAAO,IAAI,KAAK;EAChB,MAAM;EACN,YAAY;EACZ,+BAAe,IAAI,KAAK;EACxB,MAAM;EACP;;;;;;;;AASH,SAAgB,wBAAwC;AACtD,QAAO;EAAE,YAAY,EAAE;EAAE,UAAU,EAAE;EAAE;;;;;;;;;;AAWzC,SAAgB,wBAAwC;AACtD,QAAO;EACL,MAAM,uBAAuB;EAC7B,uBAAO,IAAI,KAAK;EAChB,MAAM,uBAAuB;EAC7B,4BAAY,IAAI,KAAK;EACrB,+BAAe,IAAI,KAAK;EACxB,SAAS,EAAE;EACX,eAAe;EACf,eAAe;EACf,gBAAgB;EAChB,eAAe;EACf,qBAAqB;EACrB,wBAAwB;EACxB,kBAAkB;EACnB;;;;;;;;AASH,MAAa,kBAA4B,OAAO,OAAO;CACrD,IAAI;CACJ,aAAa;CACb,eAAe;CACf,MAAM,OAAO,OAAO;EAClB,gBAAgB,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EAChE,aAAa,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EAC7D,sBAAsB,OAAO,OAAO;GAAE,QAAQ;GAAK,cAAc;GAAI,CAAC;EACvE,CAAC;CACF,MAAM;CACN,YAAY,EAAE;CACd,OAAO,OAAO,OAAO,EAAE,OAAO,EAAE,EAAgB,CAAC;CACjD,eAAe,EAAE;CAClB,CAAC;AAEF,SAAgB,gBACd,MACA,EAAE,UAAU,UAAiC,EAAE,EAC7B;AAClB,QAAO;EACL;EACA;EACA,SAAS,oBAAoB;EAC7B,QAAQ,uBAAuB;EAChC;;;AAIH,SAAgB,qBAAqB,EAAE,UAAU,SAAgC,EAAE,EAAa;AAC9F,QAAO,gBACL;EACE,GAAG;EACH,OAAO,EAAE,OAAO,EAAE,EAAE;EACpB,eAAe,EAAE;EAClB,EACD,EAAE,SAAS,CACZ;;;;;;;AAQH,MAAa,mBAA8B,sBAAsB"}