@godaddy/gd-commerce-storefront 0.1.2 → 0.2.0

package/README.md

@@ -84,7 +84,7 @@ A connection failure leaves the surrounding application and its state mounted. C
 
 The stylesheet includes all required utilities and scopes them to the package's surfaces. The build removes CSS layer wrappers in their declared order, so the exported CSS can pass through a host Tailwind v3 PostCSS pipeline without `@tailwind` directives. Import it directly; consumers do not need to copy or rewrite the CSS. It does not add a global reset or require dependency scanning by a host Tailwind build. The `theme` prop reaches the drawer even though it is portalled into `document.body`.
 
-By default, `.commerce-storefront` wrappers have transparent backgrounds and inherit the host's text color. Set `--commerce-surface` and `--commerce-text` to explicitly color those wrappers. Controls, muted text, borders, and the drawer retain their neutral palette defaults; set both variables to adapt them to a dark theme. Descendants inherit the surface text and body font instead of global heading styles. Keep text, controls and focus indicators accessible when changing colors. Utility class names and internal markup are not a customization API.
+By default, `.commerce-storefront` wrappers do not paint a background and inherit the host's text color. Set page and section backgrounds on the host application's layout elements. `--commerce-surface` colors controls and the opaque cart drawer, and supplies the base for muted colors; it does not color component wrappers. Set `--commerce-surface` and `--commerce-text` together to adapt controls and the drawer to a dark theme. Avoid setting wrapper backgrounds through CSS or the `theme` prop's `background`, `backgroundColor`, or `backgroundImage` properties, which can still override the transparent default. Descendants inherit the surface text and body font instead of global heading styles. Keep text, controls and focus indicators accessible when changing colors. Utility class names and internal markup are not a customization API.
 
 The first release uses English UI text and `en-US` currency formatting. Catalog title and description are configurable. Full localization and arbitrary component slots are outside this initial API.
 
@@ -144,3 +144,45 @@ Build before testing: artifact tests check the compiled JavaScript and shipped C
 ## License
 
 [MIT](LICENSE.md).
+
+### Before a store is connected
+
+A site can mount the same components before it has a connected store:
+
+```tsx
+<CommerceStorefront theme={theme}>
+  <Header><CartButton /></Header>
+  <Catalog sampleProducts />
+</CommerceStorefront>
+```
+
+`Catalog.sampleProducts` defaults to `false`. It allows six built-in sample products
+(Product 1–6, $10–$60 USD) **only** when `/api/commerce/config` reports `state: 'unbound'`.
+When a store is connected, the server reports a different state and the components show real
+products. You do not need to change props or the component tree. The prop has no effect while
+a store is connected. Real empty catalogs and errors never fall back to samples.
+
+The sample cart supports adding items, changing quantities (1–999), removing items, and an
+example subtotal. It uses the existing drawer and theme, keeps its items during navigation under
+the shared provider, and resets on reload, unmount, or any change away from `unbound`. It uses no
+live cart storage and makes no product, cart, checkout, or upstream Commerce requests.
+Configuration reads continue. Sample entries are not SKUs or draft orders and never move into a
+real cart. Checkout is unavailable, including direct `useCommerce().checkout()` calls.
+
+`useCommerce().connection` now includes `unbound` and `connecting` in addition to `loading`,
+`ready`, and `error`. Only `ready` means a usable store connection. The public `cart` and live
+mutation methods apply only to the connected store; sample cart data is internal. A catalog
+without `sampleProducts`, and direct product-detail visits, show the unconnected state.
+Sample grids and drawers have the attribute `data-commerce-source="sample"`.
+
+The provider reads configuration on mount and focus, and every five seconds while the page is
+visible and the state is `unbound` or `connecting`. The first failed refresh hides samples and
+clears the sample cart; a later `unbound` response starts an empty sample cart. While
+connecting, refresh failures keep the connecting state for up to 60 seconds before showing
+the error. Polling stops
+when the state is `ready`; focus and explicit retry still refresh configuration.
+
+Use a server that reports connection state before you enable `sampleProducts`. Successful
+config responses without `state` still mean ready. A server that does not report `unbound`
+never shows samples. See the [server contract](docs/server-api.md) for the host's
+responsibilities.

