@godaddy/gd-commerce-storefront 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,6 +1,6 @@
-import { Children, createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
+import { Children, Fragment, createContext, isValidElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 import { useQuery } from "@tanstack/react-query";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import * as Dialog from "@radix-ui/react-dialog";
 import { Link, useParams, useSearchParams } from "react-router";
 
@@ -61,8 +61,9 @@ async function request(path, init) {
 		throw cause;
 	}
 }
-function money(value, currency) {
-	const formatter = new Intl.NumberFormat("en-US", {
+/** Formats minor units, such as cents, as currency. Inside the provider, prefer `useMoney`, which follows its `locale`. */
+function money(value, currency, locale = "en-US") {
+	const formatter = new Intl.NumberFormat(locale, {
 		style: "currency",
 		currency
 	});
@@ -112,7 +113,7 @@ function useSampleCart() {
 	if (!value) throw new Error("Mount CommerceProvider around sample products.");
 	return value;
 }
-function SampleCartProvider({ enabled, onAdd, announce, children }) {
+function SampleCartProvider({ enabled, onAdd, announce, emit, children }) {
 	const session = useMemo(() => ({ enabled }), [enabled]);
 	const active = useRef(session);
 	active.current = session;
@@ -163,12 +164,27 @@ function SampleCartProvider({ enabled, onAdd, announce, children }) {
 			},
 			changeQuantity: async (key, quantity) => {
 				const updated = quantity >= 1 && update(key, quantity);
-				if (updated) announce("Sample cart quantity updated.");
+				if (updated) {
+					announce("Sample cart quantity updated.");
+					emit({
+						type: "quantity-changed",
+						itemId: key,
+						quantity,
+						isSample: true
+					});
+				}
 				return updated;
 			},
 			remove: async (key) => {
 				const updated = update(key, 0);
-				if (updated) announce("Sample item removed from cart.");
+				if (updated) {
+					announce("Sample item removed from cart.");
+					emit({
+						type: "item-removed",
+						itemId: key,
+						isSample: true
+					});
+				}
 				return updated;
 			}
 		},
@@ -186,7 +202,39 @@ function useCommerce() {
 	if (!context) throw new Error("Mount CommerceProvider once around the header and page outlet, inside the router.");
 	return context;
 }
+/**
+* Formats minor units, such as cents, in the provider's `locale`, the way the package's own parts do. Uses the
+* store's currency unless `currency` is given.
+*/
+function useMoney() {
+	const { locale, config } = useCommerce();
+	const { currencyCode } = config;
+	return useCallback((value, currency = currencyCode) => money(value, currency, locale), [locale, currencyCode]);
+}
 const CONNECTING_FAILURE_GRACE_MS = 6e4;
+/** `locale` as a canonical tag, or `en-US` when it is not a valid one, so one bad prop cannot break every price. */
+function resolveLocale(locale) {
+	if (!locale) return "en-US";
+	try {
+		return Intl.getCanonicalLocales(locale)[0] ?? "en-US";
+	} catch {
+		if (process.env.NODE_ENV !== "production") console.warn(`[gd-commerce-storefront] "${locale}" is not a valid locale, so prices use en-US.`);
+		return "en-US";
+	}
+}
+const logCallbackFailure = (cause) => console.error("[gd-commerce-storefront] A storefront callback threw.", cause);
+/**
+* Runs a host callback so that its failure cannot fail the cart operation that triggered it. An async callback is
+* not awaited; its rejection is logged instead of becoming an unhandled rejection.
+*/
+function callHost(callback) {
+	try {
+		const result = callback();
+		if (typeof result?.then === "function") Promise.resolve(result).catch(logCallbackFailure);
+	} catch (cause) {
+		logCallbackFailure(cause);
+	}
+}
 async function loadConfig(signal) {
 	const config = await request("/config", { signal });
 	if (config?.state === "unbound" || config?.state === "connecting") {
@@ -200,7 +248,8 @@ async function loadConfig(signal) {
 		currencyCode: config.currencyCode
 	};
 }
-function CommerceProvider({ children, catalogPath = "/shop", productPath = "/products", checkoutSuccessPath, theme = {}, onItemAdded }) {
+function CommerceProvider({ children, catalogPath = "/shop", productPath = "/products", checkoutSuccessPath, theme = {}, locale, onItemAdded, onEvent }) {
+	const resolvedLocale = useMemo(() => resolveLocale(locale), [locale]);
 	const config = useQuery({
 		retry: false,
 		queryKey: ["commerce", "configuration"],
@@ -229,11 +278,13 @@ function CommerceProvider({ children, catalogPath = "/shop", productPath = "/pro
 			config.refetch();
 		},
 		theme,
+		locale: resolvedLocale,
 		onItemAdded,
+		onEvent,
 		children
 	});
 }
-function BoundCommerceProvider({ config, children, connection, connectionError, retryConnection, theme, onItemAdded }) {
+function BoundCommerceProvider({ config, children, connection, connectionError, retryConnection, theme, locale, onItemAdded, onEvent }) {
 	const storageKey = `godaddy:commerce-storefront:cart:${config.cartScope}`;
 	const cartIdStorage = useMemo(() => new CartIdStorage(storageKey), [storageKey]);
 	const ready = connection === "ready";
@@ -257,8 +308,26 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 	const queue = useRef(Promise.resolve(true));
 	const alive = useRef(true);
 	const opener = useRef(null);
-	const added = useRef(onItemAdded);
-	added.current = onItemAdded;
+	const callbacks = useRef({
+		onItemAdded,
+		onEvent
+	});
+	callbacks.current = {
+		onItemAdded,
+		onEvent
+	};
+	/** Reports an event to the host. A callback that throws is logged, and the operation still succeeds. */
+	function emit(event) {
+		if (event.type === "item-added") {
+			const { name, quantity, isSample } = event;
+			callHost(() => callbacks.current.onItemAdded?.({
+				name,
+				quantity,
+				isSample
+			}));
+		}
+		callHost(() => callbacks.current.onEvent?.(event));
+	}
 	const drawers = useRef(0);
 	const registerDrawer = useCallback(() => {
 		drawers.current += 1;
@@ -325,7 +394,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			throw cause;
 		}
 	}
-	function run(operation, loading = false) {
+	function run(kind, operation, loading = false) {
 		const task = queue.current.then(async () => {
 			if (!isActive()) return false;
 			setPending(true);
@@ -338,7 +407,15 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 				else await operation();
 				return isActive();
 			} catch (cause) {
-				if (isActive()) setError(message(cause));
+				if (isActive()) {
+					const text = message(cause);
+					setError(text);
+					emit({
+						type: "error",
+						operation: kind,
+						message: text
+					});
+				}
 				return false;
 			} finally {
 				if (isActive()) {
@@ -351,7 +428,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 		return task;
 	}
 	function refresh() {
-		return run(hydrate, true);
+		return run("refresh", hydrate, true);
 	}
 	useEffect(() => {
 		alive.current = true;
@@ -382,7 +459,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 	}, [cartIdStorage, connection]);
 	function addItem(item) {
 		rememberOpener();
-		return run(async () => {
+		return run("add", async () => {
 			if (!item.skuId || !item.name || !Number.isInteger(item.quantity) || item.quantity < 1) throw new Error("Select a product variant and a positive quantity.");
 			await hydrate();
 			if (!isActive()) return;
@@ -404,7 +481,9 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			commit(result.cart);
 			setAnnouncement(`${item.name} added to your cart.`);
 			openDrawer();
-			added.current?.({
+			emit({
+				type: "item-added",
+				skuId: item.skuId,
 				name: item.name,
 				quantity: item.quantity,
 				isSample: false
@@ -412,7 +491,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 		});
 	}
 	function mutateItem(itemId, method, quantity) {
-		return run(async () => {
+		return run(method === "DELETE" ? "remove" : "change-quantity", async () => {
 			await hydrate();
 			if (!isActive()) return;
 			if (!id.current || !currentCart.current?.lineItems?.some((item) => item.id === itemId)) throw new Error("This item is no longer in the cart.");
@@ -425,10 +504,20 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			if (!isActive()) return;
 			commit(result.cart);
 			setAnnouncement(method === "DELETE" ? "Item removed from cart." : "Cart quantity updated.");
+			emit(method === "DELETE" ? {
+				type: "item-removed",
+				itemId,
+				isSample: false
+			} : {
+				type: "quantity-changed",
+				itemId,
+				quantity: quantity ?? 0,
+				isSample: false
+			});
 		});
 	}
 	function applyDiscount(code) {
-		return run(async () => {
+		return run("discount", async () => {
 			await hydrate();
 			if (!isActive()) return;
 			if (!id.current || !code.trim()) throw new Error("Add an item and enter a promotion code.");
@@ -441,10 +530,14 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			if (!isActive()) return;
 			commit(result.cart);
 			setAnnouncement("Promotion codes updated.");
+			emit({
+				type: "discount-applied",
+				code: code.trim()
+			});
 		});
 	}
 	function checkout() {
-		return run(async () => {
+		return run("checkout", async () => {
 			if (!config.checkoutSuccessPath) throw new Error("Checkout has not been enabled for this store.");
 			await hydrate();
 			if (!isActive()) return;
@@ -464,6 +557,10 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			if (typeof session$1.url !== "string" || !session$1.url.trim()) throw new Error("Commerce did not return a checkout URL.");
 			const url = new URL(session$1.url, origin);
 			if (url.protocol !== "https:") throw new Error("Commerce returned an invalid checkout URL.");
+			emit({
+				type: "checkout-started",
+				cartId: id.current
+			});
 			window.location.assign(url.href);
 		});
 	}
@@ -474,6 +571,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			connectionError,
 			retryConnection,
 			theme,
+			locale,
 			cart,
 			open,
 			setOpen: (next) => {
@@ -501,10 +599,13 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			children: /* @__PURE__ */ jsx(SampleCartProvider, {
 				enabled: connection === "unbound",
 				announce: setAnnouncement,
+				emit,
 				onAdd: (name) => {
 					setAnnouncement(`${name} added to your sample cart.`);
 					openDrawer();
-					added.current?.({
+					emit({
+						type: "item-added",
+						skuId: null,
 						name,
 						quantity: 1,
 						isSample: true
@@ -632,6 +733,60 @@ function getProductName(skuGroup) {
 	return skuGroup.label ?? skuGroup.name ?? "Product";
 }
 
+//#endregion
+//#region src/part.ts
+/**
+* Whether `children` renders anything, so `{custom && <Part />}` with `custom` false falls back to the default. Blank
+* text and fragments holding nothing count as nothing. A component element counts as content: what it renders is
+* not known until it renders.
+*/
+const hasChildren = (children) => Children.toArray(children).some((child) => {
+	if (typeof child === "string") return child.trim() !== "";
+	if (isValidElement(child) && child.type === Fragment) return hasChildren(child.props.children);
+	return true;
+});
+const cx = (...classes) => classes.filter(Boolean).join(" ");
+/** Classes for the element that receives a part's `className`. The package CSS reset skips `commerce-part`. */
+const partClass = (...classes) => cx("commerce-part", ...classes);
+/**
+* Props for a part's outer element: `partClass` plus `data-commerce-part`, the part's name in kebab case, such as
+* `cart-checkout`. The attribute is a stable styling hook; internal utility classes are not.
+*/
+const partProps = (name, ...classes) => ({
+	className: partClass(...classes),
+	"data-commerce-part": name
+});
+/** The host's label for `state`, or `fallback` when the host gave none or it renders nothing. */
+function renderLabel(label, state, fallback) {
+	if (typeof label === "function") {
+		const content = label(state);
+		return hasChildren(content) ? content : fallback;
+	}
+	return hasChildren(label) ? label : fallback;
+}
+/**
+* Counts the parts mounted under a root, by key. Parts register in an effect, and a parent's effects run after its
+* children's, so the root can read `has` in its own effect. `onChange` must be stable; it runs after each change.
+*/
+function usePartRegistry(onChange) {
+	const counts = useRef(/* @__PURE__ */ new Map());
+	const has = useCallback((key) => counts.current.has(key), []);
+	const register = useCallback((key) => {
+		counts.current.set(key, (counts.current.get(key) ?? 0) + 1);
+		onChange?.(has);
+		return () => {
+			const count = (counts.current.get(key) ?? 1) - 1;
+			if (count > 0) counts.current.set(key, count);
+			else counts.current.delete(key);
+			onChange?.(has);
+		};
+	}, [has, onChange]);
+	return useMemo(() => ({
+		register,
+		has
+	}), [register, has]);
+}
+
 //#endregion
 //#region src/storefront-surface.tsx
 function StorefrontSurface({ children, className = "" }) {
@@ -666,22 +821,28 @@ function CommerceStatus() {
 //#region src/cart.tsx
 const buttonClass = "inline-flex min-h-11 items-center justify-center gap-2 rounded-lg bg-commerce-accent px-5 py-2 text-sm font-semibold text-commerce-on-accent hover:bg-commerce-accent-hover focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-900 disabled:cursor-not-allowed disabled:bg-neutral-200 disabled:text-neutral-700 disabled:hover:bg-neutral-200";
 const inputClass = "min-h-11 rounded-lg border border-neutral-400 bg-white px-3 py-2 text-neutral-900 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-900";
-function CartButton() {
+/** Opens the cart drawer and shows the item count. */
+function CartButton({ children } = {}) {
 	const { setOpen, open, connection } = useCommerce();
 	const { itemCount } = useCart();
 	return /* @__PURE__ */ jsx(StorefrontSurface, {
 		className: "commerce-inline",
-		children: /* @__PURE__ */ jsxs("button", {
+		children: /* @__PURE__ */ jsx("button", {
 			type: "button",
 			className: buttonClass,
 			disabled: connection !== "ready" && connection !== "unbound",
 			"aria-haspopup": "dialog",
 			"aria-expanded": open,
+			"data-commerce-part": "cart-button",
 			onClick: () => setOpen(true),
-			children: ["Cart ", /* @__PURE__ */ jsx("span", {
-				className: "rounded-full bg-white px-2 py-0.5 text-xs text-neutral-900",
-				children: itemCount
-			})]
+			children: renderLabel(children, { itemCount }, /* @__PURE__ */ jsxs(Fragment$1, { children: [
+				"Cart",
+				" ",
+				/* @__PURE__ */ jsx("span", {
+					className: "rounded-full bg-white px-2 py-0.5 text-xs text-neutral-900",
+					children: itemCount
+				})
+			] }))
 		})
 	});
 }
@@ -693,7 +854,7 @@ function quantityProblem(quantity, available) {
 	if (available !== null && available > 0 && quantity > available) return `Only ${available} available.`;
 	return null;
 }
-function AddToCartButton({ sku, name, quantity = 1 }) {
+function AddToCartButton({ sku, name, quantity = 1, children }) {
 	const { addItem, pending, hydrating, error, open, connection } = useCommerce();
 	const [adding, setAdding] = useState(false);
 	const reasonId = useId();
@@ -729,8 +890,12 @@ function AddToCartButton({ sku, name, quantity = 1 }) {
 				"aria-disabled": disabled || pending,
 				"aria-busy": adding,
 				"aria-describedby": reason ? reasonId : void 0,
+				"data-commerce-part": "add-to-cart-button",
 				onClick: () => void handleAdd(),
-				children: soldOut ? "Out of stock" : adding ? "Adding…" : "Add to cart"
+				children: renderLabel(children, {
+					busy: adding,
+					soldOut
+				}, soldOut ? "Out of stock" : adding ? "Adding…" : "Add to cart")
 			}),
 			reason && /* @__PURE__ */ jsx("span", {
 				id: reasonId,
@@ -746,36 +911,6 @@ function AddToCartButton({ sku, name, quantity = 1 }) {
 	});
 }
 
-//#endregion
-//#region src/part.ts
-/** Whether `children` renders anything, so `{custom && <Part />}` with `custom` false falls back to the default. */
-const hasChildren = (children) => Children.toArray(children).some((child) => child !== "");
-const cx = (...classes) => classes.filter(Boolean).join(" ");
-/** Classes for the element that receives a part's `className`. The package CSS reset skips `commerce-part`. */
-const partClass = (...classes) => cx("commerce-part", ...classes);
-/**
-* Counts the parts mounted under a root, by key. Parts register in an effect, and a parent's effects run after its
-* children's, so the root can read `has` in its own effect. `onChange` must be stable; it runs after each change.
-*/
-function usePartRegistry(onChange) {
-	const counts = useRef(/* @__PURE__ */ new Map());
-	const has = useCallback((key) => counts.current.has(key), []);
-	const register = useCallback((key) => {
-		counts.current.set(key, (counts.current.get(key) ?? 0) + 1);
-		onChange?.(has);
-		return () => {
-			const count = (counts.current.get(key) ?? 1) - 1;
-			if (count > 0) counts.current.set(key, count);
-			else counts.current.delete(key);
-			onChange?.(has);
-		};
-	}, [has, onChange]);
-	return useMemo(() => ({
-		register,
-		has
-	}), [register, has]);
-}
-
 //#endregion
 //#region src/cart-parts.tsx
 const CartContext = createContext(null);
@@ -825,11 +960,11 @@ function CartRoot({ children, className }) {
 	const { connection } = useCommerce();
 	const isSample = connection === "unbound";
 	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" || isSample ? /* @__PURE__ */ jsx(CartProvider, { children: /* @__PURE__ */ jsx("section", {
-		className: partClass(className),
+		...partProps("cart-root", className),
 		"data-commerce-source": isSample ? "sample" : void 0,
 		children
 	}) }) : /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-root", className),
 		children: /* @__PURE__ */ jsx(CommerceStatus, {})
 	}) });
 }
@@ -856,7 +991,7 @@ function CartDrawerRoot({ children, className }) {
 			children: /* @__PURE__ */ jsx(Dialog.Content, {
 				"data-commerce-source": connection === "unbound" ? "sample" : void 0,
 				...described ? {} : { "aria-describedby": void 0 },
-				className: partClass("pointer-events-auto", className),
+				...partProps("cart-drawer-root", "pointer-events-auto", className),
 				onCloseAutoFocus: (event) => {
 					event.preventDefault();
 					restoreFocus();
@@ -870,26 +1005,26 @@ function CartDrawerRoot({ children, className }) {
 	});
 }
 /** "Your cart", or "Sample cart" before a store is connected, as an H2. In the drawer it names the dialog. */
-function CartTitle({ className }) {
+function CartTitle({ className, children }) {
 	const { isSample } = useCartInternal("CartTitle");
 	const Heading = useContext(CartDrawerContext) ? Dialog.Title : "h2";
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-title", className),
 		children: /* @__PURE__ */ jsx(Heading, {
 			className: "text-2xl font-semibold",
-			children: isSample ? "Sample cart" : "Your cart"
+			children: renderLabel(children, { isSample }, isSample ? "Sample cart" : "Your cart")
 		})
 	});
 }
 /** One line about the cart. In the drawer it describes the dialog. */
-function CartDescription({ className }) {
+function CartDescription({ className, children }) {
 	const { isSample } = useCartInternal("CartDescription");
 	const drawer = useContext(CartDrawerContext);
 	const register = drawer?.register;
 	useEffect(() => register?.("description"), [register]);
-	const text = isSample ? "Example products and prices in USD. Nothing can be purchased." : "Review your items before checkout.";
+	const text = renderLabel(children, { isSample }, isSample ? "Example products and prices in USD. Nothing can be purchased." : "Review your items before checkout.");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-description", className),
 		children: drawer ? /* @__PURE__ */ jsx(Dialog.Description, {
 			className: "text-sm text-neutral-600",
 			children: text
@@ -904,7 +1039,7 @@ function CartClose({ className }) {
 	useCartInternal("CartClose");
 	if (!useContext(CartDrawerContext)) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-close", className),
 		children: /* @__PURE__ */ jsx(Dialog.Close, {
 			className: "min-h-11 min-w-11 rounded-lg border border-neutral-400 bg-white px-3 text-neutral-900 focus-visible:outline focus-visible:outline-2",
 			"aria-label": "Close cart",
@@ -917,7 +1052,7 @@ function CartNotices({ className }) {
 	const { storageWarning, error, action, locked, run, refresh } = useCartInternal("CartNotices");
 	if (!storageWarning && !error) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-notices", className),
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "flex flex-col gap-4",
 			children: [storageWarning && /* @__PURE__ */ jsx("p", {
@@ -972,7 +1107,7 @@ function CartItems({ className, children }) {
 			children: "Loading your cart…"
 		}), /* @__PURE__ */ jsx("div", {
 			role: "list",
-			className: partClass(className),
+			...partProps("cart-items", className),
 			children: items.map((item, index) => /* @__PURE__ */ jsx(CartItemsContext.Provider, {
 				value: item,
 				children: template
@@ -990,7 +1125,7 @@ function CartItemRoot({ children, className }) {
 		value: item,
 		children: /* @__PURE__ */ jsx("div", {
 			role: "listitem",
-			className: partClass(className),
+			...partProps("cart-item-root", className),
 			"data-testid": "cart-item",
 			children: /* @__PURE__ */ jsx(CartItemsContext.Provider, {
 				value: null,
@@ -1004,7 +1139,7 @@ function CartItemImage({ className }) {
 	const { imageUrl } = useCartItemInternal("CartItemImage");
 	if (!imageUrl) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-item-image", className),
 		children: /* @__PURE__ */ jsx("img", {
 			src: imageUrl,
 			alt: "",
@@ -1016,7 +1151,7 @@ function CartItemImage({ className }) {
 function CartItemName({ className }) {
 	const { name } = useCartItemInternal("CartItemName");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-item-name", className),
 		children: /* @__PURE__ */ jsx("h3", {
 			className: "font-semibold",
 			children: name
@@ -1028,7 +1163,7 @@ function CartItemOptions({ className }) {
 	const { options } = useCartItemInternal("CartItemOptions");
 	if (!options.length) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-item-options", className),
 		children: options.map((option) => /* @__PURE__ */ jsxs("p", {
 			className: "text-sm text-neutral-600",
 			children: [
@@ -1042,11 +1177,12 @@ function CartItemOptions({ className }) {
 /** The line total. */
 function CartItemPrice({ className }) {
 	const { subtotal, currency } = useCartItemInternal("CartItemPrice");
+	const money$1 = useMoney();
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-item-price", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "text-sm",
-			children: subtotal === null ? "Price unavailable" : money(subtotal, currency)
+			children: subtotal === null ? "Price unavailable" : money$1(subtotal, currency)
 		})
 	});
 }
@@ -1056,7 +1192,7 @@ function CartItemQuantity({ className }) {
 	const { id, name, quantity } = useCartItemInternal("CartItemQuantity");
 	const { action, locked, run, changeQuantity } = useCartInternal("CartItemQuantity");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-item-quantity", className),
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "flex items-center rounded-lg border border-neutral-300",
 			children: [
@@ -1064,6 +1200,7 @@ function CartItemQuantity({ className }) {
 					type: "button",
 					className: stepperButtonClass,
 					"aria-label": `Decrease quantity of ${name}`,
+					"data-commerce-control": "decrease",
 					disabled: action === `decrease:${id}` || !id || quantity <= 1,
 					"aria-disabled": locked || !id || quantity <= 1,
 					"aria-busy": action === `decrease:${id}`,
@@ -1081,6 +1218,7 @@ function CartItemQuantity({ className }) {
 					type: "button",
 					className: stepperButtonClass,
 					"aria-label": `Increase quantity of ${name}`,
+					"data-commerce-control": "increase",
 					disabled: action === `increase:${id}` || !id,
 					"aria-disabled": locked || !id,
 					"aria-busy": action === `increase:${id}`,
@@ -1092,20 +1230,22 @@ function CartItemQuantity({ className }) {
 	});
 }
 /** Removes the line. */
-function CartItemRemove({ className }) {
+function CartItemRemove({ className, children }) {
 	const { id, name } = useCartItemInternal("CartItemRemove");
 	const { action, locked, run, removeItem } = useCartInternal("CartItemRemove");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
-		children: /* @__PURE__ */ jsx("button", {
+		...partProps("cart-item-remove", className),
+		children: /* @__PURE__ */ jsxs("button", {
 			type: "button",
 			className: "min-h-11 bg-white px-2 text-sm text-neutral-900 underline focus-visible:outline focus-visible:outline-2 disabled:cursor-not-allowed disabled:text-neutral-600",
-			"aria-label": `Remove ${name}`,
 			disabled: action === `remove:${id}` || !id,
 			"aria-disabled": locked || !id,
 			"aria-busy": action === `remove:${id}`,
 			onClick: () => run(`remove:${id}`, () => removeItem(id)),
-			children: "Remove"
+			children: [renderLabel(children, { busy: action === `remove:${id}` }, "Remove"), /* @__PURE__ */ jsxs("span", {
+				className: "sr-only",
+				children: [" ", name]
+			})]
 		})
 	});
 }
@@ -1131,8 +1271,8 @@ function CartEmpty({ className, children }) {
 	const { items, hydrating, isSample, catalogPath, close } = useCartInternal("CartEmpty");
 	if (hydrating || items.length) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
-		children: hasChildren(children) ? children : /* @__PURE__ */ jsxs(Fragment, { children: [
+		...partProps("cart-empty", className),
+		children: hasChildren(children) ? children : /* @__PURE__ */ jsxs(Fragment$1, { children: [
 			/* @__PURE__ */ jsx("p", {
 				className: "text-xl font-medium",
 				children: "Your cart is empty"
@@ -1155,21 +1295,22 @@ function CartSummary({ className, children }) {
 	const { items } = useCartInternal("CartSummary");
 	if (!items.length) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-summary", className),
 		children
 	});
 }
 /** The subtotal, labeled "Sample subtotal" for samples. Renders nothing until the server prices the cart. */
 function CartSubtotal({ className }) {
 	const { items, subtotal, currency, isSample } = useCartInternal("CartSubtotal");
+	const money$1 = useMoney();
 	if (!items.length || subtotal === null) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-subtotal", className),
 		children: /* @__PURE__ */ jsx("dl", {
 			className: "space-y-2 text-sm",
 			children: /* @__PURE__ */ jsxs("div", {
 				className: "flex justify-between",
-				children: [/* @__PURE__ */ jsx("dt", { children: isSample ? "Sample subtotal" : "Subtotal" }), /* @__PURE__ */ jsx("dd", { children: money(subtotal, currency) })]
+				children: [/* @__PURE__ */ jsx("dt", { children: isSample ? "Sample subtotal" : "Subtotal" }), /* @__PURE__ */ jsx("dd", { children: money$1(subtotal, currency) })]
 			})
 		})
 	});
@@ -1182,7 +1323,7 @@ function CartCheckoutNote({ className }) {
 	const { items, isSample } = useCartInternal("CartCheckoutNote");
 	if (isSample || !items.length) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass("commerce-cart-checkout-adjustments-note", className),
+		...partProps("cart-checkout-note", "commerce-cart-checkout-adjustments-note", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "text-sm text-neutral-600",
 			children: "Shipping, taxes, and discounts are calculated at checkout."
@@ -1193,7 +1334,7 @@ function CartCheckoutNote({ className }) {
 * The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable.
 * Samples never check out. Renders nothing for an empty cart.
 */
-function CartCheckout({ className }) {
+function CartCheckout({ className, children }) {
 	const { items, isSample, checkoutEnabled, checkoutReady, hydrating, action, locked, run, checkout } = useCartInternal("CartCheckout");
 	if (!items.length) return null;
 	let content;
@@ -1212,10 +1353,10 @@ function CartCheckout({ className }) {
 		"aria-disabled": locked || !checkoutReady,
 		"aria-busy": action === "checkout",
 		onClick: () => run("checkout", checkout),
-		children: action === "checkout" ? "Opening checkout…" : "Proceed to Checkout"
+		children: renderLabel(children, { busy: action === "checkout" }, action === "checkout" ? "Opening checkout…" : "Proceed to Checkout")
 	});
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("cart-checkout", className),
 		children: content
 	});
 }
@@ -1250,14 +1391,18 @@ function CartDrawer() {
 
 //#endregion
 //#region src/product-card.tsx
+/**
+* A product image that fills its container, with a labeled placeholder when there is no URL or it fails to load.
+* Use it in custom parts so they handle missing images like the package's own.
+*/
 function ProductImage({ url, name, className = "" }) {
-	const [failed, setFailed] = useState(false);
-	return url && !failed ? /* @__PURE__ */ jsx("img", {
+	const [failedUrl, setFailedUrl] = useState(null);
+	return url && url !== failedUrl ? /* @__PURE__ */ jsx("img", {
 		src: url,
 		alt: name,
 		loading: "lazy",
 		className: `h-full w-full object-cover ${className}`,
-		onError: () => setFailed(true)
+		onError: () => setFailedUrl(url)
 	}) : /* @__PURE__ */ jsx("div", {
 		className: `flex h-full min-h-44 items-center justify-center p-6 text-center ${className}`,
 		role: "img",
@@ -1338,7 +1483,7 @@ function ProductCardRoot({ children, product, className }) {
 	const card = /* @__PURE__ */ jsx(ProductCardContext.Provider, {
 		value,
 		children: /* @__PURE__ */ jsx("article", {
-			className: partClass("group", className),
+			...partProps("product-card-root", "group", className),
 			children: /* @__PURE__ */ jsx(CatalogItemContext.Provider, {
 				value: null,
 				children
@@ -1354,7 +1499,7 @@ function ProductCardRoot({ children, product, className }) {
 function ProductCardImage({ className }) {
 	const card = useProductCardInternal("ProductCardImage");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-card-image", className),
 		children: card.source === "live" ? /* @__PURE__ */ jsx(Link, {
 			to: card.href,
 			tabIndex: card.imageLinked ? void 0 : -1,
@@ -1377,7 +1522,7 @@ function ProductCardTitle({ className }) {
 	const { name, href, register } = useProductCardInternal("ProductCardTitle");
 	useEffect(() => href ? register(titleLink) : void 0, [href, register]);
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-card-title", className),
 		children: /* @__PURE__ */ jsx("h2", {
 			className: "break-words text-2xl font-semibold leading-tight",
 			children: href ? /* @__PURE__ */ jsx(Link, {
@@ -1393,7 +1538,7 @@ function ProductCardDescription({ className }) {
 	const { product } = useProductCardInternal("ProductCardDescription");
 	if (!product?.description) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-card-description", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "line-clamp-3 text-sm leading-6",
 			children: product.description
@@ -1403,16 +1548,16 @@ function ProductCardDescription({ className }) {
 /** The product's price, or its price range when variants differ. */
 function ProductCardPrice({ className }) {
 	const card = useProductCardInternal("ProductCardPrice");
-	const { config } = useCommerce();
+	const money$1 = useMoney();
 	let text;
-	if (card.source === "sample") text = money(card.sample.price, "USD");
+	if (card.source === "sample") text = money$1(card.sample.price, "USD");
 	else {
 		const min = card.product.priceRange?.min;
 		const max = card.product.priceRange?.max;
-		text = typeof min === "number" ? `${money(min, config.currencyCode)}${typeof max === "number" && max !== min ? ` – ${money(max, config.currencyCode)}` : ""}` : "Price unavailable";
+		text = typeof min === "number" ? `${money$1(min)}${typeof max === "number" && max !== min ? ` – ${money$1(max)}` : ""}` : "Price unavailable";
 	}
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-card-price", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "text-lg font-semibold leading-7",
 			children: text
@@ -1423,44 +1568,73 @@ function ProductCardPrice({ className }) {
 * Adds the product directly when it has exactly one SKU and no options; otherwise links to its page to choose.
 * Samples add to the sample cart.
 */
-function ProductCardAction({ className }) {
+function ProductCardAction({ className, children }) {
 	const card = useProductCardInternal("ProductCardAction");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-card-action", className),
 		children: card.source === "live" ? /* @__PURE__ */ jsx(LiveAction, {
 			product: card.product,
 			name: card.name,
-			href: card.href
-		}) : /* @__PURE__ */ jsx(SampleAction, { sample: card.sample })
+			href: card.href,
+			label: children
+		}) : /* @__PURE__ */ jsx(SampleAction, {
+			sample: card.sample,
+			label: children
+		})
 	});
 }
-function LiveAction({ product, name, href }) {
+function LiveAction({ product, name, href, label }) {
 	const selectedSku = getSingleMatchedSku(product);
 	const hasVariants = getProductAttributes(product).length > 0;
 	if (!hasVariants && selectedSku) return /* @__PURE__ */ jsx(AddToCartButton, {
 		sku: selectedSku,
-		name
+		name,
+		children: (state) => renderLabel(label, {
+			action: "add",
+			...state
+		}, null)
 	});
 	return /* @__PURE__ */ jsx(Link, {
 		className: buttonClass,
 		to: href,
-		children: hasVariants ? "Choose options" : "View product"
+		children: renderLabel(label, {
+			action: hasVariants ? "choose-options" : "view-product",
+			busy: false,
+			soldOut: false
+		}, hasVariants ? "Choose options" : "View product")
 	});
 }
-function SampleAction({ sample }) {
+function SampleAction({ sample, label }) {
 	const { add } = useSampleCart();
-	return /* @__PURE__ */ jsx("button", {
+	const custom = renderLabel(label, {
+		action: "add",
+		busy: false,
+		soldOut: false
+	}, null);
+	return custom === null ? /* @__PURE__ */ jsx("button", {
 		type: "button",
 		className: buttonClass,
 		"aria-label": `Add ${sample.name} to sample cart`,
 		onClick: () => add(sample.key),
 		children: "Add to cart"
+	}) : /* @__PURE__ */ jsxs("button", {
+		type: "button",
+		className: buttonClass,
+		onClick: () => add(sample.key),
+		children: [custom, /* @__PURE__ */ jsxs("span", {
+			className: "sr-only",
+			children: [
+				" (",
+				sample.name,
+				", sample)"
+			]
+		})]
 	});
 }
 const packagedCardClass = "flex min-w-0 flex-col overflow-hidden rounded-lg border border-neutral-200";
 /** The packaged card's parts, inside a root that has `packagedCardClass`. */
 function PackagedCardParts() {
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(ProductCardImage, {}), /* @__PURE__ */ jsxs("div", {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ProductCardImage, {}), /* @__PURE__ */ jsxs("div", {
 		className: "flex flex-1 flex-col p-6",
 		children: [
 			/* @__PURE__ */ jsx(ProductCardTitle, {}),
@@ -1484,9 +1658,22 @@ function ProductCard({ product }) {
 	});
 }
 
+//#endregion
+//#region src/root-params.ts
+/**
+* A root's search params: the page URL's, or with `urlState` off, the root's own. A second root on the page, such
+* as a quick view, then neither reads nor changes the page's params, and its state ends when it unmounts.
+*/
+function useRootParams(urlState) {
+	const [urlParams, setUrlParams] = useSearchParams();
+	const [localParams, setLocalParams] = useState(() => new URLSearchParams());
+	return urlState ? [urlParams, setUrlParams] : [localParams, setLocalParams];
+}
+
 //#endregion
 //#region src/catalog.tsx
 const CatalogContext = createContext(null);
+const CatalogEmptyContext = createContext(null);
 const sampleCatalog = { source: "sample" };
 function useCatalogInternal(part) {
 	const context = useContext(CatalogContext);
@@ -1494,32 +1681,47 @@ function useCatalogInternal(part) {
 	return context;
 }
 /** Loads one cursor page of products, or the built-in samples, and provides them to catalog parts. */
-function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = false }) {
+function CatalogRoot({ children, className, sampleProducts: sampleProducts$1 = false, pageSize = 6, urlState = true }) {
 	const { connection } = useCommerce();
+	const [custom, setCustom] = useState(false);
+	const { register, has } = usePartRegistry(useCallback((registered) => setCustom(registered("empty")), []));
+	useEffect(() => {
+		setCustom(has("empty"));
+	}, [has]);
+	const empty = useMemo(() => ({
+		register,
+		custom
+	}), [register, custom]);
+	if (!Number.isSafeInteger(pageSize) || pageSize < 1) throw new Error(`CatalogRoot pageSize must be a whole number of 1 or more, not ${pageSize}.`);
 	let content;
 	if (connection === "ready") content = /* @__PURE__ */ jsx(CatalogLoader, {
 		className,
+		pageSize,
+		urlState,
 		children
 	});
 	else if (connection === "unbound" && sampleProducts$1) content = /* @__PURE__ */ jsx(CatalogContext.Provider, {
 		value: sampleCatalog,
 		children: /* @__PURE__ */ jsx("section", {
-			className: partClass(className),
+			...partProps("catalog-root", className),
 			"data-commerce-source": "sample",
 			children
 		})
 	});
 	else content = /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("catalog-root", className),
 		children: /* @__PURE__ */ jsx(CommerceStatus, {})
 	});
-	return /* @__PURE__ */ jsx(StorefrontSurface, { children: content });
+	return /* @__PURE__ */ jsx(StorefrontSurface, { children: /* @__PURE__ */ jsx(CatalogEmptyContext.Provider, {
+		value: empty,
+		children: content
+	}) });
 }
-function CatalogLoader({ children, className }) {
+function CatalogLoader({ children, className, pageSize, urlState }) {
 	const { config } = useCommerce();
-	const [params, setParams] = useSearchParams();
+	const [params, setParams] = useRootParams(urlState);
 	const after = params.get("after") ?? "";
-	const urlParams = new URLSearchParams({ first: "6" });
+	const urlParams = new URLSearchParams({ first: String(pageSize) });
 	if (after) urlParams.set("after", after);
 	const products = useQuery({
 		retry: false,
@@ -1527,6 +1729,7 @@ function CatalogLoader({ children, className }) {
 			"commerce",
 			config.cartScope,
 			"products",
+			pageSize,
 			after
 		],
 		queryFn: ({ signal }) => request(`/products?${urlParams}`, {
@@ -1556,7 +1759,7 @@ function CatalogLoader({ children, className }) {
 	return /* @__PURE__ */ jsx(CatalogContext.Provider, {
 		value,
 		children: /* @__PURE__ */ jsx("section", {
-			className: partClass(className),
+			...partProps("catalog-root", className),
 			children
 		})
 	});
@@ -1565,7 +1768,7 @@ function CatalogLoader({ children, className }) {
 function CatalogHeader({ title = "Shop all products", description = "Explore the collection and find your favorites.", className }) {
 	useCatalogInternal("CatalogHeader");
 	return /* @__PURE__ */ jsxs("header", {
-		className: partClass(className),
+		...partProps("catalog-header", className),
 		children: [/* @__PURE__ */ jsx("h1", {
 			className: "max-w-3xl text-4xl font-semibold leading-tight sm:text-5xl lg:text-6xl",
 			children: title
@@ -1579,7 +1782,7 @@ function CatalogHeader({ title = "Shop all products", description = "Explore the
 function CatalogSummary({ className }) {
 	const catalog = useCatalogInternal("CatalogSummary");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("catalog-summary", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "text-sm",
 			role: "status",
@@ -1606,10 +1809,11 @@ const packagedCard = /* @__PURE__ */ jsx(ProductCardRoot, {
 });
 /**
 * The product cards. `className` goes on the element that contains the cards, such as a grid. While loading, that
-* element holds placeholder cards. The error with its retry and the empty message render just before it.
+* element holds placeholder cards. The error with its retry and, without a `CatalogEmpty`, the empty message render just before it.
 */
 function CatalogProducts({ className, children }) {
 	const catalog = useCatalogInternal("CatalogProducts");
+	const customEmpty = useContext(CatalogEmptyContext)?.custom ?? false;
 	const card = hasChildren(children) ? children : packagedCard;
 	const nodes = catalog.source === "live" ? catalog.nodes : null;
 	const items = useMemo(() => nodes ? nodes.map((product) => ({
@@ -1620,7 +1824,7 @@ function CatalogProducts({ className, children }) {
 		}
 	})) : sampleItems, [nodes]);
 	const products = catalog.source === "live" ? catalog.products : null;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
 		products?.isError && /* @__PURE__ */ jsxs("div", {
 			role: "alert",
 			className: "rounded-lg bg-red-50 p-5 text-red-800",
@@ -1631,12 +1835,12 @@ function CatalogProducts({ className, children }) {
 				children: "Retry products"
 			})]
 		}),
-		products?.isSuccess && !items.length && /* @__PURE__ */ jsx("p", {
+		products?.isSuccess && !items.length && !customEmpty && /* @__PURE__ */ jsx("p", {
 			className: "py-16 text-center",
 			children: "No products available."
 		}),
 		/* @__PURE__ */ jsx("div", {
-			className: partClass(className),
+			...partProps("catalog-products", className),
 			children: products?.isPending ? [
 				0,
 				1,
@@ -1659,6 +1863,20 @@ function CatalogProducts({ className, children }) {
 		})
 	] });
 }
+/**
+* Renders only when a connected store's catalog has no products: "No products available.", or its children. While
+* one is mounted, `CatalogProducts` leaves out its own empty message. Samples are never empty.
+*/
+function CatalogEmpty({ className, children }) {
+	const catalog = useCatalogInternal("CatalogEmpty");
+	const register = useContext(CatalogEmptyContext)?.register;
+	useEffect(() => register?.("empty"), [register]);
+	if (catalog.source === "sample" || !catalog.products.isSuccess || catalog.nodes.length) return null;
+	return /* @__PURE__ */ jsx("div", {
+		...partProps("catalog-empty", className),
+		children: hasChildren(children) ? children : /* @__PURE__ */ jsx("p", { children: "No products available." })
+	});
+}
 /** First-page and next-page buttons. Renders nothing for samples, which have one page. */
 function CatalogPagination({ className }) {
 	const catalog = useCatalogInternal("CatalogPagination");
@@ -1667,7 +1885,7 @@ function CatalogPagination({ className }) {
 	const pageInfo = catalog.products.data?.skuGroups?.pageInfo;
 	return /* @__PURE__ */ jsx("nav", {
 		"aria-label": "Product pages",
-		className: partClass(className),
+		...partProps("catalog-pagination", className),
 		children: /* @__PURE__ */ jsxs("div", {
 			className: "flex justify-between",
 			children: [after ? /* @__PURE__ */ jsx("button", {
@@ -1685,9 +1903,10 @@ function CatalogPagination({ className }) {
 	});
 }
 /** The packaged catalog. Compose `CatalogRoot` and the catalog parts for a custom layout. */
-function Catalog({ title, description, showHeader = true, sampleProducts: sampleProducts$1 }) {
+function Catalog({ title, description, showHeader = true, sampleProducts: sampleProducts$1, pageSize }) {
 	return /* @__PURE__ */ jsxs(CatalogRoot, {
 		sampleProducts: sampleProducts$1,
+		pageSize,
 		children: [
 			showHeader && /* @__PURE__ */ jsx(CatalogHeader, {
 				title,
@@ -1763,26 +1982,32 @@ function useSkuOptionRegistration() {
 	const { register } = useProductDetailsInternal("ProductDetailsOptions");
 	useEffect(() => register("sku"), [register]);
 }
-/** Loads the product for the route's `:productId` and provides state to product parts. */
-function ProductDetailsRoot({ children, className }) {
-	const { productId = "" } = useParams();
+/** Loads one product, by default the route's `:productId`, and provides state to product parts. */
+function ProductDetailsRoot({ productId: productIdProp, className,...props }) {
+	const { productId: routeProductId = "" } = useParams();
+	const productId = productIdProp ?? routeProductId;
 	const { connection } = useCommerce();
+	useEffect(() => {
+		if (process.env.NODE_ENV === "production" || productId || connection !== "ready") return;
+		console.warn("[gd-commerce-storefront] ProductDetailsRoot has no product to show. Pass `productId`, or render it on a route with a `:productId` parameter.");
+	}, [productId, connection]);
 	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" ? /* @__PURE__ */ jsx(ProductDetailsLoader, {
 		productId,
 		className,
-		children
+		...props
 	}, productId) : /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-root", className),
 		children: /* @__PURE__ */ jsx(CommerceStatus, {})
 	}) });
 }
-function ProductDetailsLoader({ productId, className, children }) {
+function ProductDetailsLoader({ productId, className, children, urlState = true, loading, notFound, error }) {
 	const { config } = useCommerce();
-	const [params, setParams] = useSearchParams();
+	const [params, setParams] = useRootParams(urlState);
 	const [quantity, setQuantity] = useState(1);
 	const [imageIndex, setImageIndex] = useState(0);
 	const product = useQuery({
 		retry: false,
+		enabled: !!productId,
 		queryKey: [
 			"commerce",
 			config.cartScope,
@@ -1841,43 +2066,49 @@ function ProductDetailsLoader({ productId, className, children }) {
 		if (missing.length === 0) return;
 		console.warn(`[gd-commerce-storefront] No control for ${missing.map((control) => control === "sku" ? "the SKU option" : `"${control.slice(10)}"`).join(", ")} is rendered right now, so this product cannot be added to the cart until one is. Render <ProductDetailsOptions />, <ProductDetailsOption attribute='…' /> for each attribute, or <ProductDetailsPurchase />, or ignore this if the control mounts later.`);
 	}, [requiredControls, has]);
-	if (product.isPending) return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
-		children: /* @__PURE__ */ jsx("p", {
+	if (product.isPending && productId) return /* @__PURE__ */ jsx("div", {
+		...partProps("product-details-root", className),
+		children: hasChildren(loading) ? loading : /* @__PURE__ */ jsx("p", {
 			role: "status",
 			children: "Loading product…"
 		})
 	});
-	if (product.isError && !productNotFound) return /* @__PURE__ */ jsxs("div", {
-		role: "alert",
-		className: partClass(className),
-		children: [
-			/* @__PURE__ */ jsx("h1", {
-				className: "text-2xl font-semibold",
-				children: "Product unavailable"
-			}),
-			/* @__PURE__ */ jsx("p", {
-				className: "my-4 text-red-700",
-				children: message(product.error)
-			}),
-			/* @__PURE__ */ jsx("button", {
-				type: "button",
-				className: buttonClass,
-				onClick: () => void product.refetch(),
-				children: "Retry product"
-			})
-		]
-	});
-	if (productNotFound || !group) return /* @__PURE__ */ jsxs("div", {
-		className: partClass(className),
-		children: [/* @__PURE__ */ jsx("h1", {
+	if (product.isError && !productNotFound) {
+		const retry = () => void product.refetch();
+		return /* @__PURE__ */ jsx("div", {
+			role: "alert",
+			...partProps("product-details-root", className),
+			children: renderLabel(error, {
+				message: message(product.error),
+				retry
+			}, /* @__PURE__ */ jsxs(Fragment$1, { children: [
+				/* @__PURE__ */ jsx("h1", {
+					className: "text-2xl font-semibold",
+					children: "Product unavailable"
+				}),
+				/* @__PURE__ */ jsx("p", {
+					className: "my-4 text-red-700",
+					children: message(product.error)
+				}),
+				/* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: buttonClass,
+					onClick: retry,
+					children: "Retry product"
+				})
+			] }))
+		});
+	}
+	if (productNotFound || !group) return /* @__PURE__ */ jsx("div", {
+		...partProps("product-details-root", className),
+		children: hasChildren(notFound) ? notFound : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("h1", {
 			className: "text-2xl font-semibold",
 			children: "Product not found"
 		}), /* @__PURE__ */ jsx(Link, {
 			className: `${buttonClass} mt-4`,
 			to: config.catalogPath,
 			children: "Back to shop"
-		})]
+		})] })
 	});
 	const value = {
 		product: group,
@@ -1908,7 +2139,7 @@ function ProductDetailsLoader({ productId, className, children }) {
 	return /* @__PURE__ */ jsx(ProductDetailsContext.Provider, {
 		value,
 		children: /* @__PURE__ */ jsx("article", {
-			className: partClass(className),
+			...partProps("product-details-root", className),
 			children
 		})
 	});
@@ -1928,7 +2159,7 @@ function ProductDetailsPurchase({ className }) {
 	const { attributes, skuOptions } = useProductDetailsInternal("ProductDetailsPurchase");
 	const belowOptions = attributes.length || skuOptions.length ? "-mt-4" : void 0;
 	return /* @__PURE__ */ jsxs("div", {
-		className: partClass("space-y-6", className),
+		...partProps("product-details-purchase", "space-y-6", className),
 		children: [
 			/* @__PURE__ */ jsx(OptionControls, {}),
 			/* @__PURE__ */ jsx(ProductDetailsPurchaseStatus, { className: belowOptions }),
@@ -1943,13 +2174,13 @@ function ProductDetailsOptions({ className }) {
 	const { attributes, skuOptions } = useProductDetailsInternal("ProductDetailsOptions");
 	if (attributes.length === 0 && skuOptions.length === 0) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass("space-y-6", className),
+		...partProps("product-details-options", "space-y-6", className),
 		children: /* @__PURE__ */ jsx(OptionControls, {})
 	});
 }
 function OptionControls() {
 	const { attributes, skuOptions } = useProductDetailsInternal("ProductDetailsOptions");
-	return /* @__PURE__ */ jsxs(Fragment, { children: [attributes.map((attribute) => /* @__PURE__ */ jsx(ProductDetailsOption, { attribute: attribute.name }, attribute.id || attribute.name)), skuOptions.length > 0 && /* @__PURE__ */ jsx(SkuOption, {})] });
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [attributes.map((attribute) => /* @__PURE__ */ jsx(ProductDetailsOption, { attribute: attribute.name }, attribute.id || attribute.name)), skuOptions.length > 0 && /* @__PURE__ */ jsx(SkuOption, {})] });
 }
 function Select({ children,...props }) {
 	return /* @__PURE__ */ jsxs("div", {
@@ -1978,7 +2209,7 @@ function SkuOption() {
 	const id = useId();
 	useSkuOptionRegistration();
 	return /* @__PURE__ */ jsxs("div", {
-		className: partClass(),
+		...partProps("product-details-sku-option"),
 		children: [/* @__PURE__ */ jsx("label", {
 			htmlFor: id,
 			className: "mb-2 block font-medium",
@@ -2002,7 +2233,8 @@ function ProductDetailsOption({ attribute, className }) {
 	const option = useProductDetailsOption(attribute);
 	if (!option) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-option", className),
+		"data-commerce-attribute": option.name,
 		children: /* @__PURE__ */ jsxs("fieldset", { children: [/* @__PURE__ */ jsx("legend", {
 			className: "mb-2 font-medium",
 			children: option.label
@@ -2061,7 +2293,7 @@ function ProductDetailsPurchaseStatus({ className }) {
 			break;
 	}
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-purchase-status", className),
 		children: content
 	});
 }
@@ -2070,7 +2302,7 @@ function ProductDetailsAvailability({ className }) {
 	const { selectedSku, availableQuantity } = useProductDetailsInternal("ProductDetailsAvailability");
 	if (!selectedSku) return null;
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-availability", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "text-sm",
 			"aria-live": "polite",
@@ -2086,7 +2318,7 @@ function ProductDetailsQuantity({ className }) {
 	if (!selectedSku) return null;
 	const problem = isSoldOut(availableQuantity) ? null : quantityProblem(quantity, availableQuantity);
 	return /* @__PURE__ */ jsxs("div", {
-		className: partClass(className),
+		...partProps("product-details-quantity", className),
 		children: [
 			/* @__PURE__ */ jsx("label", {
 				htmlFor: id,
@@ -2114,21 +2346,26 @@ function ProductDetailsQuantity({ className }) {
 	});
 }
 /** Adds the verified SKU and quantity. While disabled, its accessible description says why. */
-function ProductDetailsAddToCart({ className }) {
+function ProductDetailsAddToCart({ className, children }) {
 	const { selectedSku, name, quantity, status } = useProductDetailsInternal("ProductDetailsAddToCart");
 	const reasonId = useId();
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-add-to-cart", className),
 		children: selectedSku ? /* @__PURE__ */ jsx(AddToCartButton, {
 			sku: selectedSku,
 			name,
-			quantity
-		}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("button", {
+			quantity,
+			children
+		}) : /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("button", {
 			type: "button",
 			className: `${buttonClass} w-full`,
 			disabled: true,
 			"aria-describedby": reasonId,
-			children: "Add to cart"
+			"data-commerce-part": "add-to-cart-button",
+			children: renderLabel(children, {
+				busy: false,
+				soldOut: false
+			}, "Add to cart")
 		}), /* @__PURE__ */ jsx("span", {
 			id: reasonId,
 			hidden: true,
@@ -2154,15 +2391,16 @@ function ProductDetails() {
 		})]
 	})] });
 }
-function ProductDetailsBackLink({ className }) {
+/** A link to the catalog. */
+function ProductDetailsBackLink({ className, children }) {
 	useProductDetailsInternal("ProductDetailsBackLink");
 	const { config } = useCommerce();
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-back-link", className),
 		children: /* @__PURE__ */ jsx(Link, {
 			className: "inline-flex min-h-11 items-center text-sm text-inherit underline underline-offset-4 focus-visible:outline focus-visible:outline-2",
 			to: config.catalogPath,
-			children: "← Back to shop"
+			children: renderLabel(children, void 0, "← Back to shop")
 		})
 	});
 }
@@ -2170,7 +2408,7 @@ function ProductDetailsBackLink({ className }) {
 function ProductDetailsGallery({ className }) {
 	const { images, imageIndex, setImageIndex, name } = useProductDetailsInternal("ProductDetailsGallery");
 	return /* @__PURE__ */ jsxs("div", {
-		className: partClass(className),
+		...partProps("product-details-gallery", className),
 		children: [/* @__PURE__ */ jsx("div", {
 			className: "aspect-square overflow-hidden rounded-lg",
 			children: /* @__PURE__ */ jsx(ProductImage, {
@@ -2184,6 +2422,7 @@ function ProductDetailsGallery({ className }) {
 				className: `h-20 w-20 shrink-0 overflow-hidden rounded-lg border-2 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 ${imageIndex === index ? "border-neutral-900" : "border-transparent"}`,
 				"aria-label": `View image ${index + 1}`,
 				"aria-pressed": imageIndex === index,
+				"data-commerce-control": "thumbnail",
 				onClick: () => setImageIndex(index),
 				children: /* @__PURE__ */ jsx(ProductImage, {
 					url,
@@ -2197,7 +2436,7 @@ function ProductDetailsGallery({ className }) {
 function ProductDetailsTitle({ className }) {
 	const { name } = useProductDetailsInternal("ProductDetailsTitle");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-title", className),
 		children: /* @__PURE__ */ jsx("h1", {
 			className: "break-words text-4xl font-semibold leading-tight sm:text-5xl",
 			children: name
@@ -2208,15 +2447,16 @@ function ProductDetailsTitle({ className }) {
 function ProductDetailsPrice({ className }) {
 	const { price, product } = useProductDetailsInternal("ProductDetailsPrice");
 	const { config } = useCommerce();
+	const money$1 = useMoney();
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-price", className),
 		children: /* @__PURE__ */ jsxs("div", {
 			"aria-live": "polite",
 			className: "flex flex-wrap items-baseline gap-x-3 gap-y-1 text-2xl font-medium",
 			"data-testid": "product-price",
-			children: [price?.value?.value != null ? money(price.value.value, price.value.currencyCode ?? config.currencyCode) : product.priceRange?.min != null ? `From ${money(product.priceRange.min, config.currencyCode)}` : "Price unavailable", price?.compareAtValue?.value != null && price.value?.value != null && price.compareAtValue.value > price.value.value && /* @__PURE__ */ jsx("del", {
+			children: [price?.value?.value != null ? money$1(price.value.value, price.value.currencyCode ?? config.currencyCode) : product.priceRange?.min != null ? `From ${money$1(product.priceRange.min)}` : "Price unavailable", price?.compareAtValue?.value != null && price.value?.value != null && price.compareAtValue.value > price.value.value && /* @__PURE__ */ jsx("del", {
 				className: "text-lg font-normal",
-				children: money(price.compareAtValue.value, price.compareAtValue.currencyCode ?? config.currencyCode)
+				children: money$1(price.compareAtValue.value, price.compareAtValue.currencyCode ?? config.currencyCode)
 			})]
 		})
 	});
@@ -2225,7 +2465,7 @@ function ProductDetailsPrice({ className }) {
 function ProductDetailsDescription({ className }) {
 	const { selectedSku, product } = useProductDetailsInternal("ProductDetailsDescription");
 	return /* @__PURE__ */ jsx("div", {
-		className: partClass(className),
+		...partProps("product-details-description", className),
 		children: /* @__PURE__ */ jsx("p", {
 			className: "whitespace-pre-line text-base leading-7",
 			children: selectedSku?.description ?? product.description
@@ -2234,4 +2474,4 @@ function ProductDetailsDescription({ className }) {
 }
 
 //#endregion
-export { AddToCartButton, ApiError, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDrawer, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartRoot, CartSubtotal, CartSummary, CartTitle, Catalog, CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductCardAction, ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, ProductDetailsOptions, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, ProductDetailsTitle, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, useCart, useCartItem, useCommerce, useProductCard, useProductDetails, useProductDetailsOption };
+export { AddToCartButton, ApiError, CartButton, CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDrawer, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName, CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartRoot, CartSubtotal, CartSummary, CartTitle, Catalog, CatalogEmpty, CatalogHeader, CatalogPagination, CatalogProducts, CatalogRoot, CatalogSummary, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductCardAction, ProductCardDescription, ProductCardImage, ProductCardPrice, ProductCardRoot, ProductCardTitle, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, ProductDetailsOptions, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, ProductDetailsTitle, ProductImage, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, useCart, useCartItem, useCommerce, useMoney, useProductCard, useProductDetails, useProductDetailsOption };