@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

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

@@ -1,11 +1,14 @@
 //#region src/core/cart/cookie.d.ts
 /**
- * Serializes a cart GID into a `Set-Cookie` header value.
+ * Creates the `Set-Cookie` header value that stores the cart ID in the `cart` cookie.
  *
- * Strips the `gid://shopify/Cart/` prefix before encoding — the cookie stores
- * only the opaque suffix to keep the header compact. The cookie is set with
- * `Path=/; SameSite=Lax` and a 14-day `Max-Age`.
+ * The cookie holds the cart token without the `gid://shopify/Cart/` prefix and expires
+ * after 14 days. The cookie sets `Path=/` and `SameSite=Lax`, and leaves out `HttpOnly`
+ * and `Secure`. Append the value to the response headers to keep the response's
+ * other cookies.
  *
+ * @param cartId The cart GID or cart token to store.
+ * @returns The header value that sets the `cart` cookie.
  * @example
  * ```ts
  * const cookie = createCartCookie("gid://shopify/Cart/abc123");
@@ -13,6 +16,7 @@
  *
  * headers.append("Set-Cookie", cookie);
  * ```
+ * @publicDocs
  */
 declare function createCartCookie(cartId: string): string;
 //#endregion

package/dist/development/core/cart/cookie.mjs

@@ -16,12 +16,15 @@ function getCartIdFromCookie(input) {
 	return normalizeCartId(token);
 }
 /**
-* Serializes a cart GID into a `Set-Cookie` header value.
+* Creates the `Set-Cookie` header value that stores the cart ID in the `cart` cookie.
 *
-* Strips the `gid://shopify/Cart/` prefix before encoding — the cookie stores
-* only the opaque suffix to keep the header compact. The cookie is set with
-* `Path=/; SameSite=Lax` and a 14-day `Max-Age`.
+* The cookie holds the cart token without the `gid://shopify/Cart/` prefix and expires
+* after 14 days. The cookie sets `Path=/` and `SameSite=Lax`, and leaves out `HttpOnly`
+* and `Secure`. Append the value to the response headers to keep the response's
+* other cookies.
 *
+* @param cartId The cart GID or cart token to store.
+* @returns The header value that sets the `cart` cookie.
 * @example
 * ```ts
 * const cookie = createCartCookie("gid://shopify/Cart/abc123");
@@ -29,6 +32,7 @@ function getCartIdFromCookie(input) {
 *
 * headers.append("Set-Cookie", cookie);
 * ```
+* @publicDocs
 */
 function createCartCookie(cartId) {
 	const token = cartId.startsWith(CART_GID_PREFIX) ? cartId.slice(19) : cartId;

package/dist/development/core/cart/cookie.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cookie.mjs","names":[],"sources":["../../../../src/core/cart/cookie.ts"],"sourcesContent":["const COOKIE_NAME = \"cart\";\nconst MAX_AGE_IN_SECONDS = 1209600; // 14 days\nconst CART_GID_PREFIX = \"gid://shopify/Cart/\";\n\ntype CartCookieSource = Request | { cookie?: string };\n\nexport function normalizeCartId(cartId: string | null | undefined): string | null {\n  if (!cartId) return null;\n  return cartId.startsWith(CART_GID_PREFIX) ? cartId : CART_GID_PREFIX + cartId;\n}\n\nexport function getCartIdFromCookie(input: CartCookieSource): string | null {\n  const header = input instanceof Request ? input.headers.get(\"cookie\") : input.cookie;\n  if (!header) return null;\n\n  const match = header.match(new RegExp(`(?:^|;\\\\s*)${COOKIE_NAME}=([^;]*)`));\n  if (!match || !match[1]) return null;\n\n  const token = decodeURIComponent(match[1]);\n  if (!token) return null;\n\n  return normalizeCartId(token);\n}\n\n/**\n * Serializes a cart GID into a `Set-Cookie` header value.\n *\n * Strips the `gid://shopify/Cart/` prefix before encoding — the cookie stores\n * only the opaque suffix to keep the header compact. The cookie is set with\n * `Path=/; SameSite=Lax` and a 14-day `Max-Age`.\n *\n * @example\n * ```ts\n * const cookie = createCartCookie(\"gid://shopify/Cart/abc123\");\n * // \"cart=abc123; Path=/; SameSite=Lax; Max-Age=1209600\"\n *\n * headers.append(\"Set-Cookie\", cookie);\n * ```\n */\nexport function createCartCookie(cartId: string): string {\n  const token = cartId.startsWith(CART_GID_PREFIX) ? cartId.slice(CART_GID_PREFIX.length) : cartId;\n  const encoded = encodeURIComponent(token);\n  return `${COOKIE_NAME}=${encoded}; Path=/; SameSite=Lax; Max-Age=${MAX_AGE_IN_SECONDS}`;\n}\n\nexport function createExpiredCartCookie(): string {\n  return `${COOKIE_NAME}=; Path=/; SameSite=Lax; Max-Age=0`;\n}\n"],"mappings":";AAAA,MAAM,cAAc;AACpB,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AAIxB,SAAgB,gBAAgB,QAAkD;AAChF,KAAI,CAAC,OAAQ,QAAO;AACpB,QAAO,OAAO,WAAW,gBAAgB,GAAG,SAAS,kBAAkB;;AAGzE,SAAgB,oBAAoB,OAAwC;CAC1E,MAAM,SAAS,iBAAiB,UAAU,MAAM,QAAQ,IAAI,SAAS,GAAG,MAAM;AAC9E,KAAI,CAAC,OAAQ,QAAO;CAEpB,MAAM,QAAQ,OAAO,MAAM,IAAI,OAAO,cAAc,YAAY,UAAU,CAAC;AAC3E,KAAI,CAAC,SAAS,CAAC,MAAM,GAAI,QAAO;CAEhC,MAAM,QAAQ,mBAAmB,MAAM,GAAG;AAC1C,KAAI,CAAC,MAAO,QAAO;AAEnB,QAAO,gBAAgB,MAAM;;;;;;;;;;;;;;;;;AAkB/B,SAAgB,iBAAiB,QAAwB;CACvD,MAAM,QAAQ,OAAO,WAAW,gBAAgB,GAAG,OAAO,MAAM,GAAuB,GAAG;AAE1F,QAAO,GAAG,YAAY,GADN,mBAAmB,MACH,CAAC,kCAAkC;;AAGrE,SAAgB,0BAAkC;AAChD,QAAO,GAAG,YAAY"}
+{"version":3,"file":"cookie.mjs","names":[],"sources":["../../../../src/core/cart/cookie.ts"],"sourcesContent":["const COOKIE_NAME = \"cart\";\nconst MAX_AGE_IN_SECONDS = 1209600; // 14 days\nconst CART_GID_PREFIX = \"gid://shopify/Cart/\";\n\ntype CartCookieSource = Request | { cookie?: string };\n\nexport function normalizeCartId(cartId: string | null | undefined): string | null {\n  if (!cartId) return null;\n  return cartId.startsWith(CART_GID_PREFIX) ? cartId : CART_GID_PREFIX + cartId;\n}\n\nexport function getCartIdFromCookie(input: CartCookieSource): string | null {\n  const header = input instanceof Request ? input.headers.get(\"cookie\") : input.cookie;\n  if (!header) return null;\n\n  const match = header.match(new RegExp(`(?:^|;\\\\s*)${COOKIE_NAME}=([^;]*)`));\n  if (!match || !match[1]) return null;\n\n  const token = decodeURIComponent(match[1]);\n  if (!token) return null;\n\n  return normalizeCartId(token);\n}\n\n/**\n * Creates the `Set-Cookie` header value that stores the cart ID in the `cart` cookie.\n *\n * The cookie holds the cart token without the `gid://shopify/Cart/` prefix and expires\n * after 14 days. The cookie sets `Path=/` and `SameSite=Lax`, and leaves out `HttpOnly`\n * and `Secure`. Append the value to the response headers to keep the response's\n * other cookies.\n *\n * @param cartId The cart GID or cart token to store.\n * @returns The header value that sets the `cart` cookie.\n * @example\n * ```ts\n * const cookie = createCartCookie(\"gid://shopify/Cart/abc123\");\n * // \"cart=abc123; Path=/; SameSite=Lax; Max-Age=1209600\"\n *\n * headers.append(\"Set-Cookie\", cookie);\n * ```\n * @publicDocs\n */\nexport function createCartCookie(cartId: string): string {\n  const token = cartId.startsWith(CART_GID_PREFIX) ? cartId.slice(CART_GID_PREFIX.length) : cartId;\n  const encoded = encodeURIComponent(token);\n  return `${COOKIE_NAME}=${encoded}; Path=/; SameSite=Lax; Max-Age=${MAX_AGE_IN_SECONDS}`;\n}\n\nexport function createExpiredCartCookie(): string {\n  return `${COOKIE_NAME}=; Path=/; SameSite=Lax; Max-Age=0`;\n}\n"],"mappings":";AAAA,MAAM,cAAc;AACpB,MAAM,qBAAqB;AAC3B,MAAM,kBAAkB;AAIxB,SAAgB,gBAAgB,QAAkD;AAChF,KAAI,CAAC,OAAQ,QAAO;AACpB,QAAO,OAAO,WAAW,gBAAgB,GAAG,SAAS,kBAAkB;;AAGzE,SAAgB,oBAAoB,OAAwC;CAC1E,MAAM,SAAS,iBAAiB,UAAU,MAAM,QAAQ,IAAI,SAAS,GAAG,MAAM;AAC9E,KAAI,CAAC,OAAQ,QAAO;CAEpB,MAAM,QAAQ,OAAO,MAAM,IAAI,OAAO,cAAc,YAAY,UAAU,CAAC;AAC3E,KAAI,CAAC,SAAS,CAAC,MAAM,GAAI,QAAO;CAEhC,MAAM,QAAQ,mBAAmB,MAAM,GAAG;AAC1C,KAAI,CAAC,MAAO,QAAO;AAEnB,QAAO,gBAAgB,MAAM;;;;;;;;;;;;;;;;;;;;;AAsB/B,SAAgB,iBAAiB,QAAwB;CACvD,MAAM,QAAQ,OAAO,WAAW,gBAAgB,GAAG,OAAO,MAAM,GAAuB,GAAG;AAE1F,QAAO,GAAG,YAAY,GADN,mBAAmB,MACH,CAAC,kCAAkC;;AAGrE,SAAgB,0BAAkC;AAChD,QAAO,GAAG,YAAY"}

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