package/dist/index.d.ts

@@ -325,12 +325,14 @@ interface CatalogProps {
   title?: string;
   description?: string;
   showHeader?: boolean;
+  /** Permit built-in examples only while the host confirms this site is unbound. */
+  sampleProducts?: boolean;
 }
 declare function Catalog(props: CatalogProps): ReactElement;
 //#endregion
 //#region src/commerce-provider.d.ts
 interface CommerceContextValue {
-  connection: 'loading' | 'ready' | 'error';
+  connection: 'loading' | 'unbound' | 'connecting' | 'ready' | 'error';
   connectionError: string | null;
   retryConnection: () => void;
   theme: StorefrontTheme;

package/dist/index.js

@@ -148,6 +148,82 @@ function getProductAttributes(skuGroup) {
 	}) ?? [];
 }
 
+//#endregion
+//#region src/sample-cart.tsx
+const sampleProducts = Array.from({ length: 6 }, (_, index) => ({
+	key: `sample-${index + 1}`,
+	name: `Product ${index + 1}`,
+	price: (index + 1) * 1e3
+}));
+const SampleCartContext = createContext(null);
+function useSampleCart() {
+	const value = useContext(SampleCartContext);
+	if (!value) throw new Error("Mount CommerceProvider around sample products.");
+	return value;
+}
+function SampleCartProvider({ enabled, onAdd, announce, children }) {
+	const session = useMemo(() => ({ enabled }), [enabled]);
+	const active = useRef(session);
+	active.current = session;
+	const [state, setState] = useState({
+		session,
+		quantities: {}
+	});
+	useEffect(() => {
+		active.current = session;
+		setState({
+			session,
+			quantities: {}
+		});
+		return () => {
+			active.current = null;
+		};
+	}, [session]);
+	const quantities = state.session === session && enabled ? state.quantities : {};
+	function update(key, quantity) {
+		if (!enabled || active.current !== session || !sampleProducts.some((product) => product.key === key)) return false;
+		if (quantity !== void 0 && (!Number.isSafeInteger(quantity) || quantity < 0 || quantity > 999)) return false;
+		setState((previous) => {
+			const current = previous.session === session ? previous.quantities : {};
+			const next = quantity ?? (current[key] ?? 0) + 1;
+			if (next > 999) return previous;
+			return {
+				session,
+				quantities: {
+					...current,
+					[key]: next
+				}
+			};
+		});
+		return true;
+	}
+	return /* @__PURE__ */ jsx(SampleCartContext.Provider, {
+		value: {
+			items: sampleProducts.flatMap((product) => quantities[product.key] ? [{
+				...product,
+				quantity: quantities[product.key]
+			}] : []),
+			add: (key) => {
+				const product = sampleProducts.find((product$1) => product$1.key === key);
+				if (!product || !update(key)) return false;
+				onAdd(product.name);
+				return true;
+			},
+			changeQuantity: async (key, quantity) => {
+				const updated = quantity >= 1 && update(key, quantity);
+				if (updated) announce("Sample cart quantity updated.");
+				return updated;
+			},
+			remove: async (key) => {
+				const updated = update(key, 0);
+				if (updated) announce("Sample item removed from cart.");
+				return updated;
+			}
+		},
+		children
+	});
+}
+
 //#endregion
 //#region src/commerce-provider.tsx
 const CommerceContext = createContext(null);
@@ -156,10 +232,19 @@ function useCommerce() {
 	if (!context) throw new Error("Mount CommerceProvider once around the header and page outlet, inside the router.");
 	return context;
 }
