@godaddy/gd-commerce-storefront 0.2.0 → 0.3.0

package/README.md

@@ -84,9 +84,9 @@ 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 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.
+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. Internal utility class names and markup are not a customization API; use the [product parts](#custom-product-layouts) to change a product page's layout.
 
-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.
+The first release uses English UI text and `en-US` currency formatting. Catalog title and description are configurable. Full localization is outside this initial API.
 
 ## Compatibility
 
@@ -101,6 +101,7 @@ The repository example uses React Router 7. Follow each router version's own Rea
 | `CommerceStorefront` | Recommended integration: provider and one drawer |
 | `Catalog` | Six products per cursor page, with `title`, `description`, and `showHeader` props |
 | `ProductDetails` | Reads `:productId`; validates URL option selections against catalog results |
+| `ProductDetailsRoot` and product parts | Build a [custom product layout](#custom-product-layouts) with the same rules as `ProductDetails` |
 | `ProductCard` | Renders one `SKUGroup` with direct add or a product-details link |
 | `CartButton` | Opens the shared drawer and displays item count |
 | `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity` |
@@ -112,6 +113,71 @@ The package exports TypeScript catalog/cart response types and selection/summary
 
 `Catalog` renders its `title` as an H1 by default. When the host page owns its semantic heading, render that page H1 and pass `showHeader={false}` so the document still has exactly one H1.
 
+## Custom product layouts
+
+`ProductDetails` is the recommended product page. When its layout does not fit, compose the same parts inside `ProductDetailsRoot`. The root loads the route's `:productId` and shows the connection, loading, error and not-found states itself, so parts render only once the product exists. This is the packaged layout, written out:
+
+```tsx
+import {
+  ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsPrice,
+  ProductDetailsPurchase, ProductDetailsRoot, ProductDetailsTitle,
+} from '@godaddy/gd-commerce-storefront';
+
+<ProductDetailsRoot>
+  <ProductDetailsBackLink className='mb-8 sm:mb-10' />
+  <div className='grid items-start gap-8 lg:grid-cols-12 lg:gap-12'>
+    <ProductDetailsGallery className='min-w-0 lg:col-span-7' />
+    <div className='min-w-0 lg:col-span-5 lg:py-4'>
+      <ProductDetailsTitle />
+      <ProductDetailsPrice className='mt-6' />
+      <ProductDetailsDescription className='my-8' />
+      <ProductDetailsPurchase className='border-t border-neutral-200 pt-8' />
+    </div>
+  </div>
+</ProductDetailsRoot>
+```
+
+The grid, spacing and border classes come from your own stylesheet in a custom layout. Without them, the parts stack in one column with no space between them.
+
+Add your own elements between parts, reorder them, or leave out display parts. `ProductDetailsPurchase` renders the purchase parts below in order. Replace it with individual parts to place options apart from the add button:
+
+| Part | Renders |
+| --- | --- |
+| `ProductDetailsOptions` | A select for every attribute, or the SKU list for products without attributes |
+| `ProductDetailsOption` | A select for one attribute, by `attribute` name; nothing when the product lacks it |
+| `ProductDetailsPurchaseStatus` | The one message explaining why the selection is not purchasable yet; nothing when ready |
+| `ProductDetailsAvailability`, `ProductDetailsQuantity` | Stock and quantity for the verified SKU; nothing before verification |
+| `ProductDetailsAddToCart` | Adds the verified SKU and quantity; before a SKU is verified, its accessible description gives the reason |
+
+Every part is named `ProductDetails*` because it works only inside `ProductDetailsRoot`. `AddToCartButton` is the standalone button for a SKU you already have.
+
+Parts read state from the root and take no product, SKU, price or quantity props. Whatever the layout, only a server-verified SKU can be added, and changing a selection resets the quantity and image. Every part throws if it is rendered outside `ProductDetailsRoot`. In development builds, if no control is rendered for an attribute the product requires, a console warning names the missing ones. A control that mounts later, such as one in a closed accordion, can trigger it; the product becomes purchasable once the control renders. Products without attributes but with several SKUs need `ProductDetailsOptions` or `ProductDetailsPurchase`. Parts can be rendered more than once, such as in a sticky mobile purchase bar; each copy gets its own element IDs.
+
+Every part accepts `className`, which is added to the part's outer element, a wrapper the package's CSS reset leaves alone. Host classes there control margin, padding, border, color, width and grid placement, including layered utilities such as Tailwind v4's. The packaged layout sets its spacing and grid placement this way. Elements inside the part, such as the title's `<h1>`, keep the package's own styles: a host font size on `ProductDetailsTitle` does not change the heading's size, but a host color does reach it, because the heading inherits its color.
+
+Two hooks support custom parts inside the root:
+
+- `useProductDetails()` returns read-only `product`, `name`, `selectedSku`, `quantity`, `availableQuantity`, `images` and `status` (`incomplete`, `checking`, `variant-error`, `unavailable`, `not-purchasable` or `ready`). `selectedSku` is set only when `status` is `ready`.
+- `useProductDetailsOption(attribute)` returns `{ name, label, selected, values, select }` for building swatches or buttons, or `null` when the product has no such attribute. `select(value)` accepts only that attribute's value names, or `null` to clear. Other values are ignored. A hook-based control counts toward the layout check.
+
+```tsx
+function ColorSwatches() {
+  const color = useProductDetailsOption('color');
+  if (!color) return null;
+  return (
+    <div role='group' aria-label={color.label}>
+      {color.values.map((value) => (
+        <button key={value.name} type='button' aria-pressed={value.selected} onClick={() => color.select(value.name)}>
+          {value.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+Parts are flat named exports, not properties such as `ProductDetails.Title`, so each one is an ordinary module export.
+
 ## How it works
 
 Products are SKU groups. The package purchases only an unambiguous SKU, verifies all selected attributes through the server, uses SKU prices/images, and distinguishes untracked inventory from sold-out inventory. Server-side inventory and pricing checks remain mandatory.

package/dist/index.d.ts

@@ -387,10 +387,115 @@ declare function CommerceStorefront({
   ...props
 }: CommerceProviderProps): react_jsx_runtime0.JSX.Element;
 //#endregion
+//#region src/product-details-context.d.ts
+/** Where the shopper is in choosing a purchasable SKU. Only `ready` has a verified `selectedSku`. */
+type ProductDetailsStatus = 'incomplete' | 'checking' | 'variant-error' | 'unavailable' | 'not-purchasable' | 'ready';
+/** Read-only product state for custom parts rendered inside `ProductDetailsRoot`. */
+interface ProductDetailsState {
+  readonly product: SKUGroup;
+  readonly name: string;
+  /** Set only after the server verifies the full selection. */
+  readonly selectedSku: SKU | null;
+  readonly quantity: number;
+  /** `null` means inventory is not tracked; `0` means sold out. */
+  readonly availableQuantity: number | null;
+  readonly status: ProductDetailsStatus;
+  readonly images: readonly string[];
+}
+/** Props shared by every product part. `className` is added to the part's outer element. */
+interface ProductDetailsPartProps {
+  className?: string;
+}
+/** Read the current product, verified SKU, and purchase status from inside `ProductDetailsRoot`. */
+declare function useProductDetails(): ProductDetailsState;
+interface ProductDetailsOptionValueState {
+  readonly name: string;
+  readonly label: string;
+  readonly selected: boolean;
+}
+interface ProductDetailsOptionState {
+  readonly name: string;
+  readonly label: string;
+  readonly selected: string | null;
+  readonly values: readonly ProductDetailsOptionValueState[];
+  /** Accepts only this attribute's own value names, or `null` to clear. Other values are ignored. */
+  readonly select: (value: string | null) => void;
+}
+/**
+ * Build a custom control for one product attribute. Returns `null` when the product has no such attribute.
+ * A selection is never purchasable until the server verifies it.
+ */
+declare function useProductDetailsOption(attribute: string): ProductDetailsOptionState | null;
+interface ProductDetailsRootProps {
+  children: ReactNode;
+  /** Added to the root `<article>`. */
+  className?: string;
+}
+/** Loads the product for the route's `:productId` and provides state to product parts. */
+declare function ProductDetailsRoot({
+  children,
+  className
+}: ProductDetailsRootProps): ReactElement;
+//#endregion
 //#region src/product-details.d.ts
+/** The packaged product page for `${productPath}/:productId`. Compose the parts for a custom layout. */
 declare function ProductDetails(): ReactElement;
+declare function ProductDetailsBackLink({
+  className
+}: ProductDetailsPartProps): ReactElement;
+/** Main image with thumbnails; the selected SKU's images replace the product's when present. */
+declare function ProductDetailsGallery({
+  className
+}: ProductDetailsPartProps): ReactElement;
+/** The product name as the page's H1. */
+declare function ProductDetailsTitle({
+  className
+}: ProductDetailsPartProps): ReactElement;
+/** The verified SKU's price and compare-at price, or the product's starting price. */
+declare function ProductDetailsPrice({
+  className
+}: ProductDetailsPartProps): ReactElement;
+/** The verified SKU's description, or the product's. */
+declare function ProductDetailsDescription({
+  className
+}: ProductDetailsPartProps): ReactElement;
+//#endregion
+//#region src/product-purchase.d.ts
+/** The packaged purchase area: options, status, availability, quantity, and add to cart. */
+declare function ProductDetailsPurchase({
+  className
+}: ProductDetailsPartProps): ReactElement;
+/** A select for every product attribute, or the SKU list for products without attributes. */
+declare function ProductDetailsOptions({
+  className
+}: ProductDetailsPartProps): ReactElement | null;
+interface ProductDetailsOptionProps extends ProductDetailsPartProps {
+  /** The attribute `name`, such as `color`. Renders nothing when the product has no such attribute. */
+  attribute: string;
+}
+/** A select for one product attribute. Use `useProductDetailsOption` for swatches or other custom controls. */
+declare function ProductDetailsOption({
+  attribute,
+  className
+}: ProductDetailsOptionProps): ReactElement | null;
+/** The single message explaining why the selection is not yet purchasable. Renders nothing when ready. */
+declare function ProductDetailsPurchaseStatus({
+  className
+}: ProductDetailsPartProps): ReactElement | null;
+/** Stock for the verified SKU. Renders nothing until a SKU is verified. */
+declare function ProductDetailsAvailability({
+  className
+}: ProductDetailsPartProps): ReactElement | null;
+/** Quantity for the verified SKU. Renders nothing until a SKU is verified. */
+declare function ProductDetailsQuantity({
+  className
+}: ProductDetailsPartProps): ReactElement | null;
+/** Adds the verified SKU and quantity. While disabled, its accessible description says why. */
+declare function ProductDetailsAddToCart({
+  className
+}: ProductDetailsPartProps): ReactElement;
 //#endregion
 //#region src/storefront-surface.d.ts
 declare function CommerceStatus(): ReactElement | null;
 //#endregion
-export { AddToCartButton, AddToCartItemInput, ApiError, CartAddress, CartButton, CartDiscount, CartDrawer, CartLineItem, CartLineItemDetails, CartNote, CartOrder, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, CartSummaryTotals, CartTax, Catalog, type CatalogProps, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductDetails, ProductDetailsVariablesInput, ProductGridVariablesInput, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, getSingleMatchedSkuId, money, useCommerce };
+export { AddToCartButton, AddToCartItemInput, ApiError, CartAddress, CartButton, CartDiscount, CartDrawer, CartLineItem, CartLineItemDetails, CartNote, CartOrder, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, CartSummaryTotals, CartTax, Catalog, type CatalogProps, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, type ProductDetailsOptionProps, type ProductDetailsOptionState, type ProductDetailsOptionValueState, ProductDetailsOptions, type ProductDetailsPartProps, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, type ProductDetailsRootProps, type ProductDetailsState, type ProductDetailsStatus, ProductDetailsTitle, ProductDetailsVariablesInput, ProductGridVariablesInput, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, getSingleMatchedSkuId, money, useCommerce, useProductDetails, useProductDetailsOption };

package/dist/index.js

@@ -1,5 +1,5 @@
 import * as Dialog from "@radix-ui/react-dialog";
-import { createContext, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useId, useMemo, useRef, useState } from "react";
 import { Link, useParams, useSearchParams } from "react-router";
 import { useQuery } from "@tanstack/react-query";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -122,8 +122,9 @@ function getAvailableInventoryQuantity(item) {
 	if (!edges || edges.length === 0) return null;
 	return edges.find((edge) => edge?.node?.type === "AVAILABLE")?.node?.quantity ?? 0;
 }
+const imageMediaTypes = new Set(["IMAGE", "PHOTO"]);
 function getImageUrls(item) {
-	return item?.mediaObjects?.edges?.filter((edge) => edge?.node?.type === "IMAGE" && edge.node.url).map((edge) => edge?.node?.url).filter((url) => Boolean(url)) ?? [];
+	return item?.mediaObjects?.edges?.filter((edge) => imageMediaTypes.has(edge?.node?.type ?? "") && edge?.node?.url).map((edge) => edge?.node?.url).filter((url) => Boolean(url)) ?? [];
 }
 function getPrimaryImageUrl(item) {
 	return getImageUrls(item)[0] ?? null;
@@ -1099,15 +1100,72 @@ function CommerceStorefront({ children,...props }) {
 }
 
 //#endregion
-//#region src/product-details.tsx
-function ProductDetails() {
+//#region src/product-details-context.tsx
+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);
+const ProductDetailsContext = createContext(null);
+function useProductDetailsInternal(part) {
+	const context = useContext(ProductDetailsContext);
+	if (!context) throw new Error(`${part} must be rendered inside <ProductDetailsRoot>.`);
+	return context;
+}
+/** Read the current product, verified SKU, and purchase status from inside `ProductDetailsRoot`. */
+function useProductDetails() {
+	const { product, name, selectedSku, quantity, availableQuantity, status, images } = useProductDetailsInternal("useProductDetails");
+	return {
+		product,
+		name,
+		selectedSku,
+		quantity,
+		availableQuantity,
+		status,
+		images
+	};
+}
+/**
+* Build a custom control for one product attribute. Returns `null` when the product has no such attribute.
+* A selection is never purchasable until the server verifies it.
+*/
+function useProductDetailsOption(attribute) {
+	const { attributes, selections, selectOption, register } = useProductDetailsInternal("useProductDetailsOption");
+	useEffect(() => register(`attribute:${attribute}`), [attribute, register]);
+	const index = attributes.findIndex((candidate) => candidate.name === attribute);
+	const match = attributes[index];
+	if (!match) return null;
+	const selected = selections[index] || null;
+	return {
+		name: match.name,
+		label: match.label,
+		selected,
+		values: match.values.map((value) => ({
+			name: value.name,
+			label: value.label,
+			selected: value.name === selected
+		})),
+		select: (value) => {
+			if (value === null) selectOption(attribute, "");
+			else if (match.values.some((candidate) => candidate.name === value)) selectOption(attribute, value);
+		}
+	};
+}
+/** Register the explicit SKU control so the layout check knows SKU-list products can be completed. */
+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();
 	const { connection } = useCommerce();
-	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" ? /* @__PURE__ */ jsx(ProductDetailsContent, { productId }, productId) : /* @__PURE__ */ jsx(CommerceStatus, {}) });
+	return /* @__PURE__ */ jsx(StorefrontSurface, { children: connection === "ready" ? /* @__PURE__ */ jsx(ProductDetailsLoader, {
+		productId,
+		className,
+		children
+	}, productId) : /* @__PURE__ */ jsx(CommerceStatus, {}) });
 }
-function ProductDetailsContent({ productId }) {
+function ProductDetailsLoader({ productId, className, children }) {
 	const { config } = useCommerce();
-	const fieldId = useId();
 	const [params, setParams] = useSearchParams();
 	const [quantity, setQuantity] = useState(1);
 	const [imageIndex, setImageIndex] = useState(0);
@@ -1130,10 +1188,10 @@ function ProductDetailsContent({ productId }) {
 	const skuOptions = getLabeledSkuOptions(group);
 	const explicitSku = skuOptions.find((sku) => sku.id === params.get("sku"));
 	const selections = attributes.map((attribute) => params.get(`option.${attribute.name}`) ?? "");
-	const complete = skuOptions.length > 0 ? !!explicitSku : attributes.every((attribute, index) => attribute.values.some((value) => value.name === selections[index]));
+	const complete = skuOptions.length > 0 ? !!explicitSku : attributes.every((attribute, index) => attribute.values.some((value$1) => value$1.name === selections[index]));
 	const selectionParams = new URLSearchParams();
-	selections.filter(Boolean).forEach((value) => {
-		selectionParams.append("attributeValues", value);
+	selections.filter(Boolean).forEach((value$1) => {
+		selectionParams.append("attributeValues", value$1);
 	});
 	const matched = useQuery({
 		retry: false,
@@ -1152,20 +1210,34 @@ function ProductDetailsContent({ productId }) {
 	});
 	const selectionVerified = complete && product.isSuccess && !product.isFetching && (attributes.length === 0 || matched.isSuccess && !matched.isFetching);
 	const selectedSku = selectionVerified ? explicitSku ?? getSingleMatchedSku(attributes.length ? matched.data?.skuGroup : group) : null;
-	const skuId = selectedSku?.id ?? null;
-	const skuPrice = selectedSku?.prices?.edges?.find((edge) => edge?.node?.value)?.node;
+	const status = !complete ? "incomplete" : matched.isError && !matched.isFetching ? "variant-error" : !selectionVerified ? "checking" : selectedSku ? "ready" : attributes.length ? "unavailable" : "not-purchasable";
 	const selectedImages = getImageUrls(selectedSku);
 	const images = [...new Set(selectedImages.length ? selectedImages : getImageUrls(group))];
-	const available = getAvailableInventoryQuantity(selectedSku);
-	const name = group?.label ?? group?.name ?? "Product";
-	const selectOption = (attribute, value) => {
+	const changeSelection = (key, value$1) => {
 		const next = new URLSearchParams(params);
-		if (value) next.set(`option.${attribute}`, value);
-		else next.delete(`option.${attribute}`);
+		if (value$1) next.set(key, value$1);
+		else next.delete(key);
 		setParams(next);
 		setQuantity(1);
 		setImageIndex(0);
 	};
+	const registered = useRef(/* @__PURE__ */ new Map());
+	const register = useCallback((control) => {
+		const counts = registered.current;
+		counts.set(control, (counts.get(control) ?? 0) + 1);
+		return () => {
+			const count = (counts.get(control) ?? 1) - 1;
+			if (count > 0) counts.set(control, count);
+			else counts.delete(control);
+		};
+	}, []);
+	const requiredControls = [...attributes.map((attribute) => `attribute:${attribute.name}`), ...skuOptions.length ? ["sku"] : []].join("\n");
+	useEffect(() => {
+		if (process.env.NODE_ENV === "production") return;
+		const missing = requiredControls.split("\n").filter((control) => control && !registered.current.has(control));
+		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]);
 	if (product.isPending) return /* @__PURE__ */ jsx("p", {
 		role: "status",
 		children: "Loading product…"
@@ -1197,167 +1269,321 @@ function ProductDetailsContent({ productId }) {
 		to: config.catalogPath,
 		children: "Back to shop"
 	})] });
-	return /* @__PURE__ */ jsxs("article", { children: [/* @__PURE__ */ jsx(Link, {
-		className: "mb-8 inline-flex min-h-11 items-center text-sm text-inherit underline underline-offset-4 focus-visible:outline focus-visible:outline-2 sm:mb-10",
-		to: config.catalogPath,
-		children: "← Back to shop"
-	}), /* @__PURE__ */ jsxs("div", {
-		className: "grid items-start gap-8 lg:grid-cols-12 lg:gap-12",
-		children: [/* @__PURE__ */ jsxs("div", {
-			className: "min-w-0 lg:col-span-7",
-			children: [/* @__PURE__ */ jsx("div", {
-				className: "aspect-square overflow-hidden rounded-lg",
-				children: /* @__PURE__ */ jsx(ProductImage, {
-					url: images[imageIndex] ?? images[0],
-					name
-				}, images[imageIndex] ?? images[0])
-			}), images.length > 1 && /* @__PURE__ */ jsx("div", {
-				className: "mt-4 flex gap-3 overflow-x-auto",
-				children: images.map((url, index) => /* @__PURE__ */ jsx("button", {
-					type: "button",
-					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,
-					onClick: () => setImageIndex(index),
-					children: /* @__PURE__ */ jsx(ProductImage, {
-						url,
-						name: ""
-					})
-				}, url))
+	const value = {
+		product: group,
+		name: group.label ?? group.name ?? "Product",
+		selectedSku,
+		quantity,
+		availableQuantity: getAvailableInventoryQuantity(selectedSku),
+		status,
+		images,
+		attributes,
+		selections,
+		skuOptions,
+		explicitSkuId: explicitSku?.id ?? "",
+		price: selectedSku?.prices?.edges?.find((edge) => edge?.node?.value)?.node,
+		imageIndex: Math.min(imageIndex, Math.max(images.length - 1, 0)),
+		variantError: matched.error,
+		setImageIndex: (index) => {
+			if (Number.isInteger(index) && index >= 0 && index < images.length) setImageIndex(index);
+		},
+		setQuantity,
+		selectOption: (attribute, next) => changeSelection(`option.${attribute}`, next),
+		selectSku: (skuId) => changeSelection("sku", skuOptions.some((sku) => sku.id === skuId) ? skuId : ""),
+		retryVariant: () => {
+			if (matched.isError) matched.refetch();
+		},
+		register
+	};
+	return /* @__PURE__ */ jsx(ProductDetailsContext.Provider, {
+		value,
+		children: /* @__PURE__ */ jsx("article", {
+			className: partClass(className),
+			children
+		})
+	});
+}
+
+//#endregion
+//#region src/product-purchase.tsx
+const disabledReasons = {
+	incomplete: "Select all options to add this item to your cart.",
+	checking: "Checking this variant…",
+	"variant-error": "Availability for this selection could not be checked.",
+	unavailable: "This combination is unavailable. Choose different options.",
+	"not-purchasable": "This product is not currently available to purchase."
+};
+const flush = "mb-0";
+/** The packaged purchase area: options, status, availability, quantity, and add to cart. */
+function ProductDetailsPurchase({ className }) {
+	useProductDetailsInternal("ProductDetailsPurchase");
+	return /* @__PURE__ */ jsxs("div", {
+		className: partClass("space-y-6", className),
+		children: [
+			/* @__PURE__ */ jsx(OptionControls, {}),
+			/* @__PURE__ */ jsx(PurchaseStatusMessage, { textClassName: flush }),
+			/* @__PURE__ */ jsx(ProductDetailsAvailability, { className: flush }),
+			/* @__PURE__ */ jsx(ProductDetailsQuantity, {}),
+			/* @__PURE__ */ jsx(ProductDetailsAddToCart, {})
+		]
+	});
+}
+/** A select for every product attribute, or the SKU list for products without attributes. */
+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),
+		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,
+		className: flush
+	}, attribute.id || attribute.name)), skuOptions.length > 0 && /* @__PURE__ */ jsx(SkuOption, {})] });
+}
+function SkuOption() {
+	const { skuOptions, explicitSkuId, selectSku } = useProductDetailsInternal("ProductDetailsOptions");
+	const id = useId();
+	useSkuOptionRegistration();
+	return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("label", {
+		htmlFor: id,
+		className: "mb-2 block font-medium",
+		children: "Option"
+	}), /* @__PURE__ */ jsxs("select", {
+		id,
+		className: `${inputClass} w-full`,
+		value: explicitSkuId,
+		onChange: (event) => selectSku(event.target.value),
+		children: [/* @__PURE__ */ jsx("option", {
+			value: "",
+			children: "Select an option"
+		}), skuOptions.map((sku) => /* @__PURE__ */ jsx("option", {
+			value: sku.id ?? "",
+			children: sku.label?.trim() || sku.name?.trim()
+		}, sku.id))]
+	})] });
+}
+/** A select for one product attribute. Use `useProductDetailsOption` for swatches or other custom controls. */
+function ProductDetailsOption({ attribute, className }) {
+	const option = useProductDetailsOption(attribute);
+	if (!option) return null;
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(className),
+		children: /* @__PURE__ */ jsxs("fieldset", { children: [/* @__PURE__ */ jsx("legend", {
+			className: "mb-2 font-medium",
+			children: option.label
+		}), /* @__PURE__ */ jsxs("select", {
+			className: `${inputClass} w-full`,
+			"aria-label": option.label,
+			value: option.selected ?? "",
+			onChange: (event) => option.select(event.target.value || null),
+			children: [/* @__PURE__ */ jsxs("option", {
+				value: "",
+				children: ["Select ", option.label.toLowerCase()]
+			}), option.values.map((value) => /* @__PURE__ */ jsx("option", {
+				value: value.name,
+				children: value.label
+			}, value.name))]
+		})] })
+	});
+}
+/** The single message explaining why the selection is not yet purchasable. Renders nothing when ready. */
+function ProductDetailsPurchaseStatus({ className }) {
+	return /* @__PURE__ */ jsx(PurchaseStatusMessage, { className });
+}
+function PurchaseStatusMessage({ className, textClassName }) {
+	const { status, variantError, retryVariant } = useProductDetailsInternal("ProductDetailsPurchaseStatus");
+	const part = (children, partClassName) => /* @__PURE__ */ jsx("div", {
+		className: partClass(partClassName, className),
+		children
+	});
+	switch (status) {
+		case "ready": return null;
+		case "variant-error": return part(/* @__PURE__ */ jsxs("div", {
+			role: "alert",
+			className: "text-red-700",
+			children: [/* @__PURE__ */ jsx("p", { children: message(variantError) }), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "min-h-11 bg-white text-red-700 underline",
+				onClick: retryVariant,
+				children: "Retry availability"
 			})]
-		}), /* @__PURE__ */ jsxs("div", {
+		}));
+		case "unavailable": return part(/* @__PURE__ */ jsx("p", {
+			role: "status",
+			className: "text-sm text-red-700",
+			children: disabledReasons[status]
+		}), textClassName);
+		case "not-purchasable": return part(/* @__PURE__ */ jsx("p", {
+			className: "text-sm",
+			children: disabledReasons[status]
+		}), textClassName);
+		case "checking": return part(/* @__PURE__ */ jsx("p", {
+			role: "status",
+			children: disabledReasons[status]
+		}), textClassName);
+		case "incomplete": return part(/* @__PURE__ */ jsx("p", {
+			role: "status",
+			className: "text-sm",
+			children: disabledReasons[status]
+		}), textClassName);
+	}
+}
+/** Stock for the verified SKU. Renders nothing until a SKU is verified. */
+function ProductDetailsAvailability({ className }) {
+	const { selectedSku, availableQuantity } = useProductDetailsInternal("ProductDetailsAvailability");
+	if (!selectedSku) return null;
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(className),
+		children: /* @__PURE__ */ jsx("p", {
+			className: "text-sm",
+			"aria-live": "polite",
+			children: availableQuantity === null ? "Available to order" : availableQuantity === 0 ? "This variant is out of stock" : `${availableQuantity} available`
+		})
+	});
+}
+/** Quantity for the verified SKU. Renders nothing until a SKU is verified. */
+function ProductDetailsQuantity({ className }) {
+	const { selectedSku, availableQuantity, quantity, setQuantity } = useProductDetailsInternal("ProductDetailsQuantity");
+	const id = useId();
+	if (!selectedSku) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		className: partClass(className),
+		children: [/* @__PURE__ */ jsx("label", {
+			htmlFor: id,
+			className: "mb-2 block font-medium",
+			children: "Quantity"
+		}), /* @__PURE__ */ jsx("input", {
+			id,
+			type: "number",
+			min: 1,
+			max: availableQuantity ?? void 0,
+			step: 1,
+			className: `${inputClass} w-28`,
+			value: Number.isNaN(quantity) ? "" : quantity,
+			onChange: (event) => setQuantity(event.target.valueAsNumber)
+		})]
+	});
+}
+/** Adds the verified SKU and quantity. While disabled, its accessible description says why. */
+function ProductDetailsAddToCart({ className }) {
+	const { selectedSku, name, quantity, status } = useProductDetailsInternal("ProductDetailsAddToCart");
+	const reasonId = useId();
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(className),
+		children: selectedSku ? /* @__PURE__ */ jsx(AddToCartButton, {
+			sku: selectedSku,
+			name,
+			quantity
+		}) : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			className: `${buttonClass} w-full`,
+			disabled: true,
+			"aria-describedby": reasonId,
+			children: "Add to cart"
+		}), /* @__PURE__ */ jsx("span", {
+			id: reasonId,
+			hidden: true,
+			children: status === "ready" ? "" : disabledReasons[status]
+		})] })
+	});
+}
+
+//#endregion
+//#region src/product-details.tsx
+/** The packaged product page for `${productPath}/:productId`. Compose the parts for a custom layout. */
+function ProductDetails() {
+	return /* @__PURE__ */ jsxs(ProductDetailsRoot, { children: [/* @__PURE__ */ jsx(ProductDetailsBackLink, { className: "mb-8 sm:mb-10" }), /* @__PURE__ */ jsxs("div", {
+		className: "grid items-start gap-8 lg:grid-cols-12 lg:gap-12",
+		children: [/* @__PURE__ */ jsx(ProductDetailsGallery, { className: "min-w-0 lg:col-span-7" }), /* @__PURE__ */ jsxs("div", {
 			className: "min-w-0 lg:col-span-5 lg:py-4",
 			children: [
-				/* @__PURE__ */ jsx("h1", {
-					className: "break-words text-4xl font-semibold leading-tight sm:text-5xl",
-					children: name
-				}),
-				/* @__PURE__ */ jsxs("div", {
-					"aria-live": "polite",
-					className: "mt-6 flex flex-wrap items-baseline gap-x-3 gap-y-1 text-2xl font-medium",
-					"data-testid": "product-price",
-					children: [skuPrice?.value?.value != null ? money(skuPrice.value.value, skuPrice.value.currencyCode ?? config.currencyCode) : group.priceRange?.min != null ? `From ${money(group.priceRange.min, config.currencyCode)}` : "Price unavailable", skuPrice?.compareAtValue?.value != null && skuPrice.value?.value != null && skuPrice.compareAtValue.value > skuPrice.value.value && /* @__PURE__ */ jsx("del", {
-						className: "text-lg font-normal",
-						children: money(skuPrice.compareAtValue.value, skuPrice.compareAtValue.currencyCode ?? config.currencyCode)
-					})]
-				}),
-				/* @__PURE__ */ jsx("p", {
-					className: "my-8 whitespace-pre-line text-base leading-7",
-					children: selectedSku?.description ?? group.description
-				}),
-				/* @__PURE__ */ jsxs("div", {
-					className: "space-y-6 border-t border-neutral-200 pt-8",
-					children: [
-						attributes.map((attribute, index) => /* @__PURE__ */ jsxs("fieldset", { children: [/* @__PURE__ */ jsx("legend", {
-							className: "mb-2 font-medium",
-							children: attribute.label
-						}), /* @__PURE__ */ jsxs("select", {
-							className: `${inputClass} w-full`,
-							"aria-label": attribute.label,
-							value: selections[index],
-							onChange: (event) => selectOption(attribute.name, event.target.value),
-							children: [/* @__PURE__ */ jsxs("option", {
-								value: "",
-								children: ["Select ", attribute.label.toLowerCase()]
-							}), attribute.values.map((value) => /* @__PURE__ */ jsx("option", {
-								value: value.name,
-								children: value.label
-							}, value.id || value.name))]
-						})] }, attribute.id || attribute.name)),
-						skuOptions.length > 0 && /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("label", {
-							htmlFor: `${fieldId}-sku-option`,
-							className: "mb-2 block font-medium",
-							children: "Option"
-						}), /* @__PURE__ */ jsxs("select", {
-							id: `${fieldId}-sku-option`,
-							className: `${inputClass} w-full`,
-							value: explicitSku?.id ?? "",
-							onChange: (event) => {
-								const next = new URLSearchParams(params);
-								if (event.target.value) next.set("sku", event.target.value);
-								else next.delete("sku");
-								setParams(next);
-								setQuantity(1);
-								setImageIndex(0);
-							},
-							children: [/* @__PURE__ */ jsx("option", {
-								value: "",
-								children: "Select an option"
-							}), skuOptions.map((sku) => /* @__PURE__ */ jsx("option", {
-								value: sku.id ?? "",
-								children: sku.label?.trim() || sku.name?.trim()
-							}, sku.id))]
-						})] }),
-						matched.isError ? /* @__PURE__ */ jsxs("div", {
-							role: "alert",
-							className: "text-red-700",
-							children: [/* @__PURE__ */ jsx("p", { children: message(matched.error) }), /* @__PURE__ */ jsx("button", {
-								type: "button",
-								className: "min-h-11 bg-white text-red-700 underline",
-								onClick: () => {
-									if (matched.isError) matched.refetch();
-								},
-								children: "Retry availability"
-							})]
-						}) : null,
-						!complete && /* @__PURE__ */ jsx("p", {
-							id: `${fieldId}-variant-guidance`,
-							role: "status",
-							className: "text-sm",
-							children: "Select all options to add this item to your cart."
-						}),
-						selectionVerified && attributes.length > 0 && !skuId && /* @__PURE__ */ jsx("p", {
-							role: "status",
-							className: "text-sm text-red-700",
-							children: "This combination is unavailable. Choose different options."
-						}),
-						selectionVerified && attributes.length === 0 && !skuId && /* @__PURE__ */ jsx("p", {
-							className: "text-sm",
-							children: "This product is not currently available to purchase."
-						}),
-						complete && (product.isFetching || matched.isFetching) && /* @__PURE__ */ jsx("p", {
-							role: "status",
-							children: "Checking this variant…"
-						}),
-						selectedSku && /* @__PURE__ */ jsxs(Fragment, { children: [
-							/* @__PURE__ */ jsx("p", {
-								className: "text-sm",
-								"aria-live": "polite",
-								children: available === null ? "Available to order" : available === 0 ? "This variant is out of stock" : `${available} available`
-							}),
-							/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("label", {
-								htmlFor: `${fieldId}-quantity`,
-								className: "mb-2 block font-medium",
-								children: "Quantity"
-							}), /* @__PURE__ */ jsx("input", {
-								id: `${fieldId}-quantity`,
-								type: "number",
-								min: 1,
-								max: available ?? void 0,
-								step: 1,
-								className: `${inputClass} w-28`,
-								value: Number.isNaN(quantity) ? "" : quantity,
-								onChange: (event) => setQuantity(event.target.valueAsNumber)
-							})] }),
-							/* @__PURE__ */ jsx(AddToCartButton, {
-								sku: selectedSku,
-								name,
-								quantity
-							})
-						] }),
-						!selectedSku && /* @__PURE__ */ jsx("button", {
-							type: "button",
-							className: `${buttonClass} w-full`,
-							disabled: true,
-							"aria-describedby": !complete ? `${fieldId}-variant-guidance` : void 0,
-							children: "Add to cart"
-						})
-					]
-				})
+				/* @__PURE__ */ jsx(ProductDetailsTitle, {}),
+				/* @__PURE__ */ jsx(ProductDetailsPrice, { className: "mt-6" }),
+				/* @__PURE__ */ jsx(ProductDetailsDescription, { className: "my-8" }),
+				/* @__PURE__ */ jsx(ProductDetailsPurchase, { className: "border-t border-neutral-200 pt-8" })
 			]
 		})]
 	})] });
 }
+function ProductDetailsBackLink({ className }) {
+	useProductDetailsInternal("ProductDetailsBackLink");
+	const { config } = useCommerce();
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(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"
+		})
+	});
+}
+/** Main image with thumbnails; the selected SKU's images replace the product's when present. */
+function ProductDetailsGallery({ className }) {
+	const { images, imageIndex, setImageIndex, name } = useProductDetailsInternal("ProductDetailsGallery");
+	return /* @__PURE__ */ jsxs("div", {
+		className: partClass(className),
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "aspect-square overflow-hidden rounded-lg",
+			children: /* @__PURE__ */ jsx(ProductImage, {
+				url: images[imageIndex],
+				name
+			}, images[imageIndex])
+		}), images.length > 1 && /* @__PURE__ */ jsx("div", {
+			className: "mt-4 flex gap-3 overflow-x-auto",
+			children: images.map((url, index) => /* @__PURE__ */ jsx("button", {
+				type: "button",
+				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,
+				onClick: () => setImageIndex(index),
+				children: /* @__PURE__ */ jsx(ProductImage, {
+					url,
+					name: ""
+				})
+			}, url))
+		})]
+	});
+}
+/** The product name as the page's H1. */
+function ProductDetailsTitle({ className }) {
+	const { name } = useProductDetailsInternal("ProductDetailsTitle");
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(className),
+		children: /* @__PURE__ */ jsx("h1", {
+			className: "break-words text-4xl font-semibold leading-tight sm:text-5xl",
+			children: name
+		})
+	});
+}
+/** The verified SKU's price and compare-at price, or the product's starting price. */
+function ProductDetailsPrice({ className }) {
+	const { price, product } = useProductDetailsInternal("ProductDetailsPrice");
+	const { config } = useCommerce();
+	return /* @__PURE__ */ jsxs("div", {
+		"aria-live": "polite",
+		className: partClass("flex flex-wrap items-baseline gap-x-3 gap-y-1 text-2xl font-medium", className),
+		"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", {
+			className: "text-lg font-normal",
+			children: money(price.compareAtValue.value, price.compareAtValue.currencyCode ?? config.currencyCode)
+		})]
+	});
+}
+/** The verified SKU's description, or the product's. */
+function ProductDetailsDescription({ className }) {
+	const { selectedSku, product } = useProductDetailsInternal("ProductDetailsDescription");
+	return /* @__PURE__ */ jsx("div", {
+		className: partClass(className),
+		children: /* @__PURE__ */ jsx("p", {
+			className: "whitespace-pre-line text-base leading-7",
+			children: selectedSku?.description ?? product.description
+		})
+	});
+}
 
 //#endregion
-export { AddToCartButton, ApiError, CartButton, CartDrawer, Catalog, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductDetails, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, useCommerce };
+export { AddToCartButton, ApiError, CartButton, CartDrawer, Catalog, CommerceProvider, CommerceStatus, CommerceStorefront, ProductCard, ProductDetails, ProductDetailsAddToCart, ProductDetailsAvailability, ProductDetailsBackLink, ProductDetailsDescription, ProductDetailsGallery, ProductDetailsOption, ProductDetailsOptions, ProductDetailsPrice, ProductDetailsPurchase, ProductDetailsPurchaseStatus, ProductDetailsQuantity, ProductDetailsRoot, ProductDetailsTitle, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, money, useCommerce, useProductDetails, useProductDetailsOption };

package/dist/styles.css

@@ -68,12 +68,14 @@
     font-family: inherit;
     line-height: 1.5;
   }
-.commerce-storefront :where(*) {
+.commerce-storefront :where(*:not(.commerce-part)) {
     color: inherit;
     font-family: inherit;
   }
 .commerce-storefront *, .commerce-storefront *::before, .commerce-storefront *::after {
     box-sizing: border-box;
+  }
+.commerce-storefront :where(*:not(.commerce-part)), .commerce-storefront *::before, .commerce-storefront *::after {
     border-width: 0;
     border-style: solid;
   }
@@ -133,6 +135,9 @@
 .commerce-storefront .fixed {
     position: fixed;
   }
+.commerce-storefront .sticky {
+    position: sticky;
+  }
 .commerce-storefront .inset-0 {
     inset: calc(var(--spacing) * 0);
   }
@@ -175,6 +180,9 @@
 .commerce-storefront .mt-auto {
     margin-top: auto;
   }
+.commerce-storefront .mb-0 {
+    margin-bottom: calc(var(--spacing) * 0);
+  }
 .commerce-storefront .mb-2 {
     margin-bottom: calc(var(--spacing) * 2);
   }

package/package.json

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