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

package/dist/core/analytics/types.d.mts

@@ -3,23 +3,81 @@ import { ShopifyScriptsShop } from "../shopify-scripts/types.mjs";
 
 //#region src/core/analytics/types.d.ts
 type ShopAnalyticsBase = Pick<ShopifyScriptsShop, "shopId">;
+/** Discriminant for the analytics channel a storefront is running under. */
 type ShopAnalyticsChannel = "hydrogen" | "headless";
+/**
+ * Identifies the shop and channel for every analytics payload.
+ *
+ * The `"hydrogen"` variant carries the Hydrogen sales channel's `storefrontId`;
+ * the `"headless"` variant omits it, because analytics for the Headless channel
+ * isn't attributed to a specific storefront.
+ */
 type ShopAnalytics = (ShopAnalyticsBase & {
-  channel: "hydrogen";
+  /** The storefront is served by the Hydrogen sales channel. */channel: "hydrogen"; /** ID of the Hydrogen storefront that analytics are attributed to. */
   storefrontId: ShopifyScriptsShop["storefrontId"];
 }) | (ShopAnalyticsBase & {
-  channel: "headless";
+  /** The storefront uses the generic Headless sales channel. */channel: "headless";
   storefrontId?: never;
 });
+type ConsentPreferences = {
+  analytics: boolean;
+  marketing: boolean;
+  preferences: boolean;
+  sale_of_data: boolean;
+};
+/**
+ * Connects a consent provider once per analytics bus, after Shopify's consent API has loaded.
+ * Use window.Shopify.customerPrivacy to synchronize consent.
+ * Resolve only after the provider has a saved choice or the shopper interacts, and that
+ * consent has been synchronized with Shopify. Hydrogen then checks consent and replays
+ * allowed events. Rejection keeps delivery blocked. The integration stays active
+ * across component unmounts.
+ */
+type ConsentSetup = () => Promise<void>;
+/**
+ * Chooses which Shopify consent script `ShopifyScripts` loads and when the
+ * analytics bus releases events to destinations.
+ *
+ * - `"default-banner"` loads Shopify's hosted privacy banner. If the visitor
+ *   must see the banner, destinations wait until they accept or decline;
+ *   otherwise events are released as soon as the consent API loads.
+ * - `"custom-banner"` loads only the Customer Privacy API and requires a
+ *   `setup` callback that integrates a third-party consent provider.
+ *   Events release once the `setup` callback resolves.
+ * - `"no-banner"` (or omitted) loads only the Customer Privacy API and
+ *   releases events once it loads.
+ *
+ * In every mode, destinations only receive events while analytics processing is
+ * allowed.
+ */
 type ConsentConfig = {
-  mode?: "default-banner" | "custom-banner" | "no-banner";
+  mode?: "no-banner";
+  setup?: never;
+} | {
+  mode: "default-banner";
+  setup?: never;
+} | {
+  mode: "custom-banner";
+  setup: ConsentSetup;
 };