+const CONNECTING_FAILURE_GRACE_MS = 6e4;
 async function loadConfig(signal) {
 	const config = await request("/config", { signal });
-	if (!config || typeof config.cartScope !== "string" || !config.cartScope.trim() || typeof config.currencyCode !== "string" || !/^[A-Z]{3}$/.test(config.currencyCode)) throw new Error("The store returned invalid configuration.");
-	return config;
+	if (config?.state === "unbound" || config?.state === "connecting") {
+		if ("cartScope" in config || "currencyCode" in config) throw new Error("The store returned invalid configuration.");
+		return { state: config.state };
+	}
+	if (!config || config.state !== void 0 && config.state !== "ready" || typeof config.cartScope !== "string" || !config.cartScope.trim() || typeof config.currencyCode !== "string" || !/^[A-Z]{3}$/.test(config.currencyCode)) throw new Error("The store returned invalid configuration.");
+	return {
+		state: "ready",
+		cartScope: config.cartScope,
+		currencyCode: config.currencyCode
+	};
 }
 function CommerceProvider({ children, catalogPath = "/shop", productPath = "/products", checkoutSuccessPath, theme = {} }) {
 	const config = useQuery({
@@ -167,19 +252,25 @@ function CommerceProvider({ children, catalogPath = "/shop", productPath = "/pro
 		queryKey: ["commerce", "configuration"],
 		queryFn: ({ signal }) => loadConfig(signal),
 		staleTime: 3e4,
-		refetchOnWindowFocus: true
+		refetchOnMount: "always",
+		refetchOnWindowFocus: "always",
+		refetchInterval: (query) => query.state.data?.state === "unbound" || query.state.data?.state === "connecting" ? 5e3 : false,
+		refetchIntervalInBackground: false
 	});
+	const holdConnecting = config.isError && config.data?.state === "connecting" && config.errorUpdatedAt - config.dataUpdatedAt < CONNECTING_FAILURE_GRACE_MS;
+	let connection = config.data?.state ?? "loading";
+	if (config.isError) connection = holdConnecting ? "connecting" : "error";
 	return /* @__PURE__ */ jsx(BoundCommerceProvider, {
 		config: {
 			cartScope: "",
 			currencyCode: "USD",
-			...config.data,
+			...config.data?.state === "ready" ? config.data : {},
 			catalogPath,
 			productPath,
 			checkoutSuccessPath
 		},
-		connection: config.isError ? "error" : config.data ? "ready" : "loading",
-		connectionError: config.isError ? message(config.error) : null,
+		connection,
+		connectionError: connection === "error" ? message(config.error) : null,
 		retryConnection: () => {
 			config.refetch();
 		},
@@ -193,8 +284,8 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 	const ready = connection === "ready";
 	const session = useMemo(() => ({
 		cartIdStorage,
-		ready
-	}), [cartIdStorage, ready]);
+		connection
+	}), [cartIdStorage, connection]);
 	const currentSession = useRef(session);
 	currentSession.current = session;
 	const readyRef = useRef(ready);
@@ -299,6 +390,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 		setOpen(false);
 		setError(null);
 		setStorageWarning(null);
+		setAnnouncement("");
 		setPending(false);
 		setHydrating(ready);
 		if (ready) refresh();
@@ -315,7 +407,7 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			window.removeEventListener("storage", onStorage);
 			window.removeEventListener("focus", onFocus);
 		};
-	}, [cartIdStorage, ready]);
+	}, [cartIdStorage, connection]);
 	function addItem(item) {
 		rememberOpener();
 		return run(async () => {
@@ -426,7 +518,16 @@ function BoundCommerceProvider({ config, children, connection, connectionError,
 			refresh,
 			checkout
 		},
-		children: [children, /* @__PURE__ */ jsx("span", {
+		children: [/* @__PURE__ */ jsx(SampleCartProvider, {
+			enabled: connection === "unbound",
+			announce: setAnnouncement,
+			onAdd: (name) => {
+				rememberOpener();
+				setAnnouncement(`${name} added to your sample cart.`);
+				setOpen(true);
+			},
+			children
+		}), /* @__PURE__ */ jsx("span", {
 			className: "commerce-sr-only",
 			role: "status",
 			"aria-live": "polite",
@@ -448,7 +549,10 @@ function StorefrontSurface({ children, className = "" }) {
 function CommerceStatus() {
 	const { connection, connectionError, retryConnection } = useCommerce();
 	if (connection === "ready") return null;
-	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "loading" ? /* @__PURE__ */ jsx("p", {
+	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "unbound" ? /* @__PURE__ */ jsx("p", {
+		role: "status",
+		children: "Connect a store to show products."
+	}) : connection === "loading" || connection === "connecting" ? /* @__PURE__ */ jsx("p", {
 		role: "status",
 		children: "Connecting to the store…"
 	}) : /* @__PURE__ */ jsxs("div", {
@@ -468,13 +572,14 @@ const buttonClass = "inline-flex min-h-11 items-center justify-center gap-2 roun
 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() {
 	const { cart, setOpen, open, connection } = useCommerce();
-	const count = cart?.lineItems?.reduce((total, item) => total + (item.quantity ?? 0), 0) ?? 0;
+	const sample = useSampleCart();
+	const count = connection === "unbound" ? sample.items.reduce((total, item) => total + item.quantity, 0) : cart?.lineItems?.reduce((total, item) => total + (item.quantity ?? 0), 0) ?? 0;
 	return /* @__PURE__ */ jsx(StorefrontSurface, {
 		className: "commerce-inline",
 		children: /* @__PURE__ */ jsxs("button", {
 			type: "button",
 			className: buttonClass,
-			disabled: connection !== "ready",
+			disabled: connection !== "ready" && connection !== "unbound",
 			"aria-haspopup": "dialog",
 			"aria-expanded": open,
 			onClick: () => setOpen(true),
@@ -521,13 +626,34 @@ function AddToCartButton({ sku, name, quantity = 1 }) {
 	});
 }
 function CartDrawer() {
-	const { config, cart, open, setOpen, restoreFocus, pending, hydrating, error, storageWarning, changeQuantity, removeItem, refresh, checkout } = useCommerce();
+	const { config, connection, cart, open, setOpen, restoreFocus, pending, hydrating, error, storageWarning, changeQuantity: changeLiveQuantity, removeItem: removeLiveItem, refresh, checkout } = useCommerce();
+	const sample = useSampleCart();
+	const isSample = connection === "unbound";
+	const changeQuantity = isSample ? sample.changeQuantity : changeLiveQuantity;
+	const removeItem = isSample ? sample.remove : removeLiveItem;
 	const [drawerAction, setDrawerAction] = useState(null);
 	const checkingOut = drawerAction === "checkout";
 	const locked = pending || hydrating || drawerAction !== null;
-	const items = cart?.lineItems ?? [];
+	const items = isSample ? sample.items.map((item) => ({
+		id: item.key,
+		name: item.name,
+		quantity: item.quantity,
+		image: void 0,
+		options: void 0,
+		subtotal: item.price * item.quantity,
+		currency: "USD"
+	})) : (cart?.lineItems ?? []).map((item) => ({
+		id: item.id,
+		name: item.name,
+		quantity: item.quantity,
+		image: item.details?.productAssetUrl,
+		options: item.details?.selectedOptions,
+		subtotal: item.totals?.subTotal?.value,
+		currency: item.totals?.subTotal?.currencyCode
+	}));
 	const summary = getCartSummaryTotals(cart);
-	const currency = cart?.totals?.total?.currencyCode ?? config.currencyCode;
+	const currency = isSample ? "USD" : cart?.totals?.total?.currencyCode ?? config.currencyCode;
+	const subtotal = isSample ? sample.items.reduce((sum, item) => sum + item.price * item.quantity, 0) : summary.subtotal;
 	async function handleAction(action, operation) {
 		if (locked) return;
 		setDrawerAction(action);
@@ -541,6 +667,7 @@ function CartDrawer() {
 		open,
 		onOpenChange: setOpen,
 		children: /* @__PURE__ */ jsx(Dialog.Portal, { children: /* @__PURE__ */ jsxs(StorefrontSurface, { children: [/* @__PURE__ */ jsx(Dialog.Overlay, { className: "fixed inset-0 z-40 bg-neutral-950/40" }), /* @__PURE__ */ jsxs(Dialog.Content, {
+			"data-commerce-source": isSample ? "sample" : void 0,
 			className: "fixed inset-y-0 right-0 z-50 flex w-full max-w-lg flex-col bg-white text-neutral-900 shadow-xl",
 			onCloseAutoFocus: (event) => {
 				event.preventDefault();
@@ -551,10 +678,10 @@ function CartDrawer() {
 					className: "flex items-start justify-between border-b border-neutral-200 p-6",
 					children: [/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx(Dialog.Title, {
 						className: "text-2xl font-semibold",
-						children: "Your cart"
+						children: isSample ? "Sample cart" : "Your cart"
 					}), /* @__PURE__ */ jsx(Dialog.Description, {
 						className: "mt-1 text-sm text-neutral-600",
-						children: "Review your items before checkout."
+						children: isSample ? "Example products and prices in USD. Nothing can be purchased." : "Review your items before checkout."
 					})] }), /* @__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",
@@ -595,7 +722,7 @@ function CartDrawer() {
 								}),
 								/* @__PURE__ */ jsx("p", {
 									className: "mt-2 text-neutral-600",
-									children: "Find something you love in the shop."
+									children: isSample ? "Add a sample product to try the cart." : "Find something you love in the shop."
 								}),
 								/* @__PURE__ */ jsx(Link, {
 									className: `${buttonClass} mt-6`,
@@ -612,8 +739,8 @@ function CartDrawer() {
 								"data-testid": "cart-item",
 								children: [/* @__PURE__ */ jsxs("div", {
 									className: "flex gap-4",
-									children: [item.details?.productAssetUrl && /* @__PURE__ */ jsx("img", {
-										src: item.details.productAssetUrl,
+									children: [item.image && /* @__PURE__ */ jsx("img", {
+										src: item.image,
 										alt: "",
 										className: "h-20 w-20 rounded-lg bg-neutral-100 object-cover"
 									}), /* @__PURE__ */ jsxs("div", {
@@ -623,7 +750,7 @@ function CartDrawer() {
 												className: "font-semibold",
 												children: item.name
 											}),
-											item.details?.selectedOptions?.map((option) => /* @__PURE__ */ jsxs("p", {
+											item.options?.map((option) => /* @__PURE__ */ jsxs("p", {
 												className: "text-sm text-neutral-600",
 												children: [
 													option.attribute,
@@ -633,7 +760,7 @@ function CartDrawer() {
 											}, `${option.attribute}:${option.values?.join(",")}`)),
 											/* @__PURE__ */ jsx("p", {
 												className: "mt-1 text-sm",
-												children: typeof item.totals?.subTotal?.value === "number" ? money(item.totals.subTotal.value, item.totals.subTotal.currencyCode ?? currency) : "Price unavailable"
+												children: typeof item.subtotal === "number" ? money(item.subtotal, item.currency ?? currency) : "Price unavailable"
 											})
 										]
 									})]
@@ -690,16 +817,19 @@ function CartDrawer() {
 					children: [
 						/* @__PURE__ */ jsx("dl", {
 							className: "space-y-2 text-sm",
-							children: typeof cart?.totals?.subTotal?.value === "number" && /* @__PURE__ */ jsxs("div", {
+							children: (isSample || typeof cart?.totals?.subTotal?.value === "number") && /* @__PURE__ */ jsxs("div", {
 								className: "flex justify-between",
-								children: [/* @__PURE__ */ jsx("dt", { children: "Subtotal" }), /* @__PURE__ */ jsx("dd", { children: money(summary.subtotal, cart.totals.subTotal.currencyCode ?? currency) })]
+								children: [/* @__PURE__ */ jsx("dt", { children: isSample ? "Sample subtotal" : "Subtotal" }), /* @__PURE__ */ jsx("dd", { children: money(subtotal, isSample ? "USD" : cart?.totals?.subTotal?.currencyCode ?? currency) })]
 							})
 						}),
-						/* @__PURE__ */ jsx("p", {
+						!isSample && /* @__PURE__ */ jsx("p", {
 							className: "commerce-cart-checkout-adjustments-note mt-3 text-sm text-neutral-600",
 							children: "Shipping, taxes, and discounts are calculated at checkout."
 						}),
-						config.checkoutSuccessPath ? /* @__PURE__ */ jsx("button", {
+						isSample ? /* @__PURE__ */ jsx("p", {
+							className: "text-sm text-neutral-600",
+							children: "Example total in USD. Checkout is not set up yet."
+						}) : config.checkoutSuccessPath ? /* @__PURE__ */ jsx("button", {
 							type: "button",
 							className: `${buttonClass} w-full`,
 							disabled: checkingOut || hydrating || cart?.totals?.total?.value == null,
@@ -800,7 +930,7 @@ function ProductCardContent({ product }) {
 }
 function Catalog(props) {
 	const { connection } = useCommerce();
-	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" ? /* @__PURE__ */ jsx(CatalogContent, { ...props }) : /* @__PURE__ */ jsx(CommerceStatus, {}) });
+	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" ? /* @__PURE__ */ jsx(CatalogContent, { ...props }) : connection === "unbound" && props.sampleProducts ? /* @__PURE__ */ jsx(SampleCatalog, { ...props }) : /* @__PURE__ */ jsx(CommerceStatus, {}) });
 }
 function CatalogContent({ title = "Shop all products", description = "Explore the collection and find your favorites.", showHeader = true }) {
 	const { config } = useCommerce();
@@ -902,6 +1032,61 @@ function CatalogContent({ title = "Shop all products", description = "Explore th
 		})
 	] });
 }
+function SampleCatalog({ title = "Shop all products", description = "Explore the collection and find your favorites.", showHeader = true }) {
+	const { add } = useSampleCart();
+	return /* @__PURE__ */ jsxs("section", {
+		"data-commerce-source": "sample",
+		children: [
+			showHeader && /* @__PURE__ */ jsxs("header", {
+				className: "border-b border-neutral-200 pb-10 pt-4 sm:pb-14 sm:pt-8",
+				children: [/* @__PURE__ */ jsx("h1", {
+					className: "max-w-3xl text-4xl font-semibold leading-tight sm:text-5xl lg:text-6xl",
+					children: title
+				}), /* @__PURE__ */ jsx("p", {
+					className: "mt-5 max-w-xl text-base leading-7 sm:text-lg",
+					children: description
+				})]
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "border-b border-neutral-200 py-6 text-sm",
+				role: "status",
+				children: "Sample products · Example prices in USD"
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "grid grid-cols-1 gap-6 py-8 sm:grid-cols-2 lg:grid-cols-3 lg:gap-8 lg:py-10",
+				children: sampleProducts.map((product) => /* @__PURE__ */ jsxs("article", {
+					className: "flex min-w-0 flex-col overflow-hidden rounded-lg border border-neutral-200",
+					children: [/* @__PURE__ */ jsx("div", {
+						"aria-hidden": "true",
+						className: "flex aspect-square items-center justify-center bg-neutral-100",
+						children: /* @__PURE__ */ jsx("div", { className: "h-20 w-20 rounded-lg border border-neutral-300" })
+					}), /* @__PURE__ */ jsxs("div", {
+						className: "flex flex-1 flex-col p-6",
+						children: [/* @__PURE__ */ jsx("h2", {
+							className: "break-words text-2xl font-semibold leading-tight",
+							children: product.name
+						}), /* @__PURE__ */ jsx("div", {
+							className: "mt-auto pt-6",
+							children: /* @__PURE__ */ jsxs("div", {
+								className: "flex flex-wrap items-end justify-between gap-4 border-t border-neutral-200 pt-5",
+								children: [/* @__PURE__ */ jsx("p", {
+									className: "text-lg font-semibold leading-7",
+									children: money(product.price, "USD")
+								}), /* @__PURE__ */ jsx("button", {
+									type: "button",
+									className: buttonClass,
+									"aria-label": `Add ${product.name} to sample cart`,
+									onClick: () => add(product.key),
+									children: "Add to cart"
+								})]
+							})
+						})]
+					})]
+				}, product.key))
+			})
+		]
+	});
+}
 
 //#endregion
 //#region src/commerce-storefront.tsx

package/dist/styles.css

@@ -65,7 +65,6 @@
   }
 .commerce-storefront {
     color: var(--commerce-text, inherit);
-    background-color: var(--commerce-surface, transparent);
     font-family: inherit;
     line-height: 1.5;
   }
@@ -108,7 +107,6 @@
   }
 .commerce-inline {
     display: inline-block;
-    background-color: transparent;
   }
 .commerce-sr-only {
     position: absolute;

package/docs/server-api.md

@@ -101,3 +101,40 @@ The client refreshes the cart before checkout and sends its ID, an absolute cata
 When using `@godaddy/gd-commerce-server`, configure the router's `checkoutReturnUrls.returnUrls` with the absolute catalog return URL and `checkoutReturnUrls.successUrls` with the absolute success-page URL. The package matches these exact destinations and permits an additional `orderId` parameter on success URLs. Missing policy disables HTTP checkout. Public HTTP requests accept only cart or SKU checkout; non-catalog amounts belong in a trusted server handler.
 
 Do not treat `checkoutSuccessPath`, a client-provided URL, the redirect itself, or a draft-order response as proof that payment succeeded. Verify payment using the checkout/payment service or trusted webhook state. Expire or reject paid/closed drafts on subsequent cart reads so returning customers cannot reuse a completed cart.
+
+## Connection state
+
+A host may return one of these uncached config responses:
+
+```json
+{ "state": "unbound" }
+{ "state": "connecting" }
+{ "state": "ready", "cartScope": "opaque-cart-scope", "currencyCode": "USD" }
+```
+
+Only an explicit `unbound` response allows `Catalog sampleProducts`. `connecting` suspends all
+catalog and cart actions. Loading, malformed state, HTTP errors, and missing routes never allow
+samples. A successful `{ cartScope, currencyCode }` response without `state` still means ready.
+
+`@godaddy/gd-commerce-server` accepts an optional synchronous
+`CommerceConfiguration.readConnectionState(): 'unbound' | 'connecting' | 'ready' | undefined`.
+Return `undefined` to keep the existing config behavior. Return `unbound` only when the host has
+confirmed that no store is connected. Throw when the state is unknown or cannot be read.
+`unbound` and `connecting` responses need no credentials. `ready` still requires `read()` to
+succeed. Data and checkout handlers reject any state other than `ready`, even if credentials
+remain. Do not infer `unbound` from missing credentials or configuration.
+
+The host owns the connection lifecycle. Report `ready` only when the store connection is
+complete, and keep failures in a state other than `unbound`. After a store connects, missing
+configuration must never bring samples back. Report `unbound` again only after the store is
+deliberately disconnected. State changes must be visible to the next request. Pages switch to
+live data only when the deployed server reports a new state. If a host's deployments read
+state from deployment configuration, a deployed site keeps showing samples until that
+configuration is updated, for example by publishing again.
+
+The storefront polls every five seconds while the page is visible and the state is `unbound` or
+`connecting`, and refreshes on mount and focus. A failed refresh immediately hides samples, without
+automatic request retries. While the last response was `connecting`, refresh failures keep the
+connecting state for up to 60 seconds, so a host restart during connection does not flash an
+error. Polling continues, and a longer failure reports the error. Aborted configuration requests cannot overwrite newer responses.
+Release server and client support before using the `sampleProducts` prop. No new endpoint is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godaddy/gd-commerce-storefront",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Opinionated React storefront templates for GoDaddy Commerce",
   "type": "module",
   "license": "MIT",