@vtex/faststore 0.0.7 → 0.0.10

package/dist/matter/cart/cart.js

@@ -3,23 +3,26 @@ import { defineComponent } from "../../core/dist/define-component.js";
 import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
 import { useStorefrontContext } from "../../sdk/context/storefront-context.js";
+import { useStorefrontNavigation } from "../../sdk/navigation/use-storefront-navigation.js";
 import { graphql } from "../../sdk/generated/gql.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { NavigationLink } from "../../particles/navigation-link/navigation-link.js";
-import { Icon } from "../../particles/icon/icon.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { ListItemRefContext } from "../../sdk/data/list-item-ref-context.js";
 import { ReactiveRootContext } from "../../sdk/data/page-reactive-data-root.js";
+import { useOptionalToast } from "../../particles/toast/toast.js";
+import { Icon } from "../../particles/icon/icon.js";
 import { DrawerClose } from "../../particles/drawer/drawer.js";
 import { Image } from "../../particles/image/image.js";
 import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar, orderFormIdVar } from "../../sdk/state/cart.js";
 import { awaitCartWrites } from "../../sdk/cart/write-gate.js";
 import { readCartFromCache } from "../../sdk/cart/use-cart-actions.js";
+import { useCartSyncSalesChannel } from "../../sdk/cart/use-cart-sync-sales-channel.js";
 import { useCartValidateOnOpen } from "../../sdk/cart/use-cart-validate-on-open.js";
-import { ListItemRefContext } from "../../sdk/data/list-item-ref-context.js";
-import { useApolloClient, useReactiveVar } from "@apollo/client/react";
-import { cloneElement, createContext, isValidElement, useContext, useEffect, useMemo, useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useRouter } from "next/navigation";
+import { getApolloContext, useApolloClient, useReactiveVar } from "@apollo/client/react";
+import { cloneElement, createContext, isValidElement, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { useLinkStatus } from "next/link";
 //#region src/matter/cart/cart.tsx
 const CartDisclaimerContent = defineContentType({
@@ -88,6 +91,17 @@ const fragment = graphql(`
         code
         isUnmatchedCondition
       }
+      discounts {
+        name
+        value {
+          ...MoneyFragment
+        }
+        kind
+      }
+      salesChannelMismatch {
+        cartSalesChannel
+        activeSalesChannel
+      }
     }
   }
 `);
@@ -97,6 +111,17 @@ function formatPrice(value, locale, currency) {
 		currency
 	}).format(value);
 }
+/**
+* True when a money amount can be read as a number: a finite `number` (the optimistic-cache shape) or
+* a non-blank string `Number` parses to a finite value (the wire shape, a decimal string). Blank and
+* nullish amounts are rejected before `Number()` runs, because `Number('')` and `Number(null)` are `0`
+* and would turn a missing amount into a real zero.
+*/
+function isFiniteAmount(value) {
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value === "string") return value.trim() !== "" && Number.isFinite(Number(value));
+	return false;
+}
 const CartTotalValueContext = createContext(null);
 const CART_DATA_UNSET = Symbol("CartDataContextUnset");
 const CartDataContextInternal = createContext(CART_DATA_UNSET);