+/**
+ * Lightweight cart line shape for analytics payloads.
+ *
+ * Mirrors the Storefront API `CartLine` fields needed for tracking without
+ * depending on the cart store's `CartData` type, so the analytics bus stays
+ * framework-agnostic.
+ */
 type AnalyticsCartLine = {
   id: string;
   quantity: number;
   merchandise: {
     id: string;
-    title: string;
+    /**
+     * Variant title (`"Default Title"` for single-variant products).
+     * `trackCartAnalytics` falls back to the product title only when the cart
+     * fragment doesn't select it.
+     */
+    title: string; /** Per-unit price (`CartLine.cost.amountPerQuantity`). */
     price: {
       amount: string;
       currencyCode?: string;
@@ -34,8 +92,17 @@ type AnalyticsCartLine = {
     };
   };
 };
+/**
+ * Lightweight cart snapshot included in cart analytics payloads.
+ *
+ * Accepts both `nodes` and `edges` connection shapes so the analytics layer
+ * works regardless of which Storefront API query pattern the storefront uses.
+ */
 type AnalyticsCart = {
   id: string;
+  /**
+   * `Cart.updatedAt` (ISO 8601), used to deduplicate cart events.
+   */
   updatedAt: string;
   cost?: {
     subtotalAmount?: {
@@ -44,7 +111,7 @@ type AnalyticsCart = {
     totalAmount?: {
       currencyCode?: string;
     };
-  };
+  }; /** Cart lines in Storefront API connection format. */
   lines: {
     nodes?: AnalyticsCartLine[];
     edges?: Array<{
@@ -53,6 +120,7 @@ type AnalyticsCart = {
   };
   [key: string]: unknown;
 };
+/** Index signature that allows arbitrary extra keys on a payload. */
 type OtherData = {
   [key: string]: unknown;
 };
@@ -63,9 +131,10 @@ type BasePayload = {
 type UrlPayload = {
   url?: string;
 };
+/** Describes a single product for `product_viewed` payloads. */
 type ProductPayload = {
   id: string;
-  title: string;
+  title: string; /** Decimal amount string for the selected variant (e.g. `"19.99"`). */
   price: string;
   vendor: string;
   variantId: string;
@@ -97,14 +166,30 @@ type CartLinePayload = {
   prevLine?: AnalyticsCartLine;
   currentLine?: AnalyticsCartLine;
 };
+/** Payload for `page_viewed` events. */
 type PageViewPayload = UrlPayload & BasePayload;
+/** Payload for `product_viewed` events. */
 type ProductViewPayload = ProductsPayload & UrlPayload & BasePayload;
+/** Payload for `collection_viewed` events. */
 type CollectionViewPayload = CollectionPayload & UrlPayload & BasePayload;
+/** Payload for `cart_viewed` events. */
 type CartViewPayload = CartPayload & UrlPayload & BasePayload;
+/** Payload for `search_viewed` events. */
 type SearchViewPayload = SearchPayload & UrlPayload & BasePayload;
+/** Payload for `cart_updated` events. `prevCart` is `null` when there was no earlier snapshot. */
 type CartUpdatePayload = CartChangePayload & BasePayload & OtherData;
+/**
+ * Payload for `product_added_to_cart` and `product_removed_from_cart` events.
+ * New lines have only `currentLine`, removed lines have only `prevLine`, and
+ * quantity changes have both.
+ */
 type CartLineUpdatePayload = CartLinePayload & CartChangePayload & BasePayload & OtherData;
-type EventPayloads = PageViewPayload | ProductViewPayload | CollectionViewPayload | CartViewPayload | SearchViewPayload | CartUpdatePayload | CartLineUpdatePayload;
+/**
+ * Maps each analytics event name to its payload type.
+ *
+ * TypeScript uses this to infer the correct payload when you call
+ * `publish()` or a destination's `subscribe()` with a specific event name.
+ */
 interface AnalyticsEventMap {
   page_viewed: PageViewPayload;
   product_viewed: ProductViewPayload;
@@ -118,26 +203,77 @@ interface AnalyticsEventMap {
 /** Resolves the payload type for a supported analytics event name. */
 type PayloadFor<E extends AnalyticsEventName> = AnalyticsEventMap[E];
 type PublishPayloadArgs<E extends AnalyticsEventName> = {} extends PayloadFor<E> ? [payload?: PayloadFor<E>] : [payload: PayloadFor<E>];
+/**
+ * Analytics bus configuration, built by `ShopifyScripts` from its `shop`,
+ * `consent`, and `analytics` options.
+ */
 type StorefrontAnalyticsConfig = {
-  shop: ShopAnalytics | null;
-  consent: ConsentConfig;
+  /** Shop identity and channel for analytics payloads. */shop: ShopAnalytics | null; /** Serializable consent settings. The provider setup callback stays in the client bundle. */
+  consent: Pick<ConsentConfig, "mode">;
+  /**
+   * Extra key-value pairs accessible to destinations via `getConfig().customData`.
+   * Not added to events you publish.
+   */
   customData?: Record<string, unknown>;
 };
+/**
+ * Visitor identifiers from Shopify's Customer Privacy API, used to correlate
+ * analytics events. See `getTrackingValues` for when they are empty.
+ */
+type AnalyticsTrackingValues = {
+  /** Long-lived browser identifier; persists across visits. */uniqueToken: string; /** Session identifier (30-minute rolling expiry). */
+  visitToken: string;
+};
+/** Context provided to destination callbacks alongside each event payload. */
+type StorefrontAnalyticsDestinationEventContext = {
+  /**
+   * Reads current tokens from the consent API. Returns empty strings when tokens are
+   * unavailable or analytics tracking is not currently allowed.
+   */
+  getTrackingValues: () => AnalyticsTrackingValues;
+};
+/** Context passed into a destination's `setup()` function. */
 type StorefrontAnalyticsDestinationSetupContext = {
-  subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>) => void) => () => void;
+  /** Subscribe to an analytics event. Returns an unsubscribe function. */subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>, context: StorefrontAnalyticsDestinationEventContext) => void) => () => void; /** Returns the current analytics bus configuration. */
   getConfig: () => StorefrontAnalyticsConfig;
 };
+/**
+ * A consent-gated analytics integration that receives events after consent is granted.
+ *
+ * Destinations subscribe to events during `setup()` and receive live delivery
+ * plus replayed buffered events once tracking is allowed. Return a cleanup
+ * function from `setup()` to tear down side effects when the destination is
+ * removed via the function returned by `addDestination()`. The bus itself lives
+ * for the page's lifetime.
+ */
 type StorefrontAnalyticsDestination = {
-  name: string;
+  /** Unique name for this destination — duplicates are rejected with a warning. */name: string;
+  /**
+   * Runs immediately when the destination is added, before consent is known, so
+   * don't load third-party scripts or set cookies here. Subscribe via the context.
+   * May be async: buffered events replay after it resolves (once tracking is
+   * allowed). If it throws or rejects, the destination is removed.
+   */
   setup: (context: StorefrontAnalyticsDestinationSetupContext) => void | (() => void) | Promise<void | (() => void)>;
 };
+/**
+ * The framework-agnostic analytics event bus that `ShopifyScripts` exposes on
+ * `window.Shopify.analytics`.
+ *
+ * Storefronts publish events (page views, product views, cart changes) via
+ * `publish()`. Consent-gated tracking integrations register through
+ * `addDestination()` and receive buffered events once consent is granted.
+ */
 type StorefrontAnalytics = {
-  publish: <E extends AnalyticsEventName>(event: E, ...payload: PublishPayloadArgs<E>) => void; /** Listen for live analytics events. Destination integrations should use `addDestination()`. */
-  subscribe: <E extends AnalyticsEventName>(event: E, callback: (payload: PayloadFor<E>) => void) => () => void;
-  addDestination: (destination: StorefrontAnalyticsDestination) => () => void;
-  destroy: () => void;
+  /**
+   * Emits an event to destinations while tracking is allowed. Otherwise the
+   * event goes into a bounded replay buffer. Fills in `shop` and (for view
+   * events) `url` when omitted.
+   */
+  publish: <E extends AnalyticsEventName>(event: E, ...payload: PublishPayloadArgs<E>) => void; /** Register a consent-gated destination integration. Returns a removal function. */
+  addDestination: (destination: StorefrontAnalyticsDestination) => () => void; /** Returns the bus configuration; `shop.shopId` is normalized to a Shop GID. */
   getConfig: () => StorefrontAnalyticsConfig;
 };
 //#endregion
-export { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, EventPayloads, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, ShopAnalyticsChannel, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationSetupContext };
+export { AnalyticsCart, AnalyticsCartLine, AnalyticsEventMap, AnalyticsTrackingValues, CartLineUpdatePayload, CartUpdatePayload, CartViewPayload, CollectionViewPayload, ConsentConfig, ConsentPreferences, ConsentSetup, OtherData, PageViewPayload, PayloadFor, ProductPayload, ProductViewPayload, SearchViewPayload, ShopAnalytics, ShopAnalyticsChannel, StorefrontAnalytics, StorefrontAnalyticsConfig, StorefrontAnalyticsDestination, StorefrontAnalyticsDestinationEventContext, StorefrontAnalyticsDestinationSetupContext };
 //# sourceMappingURL=types.d.mts.map

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

@@ -1,20 +1,37 @@
 //#region src/core/cart/actions.d.ts
+/** A key-value pair attached to the cart or an individual cart line. */
 type CartAttributeInput = {
   key: string;
   value: string;
 };
 type CartLineAddInput = {
-  merchandiseId: string;
+  /** Storefront API GID of the product variant to add. */merchandiseId: string;
   quantity: number;
-  attributes?: CartAttributeInput[];
+  attributes?: CartAttributeInput[]; /** Selling plan GID for subscription line items. */
   sellingPlanId?: string;
 };
+/** Input for updating an existing cart line. Setting `quantity` to `0` removes the line. */
 type CartLineUpdateInput = {
-  id: string;
+  /** The `CartLine.id` of the line to update. */id: string;
   quantity: number;
   attributes?: CartAttributeInput[];
   sellingPlanId?: string;
 };
+/**
+ * Discriminated union of all cart mutation intents.
+ *
+ * {@link parseCartRequest} normalizes both JSON and FormData requests into one
+ * of these variants. The `intent` field determines the Storefront API mutation:
+ *
+ * - `"add"` — add new lines (cartLinesAdd, or cartCreate when no cart exists)
+ * - `"update"` — change quantity or attributes on existing lines (cartLinesUpdate)
+ * - `"remove"` — remove lines by ID (cartLinesRemove)
+ * - `"discount-update"` — replace all discount codes (cartDiscountCodesUpdate)
+ * - `"discount-apply"` — add a single discount code (read-then-write via cartDiscountCodesUpdate)
+ * - `"discount-remove"` — remove a single discount code (read-then-write via cartDiscountCodesUpdate)
+ * - `"attributes-update"` — set cart-level attributes (cartAttributesUpdate)
+ * - `"note-update"` — set the cart note (cartNoteUpdate)
+ */
 type CartAction = {
   intent: "add";
   lines: CartLineAddInput[];
@@ -44,6 +61,33 @@ type ParsedCartRequest = {
   action: CartAction;
   cartId: string | null;
 };
+/**
+ * Parses an incoming cart mutation request into a typed {@link CartAction}.
+ *
+ * Accepts `application/json` and `application/x-www-form-urlencoded` /
+ * `multipart/form-data` content types. JSON and FormData each support a
+ * different subset of intents — JSON produces `discount-update` while
+ * FormData produces `discount-apply` / `discount-remove`.
+ *
+ * FormData requests always return `cartId: null` — the server handler
+ * should fall back to the cart cookie.
+ *
+ * @throws If the content-type is unsupported, the intent is unrecognized,
+ * or required fields are missing.
+ *
+ * @example
+ * ```ts
+ * const { action, cartId } = await parseCartRequest(request);
+ *
+ * switch (action.intent) {
+ *   case "add":
+ *     return cartLinesAdd(cartId ?? getCartId(request), action.lines);
+ *   case "remove":
+ *     return cartLinesRemove(cartId ?? getCartId(request), action.lineIds);
+ *   // ...
+ * }
+ * ```
+ */
 declare function parseCartRequest(request: Request): Promise<ParsedCartRequest>;
 //#endregion
 export { CartAction, CartAttributeInput, CartLineAddInput, CartLineUpdateInput, parseCartRequest };

package/dist/core/cart/actions.mjs

@@ -8,6 +8,33 @@ var CartActionError = class extends Error {
 		this.name = "CartActionError";
 	}
 };
+/**
+* Parses an incoming cart mutation request into a typed {@link CartAction}.
+*
+* Accepts `application/json` and `application/x-www-form-urlencoded` /
+* `multipart/form-data` content types. JSON and FormData each support a
+* different subset of intents — JSON produces `discount-update` while
+* FormData produces `discount-apply` / `discount-remove`.
+*
+* FormData requests always return `cartId: null` — the server handler
+* should fall back to the cart cookie.
+*
+* @throws If the content-type is unsupported, the intent is unrecognized,
+* or required fields are missing.
+*
+* @example
+* ```ts
+* const { action, cartId } = await parseCartRequest(request);
+*
+* switch (action.intent) {
+*   case "add":
+*     return cartLinesAdd(cartId ?? getCartId(request), action.lines);
+*   case "remove":
+*     return cartLinesRemove(cartId ?? getCartId(request), action.lineIds);
+*   // ...
+* }
+* ```
+*/
 async function parseCartRequest(request) {
 	const contentType = request.headers.get("content-type") ?? "";
 	if (contentType.includes("application/json")) return parseJsonBody(await request.json());
@@ -182,6 +209,8 @@ function parseAddIntent(form, merchandiseId) {
 		quantity
 	};
 	if (sellingPlanId) line.sellingPlanId = sellingPlanId;
+	const rawAttributes = getCartAttributeFormEntries(form);
+	if (rawAttributes.length > 0) line.attributes = parseAttributes(rawAttributes);
 	return {
 		intent: "add",
 		lines: [line]

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

@@ -1 +1 @@
-{"version":3,"file":"actions.mjs","names":[],"sources":["../../../src/core/cart/actions.ts"],"sourcesContent":["import { normalizeCartId } from \"./cookie\";\nimport { getCartAttributeFormEntries } from \"./form\";\n\nexport type CartAttributeInput = { key: string; value: string };\n\nexport type CartLineAddInput = {\n  merchandiseId: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  sellingPlanId?: string;\n};\n\nexport type CartLineUpdateInput = {\n  id: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  sellingPlanId?: string;\n};\n\nexport type CartAction =\n  | { intent: \"add\"; lines: CartLineAddInput[] }\n  | { intent: \"update\"; lines: CartLineUpdateInput[] }\n  | { intent: \"remove\"; lineIds: string[] }\n  | { intent: \"discount-update\"; discountCodes: string[] }\n  | { intent: \"discount-apply\"; code: string }\n  | { intent: \"discount-remove\"; code: string }\n  | { intent: \"attributes-update\"; attributes: CartAttributeInput[] }\n  | { intent: \"note-update\"; note: string };\n\ntype ParsedCartRequest = {\n  action: CartAction;\n  cartId: string | null;\n};\n\nclass CartActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CartActionError\";\n  }\n}\n\nexport async function parseCartRequest(request: Request): Promise<ParsedCartRequest> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n\n  if (contentType.includes(\"application/json\")) {\n    return parseJsonBody(await request.json());\n  }\n\n  if (\n    contentType.includes(\"application/x-www-form-urlencoded\") ||\n    contentType.includes(\"multipart/form-data\")\n  ) {\n    return { action: parseFormData(await request.formData()), cartId: null };\n  }\n\n  throw new CartActionError(\n    `Unsupported content-type: \"${contentType}\". Expected application/json or form data.`,\n  );\n}\n\n// --- JSON parsing ---\n\nfunction parseJsonBody(body: unknown): ParsedCartRequest {\n  assertObject(body);\n  const cartId = typeof body.cartId === \"string\" ? normalizeCartId(body.cartId) : null;\n\n  if (\"note\" in body && typeof body.note === \"string\") {\n    return { action: { intent: \"note-update\", note: body.note }, cartId };\n  }\n\n  if (\"discountCodes\" in body && Array.isArray(body.discountCodes)) {\n    for (const code of body.discountCodes) {\n      assertString(code, \"discountCodes entries\");\n    }\n    return {\n      action: { intent: \"discount-update\", discountCodes: body.discountCodes as string[] },\n      cartId,\n    };\n  }\n\n  if (\"attributes\" in body && Array.isArray(body.attributes)) {\n    return {\n      action: { intent: \"attributes-update\", attributes: parseAttributes(body.attributes) },\n      cartId,\n    };\n  }\n\n  if (!(\"lines\" in body) || !Array.isArray(body.lines)) {\n    throw new CartActionError(\n      'Request body must contain \"lines\", \"discountCodes\", \"attributes\", or \"note\".',\n    );\n  }\n\n  const lines = body.lines as unknown[];\n  if (lines.length === 0) {\n    throw new CartActionError(\"Lines array must not be empty.\");\n  }\n\n  return { action: partitionLines(lines), cartId };\n}\n\nfunction partitionLines(rawLines: unknown[]): CartAction {\n  const adds: CartLineAddInput[] = [];\n  const updates: CartLineUpdateInput[] = [];\n  const removeIds: string[] = [];\n\n  for (const raw of rawLines) {\n    assertObject(raw);\n    const line = raw as Record<string, unknown>;\n    const hasId = \"id\" in line && typeof line.id === \"string\" && line.id !== \"\";\n    const hasMerchandiseId =\n      \"merchandiseId\" in line &&\n      typeof line.merchandiseId === \"string\" &&\n      line.merchandiseId !== \"\";\n\n    assertNonNegativeInteger(line.quantity, \"quantity\");\n    const quantity = line.quantity as number;\n\n    if (!hasId && !hasMerchandiseId) {\n      throw new CartActionError(\n        'Each line must have either \"id\" (for update/remove) or \"merchandiseId\" (for add).',\n      );\n    }\n\n    if (hasId && (line.id as string) === \"\") {\n      throw new CartActionError('Line \"id\" must not be empty.');\n    }\n\n    const optionalFields = extractOptionalLineFields(line);\n\n    if (!hasId && hasMerchandiseId) {\n      adds.push({\n        merchandiseId: line.merchandiseId as string,\n        quantity,\n        ...optionalFields,\n      });\n    } else if (hasId && quantity === 0) {\n      removeIds.push(line.id as string);\n    } else if (hasId) {\n      updates.push({\n        id: line.id as string,\n        quantity,\n        ...optionalFields,\n      });\n    }\n  }\n\n  const populatedBuckets = [adds.length, updates.length, removeIds.length].filter(\n    (n) => n > 0,\n  ).length;\n\n  if (populatedBuckets > 1) {\n    throw new CartActionError(\n      \"Mixed line operations are not allowed. Separate add, update, and remove into distinct requests.\",\n    );\n  }\n\n  if (adds.length > 0) return { intent: \"add\", lines: adds };\n  if (updates.length > 0) return { intent: \"update\", lines: updates };\n  return { intent: \"remove\", lineIds: removeIds };\n}\n\nfunction extractOptionalLineFields(\n  line: Record<string, unknown>,\n): Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> {\n  const result: Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> = {};\n\n  if (\"attributes\" in line && Array.isArray(line.attributes)) {\n    result.attributes = line.attributes as CartAttributeInput[];\n  }\n\n  if (\"sellingPlanId\" in line && typeof line.sellingPlanId === \"string\") {\n    result.sellingPlanId = line.sellingPlanId;\n  }\n\n  return result;\n}\n\n// --- FormData parsing ---\n//\n// HTML forms can't express the same structures as JSON. Key compromises:\n//\n//   Add line:       single item per submission (forms can't batch multiple adds)\n//   Update qty:     server does the math — form sends current qty, server increments/decrements\n//   Remove line:    explicit intent field (can't express \"quantity=0 means remove\" implicitly)\n//   Discount bulk:  no FormData equivalent — forms handle one code at a time\n//   Cart attributes: attributes.<key> fields preserve each key/value relationship\n//   Selling plan:   add only — no way to change selling plan on existing line via form\n//\n// Design decisions:\n//   - `intent` field disambiguates operations (forms need explicit routing; JSON infers from structure)\n//   - Field names match where possible: merchandiseId, quantity, lineId, discountCode, note\n//   - Form submissions get 303 redirect to referer; JSON gets JSON response\n//   - `increase`/`decrease` intents exist because forms can't atomically read-modify-write quantity\n\nconst LINE_INTENTS = new Set([\"increase\", \"decrease\", \"remove\", \"set\"]);\nconst DISCOUNT_INTENTS = new Set([\"discount-apply\", \"discount-remove\"]);\n\nfunction parseFormData(form: FormData): CartAction {\n  const intent = formString(form, \"intent\");\n  const merchandiseId = formString(form, \"merchandiseId\");\n\n  if (!intent && merchandiseId) {\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (intent === \"add\") {\n    if (!merchandiseId) {\n      throw new CartActionError('Intent \"add\" requires a \"merchandiseId\" field.');\n    }\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (!intent) {\n    throw new CartActionError(\n      'FormData must include an \"intent\" field or a \"merchandiseId\" field.',\n    );\n  }\n\n  if (LINE_INTENTS.has(intent)) {\n    return parseLineIntent(intent, form);\n  }\n\n  if (DISCOUNT_INTENTS.has(intent)) {\n    return parseDiscountIntent(intent as \"discount-apply\" | \"discount-remove\", form);\n  }\n\n  if (intent === \"note-update\") {\n    return parseNoteIntent(form);\n  }\n\n  if (intent === \"attributes-update\") {\n    return parseAttributesIntent(form);\n  }\n\n  throw new CartActionError(\n    `Unknown intent \"${intent}\". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`,\n  );\n}\n\nfunction parseLineIntent(intent: string, form: FormData): CartAction {\n  const lineId = formString(form, \"lineId\");\n  if (!lineId) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"lineId\" field.`);\n  }\n\n  if (intent === \"remove\") {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n\n  const quantity = formInt(form, \"quantity\");\n  if (quantity === null) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"quantity\" field.`);\n  }\n\n  if (intent === \"set\") {\n    if (quantity <= 0) {\n      return { intent: \"remove\", lineIds: [lineId] };\n    }\n    return { intent: \"update\", lines: [{ id: lineId, quantity }] };\n  }\n\n  if (intent === \"increase\") {\n    return { intent: \"update\", lines: [{ id: lineId, quantity: quantity + 1 }] };\n  }\n\n  const decremented = quantity - 1;\n  if (decremented <= 0) {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n  return { intent: \"update\", lines: [{ id: lineId, quantity: decremented }] };\n}\n\nfunction parseDiscountIntent(\n  intent: \"discount-apply\" | \"discount-remove\",\n  form: FormData,\n): CartAction {\n  const code = formString(form, \"discountCode\");\n  if (!code) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"discountCode\" field.`);\n  }\n  return { intent, code };\n}\n\nfunction parseAddIntent(form: FormData, merchandiseId: string): CartAction {\n  const quantity = formInt(form, \"quantity\") ?? 1;\n  const sellingPlanId = formString(form, \"sellingPlanId\");\n\n  const line: CartLineAddInput = { merchandiseId, quantity };\n  if (sellingPlanId) line.sellingPlanId = sellingPlanId;\n\n  return { intent: \"add\", lines: [line] };\n}\n\nfunction parseNoteIntent(form: FormData): CartAction {\n  const noteValue = form.get(\"note\");\n  if (noteValue === null) {\n    throw new CartActionError('Intent \"note-update\" requires a \"note\" field.');\n  }\n  return { intent: \"note-update\", note: String(noteValue) };\n}\n\nfunction parseAttributesIntent(form: FormData): CartAction {\n  return {\n    intent: \"attributes-update\",\n    attributes: parseAttributes(getCartAttributeFormEntries(form)),\n  };\n}\n\nfunction parseAttributes(values: unknown[]): CartAttributeInput[] {\n  return values.map((value, index) => {\n    assertObject(value);\n    assertString(value.key, `attributes[${index}].key`);\n    assertString(value.value, `attributes[${index}].value`);\n    if (!value.key) {\n      throw new CartActionError(`Expected \"attributes[${index}].key\" not to be empty.`);\n    }\n    return { key: value.key, value: value.value };\n  });\n}\n\n// --- Assertion helpers ---\n\nfunction assertObject(value: unknown): asserts value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new CartActionError(\"Expected an object.\");\n  }\n}\n\nfunction assertString(value: unknown, label: string): asserts value is string {\n  if (typeof value !== \"string\") {\n    throw new CartActionError(`Expected \"${label}\" to be a string.`);\n  }\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value < 0) {\n    throw new CartActionError(\n      `Expected \"${label}\" to be a non-negative integer, got ${JSON.stringify(value)}.`,\n    );\n  }\n}\n\n// --- FormData field helpers ---\n\nfunction formString(form: FormData, key: string): string | null {\n  const value = form.get(key);\n  if (value === null || typeof value !== \"string\") return null;\n  return value || null;\n}\n\nfunction formInt(form: FormData, key: string): number | null {\n  const raw = form.get(key);\n  if (raw === null || typeof raw !== \"string\") return null;\n  const parsed = parseInt(raw, 10);\n  if (Number.isNaN(parsed)) return null;\n  return parsed;\n}\n"],"mappings":"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"}
+{"version":3,"file":"actions.mjs","names":[],"sources":["../../../src/core/cart/actions.ts"],"sourcesContent":["import { normalizeCartId } from \"./cookie\";\nimport { getCartAttributeFormEntries } from \"./form\";\n\n/** A key-value pair attached to the cart or an individual cart line. */\nexport type CartAttributeInput = { key: string; value: string };\n\nexport type CartLineAddInput = {\n  /** Storefront API GID of the product variant to add. */\n  merchandiseId: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  /** Selling plan GID for subscription line items. */\n  sellingPlanId?: string;\n};\n\n/** Input for updating an existing cart line. Setting `quantity` to `0` removes the line. */\nexport type CartLineUpdateInput = {\n  /** The `CartLine.id` of the line to update. */\n  id: string;\n  quantity: number;\n  attributes?: CartAttributeInput[];\n  sellingPlanId?: string;\n};\n\n/**\n * Discriminated union of all cart mutation intents.\n *\n * {@link parseCartRequest} normalizes both JSON and FormData requests into one\n * of these variants. The `intent` field determines the Storefront API mutation:\n *\n * - `\"add\"` — add new lines (cartLinesAdd, or cartCreate when no cart exists)\n * - `\"update\"` — change quantity or attributes on existing lines (cartLinesUpdate)\n * - `\"remove\"` — remove lines by ID (cartLinesRemove)\n * - `\"discount-update\"` — replace all discount codes (cartDiscountCodesUpdate)\n * - `\"discount-apply\"` — add a single discount code (read-then-write via cartDiscountCodesUpdate)\n * - `\"discount-remove\"` — remove a single discount code (read-then-write via cartDiscountCodesUpdate)\n * - `\"attributes-update\"` — set cart-level attributes (cartAttributesUpdate)\n * - `\"note-update\"` — set the cart note (cartNoteUpdate)\n */\nexport type CartAction =\n  | { intent: \"add\"; lines: CartLineAddInput[] }\n  | { intent: \"update\"; lines: CartLineUpdateInput[] }\n  | { intent: \"remove\"; lineIds: string[] }\n  | { intent: \"discount-update\"; discountCodes: string[] }\n  | { intent: \"discount-apply\"; code: string }\n  | { intent: \"discount-remove\"; code: string }\n  | { intent: \"attributes-update\"; attributes: CartAttributeInput[] }\n  | { intent: \"note-update\"; note: string };\n\ntype ParsedCartRequest = {\n  action: CartAction;\n  cartId: string | null;\n};\n\nclass CartActionError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"CartActionError\";\n  }\n}\n\n/**\n * Parses an incoming cart mutation request into a typed {@link CartAction}.\n *\n * Accepts `application/json` and `application/x-www-form-urlencoded` /\n * `multipart/form-data` content types. JSON and FormData each support a\n * different subset of intents — JSON produces `discount-update` while\n * FormData produces `discount-apply` / `discount-remove`.\n *\n * FormData requests always return `cartId: null` — the server handler\n * should fall back to the cart cookie.\n *\n * @throws If the content-type is unsupported, the intent is unrecognized,\n * or required fields are missing.\n *\n * @example\n * ```ts\n * const { action, cartId } = await parseCartRequest(request);\n *\n * switch (action.intent) {\n *   case \"add\":\n *     return cartLinesAdd(cartId ?? getCartId(request), action.lines);\n *   case \"remove\":\n *     return cartLinesRemove(cartId ?? getCartId(request), action.lineIds);\n *   // ...\n * }\n * ```\n */\nexport async function parseCartRequest(request: Request): Promise<ParsedCartRequest> {\n  const contentType = request.headers.get(\"content-type\") ?? \"\";\n\n  if (contentType.includes(\"application/json\")) {\n    return parseJsonBody(await request.json());\n  }\n\n  if (\n    contentType.includes(\"application/x-www-form-urlencoded\") ||\n    contentType.includes(\"multipart/form-data\")\n  ) {\n    return { action: parseFormData(await request.formData()), cartId: null };\n  }\n\n  throw new CartActionError(\n    `Unsupported content-type: \"${contentType}\". Expected application/json or form data.`,\n  );\n}\n\n// --- JSON parsing ---\n\nfunction parseJsonBody(body: unknown): ParsedCartRequest {\n  assertObject(body);\n  const cartId = typeof body.cartId === \"string\" ? normalizeCartId(body.cartId) : null;\n\n  if (\"note\" in body && typeof body.note === \"string\") {\n    return { action: { intent: \"note-update\", note: body.note }, cartId };\n  }\n\n  if (\"discountCodes\" in body && Array.isArray(body.discountCodes)) {\n    for (const code of body.discountCodes) {\n      assertString(code, \"discountCodes entries\");\n    }\n    return {\n      action: { intent: \"discount-update\", discountCodes: body.discountCodes as string[] },\n      cartId,\n    };\n  }\n\n  if (\"attributes\" in body && Array.isArray(body.attributes)) {\n    return {\n      action: { intent: \"attributes-update\", attributes: parseAttributes(body.attributes) },\n      cartId,\n    };\n  }\n\n  if (!(\"lines\" in body) || !Array.isArray(body.lines)) {\n    throw new CartActionError(\n      'Request body must contain \"lines\", \"discountCodes\", \"attributes\", or \"note\".',\n    );\n  }\n\n  const lines = body.lines as unknown[];\n  if (lines.length === 0) {\n    throw new CartActionError(\"Lines array must not be empty.\");\n  }\n\n  return { action: partitionLines(lines), cartId };\n}\n\nfunction partitionLines(rawLines: unknown[]): CartAction {\n  const adds: CartLineAddInput[] = [];\n  const updates: CartLineUpdateInput[] = [];\n  const removeIds: string[] = [];\n\n  for (const raw of rawLines) {\n    assertObject(raw);\n    const line = raw as Record<string, unknown>;\n    const hasId = \"id\" in line && typeof line.id === \"string\" && line.id !== \"\";\n    const hasMerchandiseId =\n      \"merchandiseId\" in line &&\n      typeof line.merchandiseId === \"string\" &&\n      line.merchandiseId !== \"\";\n\n    assertNonNegativeInteger(line.quantity, \"quantity\");\n    const quantity = line.quantity as number;\n\n    if (!hasId && !hasMerchandiseId) {\n      throw new CartActionError(\n        'Each line must have either \"id\" (for update/remove) or \"merchandiseId\" (for add).',\n      );\n    }\n\n    if (hasId && (line.id as string) === \"\") {\n      throw new CartActionError('Line \"id\" must not be empty.');\n    }\n\n    const optionalFields = extractOptionalLineFields(line);\n\n    if (!hasId && hasMerchandiseId) {\n      adds.push({\n        merchandiseId: line.merchandiseId as string,\n        quantity,\n        ...optionalFields,\n      });\n    } else if (hasId && quantity === 0) {\n      removeIds.push(line.id as string);\n    } else if (hasId) {\n      updates.push({\n        id: line.id as string,\n        quantity,\n        ...optionalFields,\n      });\n    }\n  }\n\n  const populatedBuckets = [adds.length, updates.length, removeIds.length].filter(\n    (n) => n > 0,\n  ).length;\n\n  if (populatedBuckets > 1) {\n    throw new CartActionError(\n      \"Mixed line operations are not allowed. Separate add, update, and remove into distinct requests.\",\n    );\n  }\n\n  if (adds.length > 0) return { intent: \"add\", lines: adds };\n  if (updates.length > 0) return { intent: \"update\", lines: updates };\n  return { intent: \"remove\", lineIds: removeIds };\n}\n\nfunction extractOptionalLineFields(\n  line: Record<string, unknown>,\n): Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> {\n  const result: Pick<CartLineAddInput, \"attributes\" | \"sellingPlanId\"> = {};\n\n  if (\"attributes\" in line && Array.isArray(line.attributes)) {\n    result.attributes = line.attributes as CartAttributeInput[];\n  }\n\n  if (\"sellingPlanId\" in line && typeof line.sellingPlanId === \"string\") {\n    result.sellingPlanId = line.sellingPlanId;\n  }\n\n  return result;\n}\n\n// --- FormData parsing ---\n//\n// HTML forms can't express the same structures as JSON. Key compromises:\n//\n//   Add line:       single item per submission (forms can't batch multiple adds)\n//   Update qty:     server does the math — form sends current qty, server increments/decrements\n//   Remove line:    explicit intent field (can't express \"quantity=0 means remove\" implicitly)\n//   Discount bulk:  no FormData equivalent — forms handle one code at a time\n//   Cart attributes: attributes.<key> fields preserve each key/value relationship\n//   Selling plan:   add only — no way to change selling plan on existing line via form\n//\n// Design decisions:\n//   - `intent` field disambiguates operations (forms need explicit routing; JSON infers from structure)\n//   - Field names match where possible: merchandiseId, quantity, lineId, discountCode, note\n//   - Form submissions get 303 redirect to referer; JSON gets JSON response\n//   - `increase`/`decrease` intents exist because forms can't atomically read-modify-write quantity\n\nconst LINE_INTENTS = new Set([\"increase\", \"decrease\", \"remove\", \"set\"]);\nconst DISCOUNT_INTENTS = new Set([\"discount-apply\", \"discount-remove\"]);\n\nfunction parseFormData(form: FormData): CartAction {\n  const intent = formString(form, \"intent\");\n  const merchandiseId = formString(form, \"merchandiseId\");\n\n  if (!intent && merchandiseId) {\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (intent === \"add\") {\n    if (!merchandiseId) {\n      throw new CartActionError('Intent \"add\" requires a \"merchandiseId\" field.');\n    }\n    return parseAddIntent(form, merchandiseId);\n  }\n\n  if (!intent) {\n    throw new CartActionError(\n      'FormData must include an \"intent\" field or a \"merchandiseId\" field.',\n    );\n  }\n\n  if (LINE_INTENTS.has(intent)) {\n    return parseLineIntent(intent, form);\n  }\n\n  if (DISCOUNT_INTENTS.has(intent)) {\n    return parseDiscountIntent(intent as \"discount-apply\" | \"discount-remove\", form);\n  }\n\n  if (intent === \"note-update\") {\n    return parseNoteIntent(form);\n  }\n\n  if (intent === \"attributes-update\") {\n    return parseAttributesIntent(form);\n  }\n\n  throw new CartActionError(\n    `Unknown intent \"${intent}\". Expected one of: add, increase, decrease, remove, set, discount-apply, discount-remove, attributes-update, note-update.`,\n  );\n}\n\nfunction parseLineIntent(intent: string, form: FormData): CartAction {\n  const lineId = formString(form, \"lineId\");\n  if (!lineId) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"lineId\" field.`);\n  }\n\n  if (intent === \"remove\") {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n\n  const quantity = formInt(form, \"quantity\");\n  if (quantity === null) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"quantity\" field.`);\n  }\n\n  if (intent === \"set\") {\n    if (quantity <= 0) {\n      return { intent: \"remove\", lineIds: [lineId] };\n    }\n    return { intent: \"update\", lines: [{ id: lineId, quantity }] };\n  }\n\n  if (intent === \"increase\") {\n    return { intent: \"update\", lines: [{ id: lineId, quantity: quantity + 1 }] };\n  }\n\n  const decremented = quantity - 1;\n  if (decremented <= 0) {\n    return { intent: \"remove\", lineIds: [lineId] };\n  }\n  return { intent: \"update\", lines: [{ id: lineId, quantity: decremented }] };\n}\n\nfunction parseDiscountIntent(\n  intent: \"discount-apply\" | \"discount-remove\",\n  form: FormData,\n): CartAction {\n  const code = formString(form, \"discountCode\");\n  if (!code) {\n    throw new CartActionError(`Intent \"${intent}\" requires a \"discountCode\" field.`);\n  }\n  return { intent, code };\n}\n\nfunction parseAddIntent(form: FormData, merchandiseId: string): CartAction {\n  const quantity = formInt(form, \"quantity\") ?? 1;\n  const sellingPlanId = formString(form, \"sellingPlanId\");\n\n  const line: CartLineAddInput = { merchandiseId, quantity };\n  if (sellingPlanId) line.sellingPlanId = sellingPlanId;\n\n  const rawAttributes = getCartAttributeFormEntries(form);\n  if (rawAttributes.length > 0) {\n    line.attributes = parseAttributes(rawAttributes);\n  }\n\n  return { intent: \"add\", lines: [line] };\n}\n\nfunction parseNoteIntent(form: FormData): CartAction {\n  const noteValue = form.get(\"note\");\n  if (noteValue === null) {\n    throw new CartActionError('Intent \"note-update\" requires a \"note\" field.');\n  }\n  return { intent: \"note-update\", note: String(noteValue) };\n}\n\nfunction parseAttributesIntent(form: FormData): CartAction {\n  return {\n    intent: \"attributes-update\",\n    attributes: parseAttributes(getCartAttributeFormEntries(form)),\n  };\n}\n\nfunction parseAttributes(values: unknown[]): CartAttributeInput[] {\n  return values.map((value, index) => {\n    assertObject(value);\n    assertString(value.key, `attributes[${index}].key`);\n    assertString(value.value, `attributes[${index}].value`);\n    if (!value.key) {\n      throw new CartActionError(`Expected \"attributes[${index}].key\" not to be empty.`);\n    }\n    return { key: value.key, value: value.value };\n  });\n}\n\n// --- Assertion helpers ---\n\nfunction assertObject(value: unknown): asserts value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new CartActionError(\"Expected an object.\");\n  }\n}\n\nfunction assertString(value: unknown, label: string): asserts value is string {\n  if (typeof value !== \"string\") {\n    throw new CartActionError(`Expected \"${label}\" to be a string.`);\n  }\n}\n\nfunction assertNonNegativeInteger(value: unknown, label: string): asserts value is number {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value < 0) {\n    throw new CartActionError(\n      `Expected \"${label}\" to be a non-negative integer, got ${JSON.stringify(value)}.`,\n    );\n  }\n}\n\n// --- FormData field helpers ---\n\nfunction formString(form: FormData, key: string): string | null {\n  const value = form.get(key);\n  if (value === null || typeof value !== \"string\") return null;\n  return value || null;\n}\n\nfunction formInt(form: FormData, key: string): number | null {\n  const raw = form.get(key);\n  if (raw === null || typeof raw !== \"string\") return null;\n  const parsed = parseInt(raw, 10);\n  if (Number.isNaN(parsed)) return null;\n  return parsed;\n}\n"],"mappings":"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"}

package/dist/core/cart/attach-quantity-input.d.mts

@@ -1,4 +1,30 @@
 //#region src/core/cart/attach-quantity-input.d.ts
+/**
+ * Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.
+ *
+ * When the input's value changes, the form is automatically submitted via the
+ * first submit button (which must carry `name="intent" value="set"`). Returns
+ * a cleanup function that removes the event listener.
+ *
+ * The form must contain a `"set"` button as its first submit element — use
+ * `register("set")` from `createCartFormRegister` to produce it.
+ *
+ * @throws If the form's first submit button is not a `name="intent" value="set"` button.
+ *
+ * @example
+ * ```ts
+ * const input = document.querySelector<HTMLInputElement>('input[name="quantity"]');
+ * const form = input?.closest('form');
+ *
+ * if (input && form) {
+ *   const detach = attachQuantityInput(input, form);
+ *   // Input changes now auto-submit the form
+ *
+ *   // Clean up when unmounting
+ *   detach();
+ * }
+ * ```
+ */
 declare function attachQuantityInput(inputEl: HTMLInputElement, formEl: HTMLFormElement): () => void;
 //#endregion
 export { attachQuantityInput };

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

@@ -1,5 +1,31 @@
 //#region src/core/cart/attach-quantity-input.ts
 const FIRST_SUBMIT_BUTTON_SELECTOR = "button:not([type=button])";
+/**
+* Attaches interactive quantity behavior to a DOM `<input>` inside a cart form.
+*
+* When the input's value changes, the form is automatically submitted via the
+* first submit button (which must carry `name="intent" value="set"`). Returns
+* a cleanup function that removes the event listener.
+*
+* The form must contain a `"set"` button as its first submit element — use
+* `register("set")` from `createCartFormRegister` to produce it.
+*
+* @throws If the form's first submit button is not a `name="intent" value="set"` button.
+*
+* @example
+* ```ts
+* const input = document.querySelector<HTMLInputElement>('input[name="quantity"]');
+* const form = input?.closest('form');
+*
+* if (input && form) {
+*   const detach = attachQuantityInput(input, form);
+*   // Input changes now auto-submit the form
+*
+*   // Clean up when unmounting
+*   detach();
+* }
+* ```
+*/
 function attachQuantityInput(inputEl, formEl) {
 	const firstSubmitButton = formEl.querySelector(FIRST_SUBMIT_BUTTON_SELECTOR);
 	if (!firstSubmitButton || firstSubmitButton.name !== "intent" || firstSubmitButton.value !== "set") throw new Error(`The first button in cart form must have a name of "intent" and value of "set". Your UI will not behave as expected.`, { cause: formEl });

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

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