@@ -1,43 +1,55 @@
 //#region src/core/cart/form.d.ts
 /**
- * HTML attributes for a hidden submit button that triggers the `"set"` intent.
+ * HTML attributes for the hidden submit button that sets a line to the quantity in the form's quantity input.
  *
- * Used by {@link CartFormRegister} when `register("set")` is called. The button
- * must be the first submit button in the form for `attachQuantityInput`
- * to auto-submit on quantity changes.
+ * `register("set")` returns the attributes. Make the set button the form's first submit button. A quantity input submits on change only when the set button comes first.
+ *
+ * @publicDocs
  */
 interface SetButtonAttributes {
+  /** The form field that names the cart change. */
   name: "intent";
+  /** Sets the line to the quantity in the form's quantity input. */
   value: "set";
+  /** Makes the button the one that submits the form when the quantity changes. */
   type: "submit";
+  /** Hides the button from view. */
   hidden: true;
 }
 /**
- * HTML attributes for a quantity `<input>` in interactive mode.
+ * HTML attributes for a quantity input that submits the form when the customer changes the quantity.
+ *
+ * `register("quantity", { value, interactive: true })` returns the attributes. The input shows a number keyboard on mobile devices and has no spinner arrows.
  *
- * Returned by `register("quantity", { value, interactive: true })`. Uses
- * `type: "text"` with `inputMode: "numeric"` for mobile number keyboards
- * without the native spinner arrows.
+ * @publicDocs
  */
 interface QuantityInputAttributes {
+  /** The form field that holds the quantity. */
   name: "quantity";
+  /** The current quantity as a string. */
   value: string;
+  /** Renders a text input, which has no number spinner arrows. */
   type: "text";
+  /** Shows a numeric keyboard on mobile devices. */
   inputMode: "numeric";
+  /** Accepts digits only. */
   pattern: string;
+  /** Turns off browser autocomplete for the input. */
   autoComplete: "off";
+  /** Turns off autocorrect for the input. */
   autoCorrect: "off";
 }
 type AttributeValueName = `attributes.${string}`;
 /**
- * Overloaded function that produces the correct HTML attributes for any cart
- * form field or action button.
+ * A function that returns the HTML attributes for a cart form field or action button.
  *
- * Call with a **field name** (`"lineId"`, `"quantity"`, `"merchandiseId"`,
- * `"discountCode"`, `"note"`, `"attributeValue"`, `"sellingPlanId"`) to get
- * input attributes, or with an **action name** (`"add"`, `"increase"`,
- * `"decrease"`, `"remove"`, `"set"`, `"discount-apply"`, `"discount-remove"`,
- * `"note-update"`, `"attributes-update"`) to get submit button attributes.
+ * Pass a field name to get input attributes: `lineId`, `quantity`,
+ * `merchandiseId`, `discountCode`, `note`, `attributeValue`, or `sellingPlanId`.
+ * Pass an action name to get submit button attributes: `add`,
+ * `increase`, `decrease`, `remove`, `set`, `discount-apply`, `discount-remove`,
+ * `note-update`, or `attributes-update`.
+ *
+ * For an attribute value, pass a `key` option. The function names the field `attributes.<key>` and throws a type error when the key is missing or empty. The line ID input is read-only. Add `type="hidden"` to hide the line ID input.
  *
  * @example
  * ```tsx
@@ -56,7 +68,7 @@ type AttributeValueName = `attributes.${string}`;
  * <button {...register("increase")}>+</button>
  * ```
  *
- * @throws `TypeError` when called with `"attributeValue"` and no non-empty `key`.
+ * @throws A type error when an attribute value has a missing or empty key.
  */
 type CartFormRegister = {
   (field: "lineId", opts: {
@@ -168,11 +180,11 @@ type CartFormRegister = {
   };
 };
 /**
- * Creates a {@link CartFormRegister} function for generating cart form field attributes.
+ * Creates a register function that returns the HTML attributes for cart form fields and action buttons.
+ *
+ * Use the function to build cart forms without a framework binding. In React, `useCartForm` returns a register function and form props for you. To submit an interactive quantity input on change, call `attachQuantityInput`.
  *
- * The returned `register` function is stateless — it can be called multiple times
- * and shared across components. Framework hooks (`useCartForm`) wrap this with
- * additional conveniences like `formProps()` and interactive `ref` wiring.
+ * The register function holds no state. Share one register function across components.
  *
  * @example
  * ```ts
@@ -184,6 +196,8 @@ type CartFormRegister = {
  * const addAttrs = register("add");
  * // → { name: "intent", value: "add" }
  * ```
+ * @returns A register function for cart form fields and action buttons.
+ * @publicDocs
  */
 declare function createCartFormRegister(): CartFormRegister;
 //#endregion

package/dist/development/core/cart/form.mjs

@@ -54,11 +54,11 @@ function createFieldAttributes(name, opts) {
 	return attrs;
 }
 /**
-* Creates a {@link CartFormRegister} function for generating cart form field attributes.
+* Creates a register function that returns the HTML attributes for cart form fields and action buttons.
 *
-* The returned `register` function is stateless — it can be called multiple times
-* and shared across components. Framework hooks (`useCartForm`) wrap this with
-* additional conveniences like `formProps()` and interactive `ref` wiring.
+* Use the function to build cart forms without a framework binding. In React, `useCartForm` returns a register function and form props for you. To submit an interactive quantity input on change, call `attachQuantityInput`.
+*
+* The register function holds no state. Share one register function across components.
 *
 * @example
 * ```ts
@@ -70,6 +70,8 @@ function createFieldAttributes(name, opts) {
 * const addAttrs = register("add");
 * // → { name: "intent", value: "add" }
 * ```
+* @returns A register function for cart form fields and action buttons.
+* @publicDocs
 */
 function createCartFormRegister() {
 	return ((nameOrAction, opts) => {

package/dist/development/core/cart/form.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"form.mjs","names":[],"sources":["../../../../src/core/cart/form.ts"],"sourcesContent":["/**\n * HTML attributes for a hidden submit button that triggers the `\"set\"` intent.\n *\n * Used by {@link CartFormRegister} when `register(\"set\")` is called. The button\n * must be the first submit button in the form for `attachQuantityInput`\n * to auto-submit on quantity changes.\n */\nexport interface SetButtonAttributes {\n  name: \"intent\";\n  value: \"set\";\n  type: \"submit\";\n  hidden: true;\n}\n\n/**\n * HTML attributes for a quantity `<input>` in interactive mode.\n *\n * Returned by `register(\"quantity\", { value, interactive: true })`. Uses\n * `type: \"text\"` with `inputMode: \"numeric\"` for mobile number keyboards\n * without the native spinner arrows.\n */\nexport interface QuantityInputAttributes {\n  name: \"quantity\";\n  value: string;\n  type: \"text\";\n  inputMode: \"numeric\";\n  pattern: string;\n  autoComplete: \"off\";\n  autoCorrect: \"off\";\n}\n\ntype AttributeValueName = `attributes.${string}`;\n\n/**\n * Overloaded function that produces the correct HTML attributes for any cart\n * form field or action button.\n *\n * Call with a **field name** (`\"lineId\"`, `\"quantity\"`, `\"merchandiseId\"`,\n * `\"discountCode\"`, `\"note\"`, `\"attributeValue\"`, `\"sellingPlanId\"`) to get\n * input attributes, or with an **action name** (`\"add\"`, `\"increase\"`,\n * `\"decrease\"`, `\"remove\"`, `\"set\"`, `\"discount-apply\"`, `\"discount-remove\"`,\n * `\"note-update\"`, `\"attributes-update\"`) to get submit button attributes.\n *\n * @example\n * ```tsx\n * const register = createCartFormRegister();\n *\n * // Line ID field (register returns readOnly; add type=\"hidden\" to hide it)\n * <input {...register(\"lineId\", { value: line.id })} />\n *\n * // Interactive quantity input (pair with attachQuantityInput to auto-submit on change)\n * <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *\n * // Hidden submit button for the \"set\" intent\n * <button {...register(\"set\")} />\n *\n * // Increase quantity button\n * <button {...register(\"increase\")}>+</button>\n * ```\n *\n * @throws `TypeError` when called with `\"attributeValue\"` and no non-empty `key`.\n */\nexport type CartFormRegister = {\n  (field: \"lineId\", opts: { value: string }): { name: \"lineId\"; value: string; readOnly: true };\n  (field: \"quantity\", opts: { value: number | string; interactive: true }): QuantityInputAttributes;\n  (\n    field: \"quantity\",\n    opts: { value: number | string; interactive?: false },\n  ): { name: \"quantity\"; value: string };\n  (field: \"quantity\", opts: { defaultValue: number }): { name: \"quantity\"; defaultValue: string };\n  (field: \"discountCode\", opts: { value: string }): { name: \"discountCode\"; value: string };\n  (\n    field: \"discountCode\",\n    opts: { defaultValue: string },\n  ): { name: \"discountCode\"; defaultValue: string };\n  (field: \"merchandiseId\", opts: { value: string }): { name: \"merchandiseId\"; value: string };\n  (field: \"note\", opts: { value: string }): { name: \"note\"; value: string };\n  (field: \"note\", opts: { defaultValue: string }): { name: \"note\"; defaultValue: string };\n  (\n    field: \"attributeValue\",\n    opts: { key: string; value: string },\n  ): { name: AttributeValueName; value: string };\n  (\n    field: \"attributeValue\",\n    opts: { key: string; defaultValue: string },\n  ): { name: AttributeValueName; defaultValue: string };\n  (field: \"sellingPlanId\", opts: { value: string }): { name: \"sellingPlanId\"; value: string };\n  (action: \"add\"): { name: \"intent\"; value: \"add\" };\n  (action: \"increase\"): { name: \"intent\"; value: \"increase\" };\n  (action: \"decrease\"): { name: \"intent\"; value: \"decrease\" };\n  (action: \"remove\"): { name: \"intent\"; value: \"remove\" };\n  (action: \"set\"): SetButtonAttributes;\n  (action: \"discount-apply\"): { name: \"intent\"; value: \"discount-apply\" };\n  (action: \"discount-remove\"): { name: \"intent\"; value: \"discount-remove\" };\n  (action: \"note-update\"): { name: \"intent\"; value: \"note-update\" };\n  (action: \"attributes-update\"): { name: \"intent\"; value: \"attributes-update\" };\n};\n\nconst FIELD_REGISTERS = new Set([\n  \"lineId\",\n  \"quantity\",\n  \"discountCode\",\n  \"merchandiseId\",\n  \"note\",\n  \"sellingPlanId\",\n]);\n\nconst ATTRIBUTE_VALUE_NAME_PREFIX = \"attributes.\";\n\ntype RegisterOptions = {\n  key?: string;\n  value?: string | number;\n  defaultValue?: string;\n  interactive?: boolean;\n};\n\nexport function getCartAttributeFormEntries(\n  formData: FormData,\n): Array<{ key: string; value: FormDataEntryValue }> {\n  const attributes: Array<{ key: string; value: FormDataEntryValue }> = [];\n  for (const [name, value] of formData.entries()) {\n    if (!name.startsWith(ATTRIBUTE_VALUE_NAME_PREFIX)) continue;\n    attributes.push({ key: name.slice(ATTRIBUTE_VALUE_NAME_PREFIX.length), value });\n  }\n  return attributes;\n}\n\nfunction createAttributeValueAttributes(opts?: RegisterOptions) {\n  if (!opts?.key) throw new TypeError('Cart attribute values require a non-empty \"key\".');\n  const name = `${ATTRIBUTE_VALUE_NAME_PREFIX}${opts.key}` as AttributeValueName;\n  if (\"defaultValue\" in opts) {\n    return { name, defaultValue: String(opts.defaultValue) };\n  }\n  return { name, value: String(opts.value ?? \"\") };\n}\n\nfunction createFieldAttributes(name: string, opts?: RegisterOptions) {\n  if (opts && \"defaultValue\" in opts) {\n    return { name, defaultValue: String(opts.defaultValue) };\n  }\n\n  const value = String(opts?.value ?? \"\");\n\n  if (name === \"quantity\" && opts?.interactive) {\n    return {\n      name: \"quantity\",\n      value,\n      type: \"text\",\n      inputMode: \"numeric\",\n      pattern: \"\\\\d+\",\n      autoComplete: \"off\",\n      autoCorrect: \"off\",\n    } satisfies QuantityInputAttributes;\n  }\n\n  const attrs: Record<string, string | boolean> = { name, value };\n  if (name === \"lineId\") attrs.readOnly = true;\n  return attrs;\n}\n\n/**\n * Creates a {@link CartFormRegister} function for generating cart form field attributes.\n *\n * The returned `register` function is stateless — it can be called multiple times\n * and shared across components. Framework hooks (`useCartForm`) wrap this with\n * additional conveniences like `formProps()` and interactive `ref` wiring.\n *\n * @example\n * ```ts\n * const register = createCartFormRegister();\n *\n * const lineIdAttrs = register(\"lineId\", { value: \"gid://shopify/CartLine/123\" });\n * // → { name: \"lineId\", value: \"gid://shopify/CartLine/123\", readOnly: true }\n *\n * const addAttrs = register(\"add\");\n * // → { name: \"intent\", value: \"add\" }\n * ```\n */\nexport function createCartFormRegister(): CartFormRegister {\n  return ((nameOrAction: string, opts?: RegisterOptions) => {\n    if (nameOrAction === \"attributeValue\") {\n      return createAttributeValueAttributes(opts);\n    }\n\n    if (FIELD_REGISTERS.has(nameOrAction)) {\n      return createFieldAttributes(nameOrAction, opts);\n    }\n\n    if (nameOrAction === \"set\") {\n      return {\n        name: \"intent\",\n        value: \"set\",\n        type: \"submit\",\n        hidden: true,\n      } satisfies SetButtonAttributes;\n    }\n\n    return { name: \"intent\", value: nameOrAction };\n  }) as CartFormRegister;\n}\n"],"mappings":";AAkGA,MAAM,kBAAkB,IAAI,IAAI;CAC9B;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,MAAM,8BAA8B;AASpC,SAAgB,4BACd,UACmD;CACnD,MAAM,aAAgE,EAAE;AACxE,MAAK,MAAM,CAAC,MAAM,UAAU,SAAS,SAAS,EAAE;AAC9C,MAAI,CAAC,KAAK,WAAW,4BAA4B,CAAE;AACnD,aAAW,KAAK;GAAE,KAAK,KAAK,MAAM,GAAmC;GAAE;GAAO,CAAC;;AAEjF,QAAO;;AAGT,SAAS,+BAA+B,MAAwB;AAC9D,KAAI,CAAC,MAAM,IAAK,OAAM,IAAI,UAAU,qDAAmD;CACvF,MAAM,OAAO,GAAG,8BAA8B,KAAK;AACnD,KAAI,kBAAkB,KACpB,QAAO;EAAE;EAAM,cAAc,OAAO,KAAK,aAAa;EAAE;AAE1D,QAAO;EAAE;EAAM,OAAO,OAAO,KAAK,SAAS,GAAG;EAAE;;AAGlD,SAAS,sBAAsB,MAAc,MAAwB;AACnE,KAAI,QAAQ,kBAAkB,KAC5B,QAAO;EAAE;EAAM,cAAc,OAAO,KAAK,aAAa;EAAE;CAG1D,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAG;AAEvC,KAAI,SAAS,cAAc,MAAM,YAC/B,QAAO;EACL,MAAM;EACN;EACA,MAAM;EACN,WAAW;EACX,SAAS;EACT,cAAc;EACd,aAAa;EACd;CAGH,MAAM,QAA0C;EAAE;EAAM;EAAO;AAC/D,KAAI,SAAS,SAAU,OAAM,WAAW;AACxC,QAAO;;;;;;;;;;;;;;;;;;;;AAqBT,SAAgB,yBAA2C;AACzD,UAAS,cAAsB,SAA2B;AACxD,MAAI,iBAAiB,iBACnB,QAAO,+BAA+B,KAAK;AAG7C,MAAI,gBAAgB,IAAI,aAAa,CACnC,QAAO,sBAAsB,cAAc,KAAK;AAGlD,MAAI,iBAAiB,MACnB,QAAO;GACL,MAAM;GACN,OAAO;GACP,MAAM;GACN,QAAQ;GACT;AAGH,SAAO;GAAE,MAAM;GAAU,OAAO;GAAc"}
+{"version":3,"file":"form.mjs","names":[],"sources":["../../../../src/core/cart/form.ts"],"sourcesContent":["/**\n * HTML attributes for the hidden submit button that sets a line to the quantity in the form's quantity input.\n *\n * `register(\"set\")` returns the attributes. Make the set button the form's first submit button. A quantity input submits on change only when the set button comes first.\n *\n * @publicDocs\n */\nexport interface SetButtonAttributes {\n  /** The form field that names the cart change. */\n  name: \"intent\";\n  /** Sets the line to the quantity in the form's quantity input. */\n  value: \"set\";\n  /** Makes the button the one that submits the form when the quantity changes. */\n  type: \"submit\";\n  /** Hides the button from view. */\n  hidden: true;\n}\n\n/**\n * HTML attributes for a quantity input that submits the form when the customer changes the quantity.\n *\n * `register(\"quantity\", { value, interactive: true })` returns the attributes. The input shows a number keyboard on mobile devices and has no spinner arrows.\n *\n * @publicDocs\n */\nexport interface QuantityInputAttributes {\n  /** The form field that holds the quantity. */\n  name: \"quantity\";\n  /** The current quantity as a string. */\n  value: string;\n  /** Renders a text input, which has no number spinner arrows. */\n  type: \"text\";\n  /** Shows a numeric keyboard on mobile devices. */\n  inputMode: \"numeric\";\n  /** Accepts digits only. */\n  pattern: string;\n  /** Turns off browser autocomplete for the input. */\n  autoComplete: \"off\";\n  /** Turns off autocorrect for the input. */\n  autoCorrect: \"off\";\n}\n\ntype AttributeValueName = `attributes.${string}`;\n\n/**\n * A function that returns the HTML attributes for a cart form field or action button.\n *\n * Pass a field name to get input attributes: `lineId`, `quantity`,\n * `merchandiseId`, `discountCode`, `note`, `attributeValue`, or `sellingPlanId`.\n * Pass an action name to get submit button attributes: `add`,\n * `increase`, `decrease`, `remove`, `set`, `discount-apply`, `discount-remove`,\n * `note-update`, or `attributes-update`.\n *\n * For an attribute value, pass a `key` option. The function names the field `attributes.<key>` and throws a type error when the key is missing or empty. The line ID input is read-only. Add `type=\"hidden\"` to hide the line ID input.\n *\n * @example\n * ```tsx\n * const register = createCartFormRegister();\n *\n * // Line ID field (register returns readOnly; add type=\"hidden\" to hide it)\n * <input {...register(\"lineId\", { value: line.id })} />\n *\n * // Interactive quantity input (pair with attachQuantityInput to auto-submit on change)\n * <input {...register(\"quantity\", { value: line.quantity, interactive: true })} />\n *\n * // Hidden submit button for the \"set\" intent\n * <button {...register(\"set\")} />\n *\n * // Increase quantity button\n * <button {...register(\"increase\")}>+</button>\n * ```\n *\n * @throws A type error when an attribute value has a missing or empty key.\n */\nexport type CartFormRegister = {\n  (field: \"lineId\", opts: { value: string }): { name: \"lineId\"; value: string; readOnly: true };\n  (field: \"quantity\", opts: { value: number | string; interactive: true }): QuantityInputAttributes;\n  (\n    field: \"quantity\",\n    opts: { value: number | string; interactive?: false },\n  ): { name: \"quantity\"; value: string };\n  (field: \"quantity\", opts: { defaultValue: number }): { name: \"quantity\"; defaultValue: string };\n  (field: \"discountCode\", opts: { value: string }): { name: \"discountCode\"; value: string };\n  (\n    field: \"discountCode\",\n    opts: { defaultValue: string },\n  ): { name: \"discountCode\"; defaultValue: string };\n  (field: \"merchandiseId\", opts: { value: string }): { name: \"merchandiseId\"; value: string };\n  (field: \"note\", opts: { value: string }): { name: \"note\"; value: string };\n  (field: \"note\", opts: { defaultValue: string }): { name: \"note\"; defaultValue: string };\n  (\n    field: \"attributeValue\",\n    opts: { key: string; value: string },\n  ): { name: AttributeValueName; value: string };\n  (\n    field: \"attributeValue\",\n    opts: { key: string; defaultValue: string },\n  ): { name: AttributeValueName; defaultValue: string };\n  (field: \"sellingPlanId\", opts: { value: string }): { name: \"sellingPlanId\"; value: string };\n  (action: \"add\"): { name: \"intent\"; value: \"add\" };\n  (action: \"increase\"): { name: \"intent\"; value: \"increase\" };\n  (action: \"decrease\"): { name: \"intent\"; value: \"decrease\" };\n  (action: \"remove\"): { name: \"intent\"; value: \"remove\" };\n  (action: \"set\"): SetButtonAttributes;\n  (action: \"discount-apply\"): { name: \"intent\"; value: \"discount-apply\" };\n  (action: \"discount-remove\"): { name: \"intent\"; value: \"discount-remove\" };\n  (action: \"note-update\"): { name: \"intent\"; value: \"note-update\" };\n  (action: \"attributes-update\"): { name: \"intent\"; value: \"attributes-update\" };\n};\n\nconst FIELD_REGISTERS = new Set([\n  \"lineId\",\n  \"quantity\",\n  \"discountCode\",\n  \"merchandiseId\",\n  \"note\",\n  \"sellingPlanId\",\n]);\n\nconst ATTRIBUTE_VALUE_NAME_PREFIX = \"attributes.\";\n\ntype RegisterOptions = {\n  key?: string;\n  value?: string | number;\n  defaultValue?: string;\n  interactive?: boolean;\n};\n\nexport function getCartAttributeFormEntries(\n  formData: FormData,\n): Array<{ key: string; value: FormDataEntryValue }> {\n  const attributes: Array<{ key: string; value: FormDataEntryValue }> = [];\n  for (const [name, value] of formData.entries()) {\n    if (!name.startsWith(ATTRIBUTE_VALUE_NAME_PREFIX)) continue;\n    attributes.push({ key: name.slice(ATTRIBUTE_VALUE_NAME_PREFIX.length), value });\n  }\n  return attributes;\n}\n\nfunction createAttributeValueAttributes(opts?: RegisterOptions) {\n  if (!opts?.key) throw new TypeError('Cart attribute values require a non-empty \"key\".');\n  const name = `${ATTRIBUTE_VALUE_NAME_PREFIX}${opts.key}` as AttributeValueName;\n  if (\"defaultValue\" in opts) {\n    return { name, defaultValue: String(opts.defaultValue) };\n  }\n  return { name, value: String(opts.value ?? \"\") };\n}\n\nfunction createFieldAttributes(name: string, opts?: RegisterOptions) {\n  if (opts && \"defaultValue\" in opts) {\n    return { name, defaultValue: String(opts.defaultValue) };\n  }\n\n  const value = String(opts?.value ?? \"\");\n\n  if (name === \"quantity\" && opts?.interactive) {\n    return {\n      name: \"quantity\",\n      value,\n      type: \"text\",\n      inputMode: \"numeric\",\n      pattern: \"\\\\d+\",\n      autoComplete: \"off\",\n      autoCorrect: \"off\",\n    } satisfies QuantityInputAttributes;\n  }\n\n  const attrs: Record<string, string | boolean> = { name, value };\n  if (name === \"lineId\") attrs.readOnly = true;\n  return attrs;\n}\n\n/**\n * Creates a register function that returns the HTML attributes for cart form fields and action buttons.\n *\n * Use the function to build cart forms without a framework binding. In React, `useCartForm` returns a register function and form props for you. To submit an interactive quantity input on change, call `attachQuantityInput`.\n *\n * The register function holds no state. Share one register function across components.\n *\n * @example\n * ```ts\n * const register = createCartFormRegister();\n *\n * const lineIdAttrs = register(\"lineId\", { value: \"gid://shopify/CartLine/123\" });\n * // → { name: \"lineId\", value: \"gid://shopify/CartLine/123\", readOnly: true }\n *\n * const addAttrs = register(\"add\");\n * // → { name: \"intent\", value: \"add\" }\n * ```\n * @returns A register function for cart form fields and action buttons.\n * @publicDocs\n */\nexport function createCartFormRegister(): CartFormRegister {\n  return ((nameOrAction: string, opts?: RegisterOptions) => {\n    if (nameOrAction === \"attributeValue\") {\n      return createAttributeValueAttributes(opts);\n    }\n\n    if (FIELD_REGISTERS.has(nameOrAction)) {\n      return createFieldAttributes(nameOrAction, opts);\n    }\n\n    if (nameOrAction === \"set\") {\n      return {\n        name: \"intent\",\n        value: \"set\",\n        type: \"submit\",\n        hidden: true,\n      } satisfies SetButtonAttributes;\n    }\n\n    return { name: \"intent\", value: nameOrAction };\n  }) as CartFormRegister;\n}\n"],"mappings":";AA8GA,MAAM,kBAAkB,IAAI,IAAI;CAC9B;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,MAAM,8BAA8B;AASpC,SAAgB,4BACd,UACmD;CACnD,MAAM,aAAgE,EAAE;AACxE,MAAK,MAAM,CAAC,MAAM,UAAU,SAAS,SAAS,EAAE;AAC9C,MAAI,CAAC,KAAK,WAAW,4BAA4B,CAAE;AACnD,aAAW,KAAK;GAAE,KAAK,KAAK,MAAM,GAAmC;GAAE;GAAO,CAAC;;AAEjF,QAAO;;AAGT,SAAS,+BAA+B,MAAwB;AAC9D,KAAI,CAAC,MAAM,IAAK,OAAM,IAAI,UAAU,qDAAmD;CACvF,MAAM,OAAO,GAAG,8BAA8B,KAAK;AACnD,KAAI,kBAAkB,KACpB,QAAO;EAAE;EAAM,cAAc,OAAO,KAAK,aAAa;EAAE;AAE1D,QAAO;EAAE;EAAM,OAAO,OAAO,KAAK,SAAS,GAAG;EAAE;;AAGlD,SAAS,sBAAsB,MAAc,MAAwB;AACnE,KAAI,QAAQ,kBAAkB,KAC5B,QAAO;EAAE;EAAM,cAAc,OAAO,KAAK,aAAa;EAAE;CAG1D,MAAM,QAAQ,OAAO,MAAM,SAAS,GAAG;AAEvC,KAAI,SAAS,cAAc,MAAM,YAC/B,QAAO;EACL,MAAM;EACN;EACA,MAAM;EACN,WAAW;EACX,SAAS;EACT,cAAc;EACd,aAAa;EACd;CAGH,MAAM,QAA0C;EAAE;EAAM;EAAO;AAC/D,KAAI,SAAS,SAAU,OAAM,WAAW;AACxC,QAAO;;;;;;;;;;;;;;;;;;;;;;AAuBT,SAAgB,yBAA2C;AACzD,UAAS,cAAsB,SAA2B;AACxD,MAAI,iBAAiB,iBACnB,QAAO,+BAA+B,KAAK;AAG7C,MAAI,gBAAgB,IAAI,aAAa,CACnC,QAAO,sBAAsB,cAAc,KAAK;AAGlD,MAAI,iBAAiB,MACnB,QAAO;GACL,MAAM;GACN,OAAO;GACP,MAAM;GACN,QAAQ;GACT;AAGH,SAAO;GAAE,MAAM;GAAU,OAAO;GAAc"}

package/dist/development/core/cart/get-cart.d.mts

@@ -5,34 +5,41 @@ import { CartData } from "./state.mjs";
 import { cartQueries } from "./queries.mjs";
 
 //#region src/core/cart/get-cart.d.ts
+/** The cart data type with the fields from your cart query. Your query's field types replace the matching default cart fields. */
 type MergeCartData<TCart> = Omit<CartData, keyof TCart> & TCart;
 /**
- * Infers the {@link CartData} shape from a custom Storefront API cart query string.
+ * Gets the cart data type from a custom Storefront API cart query.
  *
- * When you pass a custom cart query to {@link getCart}, this type extracts the
- * `cart` field from the query's result type and merges it with the base
- * {@link CartData} interface, so the returned data is fully typed to your query.
+ * The type adds the cart fields from your query to the base cart data type.
+ *
+ * @publicDocs
  */
 type CartDataFromQuery<TQuery extends AnyStorefrontQueryString> = TQuery extends StorefrontQueryString<infer Result, infer _Variables, string> ? Result extends {
   cart?: (infer Cart) | null;
 } ? MergeCartData<NonNullable<Cart>> : CartData : CartData;
-/** Result of a {@link getCart} call — the cart data (or `null`), any errors, and response headers. */
+/**
+ * The cart that `getCart` returns, with any GraphQL errors and the Storefront API response headers.
+ *
+ * @publicDocs
+ */
 type CartResult<TCart extends CartData = CartData> = {
-  /** The cart, or `null` when no cart exists or the query failed. */cart: TCart | null;
+  /** The cart, or `null` when the cart ID is missing, the cart doesn't exist, or the query fails. */cart: TCart | null; /** GraphQL errors from the cart query. */
   errors?: Array<{
     message: string;
-  }>; /** Response headers from the Storefront API (e.g. cache directives). */
+  }>; /** The Storefront API response headers, such as cache directives. The headers are empty when `getCart` skips the request. */
   headers: Headers;
 };
+/** The Storefront API client that runs the cart query. */
 type StorefrontCartClient = Pick<StorefrontClient, "graphql">;
+/** A request, or a request context with a `Cookie` header and a URL. */
 type CartIdSource = Request | Pick<ShopifyRequestContext, "cookie" | "url">;
 /**
- * Extracts the cart GID from a request.
+ * Reads the cart ID from a request.
  *
- * Checks the `cartId` search parameter first (for explicit linking), then
- * falls back to the `cart` cookie. Returns `null` when neither source
- * contains a cart identifier.
+ * The function checks the `cartId` search parameter first, then the `cart` cookie. The function returns a search parameter value unchanged and adds the `gid://shopify/Cart/` prefix to a cookie value.
  *
+ * @param input The request or request context that carries the cart ID.
+ * @returns The cart ID, or `null` when neither the search parameter nor the cookie has one.
  * @example
  * ```ts
  * // In a framework loader
@@ -41,16 +48,20 @@ type CartIdSource = Request | Pick<ShopifyRequestContext, "cookie" | "url">;
  *   const { cart } = await getCart(cartId, storefront);
  * }
  * ```
+ * @publicDocs
  */
 declare function getCartId(input: CartIdSource): string | null;
 /**
  * Fetches a cart by ID from the Storefront API.
  *
- * Accepts an optional custom cart query document — the result type is inferred
- * via {@link CartDataFromQuery} so the returned `cart` is fully typed to your
- * query's fields. When `cartId` is `null`, returns `{ cart: null }` immediately
- * without making a network request.
+ * Pass a custom cart query to get a cart with that query's fields. Declare an `$id` variable in the query. The function passes the cart ID as the query's only variable.
+ *
+ * When the cart ID is `null`, the function returns a `null` cart without a network request. The function throws when the Storefront API request fails.
  *
+ * @param cartId The ID of the cart to fetch, or `null` to skip the request.
+ * @param storefront The Storefront API client that runs the cart query.
+ * @param cartQuery A cart query document that replaces the default cart query.
+ * @returns The cart or `null`, any GraphQL errors, and the Storefront API response headers.
  * @example
  * ```ts
  * const cartId = getCartId(request);
@@ -59,6 +70,7 @@ declare function getCartId(input: CartIdSource): string | null;
  * // With a custom query
  * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);
  * ```
+ * @publicDocs
  */
 declare function getCart<TQuery extends AnyStorefrontQueryString = typeof cartQueries.cart>(cartId: string | null, storefront: StorefrontCartClient, cartQuery?: TQuery): Promise<CartResult<CartDataFromQuery<TQuery>>>;
 //#endregion

package/dist/development/core/cart/get-cart.mjs

@@ -3,12 +3,12 @@ import { cartQueries } from "./queries.mjs";
 
 //#region src/core/cart/get-cart.ts
 /**
-* Extracts the cart GID from a request.
+* Reads the cart ID from a request.
 *
-* Checks the `cartId` search parameter first (for explicit linking), then
-* falls back to the `cart` cookie. Returns `null` when neither source
-* contains a cart identifier.
+* The function checks the `cartId` search parameter first, then the `cart` cookie. The function returns a search parameter value unchanged and adds the `gid://shopify/Cart/` prefix to a cookie value.
 *
+* @param input The request or request context that carries the cart ID.
+* @returns The cart ID, or `null` when neither the search parameter nor the cookie has one.
 * @example
 * ```ts
 * // In a framework loader
@@ -17,6 +17,7 @@ import { cartQueries } from "./queries.mjs";
 *   const { cart } = await getCart(cartId, storefront);
 * }
 * ```
+* @publicDocs
 */
 function getCartId(input) {
 	if (input.url) {
@@ -28,11 +29,14 @@ function getCartId(input) {
 /**
 * Fetches a cart by ID from the Storefront API.
 *
-* Accepts an optional custom cart query document — the result type is inferred
-* via {@link CartDataFromQuery} so the returned `cart` is fully typed to your
-* query's fields. When `cartId` is `null`, returns `{ cart: null }` immediately
-* without making a network request.
+* Pass a custom cart query to get a cart with that query's fields. Declare an `$id` variable in the query. The function passes the cart ID as the query's only variable.
 *
+* When the cart ID is `null`, the function returns a `null` cart without a network request. The function throws when the Storefront API request fails.
+*
+* @param cartId The ID of the cart to fetch, or `null` to skip the request.
+* @param storefront The Storefront API client that runs the cart query.
+* @param cartQuery A cart query document that replaces the default cart query.
+* @returns The cart or `null`, any GraphQL errors, and the Storefront API response headers.
 * @example
 * ```ts
 * const cartId = getCartId(request);
@@ -41,6 +45,7 @@ function getCartId(input) {
 * // With a custom query
 * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);
 * ```
+* @publicDocs
 */
 async function getCart(cartId, storefront, cartQuery = cartQueries.cart) {
 	if (!cartId) return {

package/dist/development/core/cart/get-cart.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"get-cart.mjs","names":[],"sources":["../../../../src/core/cart/get-cart.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\nimport type { AnyStorefrontQueryString, StorefrontQueryString } from \"../../graphql\";\nimport type { ShopifyRequestContext } from \"../request-context\";\nimport { getCartIdFromCookie } from \"./cookie\";\nimport { cartQueries } from \"./queries\";\nimport type { CartData } from \"./state\";\n\ntype MergeCartData<TCart> = Omit<CartData, keyof TCart> & TCart;\n\n/**\n * Infers the {@link CartData} shape from a custom Storefront API cart query string.\n *\n * When you pass a custom cart query to {@link getCart}, this type extracts the\n * `cart` field from the query's result type and merges it with the base\n * {@link CartData} interface, so the returned data is fully typed to your query.\n */\nexport type CartDataFromQuery<TQuery extends AnyStorefrontQueryString> =\n  TQuery extends StorefrontQueryString<infer Result, infer _Variables, string>\n    ? Result extends { cart?: (infer Cart) | null }\n      ? MergeCartData<NonNullable<Cart>>\n      : CartData\n    : CartData;\n\n/** Result of a {@link getCart} call — the cart data (or `null`), any errors, and response headers. */\nexport type CartResult<TCart extends CartData = CartData> = {\n  /** The cart, or `null` when no cart exists or the query failed. */\n  cart: TCart | null;\n  errors?: Array<{ message: string }>;\n  /** Response headers from the Storefront API (e.g. cache directives). */\n  headers: Headers;\n};\n\ntype CartQueryResult = {\n  data: { cart?: unknown } | null;\n  errors?: Array<{ message: string }>;\n  headers: Headers;\n};\n\ntype StorefrontCartClient = Pick<StorefrontClient, \"graphql\">;\n\ntype CartQueryDocument = AnyStorefrontQueryString;\n\ntype CartQueryGraphql = (\n  query: CartQueryDocument,\n  options: { variables: { id: string } },\n) => Promise<CartQueryResult>;\n\ntype CartIdSource = Request | Pick<ShopifyRequestContext, \"cookie\" | \"url\">;\n\n/**\n * Extracts the cart GID from a request.\n *\n * Checks the `cartId` search parameter first (for explicit linking), then\n * falls back to the `cart` cookie. Returns `null` when neither source\n * contains a cart identifier.\n *\n * @example\n * ```ts\n * // In a framework loader\n * const cartId = getCartId(request);\n * if (cartId) {\n *   const { cart } = await getCart(cartId, storefront);\n * }\n * ```\n */\nexport function getCartId(input: CartIdSource): string | null {\n  if (input.url) {\n    const parsedUrl = new URL(input.url, \"https://hydrogen.local\");\n    const cartId = parsedUrl.searchParams.get(\"cartId\");\n    if (cartId) return cartId;\n  }\n\n  return getCartIdFromCookie(input);\n}\n\n/**\n * Fetches a cart by ID from the Storefront API.\n *\n * Accepts an optional custom cart query document — the result type is inferred\n * via {@link CartDataFromQuery} so the returned `cart` is fully typed to your\n * query's fields. When `cartId` is `null`, returns `{ cart: null }` immediately\n * without making a network request.\n *\n * @example\n * ```ts\n * const cartId = getCartId(request);\n * const { cart, errors, headers } = await getCart(cartId, storefront);\n *\n * // With a custom query\n * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);\n * ```\n */\nexport async function getCart<TQuery extends AnyStorefrontQueryString = typeof cartQueries.cart>(\n  cartId: string | null,\n  storefront: StorefrontCartClient,\n  cartQuery: TQuery = cartQueries.cart as TQuery,\n): Promise<CartResult<CartDataFromQuery<TQuery>>> {\n  if (!cartId) {\n    return {\n      cart: null,\n      headers: new Headers(),\n    };\n  }\n\n  const queryCart = storefront.graphql as CartQueryGraphql;\n  const result = await queryCart(cartQuery, { variables: { id: cartId } });\n\n  if (result.errors || !result.data?.cart) {\n    return {\n      cart: null,\n      errors: result.errors,\n      headers: result.headers,\n    };\n  }\n\n  return { cart: result.data.cart as CartDataFromQuery<TQuery>, headers: result.headers };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,UAAU,OAAoC;AAC5D,KAAI,MAAM,KAAK;EAEb,MAAM,SAAS,IADO,IAAI,MAAM,KAAK,yBACb,CAAC,aAAa,IAAI,SAAS;AACnD,MAAI,OAAQ,QAAO;;AAGrB,QAAO,oBAAoB,MAAM;;;;;;;;;;;;;;;;;;;AAoBnC,eAAsB,QACpB,QACA,YACA,YAAoB,YAAY,MACgB;AAChD,KAAI,CAAC,OACH,QAAO;EACL,MAAM;EACN,SAAS,IAAI,SAAS;EACvB;CAGH,MAAM,YAAY,WAAW;CAC7B,MAAM,SAAS,MAAM,UAAU,WAAW,EAAE,WAAW,EAAE,IAAI,QAAQ,EAAE,CAAC;AAExE,KAAI,OAAO,UAAU,CAAC,OAAO,MAAM,KACjC,QAAO;EACL,MAAM;EACN,QAAQ,OAAO;EACf,SAAS,OAAO;EACjB;AAGH,QAAO;EAAE,MAAM,OAAO,KAAK;EAAmC,SAAS,OAAO;EAAS"}
+{"version":3,"file":"get-cart.mjs","names":[],"sources":["../../../../src/core/cart/get-cart.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\nimport type { AnyStorefrontQueryString, StorefrontQueryString } from \"../../graphql\";\nimport type { ShopifyRequestContext } from \"../request-context\";\nimport { getCartIdFromCookie } from \"./cookie\";\nimport { cartQueries } from \"./queries\";\nimport type { CartData } from \"./state\";\n\n/** The cart data type with the fields from your cart query. Your query's field types replace the matching default cart fields. */\ntype MergeCartData<TCart> = Omit<CartData, keyof TCart> & TCart;\n\n/**\n * Gets the cart data type from a custom Storefront API cart query.\n *\n * The type adds the cart fields from your query to the base cart data type.\n *\n * @publicDocs\n */\nexport type CartDataFromQuery<TQuery extends AnyStorefrontQueryString> =\n  TQuery extends StorefrontQueryString<infer Result, infer _Variables, string>\n    ? Result extends { cart?: (infer Cart) | null }\n      ? MergeCartData<NonNullable<Cart>>\n      : CartData\n    : CartData;\n\n/**\n * The cart that `getCart` returns, with any GraphQL errors and the Storefront API response headers.\n *\n * @publicDocs\n */\nexport type CartResult<TCart extends CartData = CartData> = {\n  /** The cart, or `null` when the cart ID is missing, the cart doesn't exist, or the query fails. */\n  cart: TCart | null;\n  /** GraphQL errors from the cart query. */\n  errors?: Array<{ message: string }>;\n  /** The Storefront API response headers, such as cache directives. The headers are empty when `getCart` skips the request. */\n  headers: Headers;\n};\n\ntype CartQueryResult = {\n  data: { cart?: unknown } | null;\n  errors?: Array<{ message: string }>;\n  headers: Headers;\n};\n\n/** The Storefront API client that runs the cart query. */\ntype StorefrontCartClient = Pick<StorefrontClient, \"graphql\">;\n\ntype CartQueryDocument = AnyStorefrontQueryString;\n\ntype CartQueryGraphql = (\n  query: CartQueryDocument,\n  options: { variables: { id: string } },\n) => Promise<CartQueryResult>;\n\n/** A request, or a request context with a `Cookie` header and a URL. */\ntype CartIdSource = Request | Pick<ShopifyRequestContext, \"cookie\" | \"url\">;\n\n/**\n * Reads the cart ID from a request.\n *\n * The function checks the `cartId` search parameter first, then the `cart` cookie. The function returns a search parameter value unchanged and adds the `gid://shopify/Cart/` prefix to a cookie value.\n *\n * @param input The request or request context that carries the cart ID.\n * @returns The cart ID, or `null` when neither the search parameter nor the cookie has one.\n * @example\n * ```ts\n * // In a framework loader\n * const cartId = getCartId(request);\n * if (cartId) {\n *   const { cart } = await getCart(cartId, storefront);\n * }\n * ```\n * @publicDocs\n */\nexport function getCartId(input: CartIdSource): string | null {\n  if (input.url) {\n    const parsedUrl = new URL(input.url, \"https://hydrogen.local\");\n    const cartId = parsedUrl.searchParams.get(\"cartId\");\n    if (cartId) return cartId;\n  }\n\n  return getCartIdFromCookie(input);\n}\n\n/**\n * Fetches a cart by ID from the Storefront API.\n *\n * Pass a custom cart query to get a cart with that query's fields. Declare an `$id` variable in the query. The function passes the cart ID as the query's only variable.\n *\n * When the cart ID is `null`, the function returns a `null` cart without a network request. The function throws when the Storefront API request fails.\n *\n * @param cartId The ID of the cart to fetch, or `null` to skip the request.\n * @param storefront The Storefront API client that runs the cart query.\n * @param cartQuery A cart query document that replaces the default cart query.\n * @returns The cart or `null`, any GraphQL errors, and the Storefront API response headers.\n * @example\n * ```ts\n * const cartId = getCartId(request);\n * const { cart, errors, headers } = await getCart(cartId, storefront);\n *\n * // With a custom query\n * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);\n * ```\n * @publicDocs\n */\nexport async function getCart<TQuery extends AnyStorefrontQueryString = typeof cartQueries.cart>(\n  cartId: string | null,\n  storefront: StorefrontCartClient,\n  cartQuery: TQuery = cartQueries.cart as TQuery,\n): Promise<CartResult<CartDataFromQuery<TQuery>>> {\n  if (!cartId) {\n    return {\n      cart: null,\n      headers: new Headers(),\n    };\n  }\n\n  const queryCart = storefront.graphql as CartQueryGraphql;\n  const result = await queryCart(cartQuery, { variables: { id: cartId } });\n\n  if (result.errors || !result.data?.cart) {\n    return {\n      cart: null,\n      errors: result.errors,\n      headers: result.headers,\n    };\n  }\n\n  return { cart: result.data.cart as CartDataFromQuery<TQuery>, headers: result.headers };\n}\n\n/**\n * Fetches a cart by ID from the Storefront API.\n *\n * Pass a custom cart query to get a cart with that query's fields. Declare an `$id` variable in the query. The function passes the cart ID as the query's only variable.\n *\n * When the cart ID is `null`, the function returns a `null` cart without a network request. The function throws when the Storefront API request fails.\n *\n * @example\n * ```ts\n * const cartId = getCartId(request);\n * const { cart, errors, headers } = await getCart(cartId, storefront);\n *\n * // With a custom query\n * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);\n * ```\n * @publicDocs\n */\nexport type GetCartForDocs =\n  /**\n   * @param cartId - The ID of the cart to fetch, or `null` to skip the request.\n   * @param storefront - The Storefront API client that runs the cart query.\n   * @param cartQuery - A cart query document that replaces the default cart query.\n   * @returns The cart or `null`, any GraphQL errors, and the Storefront API response headers.\n   */\n  (\n    cartId: string | null,\n    storefront: StorefrontCartClient,\n    cartQuery?: AnyStorefrontQueryString,\n  ) => Promise<CartResult<CartData>>;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA0EA,SAAgB,UAAU,OAAoC;AAC5D,KAAI,MAAM,KAAK;EAEb,MAAM,SAAS,IADO,IAAI,MAAM,KAAK,yBACb,CAAC,aAAa,IAAI,SAAS;AACnD,MAAI,OAAQ,QAAO;;AAGrB,QAAO,oBAAoB,MAAM;;;;;;;;;;;;;;;;;;;;;;;AAwBnC,eAAsB,QACpB,QACA,YACA,YAAoB,YAAY,MACgB;AAChD,KAAI,CAAC,OACH,QAAO;EACL,MAAM;EACN,SAAS,IAAI,SAAS;EACvB;CAGH,MAAM,YAAY,WAAW;CAC7B,MAAM,SAAS,MAAM,UAAU,WAAW,EAAE,WAAW,EAAE,IAAI,QAAQ,EAAE,CAAC;AAExE,KAAI,OAAO,UAAU,CAAC,OAAO,MAAM,KACjC,QAAO;EACL,MAAM;EACN,QAAQ,OAAO;EACf,SAAS,OAAO;EACjB;AAGH,QAAO;EAAE,MAAM,OAAO,KAAK;EAAmC,SAAS,OAAO;EAAS"}

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

@@ -1,14 +1,24 @@
 //#region src/core/cart/quantity.d.ts
-/** Default lower bound for {@link sanitizeQuantity} when no `min` is given. */
+/**
+ * The minimum quantity that sanitizeQuantity uses when you omit `min`.
+ *
+ * @publicDocs
+ */
 declare const DEFAULT_MINIMUM_QUANTITY = 1;
-/** Sentinel upper bound for {@link sanitizeQuantity} meaning "no maximum". */
+/**
+ * The maximum quantity that sanitizeQuantity uses when you omit `max`. The value, `Infinity`, sets no upper limit.
+ *
+ * @publicDocs
+ */
 declare const NO_QUANTITY_LIMIT: number;
 /**
- * Clamps a raw value to a valid integer quantity within `min`/`max` bounds.
+ * Turns a raw value, such as text from a quantity input, into a whole-number quantity between a minimum and a maximum.
  *
- * Parses strings, rounds floats, and falls back to `min` for unparseable input.
- * Used internally by the cart form system to sanitize user-typed quantities.
+ * The function parses strings and rounds decimals. Input that the function can't parse returns the minimum.
  *
+ * @param raw The value to turn into a quantity.
+ * @param options The lower and upper bounds. The `min` option defaults to `1`, and `max` defaults to no limit. To stop at available stock, pass the variant's available quantity as `max`.
+ * @returns The rounded quantity, between the minimum and the maximum.
  * @example
  * ```ts
  * sanitizeQuantity("3")           // → 3
@@ -17,6 +27,7 @@ declare const NO_QUANTITY_LIMIT: number;
  * sanitizeQuantity(5, { max: 3 }) // → 3
  * sanitizeQuantity(0, { min: 1 }) // → 1
  * ```
+ * @publicDocs
  */
 declare function sanitizeQuantity(raw: unknown, options?: {
   min?: number;

package/dist/development/core/cart/quantity.mjs

@@ -1,14 +1,24 @@
 //#region src/core/cart/quantity.ts
-/** Default lower bound for {@link sanitizeQuantity} when no `min` is given. */
+/**
+* The minimum quantity that sanitizeQuantity uses when you omit `min`.
+*
+* @publicDocs
+*/
 const DEFAULT_MINIMUM_QUANTITY = 1;
-/** Sentinel upper bound for {@link sanitizeQuantity} meaning "no maximum". */
+/**
+* The maximum quantity that sanitizeQuantity uses when you omit `max`. The value, `Infinity`, sets no upper limit.
+*
+* @publicDocs
+*/
 const NO_QUANTITY_LIMIT = Infinity;
 /**
-* Clamps a raw value to a valid integer quantity within `min`/`max` bounds.
+* Turns a raw value, such as text from a quantity input, into a whole-number quantity between a minimum and a maximum.
 *
-* Parses strings, rounds floats, and falls back to `min` for unparseable input.
-* Used internally by the cart form system to sanitize user-typed quantities.
+* The function parses strings and rounds decimals. Input that the function can't parse returns the minimum.
 *
+* @param raw The value to turn into a quantity.
+* @param options The lower and upper bounds. The `min` option defaults to `1`, and `max` defaults to no limit. To stop at available stock, pass the variant's available quantity as `max`.
+* @returns The rounded quantity, between the minimum and the maximum.
 * @example
 * ```ts
 * sanitizeQuantity("3")           // → 3
@@ -17,6 +27,7 @@ const NO_QUANTITY_LIMIT = Infinity;
 * sanitizeQuantity(5, { max: 3 }) // → 3
 * sanitizeQuantity(0, { min: 1 }) // → 1
 * ```
+* @publicDocs
 */
 function sanitizeQuantity(raw, options) {
 	const min = options?.min ?? 1;

package/dist/development/core/cart/quantity.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"quantity.mjs","names":[],"sources":["../../../../src/core/cart/quantity.ts"],"sourcesContent":["/** Default lower bound for {@link sanitizeQuantity} when no `min` is given. */\nexport const DEFAULT_MINIMUM_QUANTITY = 1;\n\n/** Sentinel upper bound for {@link sanitizeQuantity} meaning \"no maximum\". */\nexport const NO_QUANTITY_LIMIT = Infinity;\n\n/**\n * Clamps a raw value to a valid integer quantity within `min`/`max` bounds.\n *\n * Parses strings, rounds floats, and falls back to `min` for unparseable input.\n * Used internally by the cart form system to sanitize user-typed quantities.\n *\n * @example\n * ```ts\n * sanitizeQuantity(\"3\")           // → 3\n * sanitizeQuantity(\"2.7\")         // → 3\n * sanitizeQuantity(\"abc\")         // → 1 (falls back to min)\n * sanitizeQuantity(5, { max: 3 }) // → 3\n * sanitizeQuantity(0, { min: 1 }) // → 1\n * ```\n */\nexport function sanitizeQuantity(raw: unknown, options?: { min?: number; max?: number }): number {\n  const min = options?.min ?? DEFAULT_MINIMUM_QUANTITY;\n  const max = options?.max ?? NO_QUANTITY_LIMIT;\n\n  const parsed = Number(String(raw).trim());\n  if (Number.isNaN(parsed)) return min;\n\n  const rounded = Math.round(parsed);\n  return Math.min(Math.max(rounded, min), max);\n}\n"],"mappings":";;AACA,MAAa,2BAA2B;;AAGxC,MAAa,oBAAoB;;;;;;;;;;;;;;;;AAiBjC,SAAgB,iBAAiB,KAAc,SAAkD;CAC/F,MAAM,MAAM,SAAS;CACrB,MAAM,MAAM,SAAS;CAErB,MAAM,SAAS,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC;AACzC,KAAI,OAAO,MAAM,OAAO,CAAE,QAAO;AAGjC,QAAO,KAAK,IAAI,KAAK,IADL,KAAK,MAAM,OACK,EAAE,IAAI,EAAE,IAAI"}
+{"version":3,"file":"quantity.mjs","names":[],"sources":["../../../../src/core/cart/quantity.ts"],"sourcesContent":["/**\n * The minimum quantity that sanitizeQuantity uses when you omit `min`.\n *\n * @publicDocs\n */\nexport const DEFAULT_MINIMUM_QUANTITY = 1;\n\n/**\n * The maximum quantity that sanitizeQuantity uses when you omit `max`. The value, `Infinity`, sets no upper limit.\n *\n * @publicDocs\n */\nexport const NO_QUANTITY_LIMIT = Infinity;\n\n/**\n * Turns a raw value, such as text from a quantity input, into a whole-number quantity between a minimum and a maximum.\n *\n * The function parses strings and rounds decimals. Input that the function can't parse returns the minimum.\n *\n * @param raw The value to turn into a quantity.\n * @param options The lower and upper bounds. The `min` option defaults to `1`, and `max` defaults to no limit. To stop at available stock, pass the variant's available quantity as `max`.\n * @returns The rounded quantity, between the minimum and the maximum.\n * @example\n * ```ts\n * sanitizeQuantity(\"3\")           // → 3\n * sanitizeQuantity(\"2.7\")         // → 3\n * sanitizeQuantity(\"abc\")         // → 1 (falls back to min)\n * sanitizeQuantity(5, { max: 3 }) // → 3\n * sanitizeQuantity(0, { min: 1 }) // → 1\n * ```\n * @publicDocs\n */\nexport function sanitizeQuantity(raw: unknown, options?: { min?: number; max?: number }): number {\n  const min = options?.min ?? DEFAULT_MINIMUM_QUANTITY;\n  const max = options?.max ?? NO_QUANTITY_LIMIT;\n\n  const parsed = Number(String(raw).trim());\n  if (Number.isNaN(parsed)) return min;\n\n  const rounded = Math.round(parsed);\n  return Math.min(Math.max(rounded, min), max);\n}\n"],"mappings":";;;;;;AAKA,MAAa,2BAA2B;;;;;;AAOxC,MAAa,oBAAoB;;;;;;;;;;;;;;;;;;;AAoBjC,SAAgB,iBAAiB,KAAc,SAAkD;CAC/F,MAAM,MAAM,SAAS;CACrB,MAAM,MAAM,SAAS;CAErB,MAAM,SAAS,OAAO,OAAO,IAAI,CAAC,MAAM,CAAC;AACzC,KAAI,OAAO,MAAM,OAAO,CAAE,QAAO;AAGjC,QAAO,KAAK,IAAI,KAAK,IADL,KAAK,MAAM,OACK,EAAE,IAAI,EAAE,IAAI"}