@@ -126,7 +151,8 @@ const CartRootDefinition = defineComponent({
 		category: "commerce"
 	},
 	schema: {},
-	guideline: "Cart data provider hosted by the layout (shared shell), wrapping the slot so every page consumes its context; exactly one per tree — do not place it as a page root. To build a mini-cart, wrap this CartRoot subtree in a modal DrawerRoot: the header carries a DrawerTrigger with a CartCount badge, the DrawerPopup body is a CartList line-item template, and its footer is CartTotal plus CartGoCheckout. The mini-cart is this layout composition, not a dedicated component. See cart.md."
+	actions: { cart: ["syncSalesChannel"] },
+	guideline: "Cart data provider hosted by the layout (shared shell), wrapping the slot so every page consumes its context; exactly one per tree — do not place it as a page root. To build a mini-cart, wrap this CartRoot subtree in a modal DrawerRoot: the header carries a DrawerTrigger with a CartCount badge, the DrawerPopup body is a CartList line-item template, and its footer is CartTotal plus CartGoCheckout. The mini-cart is this layout composition, not a dedicated component. See cart.md. On load, a cart whose sales channel differs from the request is moved onto the active channel."
 });
 const CartListDefinition = defineComponent({
 	name: "CartList",
@@ -166,12 +192,18 @@ const CartCountDefinition = defineComponent({
 		label: "Cart Count",
 		category: "commerce"
 	},
-	schema: { template: {
-		type: "string",
-		default: "{count}",
-		label: "Template"
-	} },
-	guideline: "Renders the total item count in the cart; use the template prop to customize the format (e.g. '{count} produtos'). Gift lines are excluded from the count — a promotional gift is not something the shopper added — so a cart holding only gifts shows 0. In a mini-cart, place it as the badge on the header DrawerTrigger and again in the DrawerPopup header. Must be inside CartRoot."
+	schema: {
+		template: {
+			type: "string",
+			default: "{count}",
+			label: "Template"
+		},
+		templateOne: {
+			type: "string",
+			label: "Template (one)"
+		}
+	},
+	guideline: "Renders the total item count in the cart; use the template prop to customize the format (e.g. '{count} produtos'). Set templateOne (e.g. '{count} produto') to word the count of exactly 1; template covers every other count, including 0, and is also used when templateOne is unset. A count that is not a finite number renders nothing. Gift lines are excluded from the count — a promotional gift is not something the shopper added — so a cart holding only gifts shows 0. In a mini-cart, place it as the badge on the header DrawerTrigger and again in the DrawerPopup header. Must be inside CartRoot."
 });
 const CartErrorDefinition = defineComponent({
 	name: "CartError",
@@ -195,8 +227,8 @@ const CartGoCheckoutDefinition = defineComponent({
 	},
 	schema: {
 		href: {
-			type: "string",
-			default: "/checkout",
+			type: "link",
+			default: { standard: "checkout" },
 			label: "Checkout URL"
 		},
 		label: {
@@ -206,7 +238,7 @@ const CartGoCheckoutDefinition = defineComponent({
 		}
 	},
 	actions: { cart: ["validate"] },
-	guideline: "Navigation link to the checkout page (default href /checkout); use as the checkout CTA inside the cart summary. In a mini-cart it is the DrawerPopup footer CTA, next to CartTotal. The button wording is merchant-editable content: a CMS entry wins, then the label prop (default \"Checkout\"), then children — so a store that labels the button through children keeps working and a CMS save overrides it without a deploy. The destination is not content-editable: href stays an authored prop, because re-pointing checkout is not a copy decision. Before routing it runs a stock validation and only navigates when the re-checked cart has no unavailable line; a validation that cannot run falls open and navigates anyway. During a client-side route transition to checkout it surfaces a loading state on its content wrapper as aria-busy plus data-fs-cart-go-checkout-pending, and while the pre-checkout validation runs it exposes data-fs-cart-go-checkout-validating — there is no built-in spinner, so opt into one by styling those attributes (e.g. composing a Spinner). For an external or hard checkout navigation there is no client-side transition, so the loading state simply does not show (a graceful no-op). The enriched footer checkout CTA is CartCheckoutGuard wrapping CartTotal and this CartGoCheckout: the guard makes the CTA inert (data-fs-cart-checkout-blocked) while any item is unavailable, and CartTotal shows the grand total at the button. Must be inside CartRoot."
+	guideline: "Navigation link to the checkout page (default href the checkout page); use as the checkout CTA inside the cart summary. In a mini-cart it is the DrawerPopup footer CTA, next to CartTotal. The button wording is merchant-editable content: a CMS entry wins, then the label prop (default \"Checkout\"), then children — so a store that labels the button through children keeps working and a CMS save overrides it without a deploy. The destination is not content-editable: href stays an authored prop, because re-pointing checkout is not a copy decision. Before routing it runs a stock validation and only navigates when the re-checked cart has no unavailable line; a validation that cannot run falls open and navigates anyway. During a client-side route transition to checkout it surfaces a loading state on its content wrapper as aria-busy plus data-fs-cart-go-checkout-pending, and while the pre-checkout validation runs it exposes data-fs-cart-go-checkout-validating — there is no built-in spinner, so opt into one by styling those attributes (e.g. composing a Spinner). For an external or hard checkout navigation there is no client-side transition, so the loading state simply does not show (a graceful no-op). The enriched footer checkout CTA is CartCheckoutGuard wrapping CartTotal and this CartGoCheckout: the guard makes the CTA inert (data-fs-cart-checkout-blocked) while any item is unavailable, and CartTotal shows the grand total at the button. Must be inside CartRoot."
 });
 const CartCouponFormDefinition = defineComponent({
 	name: "CartCouponForm",
@@ -224,10 +256,15 @@ const CartCouponFormDefinition = defineComponent({
 		applyLabel: {
 			type: "string",
 			label: "Apply Label"
+		},
+		appliedMessage: {
+			type: "string",
+			default: "Coupon applied",
+			label: "Applied message"
 		}
 	},
 	actions: { cart: ["applyCoupon"] },
-	guideline: "Coupon code input plus an apply button; root-agnostic (dispatches $actions.cart.applyCoupon). While an apply is in flight it disables the input and button and exposes data-fs-cart-coupon-pending. In a mini-cart it sits in the DrawerPopup footer above the totals; pair it with CartAppliedCoupons (the applied list) and CartCouponError (the error banner). Must be inside CartRoot."
+	guideline: "Coupon code input plus an apply button; root-agnostic (dispatches $actions.cart.applyCoupon). While an apply is in flight it disables the input and button and exposes data-fs-cart-coupon-pending. In a mini-cart it sits in the DrawerPopup footer above the totals; pair it with CartAppliedCoupons (the applied list) and CartCouponError (the error banner). For a single-coupon store, wrap the entry (the accordion holding this form) in CartCouponEmpty so it hides once a code is applied. When an apply returns no errors and the submitted code comes back matched, it raises a toast titled appliedMessage (needs a ToastProvider with a ToastList in the layout; with none, no toast shows and the apply still works). An unmatched code raises no toast; compose CartCouponUnmatched in the chip for that case. The toast still shows when CartCouponEmpty removes the form. Must be inside CartRoot."
 });
 const CartAppliedCouponsDefinition = defineComponent({
 	name: "CartAppliedCoupons",
@@ -239,7 +276,7 @@ const CartAppliedCouponsDefinition = defineComponent({
 	},
 	schema: {},
 	actions: { cart: ["removeCoupon"] },
-	guideline: "Renders one chip per applied coupon (cart.appliedCoupons), each showing its code and a CartCouponRemove control; renders nothing when no coupons are applied. A coupon whose conditions did not match is marked with data-fs-cart-coupon-unmatched. Place it next to CartCouponForm in the mini-cart footer. Must be inside CartRoot."
+	guideline: "Renders one chip per applied coupon (cart.appliedCoupons), each showing its code and a CartCouponRemove control; renders nothing when no coupons are applied. A coupon whose conditions did not match is marked with data-fs-cart-coupon-unmatched. Place it next to CartCouponForm in the mini-cart footer. Composed children replace the built-in remove control, so a chip template that adds CartCouponUnmatched (the unmatched-coupon notice) or CartCouponSavings (the amount the coupon saves) must also compose CartCouponRemove. Must be inside CartRoot."
 });
 const CartCouponRemoveDefinition = defineComponent({
 	name: "CartCouponRemove",
@@ -267,13 +304,62 @@ const CartCouponErrorDefinition = defineComponent({
 	schema: {},
 	guideline: "Inline error banner that surfaces coupon apply/remove errors next to the CartCouponForm; renders nothing when there are none. Reads a dedicated coupon error channel, separate from CartError. Must be inside CartRoot."
 });
-function CartRoot({ $data: $dataProp, className, children, ...props }) {
-	const cart = useDataOverride($dataProp) ?? null;
+const CartCouponEmptyDefinition = defineComponent({
+	name: "CartCouponEmpty",
+	importPath: "@vtex/faststore/components",
+	component: CartCouponEmpty,
+	editor: {
+		label: "Cart Coupon Empty",
+		category: "commerce"
+	},
+	schema: {},
+	guideline: "Coupon entry gate: renders its children only while the resolved cart has no applied coupon (cart.appliedCoupons is empty), and nothing while the cart loads. The merchant coupon policy is composition: for a single-coupon store, wrap the coupon entry (the AccordionRoot holding CartCouponForm) in it so the entry hides once a code is applied and returns when the chip is removed; for a multi-coupon store, omit it so the entry stays open for more codes. Keep CartAppliedCoupons and CartCouponError outside it, so the applied chips and coupon errors stay visible. Must be inside CartRoot. See cart.md."
+});
+const CartCouponUnmatchedDefinition = defineComponent({
+	name: "CartCouponUnmatched",
+	importPath: "@vtex/faststore/components",
+	component: CartCouponUnmatched,
+	editor: {
+		label: "Cart Coupon Unmatched",
+		category: "commerce"
+	},
+	schema: { message: {
+		type: "string",
+		default: "This coupon is not being applied to your cart",
+		label: "Message"
+	} },
+	guideline: "Per-chip notice for an applied coupon that grants nothing: renders the message copy in an <output> live region only while the enclosing chip's coupon has isUnmatchedCondition (its conditions stopped matching, were never met, or the code was accepted without validation), and nothing once it matches again, outside a chip, or when the copy is blank. Place it inside CartAppliedCoupons next to CartCouponRemove: composed children replace the built-in remove control, so a chip template without CartCouponRemove loses the X. It does not remove the coupon; the shopper removes it with the X. See cart.md."
+});
+const CartCouponSavingsDefinition = defineComponent({
+	name: "CartCouponSavings",
+	importPath: "@vtex/faststore/components",
+	component: CartCouponSavings,
+	editor: {
+		label: "Cart Coupon Savings",
+		category: "commerce"
+	},
+	schema: { template: {
+		type: "string",
+		default: "{amount}",
+		label: "Template"
+	} },
+	guideline: "Per-chip amount a fixed-amount coupon took off, summed from cart.discounts for the enclosing chip's code. Renders nothing for an unmatched, free-shipping or percentage coupon (the API attributes no amount to them), outside a chip, or when the sum is not above zero. Set template to word the chip text, e.g. 'Economia de {amount}' or '{code} — Economia de {amount}': every {amount} becomes the saving and every {code} the chip's code; the default is '{amount}' and a blank template counts as unset. The chip already shows the code before its children, so {code} repeats it. Place it inside a CartAppliedCoupons chip template next to CartCouponRemove: composed children replace the built-in remove control, so a chip template without CartCouponRemove loses the X. Must be inside CartRoot. See cart.md."
+});
+const useIsomorphicLayoutEffect = globalThis.window === void 0 ? useEffect : useLayoutEffect;
+function CartRoot({ $data: $dataProp, $actions: $actionsProp, className, children, ...props }) {
+	const $data = useDataOverride($dataProp);
+	const $actions = useActionsOverride($actionsProp);
+	const cart = $data ?? null;
+	useCartSyncSalesChannel($actions?.cart?.syncSalesChannel, cart?.id ?? null, cart?.salesChannelMismatch);
 	const { error: rootError } = useContext(ReactiveRootContext);
 	const cartEntityId = cart?.id ?? null;
 	useEffect(() => {
 		if (cartEntityId) orderFormIdVar(cartEntityId);
 	}, [cartEntityId]);
+	useIsomorphicLayoutEffect(() => {
+		cartUserErrorsVar([]);
+		cartCouponErrorsVar([]);
+	}, []);
 	const dataValue = useMemo(() => ({
 		cart,
 		error: rootError ?? null
@@ -318,24 +404,37 @@ function CartList({ className, children, skeletonCount = 3, ...props }) {
 function CartTotal({ label, className, children, ...props }) {
 	const total = useContext(CartTotalValueContext);
 	const { locale, currency } = useStorefrontContext();
-	const value = children ?? formatPrice(total?.amount ?? 0, locale, currency);
+	const value = children ?? formatPrice(Number(total?.amount ?? 0), locale, currency);
 	return /* @__PURE__ */ jsx("span", {
 		...props,
 		className,
 		"data-fs-cart-total": "",
 		"data-fs-text": "",
-		children: label == null ? value : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", { children: label }), /* @__PURE__ */ jsx("span", { children: value })] })
+		children: label == null ? value : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", { children: label }), /* @__PURE__ */ jsx("span", { children: value })] })
 	});
 }
-function CartCount({ className, children, template = "{count}", ...props }) {
+/**
+* Fills `{count}` in the template for the count. `templateOne` is used only at exactly 1 and only when
+* it is not blank. A count that is not a finite number yields `null`.
+*/
+function formatCount(count, template, templateOne) {
+	if (!Number.isFinite(count)) return null;
+	return (count === 1 && templateOne?.trim() ? templateOne : template).replace("{count}", String(count));
+}
+function addToCount(sum, item) {
+	if (item.gift) return sum;
+	return Number.isFinite(item.quantity) ? sum + item.quantity : NaN;
+}
+function CartCount({ className, children, template = "{count}", templateOne, ...props }) {
 	const { cart } = useCart();
-	const count = cart?.items.reduce((sum, item) => item.gift ? sum : sum + item.quantity, 0) ?? 0;
+	const count = cart?.items.reduce(addToCount, 0) ?? 0;
+	if (!Number.isFinite(count)) return null;
 	return /* @__PURE__ */ jsx("span", {
 		...props,
 		className,
 		"data-fs-cart-count": "",
 		"data-fs-text": "",
-		children: children ?? template.replace("{count}", String(count))
+		children: children ?? formatCount(count, template, templateOne)
 	});
 }
 function CartError({ className, children, ...props }) {
@@ -362,14 +461,12 @@ function CartGoCheckoutPending({ children }) {
 function configuredLabel(value) {
 	return value?.trim() ? value : void 0;
 }
-function navigateToCheckout(href, push) {
-	if (/^https?:\/\//i.test(href)) globalThis.location.assign(href);
-	else push(href);
-}
-function CartGoCheckout({ href = "/checkout", label, className, children, onClick, $content, $actions: $actionsProp, ...props }) {
+/** The default destination of both checkout navigations. Module-level, so an effect keyed on it is stable. */
+const CHECKOUT_PAGE = { standard: "checkout" };
+function CartGoCheckout({ href = CHECKOUT_PAGE, label, className, children, onClick, $content, $actions: $actionsProp, ...props }) {
 	const $actions = useActionsOverride($actionsProp);
 	const client = useApolloClient();
-	const router = useRouter();
+	const { push } = useStorefrontNavigation();
 	const [validating, setValidating] = useState(false);
 	const inFlight = useRef(false);
 	const resolvedChildren = typeof children === "string" ? configuredLabel(children) : children;
@@ -386,10 +483,10 @@ function CartGoCheckout({ href = "/checkout", label, className, children, onClic
 		try {
 			await awaitCartWrites();
 			if ((await validate()).length > 0) {
-				navigateToCheckout(href, router.push);
+				push(href);
 				return;
 			}
-			if (!(readCartFromCache(client)?.items ?? []).some((item) => item.variant.availability !== "AVAILABLE")) navigateToCheckout(href, router.push);
+			if (!(readCartFromCache(client)?.items ?? []).some((item) => item.variant.availability !== "AVAILABLE")) push(href);
 		} finally {
 			inFlight.current = false;
 			setValidating(false);
@@ -405,8 +502,10 @@ function CartGoCheckout({ href = "/checkout", label, className, children, onClic
 		children: /* @__PURE__ */ jsx(CartGoCheckoutPending, { children: resolvedLabel })
 	});
 }
-function CartCouponForm({ placeholder = "Coupon code", applyLabel = "Apply", className, children, onSubmit, $actions: $actionsProp, ...props }) {
+function CartCouponForm({ placeholder = "Coupon code", applyLabel = "Apply", appliedMessage = "Coupon applied", className, children, onSubmit, $actions: $actionsProp, ...props }) {
 	const $actions = useActionsOverride($actionsProp);
+	const toast = useOptionalToast();
+	const { client } = useContext(getApolloContext());
 	const [code, setCode] = useState("");
 	const [pending, setPending] = useState(false);
 	async function handleSubmit(e) {
@@ -418,6 +517,13 @@ function CartCouponForm({ placeholder = "Coupon code", applyLabel = "Apply", cla
 		try {
 			const errors = await $actions?.cart?.applyCoupon?.({ code: trimmed });
 			if (!errors || errors.length === 0) setCode("");
+			if (errors?.length === 0 && client && appliedMessage?.trim()) {
+				const submitted = trimmed.toLowerCase();
+				if ((readCartFromCache(client)?.appliedCoupons ?? []).some((coupon) => coupon.code.trim().toLowerCase() === submitted && coupon.isUnmatchedCondition === false)) toast?.add({
+					title: appliedMessage,
+					type: "success"
+				});
+			}
 		} finally {
 			setPending(false);
 		}
@@ -428,7 +534,7 @@ function CartCouponForm({ placeholder = "Coupon code", applyLabel = "Apply", cla
 		onSubmit: handleSubmit,
 		"data-fs-cart-coupon-form": "",
 		...pending ? { "data-fs-cart-coupon-pending": "" } : {},
-		children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("input", {
+		children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("input", {
 			type: "text",
 			value: code,
 			placeholder,
@@ -510,6 +616,52 @@ function CartCouponError({ className, children, ...props }) {
 		children: children ?? firstError.message
 	});
 }
+function CartCouponEmpty({ className, children, ...props }) {
+	const { cart } = useCart();
+	if (cart == null || (cart.appliedCoupons ?? []).length > 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className,
+		"data-fs-cart-coupon-empty": "",
+		children
+	});
+}
+function CartCouponUnmatched({ message = "This coupon is not being applied to your cart", className, children, ...props }) {
+	if (useContext(CartCouponContext)?.isUnmatchedCondition !== true) return null;
+	if (children == null && !message?.trim()) return null;
+	return /* @__PURE__ */ jsx("output", {
+		...props,
+		className,
+		"data-fs-cart-coupon-unmatched-notice": "",
+		"data-fs-text": "",
+		children: children ?? message
+	});
+}
+/**
+* Fills every `{code}` and `{amount}` in one pass. A function replacer keeps `$` sequences in the
+* values literal, and a substituted value is never scanned again for placeholders.
+*/
+function fillCouponTemplate(template, { code, amount }) {
+	return template.replaceAll(/\{(code|amount)\}/g, (_, key) => key === "code" ? code : amount);
+}
+function CartCouponSavings({ className, template = "{amount}", ...props }) {
+	const coupon = useContext(CartCouponContext);
+	const { cart } = useCart();
+	const { locale, currency } = useStorefrontContext();
+	if (!cart || !coupon || coupon.isUnmatchedCondition || coupon.code === "") return null;
+	const saved = cart.discounts.reduce((sum, discount) => discount.kind === "COUPON" && discount.name === coupon.code && isFiniteAmount(discount.value.amount) ? sum + Number(discount.value.amount) : sum, 0);
+	if (saved <= 0) return null;
+	return /* @__PURE__ */ jsx("span", {
+		...props,
+		className,
+		"data-fs-cart-coupon-savings": "",
+		"data-fs-text": "",
+		children: fillCouponTemplate(template?.trim() ? template : "{amount}", {
+			code: coupon.code,
+			amount: formatPrice(-saved, locale, currency)
+		})
+	});
+}
 const CartCheckoutGuardDefinition = defineComponent({
 	name: "CartCheckoutGuard",
 	importPath: "@vtex/faststore/components",
@@ -562,12 +714,18 @@ const CartUnavailableCountDefinition = defineComponent({
 		label: "Cart Unavailable Count",
 		category: "commerce"
 	},
-	schema: { template: {
-		type: "string",
-		default: "{count} items unavailable",
-		label: "Template"
-	} },
-	guideline: "Cart-level summary of how many lines are unavailable; self-hides when none. See cart.md."
+	schema: {
+		template: {
+			type: "string",
+			default: "{count} items unavailable",
+			label: "Template"
+		},
+		templateOne: {
+			type: "string",
+			label: "Template (one)"
+		}
+	},
+	guideline: "Cart-level summary of how many lines are unavailable; self-hides when none. Set templateOne to word the count of exactly 1 line; template covers every other count, including 0, and is also used when templateOne is unset. See cart.md."
 });
 const CartRemoveUnavailableDefinition = defineComponent({
 	name: "CartRemoveUnavailable",
@@ -581,6 +739,18 @@ const CartRemoveUnavailableDefinition = defineComponent({
 	actions: { cart: ["removeItems"] },
 	guideline: "Button that removes every unavailable line in one batch call; self-hides when none. See cart.md."
 });
+const ClearCartButtonDefinition = defineComponent({
+	name: "ClearCartButton",
+	importPath: "@vtex/faststore/components",
+	component: ClearCartButton,
+	editor: {
+		label: "Clear Cart Button",
+		category: "commerce"
+	},
+	schema: {},
+	actions: { cart: ["removeItems"] },
+	guideline: "Button that removes every line in the cart (gift and unavailable lines included) in one batch call; self-hides when the cart has no lines. Disabled, with data-fs-clear-cart-button-pending, while the call is in flight. No confirmation and no toast. The write is optimistic: CartEmpty replaces CartFilled as soon as it is clicked; on failure the lines come back and the error shows in CartError, so compose a CartError outside the CartFilled/CartEmpty branches. Children are the label (default \"Clear cart\"). Must be inside CartRoot. See cart.md."
+});
 function isUnavailable(item) {
 	return item.variant.availability !== "AVAILABLE";
 }
@@ -597,7 +767,7 @@ function CartCheckoutGuard({ className, children, ...props }) {
 		children
 	});
 }
-function CartUnavailableCount({ className, children, template = "{count} items unavailable", ...props }) {
+function CartUnavailableCount({ className, children, template = "{count} items unavailable", templateOne, ...props }) {
 	const { cart } = useCart();
 	const count = (cart?.items ?? []).filter(isUnavailable).length;
 	if (count === 0) return null;
@@ -606,7 +776,7 @@ function CartUnavailableCount({ className, children, template = "{count} items u
 		className,
 		"data-fs-cart-unavailable-count": "",
 		"data-fs-text": "",
-		children: children ?? template.replace("{count}", String(count))
+		children: children ?? formatCount(count, template, templateOne)
 	});
 }
 function CartRemoveUnavailable({ className, children, onClick, $actions: $actionsProp, ...props }) {
@@ -628,6 +798,44 @@ function CartRemoveUnavailable({ className, children, onClick, $actions: $action
 		children: children ?? "Remove unavailable items"
 	});
 }
+function ClearCartButton({ className, children, disabled, onClick, $actions: $actionsProp, ...props }) {
+	const $actions = useActionsOverride($actionsProp);
+	const { cart } = useCart();
+	const [pending, setPending] = useState(false);
+	const inFlight = useRef(false);
+	const ids = (cart?.items ?? []).map((item) => item.id);
+	if (ids.length === 0) return null;
+	async function clear(removeItems) {
+		try {
+			await removeItems({ ids });
+		} catch (error) {
+			console.error("[ClearCartButton] removeItems failed", loggableErrorName(error));
+		} finally {
+			inFlight.current = false;
+			setPending(false);
+		}
+	}
+	function handleClick(e) {
+		if (inFlight.current) return;
+		onClick?.(e);
+		const removeItems = $actions?.cart?.removeItems;
+		if (typeof removeItems !== "function") return;
+		inFlight.current = true;
+		setPending(true);
+		clear(removeItems);
+	}
+	return /* @__PURE__ */ jsx("button", {
+		...props,
+		type: "button",
+		className,
+		onClick: handleClick,
+		disabled: pending || disabled,
+		"data-fs-clear-cart-button": "",
+		"data-fs-button": "",
+		...pending ? { "data-fs-clear-cart-button-pending": "" } : {},
+		children: children ?? "Clear cart"
+	});
+}
 const CartOpenOnAddDefinition = defineComponent({
 	name: "CartOpenOnAdd",
 	importPath: "@vtex/faststore/components",
@@ -649,11 +857,11 @@ const CartRedirectOnAddDefinition = defineComponent({
 		category: "commerce"
 	},
 	schema: { href: {
-		type: "string",
-		default: "/checkout",
+		type: "link",
+		default: { standard: "checkout" },
 		label: "Checkout URL"
 	} },
-	guideline: "No-mini-cart post-add behavior: navigates the shopper to checkout (href, default /checkout) after each successful add to cart. Compose it once in the layout for a store that has no mini-cart drawer; it renders no UI of its own. Use this instead of a mini-cart when adding a product should go straight to checkout. Mutually exclusive with CartOpenOnAdd — compose exactly one, and omit the drawer when using this. See cart.md."
+	guideline: "No-mini-cart post-add behavior: navigates the shopper to checkout (href, default the checkout page) after each successful add to cart. Compose it once in the layout for a store that has no mini-cart drawer; it renders no UI of its own. Use this instead of a mini-cart when adding a product should go straight to checkout. Mutually exclusive with CartOpenOnAdd — compose exactly one, and omit the drawer when using this. See cart.md."
 });
 /**
 * Makes the wrapped mini-cart `DrawerRoot` controlled by `miniCartOpenVar` and opens it on each
@@ -683,16 +891,21 @@ function CartOpenOnAdd({ children, $actions: $actionsProp }) {
 * redirect is post-resolve and success-gated. The initial `0` is ignored, so a fresh mount never
 * navigates. Context-free — no `CartRoot` ancestor (ADR-0010). Renders its passthrough children (or
 * nothing); it carries no drawer.
+*
+* The effect keys on the serialized `href`, not on its identity: a reference authored in a schema
+* arrives as a new object on every server render, and keying on it would push to checkout again on a
+* `router.refresh()` long after the add.
 */
-function CartRedirectOnAdd({ href = "/checkout", children }) {
-	const router = useRouter();
+function CartRedirectOnAdd({ href = CHECKOUT_PAGE, children }) {
+	const { push } = useStorefrontNavigation();
 	const pulse = useReactiveVar(cartLastAddVar);
+	const hrefKey = JSON.stringify(href);
 	useEffect(() => {
-		if (pulse > 0) router.push(href);
+		if (pulse > 0) push(JSON.parse(hrefKey));
 	}, [
 		pulse,
-		href,
-		router
+		hrefKey,
+		push
 	]);
 	return children;
 }
@@ -873,7 +1086,7 @@ const CartAlertRootDefinition = defineComponent({
 		}
 	},
 	providesContext: "cart-alert",
-	guideline: "Merchant-authored notice near the top of the mini-cart overlay (a minimum order, a running promotion): wraps CartAlertIcon and CartAlertText in any subset, any order — the arrangement is the composition, not a prop — and renders the glyph then the copy when composed with no children. Its copy and glyph are CMS-editable through the cart-alert content model, with the text, icon, iconUrl and iconAlt props as the non-CMS fallback; it renders nothing when no message is configured, so an unconfigured banner leaves no empty box. Reads no cart data, so it needs no CartRoot ancestor and no cart-state gate — place it inside CartFilled to hide it on an empty cart. A store whose merchants choose the icon must list CART_ALERT_ICON_NAMES under icons.include in global.json, or a chosen glyph renders empty. Distinct from CartError (cart mutation errors) and CartUnavailableCount (data-driven). See cart.md."
+	guideline: "Merchant-authored notice near the top of the mini-cart overlay (a minimum order, a running promotion): wraps CartAlertIcon and CartAlertText in any subset, any order — the arrangement is the composition, not a prop — and renders the glyph then the copy when composed with no children. Its copy and glyph are CMS-editable through the cart-alert content model, with the text, icon, iconUrl and iconAlt props as the non-CMS fallback; it renders nothing when no message is configured, so an unconfigured banner leaves no empty box. Reads no cart data, so it needs no CartRoot ancestor and no cart-state gate — place it inside CartFilled to hide it on an empty cart. A store whose merchants choose the icon must list CART_ALERT_ICON_NAMES under icons.include in its foundation, or a chosen glyph renders empty. Distinct from CartError (cart mutation errors) and CartUnavailableCount (data-driven). See cart.md."
 });
 const CartAlertIconDefinition = defineComponent({
 	name: "CartAlertIcon",
@@ -920,7 +1133,7 @@ function CartAlertRoot({ text, icon, iconUrl, iconAlt, className, children, $con
 			...props,
 			className,
 			"data-fs-cart-alert": "",
-			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(CartAlertIcon, {}), /* @__PURE__ */ jsx(CartAlertText, {})] })
+			children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(CartAlertIcon, {}), /* @__PURE__ */ jsx(CartAlertText, {})] })
 		})
 	});
 }
@@ -1036,6 +1249,6 @@ function CartContinueShopping({ label = "Continue shopping", $content, className
 	});
 }
 //#endregion
-export { CART_ALERT_ICON_NAMES, CartAlertContent, CartAlertIcon, CartAlertIconDefinition, CartAlertRoot, CartAlertRootDefinition, CartAlertText, CartAlertTextDefinition, CartAppliedCoupons, CartAppliedCouponsDefinition, CartCheckoutGuard, CartCheckoutGuardDefinition, CartCheckoutLabelContent, CartContinueShopping, CartContinueShoppingContent, CartContinueShoppingDefinition, CartCount, CartCountDefinition, CartCouponError, CartCouponErrorDefinition, CartCouponForm, CartCouponFormDefinition, CartCouponRemove, CartCouponRemoveDefinition, CartDataContext, CartDisclaimer, CartDisclaimerContent, CartDisclaimerDefinition, CartEmpty, CartEmptyDefinition, CartEmptyMessage, CartEmptyMessageContent, CartEmptyMessageDefinition, CartError, CartErrorDefinition, CartFilled, CartFilledDefinition, CartGoCheckout, CartGoCheckoutDefinition, CartItemSkeleton, CartList, CartListDefinition, CartLoading, CartLoadingDefinition, CartOpenOnAdd, CartOpenOnAddDefinition, CartRedirectOnAdd, CartRedirectOnAddDefinition, CartRemoveUnavailable, CartRemoveUnavailableDefinition, CartRoot, CartRootDefinition, CartTotal, CartTotalDefinition, CartTotalValueContext, CartUnavailableCount, CartUnavailableCountDefinition, formatPrice, useCart };
+export { CART_ALERT_ICON_NAMES, CartAlertContent, CartAlertIcon, CartAlertIconDefinition, CartAlertRoot, CartAlertRootDefinition, CartAlertText, CartAlertTextDefinition, CartAppliedCoupons, CartAppliedCouponsDefinition, CartCheckoutGuard, CartCheckoutGuardDefinition, CartCheckoutLabelContent, CartContinueShopping, CartContinueShoppingContent, CartContinueShoppingDefinition, CartCount, CartCountDefinition, CartCouponEmpty, CartCouponEmptyDefinition, CartCouponError, CartCouponErrorDefinition, CartCouponForm, CartCouponFormDefinition, CartCouponRemove, CartCouponRemoveDefinition, CartCouponSavings, CartCouponSavingsDefinition, CartCouponUnmatched, CartCouponUnmatchedDefinition, CartDataContext, CartDisclaimer, CartDisclaimerContent, CartDisclaimerDefinition, CartEmpty, CartEmptyDefinition, CartEmptyMessage, CartEmptyMessageContent, CartEmptyMessageDefinition, CartError, CartErrorDefinition, CartFilled, CartFilledDefinition, CartGoCheckout, CartGoCheckoutDefinition, CartItemSkeleton, CartList, CartListDefinition, CartLoading, CartLoadingDefinition, CartOpenOnAdd, CartOpenOnAddDefinition, CartRedirectOnAdd, CartRedirectOnAddDefinition, CartRemoveUnavailable, CartRemoveUnavailableDefinition, CartRoot, CartRootDefinition, CartTotal, CartTotalDefinition, CartTotalValueContext, CartUnavailableCount, CartUnavailableCountDefinition, ClearCartButton, ClearCartButtonDefinition, fillCouponTemplate, formatPrice, isFiniteAmount, useCart };
 
 //# sourceMappingURL=cart.js.map