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

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

@@ -1,4 +1,19 @@
 //#region src/core/cart/cookie.d.ts
+/**
+ * Serializes a cart GID into a `Set-Cookie` header value.
+ *
+ * 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`.
+ *
+ * @example
+ * ```ts
+ * const cookie = createCartCookie("gid://shopify/Cart/abc123");
+ * // "cart=abc123; Path=/; SameSite=Lax; Max-Age=1209600"
+ *
+ * headers.append("Set-Cookie", cookie);
+ * ```
+ */
 declare function createCartCookie(cartId: string): string;
 //#endregion
 export { createCartCookie };

package/dist/core/cart/cookie.mjs

@@ -15,6 +15,21 @@ function getCartIdFromCookie(input) {
 	if (!token) return null;
 	return normalizeCartId(token);
 }
+/**
+* Serializes a cart GID into a `Set-Cookie` header value.
+*
+* 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`.
+*
+* @example
+* ```ts
+* const cookie = createCartCookie("gid://shopify/Cart/abc123");
+* // "cart=abc123; Path=/; SameSite=Lax; Max-Age=1209600"
+*
+* headers.append("Set-Cookie", cookie);
+* ```
+*/
 function createCartCookie(cartId) {
 	const token = cartId.startsWith(CART_GID_PREFIX) ? cartId.slice(19) : cartId;
 	return `${COOKIE_NAME}=${encodeURIComponent(token)}; Path=/; SameSite=Lax; Max-Age=${MAX_AGE_IN_SECONDS}`;

package/dist/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\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;;AAG/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 * 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"}

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

@@ -1,10 +1,24 @@
 //#region src/core/cart/form.d.ts
+/**
+ * HTML attributes for a hidden submit button that triggers the `"set"` intent.
+ *
+ * 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.
+ */
 interface SetButtonAttributes {
   name: "intent";
   value: "set";
   type: "submit";
   hidden: true;
 }
+/**
+ * HTML attributes for a quantity `<input>` in interactive mode.
+ *
+ * Returned by `register("quantity", { value, interactive: true })`. Uses
+ * `type: "text"` with `inputMode: "numeric"` for mobile number keyboards
+ * without the native spinner arrows.
+ */
 interface QuantityInputAttributes {
   name: "quantity";
   value: string;
@@ -15,6 +29,35 @@ interface QuantityInputAttributes {
   autoCorrect: "off";
 }
 type AttributeValueName = `attributes.${string}`;
+/**
+ * Overloaded function that produces the correct HTML attributes for any 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.
+ *
+ * @example
+ * ```tsx
+ * const register = createCartFormRegister();
+ *
+ * // Line ID field (register returns readOnly; add type="hidden" to hide it)
+ * <input {...register("lineId", { value: line.id })} />
+ *
+ * // Interactive quantity input (pair with attachQuantityInput to auto-submit on change)
+ * <input {...register("quantity", { value: line.quantity, interactive: true })} />
+ *
+ * // Hidden submit button for the "set" intent
+ * <button {...register("set")} />
+ *
+ * // Increase quantity button
+ * <button {...register("increase")}>+</button>
+ * ```
+ *
+ * @throws `TypeError` when called with `"attributeValue"` and no non-empty `key`.
+ */
 type CartFormRegister = {
   (field: "lineId", opts: {
     value: string;
@@ -124,6 +167,24 @@ type CartFormRegister = {
     value: "attributes-update";
   };
 };
+/**
+ * Creates a {@link CartFormRegister} function for generating cart form field attributes.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * const register = createCartFormRegister();
+ *
+ * const lineIdAttrs = register("lineId", { value: "gid://shopify/CartLine/123" });
+ * // → { name: "lineId", value: "gid://shopify/CartLine/123", readOnly: true }
+ *
+ * const addAttrs = register("add");
+ * // → { name: "intent", value: "add" }
+ * ```
+ */
 declare function createCartFormRegister(): CartFormRegister;
 //#endregion
 export { CartFormRegister, QuantityInputAttributes, SetButtonAttributes, createCartFormRegister };

package/dist/core/cart/form.mjs

@@ -53,6 +53,24 @@ function createFieldAttributes(name, opts) {
 	if (name === "lineId") attrs.readOnly = true;
 	return attrs;
 }
+/**
+* Creates a {@link CartFormRegister} function for generating cart form field attributes.
+*
+* 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.
+*
+* @example
+* ```ts
+* const register = createCartFormRegister();
+*
+* const lineIdAttrs = register("lineId", { value: "gid://shopify/CartLine/123" });
+* // → { name: "lineId", value: "gid://shopify/CartLine/123", readOnly: true }
+*
+* const addAttrs = register("add");
+* // → { name: "intent", value: "add" }
+* ```
+*/
 function createCartFormRegister() {
 	return ((nameOrAction, opts) => {
 		if (nameOrAction === "attributeValue") return createAttributeValueAttributes(opts);

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

@@ -1 +1 @@
-{"version":3,"file":"form.mjs","names":[],"sources":["../../../src/core/cart/form.ts"],"sourcesContent":["export interface SetButtonAttributes {\n  name: \"intent\";\n  value: \"set\";\n  type: \"submit\";\n  hidden: true;\n}\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\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\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":";AAuDA,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;;AAGT,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 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"}

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

@@ -6,19 +6,60 @@ import { cartQueries } from "./queries.mjs";
 
 //#region src/core/cart/get-cart.d.ts
 type MergeCartData<TCart> = Omit<CartData, keyof TCart> & TCart;
+/**
+ * Infers the {@link CartData} shape from a custom Storefront API cart query string.
+ *
+ * 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.
+ */
 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. */
 type CartResult<TCart extends CartData = CartData> = {
-  cart: TCart | null;
+  /** The cart, or `null` when no cart exists or the query failed. */cart: TCart | null;
   errors?: Array<{
     message: string;
-  }>;
+  }>; /** Response headers from the Storefront API (e.g. cache directives). */
   headers: Headers;
 };
 type StorefrontCartClient = Pick<StorefrontClient, "graphql">;
 type CartIdSource = Request | Pick<ShopifyRequestContext, "cookie" | "url">;
+/**
+ * Extracts the cart GID 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.
+ *
+ * @example
+ * ```ts
+ * // In a framework loader
+ * const cartId = getCartId(request);
+ * if (cartId) {
+ *   const { cart } = await getCart(cartId, storefront);
+ * }
+ * ```
+ */
 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.
+ *
+ * @example
+ * ```ts
+ * const cartId = getCartId(request);
+ * const { cart, errors, headers } = await getCart(cartId, storefront);
+ *
+ * // With a custom query
+ * const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);
+ * ```
+ */
 declare function getCart<TQuery extends AnyStorefrontQueryString = typeof cartQueries.cart>(cartId: string | null, storefront: StorefrontCartClient, cartQuery?: TQuery): Promise<CartResult<CartDataFromQuery<TQuery>>>;
 //#endregion
 export { CartDataFromQuery, CartResult, getCart, getCartId };

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

@@ -2,6 +2,22 @@ import { getCartIdFromCookie } from "./cookie.mjs";
 import { cartQueries } from "./queries.mjs";
 
 //#region src/core/cart/get-cart.ts
+/**
+* Extracts the cart GID 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.
+*
+* @example
+* ```ts
+* // In a framework loader
+* const cartId = getCartId(request);
+* if (cartId) {
+*   const { cart } = await getCart(cartId, storefront);
+* }
+* ```
+*/
 function getCartId(input) {
 	if (input.url) {
 		const cartId = new URL(input.url, "https://hydrogen.local").searchParams.get("cartId");
@@ -9,6 +25,23 @@ function getCartId(input) {
 	}
 	return getCartIdFromCookie(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.
+*
+* @example
+* ```ts
+* const cartId = getCartId(request);
+* const { cart, errors, headers } = await getCart(cartId, storefront);
+*
+* // With a custom query
+* const { cart } = await getCart(cartId, storefront, CUSTOM_CART_QUERY);
+* ```
+*/
 async function getCart(cartId, storefront, cartQuery = cartQueries.cart) {
 	if (!cartId) return {
 		cart: null,

package/dist/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\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\nexport type CartResult<TCart extends CartData = CartData> = {\n  cart: TCart | null;\n  errors?: Array<{ message: string }>;\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\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\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":";;;;AAuCA,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;;AAGnC,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\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"}

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

@@ -1,5 +1,5 @@
 import { Attribute, CartCost, CartData, CartErrorGroup, CartErrorState, CartLine, CartLineConnection, CartLineCost, CartLineMerchandise, CartNetworkEntry, CartPending, CartState, CartUserError, CartWarning, DiscountCode, EMPTY_CART_DATA, EMPTY_CART_STATE, createEmptyCartErrors, createEmptyErrorGroup } from "./state.mjs";
-import { CartNetworkError, CartStore, CreateCartStoreOptions, STANDARD_ACTION_TIMEOUT_IN_MS, configureCartEndpoint, createCartStore } from "./cart.mjs";
+import { CartActions, CartNetworkError, CartStore, CreateCartStoreOptions, STANDARD_ACTION_TIMEOUT_IN_MS, configureCartEndpoint, createCartStore } from "./cart.mjs";
 import { CartFormRegister, QuantityInputAttributes, SetButtonAttributes, createCartFormRegister } from "./form.mjs";
 import { attachQuantityInput } from "./attach-quantity-input.mjs";
 import { CartAction, CartAttributeInput, CartLineAddInput, CartLineUpdateInput, parseCartRequest } from "./actions.mjs";

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

@@ -1,6 +1,23 @@
 //#region src/core/cart/quantity.d.ts
+/** Default lower bound for {@link sanitizeQuantity} when no `min` is given. */
 declare const DEFAULT_MINIMUM_QUANTITY = 1;
+/** Sentinel upper bound for {@link sanitizeQuantity} meaning "no maximum". */
 declare const NO_QUANTITY_LIMIT: number;
+/**
+ * Clamps a raw value to a valid integer quantity within `min`/`max` bounds.
+ *
+ * Parses strings, rounds floats, and falls back to `min` for unparseable input.
+ * Used internally by the cart form system to sanitize user-typed quantities.
+ *
+ * @example
+ * ```ts
+ * sanitizeQuantity("3")           // → 3
+ * sanitizeQuantity("2.7")         // → 3
+ * sanitizeQuantity("abc")         // → 1 (falls back to min)
+ * sanitizeQuantity(5, { max: 3 }) // → 3
+ * sanitizeQuantity(0, { min: 1 }) // → 1
+ * ```
+ */
 declare function sanitizeQuantity(raw: unknown, options?: {
   min?: number;
   max?: number;

package/dist/core/cart/quantity.mjs

@@ -1,6 +1,23 @@
 //#region src/core/cart/quantity.ts
+/** Default lower bound for {@link sanitizeQuantity} when no `min` is given. */
 const DEFAULT_MINIMUM_QUANTITY = 1;
+/** Sentinel upper bound for {@link sanitizeQuantity} meaning "no maximum". */
 const NO_QUANTITY_LIMIT = Infinity;
+/**
+* Clamps a raw value to a valid integer quantity within `min`/`max` bounds.
+*
+* Parses strings, rounds floats, and falls back to `min` for unparseable input.
+* Used internally by the cart form system to sanitize user-typed quantities.
+*
+* @example
+* ```ts
+* sanitizeQuantity("3")           // → 3
+* sanitizeQuantity("2.7")         // → 3
+* sanitizeQuantity("abc")         // → 1 (falls back to min)
+* sanitizeQuantity(5, { max: 3 }) // → 3
+* sanitizeQuantity(0, { min: 1 }) // → 1
+* ```
+*/
 function sanitizeQuantity(raw, options) {
 	const min = options?.min ?? 1;
 	const max = options?.max ?? Infinity;

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

@@ -1 +1 @@
-{"version":3,"file":"quantity.mjs","names":[],"sources":["../../../src/core/cart/quantity.ts"],"sourcesContent":["export const DEFAULT_MINIMUM_QUANTITY = 1;\nexport const NO_QUANTITY_LIMIT = Infinity;\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":";AAAA,MAAa,2BAA2B;AACxC,MAAa,oBAAoB;AAEjC,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":["/** 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"}